README
¶
goption
Optional values for Go. Inspired by the Rust implementation.
Why?
I created this to provide greater coherency of optional handling across the language. In sql, we use NullType, in json and encoding friends we use pointers, and elsewhere we use ok. This package adds a more coherent optional experience across the language and is well tested.
Features
Highly tested and aims at high utility. Attempts to follow a monadic design where if the wrapped type T implements some interface, so should Option[T]. The following are implemented:
json.Marshalerjson.Unmarshalerfmt.Stringerfmt.GoStringersql.Scannersql.driver.Valuer
If there are any more interfaces which should be wrapped, please open an issue or a PR. All features must be tested.
Examples
Basic
To declare a present optional value do:
myOption := Some[int](3)
To declare an empty optional value do:
empty := None[int]()
The default value for an Option[T] is None[T]():
var maybeInt Option[int]
if !maybeInt.Ok() {
fmt.Println("The value isn't present!") // This will print, maybeInt hasn't been set.
}
To check if an optional value is present do:
opt := functionReturningOption()
if opt.Ok() {
fmt.Println(opt.Unwrap())
}
To convert a pointer into an optional value do:
var pointer *int
myOption := FromRef(pointer) // Empty for nil pointers
sql
To move values in and out of a sql database do:
db.Exec(`
INSERT INTO test (optional_field) VALUES ($1);
`, Some[int](0))
rows, err := db.Query(`
SELECT * FROM test;
`)
for rows.Next() {
var opt Option[int]
rows.Scan(&opt)
fmt.Println(opt)
}
json
type MyStruct struct {
Foo Option[int]
}
var v MyStruct
json.Unmarshal([]byte(`{}`), &v)
if v.Foo.Ok() {
fmt.Println(v.Foo.Unwrap())
}
Documentation
¶
Index ¶
- Variables
- type Option
- func (o Option[T]) Expect(msg string) T
- func (o *Option[T]) ExpectRef(msg string) *T
- func (o Option[T]) Get() (T, bool)
- func (o Option[T]) GoString() string
- func (o Option[T]) MarshalJSON() ([]byte, error)
- func (o Option[T]) MarshalText() ([]byte, error)
- func (o Option[T]) Ok() bool
- func (o *Option[T]) Scan(src any) error
- func (o Option[T]) String() string
- func (o *Option[T]) UnmarshalJSON(data []byte) error
- func (o *Option[T]) UnmarshalText(data []byte) error
- func (o Option[T]) Unwrap() T
- func (o Option[T]) UnwrapOr(def T) T
- func (o Option[T]) UnwrapOrDefault() T
- func (o *Option[T]) UnwrapRef() *T
- func (o *Option[T]) UnwrapRefOr(def *T) *T
- func (o *Option[T]) UnwrapRefOrNil() *T
- func (o Option[T]) Value() (driver.Value, error)
Constants ¶
This section is empty.
Variables ¶
var ErrNotAScanner errNotAScanner
Functions ¶
This section is empty.
Types ¶
type Option ¶
type Option[T any] struct { // contains filtered or unexported fields }
Option represents a value whose presence is optional.
func Do ¶
Do runs the function f which may panic. If f does not panic Some(f()) is returned. Otherwise none is returned.
func FromRef ¶ added in v1.0.1
FromRef returns an Option whose underlying value is present if t is not nil. Otherwise, it returns an empty optional value.
func (Option[T]) Get ¶ added in v1.0.1
Get returns the underlying value and a boolean indicating if it's present.
func (Option[T]) MarshalJSON ¶
MarshalJSON marshals the underlying option data
func (Option[T]) MarshalText ¶ added in v1.1.0
MarshalText marshals the underlying option data
func (*Option[T]) UnmarshalJSON ¶
UnmarshalJSON unmarshals the underlying
func (*Option[T]) UnmarshalText ¶ added in v1.1.0
UnmarshalText unmarshals the underlying
func (Option[T]) Unwrap ¶
func (o Option[T]) Unwrap() T
Unwrap forcefully unwraps the Optional value. If the optional is not ok this function will panic.
func (Option[T]) UnwrapOr ¶
func (o Option[T]) UnwrapOr(def T) T
UnwrapOr unwraps the optional if it's present, otherwise it returns default.
func (Option[T]) UnwrapOrDefault ¶
func (o Option[T]) UnwrapOrDefault() T
UnwrapOrDefault unwraps T if it's present, otherwise it returns the default value for T.
func (*Option[T]) UnwrapRef ¶
func (o *Option[T]) UnwrapRef() *T
UnwrapRef returns a reference to the underlying T.
func (*Option[T]) UnwrapRefOr ¶ added in v1.2.0
func (o *Option[T]) UnwrapRefOr(def *T) *T
UnwrapRefOr returns a reference if optional is present, otherwise it returns default.
func (*Option[T]) UnwrapRefOrNil ¶ added in v1.2.0
func (o *Option[T]) UnwrapRefOrNil() *T
UnwrapRefOrNil returns a reference if optional is present, otherwise it returns nil.
Source Files