README
¶
opt
Install: go get -u github.com/ifnotnil/opt
Golang generic optional type with support for json.Marshaler, json.Unmarshaler, driver.Valuer, sql.Scanner and golang 1.24 json omitzero tag.
The main ideas are:
- Separate present-but-nil from not present (e.g., for the HTTP PATCH method).
- Implement optional values without using pointers.
States
| State | Constructor function | Description |
|---|---|---|
| None | None[T]() |
Value is absent, not preset nor nil. |
| Nil | Nil[T]() |
Value is present but nil |
| Valid | New[T](t T) |
Value is preset and valid (not nil) |
Json unmarshaling
Given a struct
type Foo struct {
A Optional[int] `json:"a"`
}
| Json | Resulted state of A |
|---|---|
{} |
None |
{"a": null} |
Nil |
{"a": 123} |
Valid |
Why not Set?
We can achieve that by writing the optional value using one of the constructor functions.
a := Nil["string")
// ...
a = New("test")
Documentation
¶
Index ¶
- type Optional
- func (e Optional[T]) IsNil() bool
- func (e Optional[T]) IsPresent() bool
- func (e Optional[T]) IsValid() bool
- func (e Optional[T]) IsZero() bool
- func (e Optional[T]) MarshalJSON() ([]byte, error)
- func (e Optional[T]) OrElse(d T) T
- func (e Optional[T]) Ptr() *T
- func (e *Optional[T]) Scan(src any) error
- func (e *Optional[T]) UnmarshalJSON(data []byte) error
- func (e Optional[T]) Value() (driver.Value, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Optional ¶
type Optional[T any] struct { Item T // contains filtered or unexported fields }
func (Optional[T]) IsZero ¶ added in v0.1.0
IsZero implements the interface used by go 1.24 encoding/json marshall when `omitzero` tag is present.
func (Optional[T]) MarshalJSON ¶
MarshalJSON implements the json.Marshaler interface. It returns "null" if the state is either none or nil.
func (Optional[T]) OrElse ¶
func (e Optional[T]) OrElse(d T) T
OrElse checks if the value of Optional struct exists and is not nil, if so it returns it, otherwise it returns the given argument d.
func (Optional[T]) Ptr ¶
func (e Optional[T]) Ptr() *T
Ptr returns a pointer to the inner value if the value is present and not nil. Otherwise it returns nil.
func (*Optional[T]) Scan ¶
Scan implements sql.Scanner interface. Upon calling this function (e.g. from sql.Rows Scan function), the isPresent is set to true. It sets isNil to true if the database value (src) is null, otherwise it sets the value to [Optional.Item] and sets isNil to false.
func (*Optional[T]) UnmarshalJSON ¶
UnmarshalJSON implements the json.Unmarshaler interface. When this function is called (e.g. by json.Unmarshal), the isPresent value is set to true. This is because it means there is a field matching this value field name, and there is a value for it. If the JSON value of data is null, the soil is set to true. If the json.Unmarshal returns error isPresent and isNil are set to false before returning the error.
func (Optional[T]) Value ¶
Value implements driver.Valuer interface. If the wrapped value Item implements driver.Valuer that Value() function will be called.
Source Files