1.4 Option Values

8.16.0.2

1.4 Option Values🔗ℹ

An option is an optional value that is either present or absent. Present values are constructed with the present function, and absent values are represented by the absent constant.

Examples:

(define (hash-ref-option h k)
  (if (hash-has-key? h k)
      (present (hash-ref h k))
      absent))

> (hash-ref-option (hash 'a 1 'b 2) 'a)
(present 1)
> (hash-ref-option (hash 'a 1 'b 2) 'c)
#<absent>

procedure
(option? v) → boolean?
v : any/c

A predicate for option values, which are either present or absent.

procedure
(present? v) → boolean?
v : any/c

A predicate for present values. Implies option?.

procedure
(present v) → present?
v : any/c

Constructs a present value containing v. Additionally, can be used as a match expander to match present values and unwrap them.

Example:

> (match (present 42)
[(present x) (add1 x)]
[(== absent) 0])
43

procedure
(present-value pres) → any/c
pres : present?

Returns the value wrapped by pres.

procedure
(absent? v) → boolean?
v : any/c

A predicate for the absent value. Implies option?.

value
absent : absent?

The absent constant.

procedure
(falsey->option falsey-value) → option?
falsey-value : any/c

Converts falsey-value to an option. If falsey-value is #false, absent is returned, otherwise falsey-value is wrapped as a present value.

Examples:

> (falsey->option 5)
(present 5)
> (falsey->option #false)
#<absent>

Note that there is no specialized option->falsey function. In order to convert from an option to a falsey value, use option-get with #false as the default value.

procedure
(option-case opt
#:present present-handler
#:absent absent-handler) → any/c
  opt : option?
  present-handler : (-> any/c any/c)
  absent-handler : (-> any/c)

Inspects opt and, if it is present, calls present-handler on the present value. If it is absent, calls absent-handler. Returns the result of the called handler.

Examples:

> (option-case (present 42)
               #:present add1
               #:absent (λ () (error "missing!")))
43
> (option-case absent
               #:present add1
               #:absent (λ () (error "missing!")))
missing!

procedure
(option-map opt f) → option?
opt : option?
f : (-> any/c any/c)

Applies f to the value contained in opt if it is present and returns the result wrapped in a present value. If opt is absent, returns absent.

Examples:

> (option-map (present 42) add1)
(present 43)
> (option-map absent add1)
#<absent>

procedure
(option-flat-map opt f) → option?
opt : option?
f : (-> any/c option?)

Applies f to the value contained in opt if it is present and returns the result of f. If opt is absent, returns absent.

Examples:

(define (inverse x)
  (if (zero? x)
      absent
      (present (/ 1 x))))

> (option-flat-map (present 42) inverse)
(present 1/42)
> (option-flat-map absent inverse)
#<absent>
> (option-flat-map (present 0) inverse)
#<absent>

procedure
(option-filter opt pred) → option?
opt : option?
pred : predicate/c

If opt is present, tests its value with pred and returns it if pred results in #t. Otherwise, returns absent.

Examples:

> (option-filter (present 42) number?)
(present 42)
> (option-filter (present "hello") number?)
#<absent>
> (option-filter absent number?)
#<absent>

procedure
(option-or first-opt opt ...) → option?
first-opt : option?
opt : option?

Returns the first option that’s present, or absent if none are present.

Examples:

> (option-or (present 1) (present 2) (present 3))
(present 1)
> (option-or absent (present 2) (present 3))
(present 2)

procedure
(option-or-call first-opt opt-thunk ...) → option?
first-opt : option?
opt-thunk : (-> option?)

Returns first-opt if it’s present, otherwise returns the first present option from calling each opt-thunk. Returns absent if first-opt is absent and every opt-thunk returns absent.

Example:

> (option-or-call
   absent
   (λ ()
     (printf "Calling first thunk...")
     absent)
   (λ ()
     (printf "Calling second thunk...")
     (present 1))
   (λ ()
     (printf "Calling third thunk...")
     (present 2)))
Calling first thunk...Calling second thunk...
(present 1)

procedure
(option-get opt default) → any/c
opt : option?
default : any/c

Returns the value in opt if it is present, otherwise returns default.

Examples:

> (option-get (present 42) 0)
42
> (option-get absent 0)
0

procedure
(in-option opt) → (sequence/c any/c)
opt : option?

Returns either a sequence that contains the present value of opt, or an empty sequence if opt is absent. This function is particularly useful in transduce pipelines, as it can be used with append-mapping and similar transducers in order to safely filter out absent values while simultaneously unwrapping present values.

1.4.1 Contracts for Option Values🔗ℹ

procedure
(option/c contract) → chaperone-contract?
contract : chaperone-contract?

Constructs a contract for option values that accepts either the absent value or a present value that satisfies contract. Equivalent to (or/c absent? (present/c contract)).

procedure
(present/c contract) → chaperone-contract?
contract : chaperone-contract?

Constructs a contract for present values that satisfy contract.

1	Base Libraries
2	Data Types
3	Streaming Computations
4	Collections
5	Concurrency
6	Binary Data
7	Module Utilities
8	Other Libraries

1.1	Generative Tokens
1.2	Immutable Strings
1.3	Uncallable Functions
1.4	Option Values
1.5	Pairs
1.6	Results
1.7	Symbols
1.8	Variants
1.9	Converters
1.10	Comparators
1.11	Equivalence Relations
1.12	Ranges