package uopt

  1. Overview
  2. Docs
An [option]-like type that incurs no allocation, without requiring a reserved value in the underlying type

Install 

dune-project
 Dependency

github.com MIT License Edit opam file Versions (1)

Authors

  1. J
    Jane Street Group, LLC

Maintainers

  1. J
    Jane Street developers

Sources

v0.17.0.tar.gz
sha256=a6534df59d54cfa50ac22c4406d425b098e94b198cee48c3d82e15a348577cc6

doc/uopt/Uopt/index.html

Module UoptSource

Uopt.t is an unboxed option: an option-like type that incurs no allocation, without requiring a reserved value in the underlying type.

The downsides compared to option are that:

  • Uopt.t cannot be nested, i.e. used as 'a Uopt.t Uopt.t, because trying to create Uopt.some Uopt.none is not supported and would raise.
  • it is unsafe to have values of type float Uopt.t array, or any type which has the same memory representation, since the representation of the array would vary depending on whether none or some is used to create the array. Using float Uopt.t Uniform_array.t is fine.
  • the implementation has unsafe code which has resulted in miscompilation in the past.

As a result, we advise against using this in systems that are not high performance.

When using Uopt, we recommend:

  • not exposing Uopt in APIs for casual users, so you don't force other people to learn about this unnecessarily.
  • not giving values of type Uopt.t (whether the type is abstract or not) to other APIs, so they are free to use Uopt internally (and also for memory safety in the cause of float Uopt.t).
  • not returning values of type Uopt.t from your libraries when the type is abstract, so callers are free to use Uopt.t on abstract types. Returning explicit Uopt.t can be fine, although turning a type that's not Uopt into a type that is could break code.

Since 'a Uopt.t is abstract, manipulation of an 'a Uopt.t array does runtime checks to see if this is a float array. This can be mostly avoided with Uniform_array.t, although array creation will still do such checks, and you may want to use the set_with_caml_modify kind of function to skip the immediacy checks.

Sourcetype +'a t
include Sexplib0.Sexpable.S1 with type +'a t := 'a t
Sourceval t_of_sexp : (Sexplib0.Sexp.t -> 'a) -> Sexplib0.Sexp.t -> 'a t
Sourceval sexp_of_t : ('a -> Sexplib0.Sexp.t) -> 'a t -> Sexplib0.Sexp.t
Sourceval globalize : ('a -> 'a) -> 'a t -> 'a t
include Base.Invariant.S1 with type 'a t := 'a t
Sourceval invariant : ('a -> unit) -> 'a t -> unit
Sourceval none : _ t
Sourceval some : 'a -> 'a t
Sourceval is_none : _ t -> Base.bool
Sourceval is_some : _ t -> Base.bool
Sourceval value_exn : 'a t -> 'a
Sourceval value : 'a t -> default:'a -> 'a
Sourceval some_if : Base.bool -> 'a -> 'a t
Sourceval unsafe_value : 'a t -> 'a

It is safe to call unsafe_value t iff is_some t.

Sourceval to_option : 'a t -> 'a Base.option
Sourceval of_option : 'a Base.option -> 'a t
Sourcemodule Optional_syntax : sig ... end
Sourcemodule Local : sig ... end

Same as their global equivalents.