README
¶
Optional Values in Go
Support user-friendly, type-safe optionals in Go.
value = option.Some(4)
no_value = option.None[int]()
Usage
This package adds a single type, the Option. Option's are instantiated as
one of two variants. Some denotes the presence of a value and None denotes
the absence.
Historically pointers have been used to denote optional values, this package removes the risk of null pointer exceptions by leveraging generics to implement type-safe optional values.
Options can be tested for the presence of a value:
two = option.Some(2)
if two.IsSome() {
...
}
Values can be extracted along with a boolean test for their presence:
two = option.Some(2)
if value, ok := two.Value(); ok {
...
}
Optionals that you're sure have a value can be "unwrapped":
two := option.Some(2)
two.Unwrap() // returns 2
Accessing a value on a None variant will cause a runtime panic.
none := option.None[int]()
none.Unwrap() // panics
Ergonomics
Use of a package like this may be pervasive if you really commit to it. This
package was inspired by Rust's options implemenation. It might be worth
considering dropping the repetative option. preceding the variants. Since
importing names into the global namespace is to be avoided, the following
import pattern may work for you:
import (
"fmt"
"github.com/BooleanCat/option"
)
var (
Some = option.Some
None = option.None
)
func main() {
two := Some(2)
fmt.Println(two)
}
Documentation
¶
Index ¶
- type Option
- func (o Option[T]) Expect(message string) T
- func (o Option[T]) IsNone() bool
- func (o Option[T]) IsSome() bool
- func (o Option[T]) MarshalJSON() ([]byte, error)
- func (o Option[T]) String() string
- func (o *Option[T]) UnmarshalJSON(data []byte) error
- func (o Option[T]) Unwrap() T
- func (o Option[T]) UnwrapOr(value T) T
- func (o Option[T]) UnwrapOrElse(f func() T) T
- func (o Option[T]) UnwrapOrZero() T
- func (o Option[T]) Value() (T, bool)
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Option ¶
type Option[T any] struct { // contains filtered or unexported fields }
Option represents an optional value. The Some variant contains a value and the None variant represents the absence of a value.
func (Option[T]) Expect ¶
Expect returns the underlying value for a Some variant, or panics with the provided message for a None variant.
Example ¶
package main
import (
"fmt"
"github.com/BooleanCat/option"
)
func main() {
fmt.Println(option.Some(4).Expect("oops"))
}
Output: 4
func (Option[T]) IsNone ¶
IsNone returns true if the Option is a None variant.
Example ¶
package main
import (
"fmt"
"github.com/BooleanCat/option"
)
func main() {
fmt.Println(option.Some(4).IsNone())
fmt.Println(option.None[int]().IsNone())
}
Output: false true
func (Option[T]) IsSome ¶
IsSome returns true if the Option is a Some variant.
Example ¶
package main
import (
"fmt"
"github.com/BooleanCat/option"
)
func main() {
fmt.Println(option.Some(4).IsSome())
fmt.Println(option.None[int]().IsSome())
}
Output: true false
func (Option[T]) MarshalJSON ¶
MarshalJSON implements the json.Marshaler interface.
func (Option[T]) String ¶
String implements the fmt.Stringer interface.
func (*Option[T]) UnmarshalJSON ¶
UnmarshalJSON implements the json.Unmarshaler interface.
func (Option[T]) Unwrap ¶
func (o Option[T]) Unwrap() T
Unwrap returns the underlying value of a Some variant, or panics if called on a None variant.
Example ¶
package main
import (
"fmt"
"github.com/BooleanCat/option"
)
func main() {
fmt.Println(option.Some(4).Unwrap())
}
Output: 4
func (Option[T]) UnwrapOr ¶
func (o Option[T]) UnwrapOr(value T) T
UnwrapOr returns the underlying value of a Some variant, or the provided value on a None variant.
Example ¶
package main
import (
"fmt"
"github.com/BooleanCat/option"
)
func main() {
fmt.Println(option.Some(4).UnwrapOr(3))
fmt.Println(option.None[int]().UnwrapOr(3))
}
Output: 4 3
func (Option[T]) UnwrapOrElse ¶
func (o Option[T]) UnwrapOrElse(f func() T) T
UnwrapOrElse returns the underlying value of a Some variant, or the result of calling the provided function on a None variant.
Example ¶
package main
import (
"fmt"
"github.com/BooleanCat/option"
)
func main() {
fmt.Println(option.Some(4).UnwrapOrElse(func() int {
return 3
}))
fmt.Println(option.None[int]().UnwrapOrElse(func() int {
return 3
}))
}
Output: 4 3
func (Option[T]) UnwrapOrZero ¶
func (o Option[T]) UnwrapOrZero() T
UnwrapOrZero returns the underlying value of a Some variant, or the zero value on a None variant.
Example ¶
package main
import (
"fmt"
"github.com/BooleanCat/option"
)
func main() {
fmt.Println(option.Some(4).UnwrapOrZero())
fmt.Println(option.None[int]().UnwrapOrZero())
// Output
// 4
// 0
}
func (Option[T]) Value ¶
Value returns the underlying value and true for a Some variant, or the zero value and false for a None variant.
Example ¶
package main
import (
"fmt"
"github.com/BooleanCat/option"
)
func main() {
value, ok := option.Some(4).Value()
fmt.Println(value)
fmt.Println(ok)
}
Output: 4 true
Source Files
Directories