option

Overview ¶

Package optional provides an Option type for Go. A value of the Option type will be in one of two states: "Some" (containing a value) or "None" (containing no value).

The purpose of the Option type is to more clearly distinguish the two situations that standard Go uses pointer types for:

• to provide a way to edit the inside of a value without changing the value itself
• to allow for a value to be either present or absent (with absence being represented as "nil")

Using the Option type, pointers may be reserved for the first purpose. For instance, a type like *int32 would clearly represent an editable value, whereas Option[int32] clearly represents an optional value.

Clean import guarantee ¶

This package is supposed to be used as a dot-import:

import . "github.com/majewsky/go-option"

To avoid backwards incompatibilities, we guarantee that, at least throughout the 1.x series, newer versions of this package will never export any more names than it currently does ("None", "Option" and "Some").

Marshalling considerations ¶

Marshaling into and from YAML using https://github.com/go-yaml/yaml is supported. The "omitempty" flag works as expected.

Marshaling into and from JSON using encoding/json is supported, but the "omitempty" flag does not work. You must use the "omitzero" flag to get the same effect, but note that this flag is only supported by Go 1.24 and newer.

How to replace pointer types with Option types ¶

This abridged example shows the most common ways to interact with pointer types that represent optional values:

type ServerConfiguration struct {
	CrashLogPath *string
	ListenAddress *string
	ThreadCount *uint64
}

func RunServer(cfg ServerConfiguration) {
	// inform about a value being absent
	if cfg.CrashLogPath == nil {
		log.Print("crash logging disabled because no CrashLogPath is given")
	}

	// fill a default value if nil is given
	listenAddress := "127.0.0.1:8080"
	if cfg.ListenAddress != nil {
		listenAddress = *listenAddress
	}

	// access contained value if present, or proceed without contained value if absent
	if cfg.ThreadCount != nil {
		startMultiThreadedServer(listenAddress, *cfg.ThreadCount)
	} else {
		startSingleThreadedServer(listenAddress)
	}
}

This is how the same code snippet looks when replacing the pointer types with Option types and taking advantage of the methods on type Option:

type ServerConfiguration struct {
	CrashLogPath Option[string]
	ListenAddress Option[string]
	ThreadCount Option[uint64]
}

func RunServer(cfg ServerConfiguration) {
	// "if x == nil" becomes "if x.IsNone()"; the opposite check is called IsSome()
	if cfg.CrashLogPath.IsNone() {
		log.Print("crash logging disabled because no CrashLogPath is given")
	}

	// default values can be filled with UnwrapOr()
	listenAddress := cfg.ListenAddress.UnwrapOr("127.0.0.1:8080")

	// Unpack() provides the contained value and a success flag, similar to the double-return-value form of map indexing
	if threadCount, ok := cfg.ThreadCount.Unpack(); ok {
		startMultiThreadedServer(listenAddress, *cfg.ThreadCount)
	} else {
		startSingleThreadedServer(listenAddress)
	}
}

Differences to Rust ¶

This package's API is obviously modeled after the Option type in the Rust standard library, but with some exceptions.

• Go does not allow to introduce additional type parameters for individual methods. Any methods that, in Rust, introduce the second type parameter U, cannot be represented in Go. Some methods like and() or zip() could be allowed if the argument is restricted to Option[T] instead of Option[U], but this restriction degrades their usefulness beyond reasonable limits.
• Go does not allow to introduce additional type restrictions in individual methods. This makes methods like unzip() or cloned() unrepresentable in Go. We might make these available as free-standing functions in the future, but if we do, they will definitely not be in this package (see "Clean import guarantee" above).
• Mixing of struct receiver methods and pointer receiver methods on the same type is discouraged to avoid unintentional copies and data races. Since most of the useful methods require only a struct receiver, we forego those that require a pointer receiver, like get_or_insert() or take(). The only exception to this is the methods implementing Unmarshaler interfaces, where concurrency bugs are very unlikely.

Finally, the unwrap() function is not provided since its meaningless error message is not helpful in most contexts. We only provide expect(), but under the different name UnwrapOrPanic(), since expect() reads terribly in context. Consider the following example:

dbURL := GetDatabaseURLFromEnvironment().Expect("no DB connection found")
// ^ This reads like we *expect* to not find a DB connection, even though the opposite is true.

dbURL := GetDatabaseURLFromEnvironment().UnwrapOrPanic("no DB connection found")
// ^ This is a much clearer phrasing.