FSharp.Core


ValueOption Module

Contains operations for working with value options.

Functions and values

Function or value Description

ValueOption.bind binder voption

Full Usage: ValueOption.bind binder voption

Parameters:
    binder : 'T -> 'U voption - A function that takes the value of type T from a value option and transforms it into a value option containing a value of type U.
    voption : 'T voption - The input value option.

Returns: 'U voption An option of the output type of the binder.

bind f inp evaluates to match inp with ValueNone -> ValueNone | ValueSome x -> f x

binder : 'T -> 'U voption

A function that takes the value of type T from a value option and transforms it into a value option containing a value of type U.

voption : 'T voption

The input value option.

Returns: 'U voption

An option of the output type of the binder.

Example

 let tryParse input =
     match System.Int32.TryParse (input: string) with
     | true, v -> ValueSome v
     | false, _ -> ValueNone
 ValueNone |> ValueOption.bind tryParse // evaluates to ValueNone
 ValueSome "42" |> ValueOption.bind tryParse // evaluates to ValueSome 42
 ValueSome "Forty-two" |> ValueOption.bind tryParse // evaluates to ValueNone

ValueOption.contains value voption

Full Usage: ValueOption.contains value voption

Parameters:
    value : 'T - The value to test for equality.
    voption : 'T voption - The input value option.

Returns: bool True if the option is ValueSome and contains a value equal to value, otherwise false.
Modifiers: inline
Type parameters: 'T

Evaluates to true if voption is ValueSome and its value is equal to value.

value : 'T

The value to test for equality.

voption : 'T voption

The input value option.

Returns: bool

True if the option is ValueSome and contains a value equal to value, otherwise false.

Example

 (99, ValueNone) ||> ValueOption.contains // evaluates to false
 (99, ValueSome 99) ||> ValueOption.contains // evaluates to true
 (99, ValueSome 100) ||> ValueOption.contains // evaluates to false

ValueOption.count voption

Full Usage: ValueOption.count voption

Parameters:
    voption : 'T voption - The input value option.

Returns: int A zero if the option is ValueNone, a one otherwise.

count inp evaluates to match inp with ValueNone -> 0 | ValueSome _ -> 1.

voption : 'T voption

The input value option.

Returns: int

A zero if the option is ValueNone, a one otherwise.

Example

 ValueNone |> ValueOption.count // evaluates to 0
 ValueSome 99 |> ValueOption.count // evaluates to 1

ValueOption.defaultValue value voption

Full Usage: ValueOption.defaultValue value voption

Parameters:
    value : 'T - The specified default value.
    voption : 'T voption - The input voption.

Returns: 'T The voption if the voption is ValueSome, else the default value.

Gets the value of the value option if the option is ValueSome, otherwise returns the specified default value.

Identical to the built-in defaultArg operator, except with the arguments swapped.

value : 'T

The specified default value.

voption : 'T voption

The input voption.

Returns: 'T

The voption if the voption is ValueSome, else the default value.

Example

 (99, ValueNone) ||> ValueOption.defaultValue // evaluates to 99
 (99, ValueSome 42) ||> ValueOption.defaultValue // evaluates to 42

ValueOption.defaultWith defThunk voption

Full Usage: ValueOption.defaultWith defThunk voption

Parameters:
    defThunk : unit -> 'T - A thunk that provides a default value when evaluated.
    voption : 'T voption - The input voption.

Returns: 'T The voption if the voption is ValueSome, else the result of evaluating defThunk.

Gets the value of the voption if the voption is ValueSome, otherwise evaluates defThunk and returns the result.

defThunk is not evaluated unless voption is ValueNone.

defThunk : unit -> 'T

A thunk that provides a default value when evaluated.

voption : 'T voption

The input voption.

Returns: 'T

The voption if the voption is ValueSome, else the result of evaluating defThunk.

Example

 ValueNone |> ValueOption.defaultWith (fun () -> 99) // evaluates to 99
 ValueSome 42 |> ValueOption.defaultWith (fun () -> 99) // evaluates to 42

ValueOption.exists predicate voption

Full Usage: ValueOption.exists predicate voption

Parameters:
    predicate : 'T -> bool - A function that evaluates to a boolean when given a value from the option type.
    voption : 'T voption - The input value option.

Returns: bool False if the option is ValueNone, otherwise it returns the result of applying the predicate to the option value.

exists p inp evaluates to match inp with ValueNone -> false | ValueSome x -> p x.

predicate : 'T -> bool

A function that evaluates to a boolean when given a value from the option type.

voption : 'T voption

The input value option.

Returns: bool

False if the option is ValueNone, otherwise it returns the result of applying the predicate to the option value.

Example

 ValueNone |> ValueOption.exists (fun x -> x >= 5) // evaluates to false
 ValueSome 42 |> ValueOption.exists (fun x -> x >= 5) // evaluates to true
 ValueSome 4 |> ValueOption.exists (fun x -> x >= 5) // evaluates to false

ValueOption.filter predicate voption

Full Usage: ValueOption.filter predicate voption

Parameters:
    predicate : 'T -> bool - A function that evaluates whether the value contained in the value option should remain, or be filtered out.
    voption : 'T voption - The input value option.

Returns: 'T voption The input if the predicate evaluates to true; otherwise, ValueNone.

filter f inp evaluates to match inp with ValueNone -> ValueNone | ValueSome x -> if f x then ValueSome x else ValueNone.

predicate : 'T -> bool

A function that evaluates whether the value contained in the value option should remain, or be filtered out.

voption : 'T voption

The input value option.

Returns: 'T voption

The input if the predicate evaluates to true; otherwise, ValueNone.

Example

 ValueNone |> ValueOption.filter (fun x -> x >= 5) // evaluates to ValueNone
 ValueSome 42 |> ValueOption.filter (fun x -> x >= 5) // evaluates to ValueSome 42
 ValueSome 4 |> ValueOption.filter (fun x -> x >= 5) // evaluates to ValueNone

ValueOption.flatten voption

Full Usage: ValueOption.flatten voption

Parameters:
Returns: 'T voption The input value if the value is Some; otherwise, ValueNone.

flatten inp evaluates to match inp with ValueNone -> ValueNone | ValueSome x -> x

flatten is equivalent to bind id.

voption : 'T voption voption

The input value option.

Returns: 'T voption

The input value if the value is Some; otherwise, ValueNone.

Example

 (ValueNone: int ValueOption ValueOption) |> ValueOption.flatten // evaluates to ValueNone
 (ValueSome ((ValueNone: int ValueOption))) |> ValueOption.flatten // evaluates to ValueNone
 (ValueSome (ValueSome 42)) |> ValueOption.flatten // evaluates to ValueSome 42

ValueOption.fold folder state voption

Full Usage: ValueOption.fold folder state voption

Parameters:
    folder : 'State -> 'T -> 'State - A function to update the state data when given a value from a value option.
    state : 'State - The initial state.
    voption : 'T voption - The input value option.

Returns: 'State The original state if the option is ValueNone, otherwise it returns the updated state with the folder and the voption value.

fold f s inp evaluates to match inp with ValueNone -> s | ValueSome x -> f s x.

folder : 'State -> 'T -> 'State

A function to update the state data when given a value from a value option.

state : 'State

The initial state.

voption : 'T voption

The input value option.

Returns: 'State

The original state if the option is ValueNone, otherwise it returns the updated state with the folder and the voption value.

Example

 (0, ValueNone) ||> ValueOption.fold (fun accum x -> accum + x * 2) // evaluates to 0
 (0, ValueSome 1) ||> ValueOption.fold (fun accum x -> accum + x * 2) // evaluates to 2
 (10, ValueSome 1) ||> ValueOption.fold (fun accum x -> accum + x * 2) // evaluates to 12

ValueOption.foldBack folder voption state

Full Usage: ValueOption.foldBack folder voption state

Parameters:
    folder : 'T -> 'State -> 'State - A function to update the state data when given a value from a value option.
    voption : 'T voption - The input value option.
    state : 'State - The initial state.

Returns: 'State The original state if the option is ValueNone, otherwise it returns the updated state with the folder and the voption value.

fold f inp s evaluates to match inp with ValueNone -> s | ValueSome x -> f x s.

folder : 'T -> 'State -> 'State

A function to update the state data when given a value from a value option.

voption : 'T voption

The input value option.

state : 'State

The initial state.

Returns: 'State

The original state if the option is ValueNone, otherwise it returns the updated state with the folder and the voption value.

Example

 (ValueNone, 0) ||> ValueOption.foldBack (fun x accum -> accum + x * 2) // evaluates to 0
 (ValueSome 1, 0) ||> ValueOption.foldBack (fun x accum -> accum + x * 2) // evaluates to 2
 (ValueSome 1, 10) ||> ValueOption.foldBack (fun x accum -> accum + x * 2) // evaluates to 12

ValueOption.forall predicate voption

Full Usage: ValueOption.forall predicate voption

Parameters:
    predicate : 'T -> bool - A function that evaluates to a boolean when given a value from the value option type.
    voption : 'T voption - The input value option.

Returns: bool True if the option is None, otherwise it returns the result of applying the predicate to the option value.

forall p inp evaluates to match inp with ValueNone -> true | ValueSome x -> p x.

predicate : 'T -> bool

A function that evaluates to a boolean when given a value from the value option type.

voption : 'T voption

The input value option.

Returns: bool

True if the option is None, otherwise it returns the result of applying the predicate to the option value.

Example

 ValueNone |> ValueOption.forall (fun x -> x >= 5) // evaluates to true
 ValueSome 42 |> ValueOption.forall (fun x -> x >= 5) // evaluates to true
 ValueSome 4 |> ValueOption.forall (fun x -> x >= 5) // evaluates to false

ValueOption.get voption

Full Usage: ValueOption.get voption

Parameters:
    voption : 'T voption - The input value option.

Returns: 'T The value within the option.

Gets the value associated with the option.

voption : 'T voption

The input value option.

Returns: 'T

The value within the option.

Example

 ValueSome 42 |> ValueOption.get // evaluates to 42
 (ValueNone: int ValueOption) |> ValueOption.get // throws exception!

ValueOption.isNone voption

Full Usage: ValueOption.isNone voption

Parameters:
    voption : 'T voption - The input value option.

Returns: bool True if the voption is ValueNone.
Modifiers: inline
Type parameters: 'T

Returns true if the value option is ValueNone.

voption : 'T voption

The input value option.

Returns: bool

True if the voption is ValueNone.

Example

 ValueNone |> ValueOption.isNone // evaluates to true
 ValueSome 42 |> ValueOption.isNone // evaluates to false

ValueOption.isSome voption

Full Usage: ValueOption.isSome voption

Parameters:
    voption : 'T voption - The input value option.

Returns: bool True if the value option is not ValueNone.
Modifiers: inline
Type parameters: 'T

Returns true if the value option is not ValueNone.

voption : 'T voption

The input value option.

Returns: bool

True if the value option is not ValueNone.

Example

 ValueNone |> ValueOption.isSome // evaluates to false
 ValueSome 42 |> ValueOption.isSome // evaluates to true

ValueOption.iter action voption

Full Usage: ValueOption.iter action voption

Parameters:
    action : 'T -> unit - A function to apply to the voption value.
    voption : 'T voption - The input value option.

iter f inp executes match inp with ValueNone -> () | ValueSome x -> f x.

action : 'T -> unit

A function to apply to the voption value.

voption : 'T voption

The input value option.

Example

 ValueNone |> ValueOption.iter (printfn "%s") // does nothing
 ValueSome "Hello world" |> ValueOption.iter (printfn "%s") // prints "Hello world"

ValueOption.map mapping voption

Full Usage: ValueOption.map mapping voption

Parameters:
    mapping : 'T -> 'U - A function to apply to the voption value.
    voption : 'T voption - The input value option.

Returns: 'U voption A value option of the input value after applying the mapping function, or ValueNone if the input is ValueNone.

map f inp evaluates to match inp with ValueNone -> ValueNone | ValueSome x -> ValueSome (f x).

mapping : 'T -> 'U

A function to apply to the voption value.

voption : 'T voption

The input value option.

Returns: 'U voption

A value option of the input value after applying the mapping function, or ValueNone if the input is ValueNone.

Example

 ValueNone |> ValueOption.map (fun x -> x * 2) // evaluates to ValueNone
 ValueSome 42 |> ValueOption.map (fun x -> x * 2) // evaluates to ValueSome 84

ValueOption.map2 mapping voption1 voption2

Full Usage: ValueOption.map2 mapping voption1 voption2

Parameters:
    mapping : 'T1 -> 'T2 -> 'U - A function to apply to the voption values.
    voption1 : 'T1 voption - The first value option.
    voption2 : 'T2 voption - The second value option.

Returns: 'U voption A value option of the input values after applying the mapping function, or ValueNone if either input is ValueNone.

map f voption1 voption2 evaluates to match voption1, voption2 with ValueSome x, ValueSome y -> ValueSome (f x y) | _ -> ValueNone.

mapping : 'T1 -> 'T2 -> 'U

A function to apply to the voption values.

voption1 : 'T1 voption

The first value option.

voption2 : 'T2 voption

The second value option.

Returns: 'U voption

A value option of the input values after applying the mapping function, or ValueNone if either input is ValueNone.

Example

 (ValueNone, ValueNone) ||> ValueOption.map2 (fun x y -> x + y) // evaluates to ValueNone
 (ValueSome 5, ValueNone) ||> ValueOption.map2 (fun x y -> x + y) // evaluates to ValueNone
 (ValueNone, ValueSome 10) ||> ValueOption.map2 (fun x y -> x + y) // evaluates to ValueNone
 (ValueSome 5, ValueSome 10) ||> ValueOption.map2 (fun x y -> x + y) // evaluates to ValueSome 15

ValueOption.map3 mapping voption1 voption2 voption3

Full Usage: ValueOption.map3 mapping voption1 voption2 voption3

Parameters:
    mapping : 'T1 -> 'T2 -> 'T3 -> 'U - A function to apply to the value option values.
    voption1 : 'T1 voption - The first value option.
    voption2 : 'T2 voption - The second value option.
    voption3 : 'T3 voption - The third value option.

Returns: 'U voption A value option of the input values after applying the mapping function, or ValueNone if any input is ValueNone.

map f voption1 voption2 voption3 evaluates to match voption1, voption2, voption3 with ValueSome x, ValueSome y, ValueSome z -> ValueSome (f x y z) | _ -> ValueNone.

mapping : 'T1 -> 'T2 -> 'T3 -> 'U

A function to apply to the value option values.

voption1 : 'T1 voption

The first value option.

voption2 : 'T2 voption

The second value option.

voption3 : 'T3 voption

The third value option.

Returns: 'U voption

A value option of the input values after applying the mapping function, or ValueNone if any input is ValueNone.

Example

 (ValueNone, ValueNone, ValueNone) |||> ValueOption.map3 (fun x y z -> x + y + z) // evaluates to ValueNone
 (ValueSome 100, ValueNone, ValueNone) |||> ValueOption.map3 (fun x y z -> x + y + z) // evaluates to ValueNone
 (ValueNone, ValueSome 100, ValueNone) |||> ValueOption.map3 (fun x y z -> x + y + z) // evaluates to ValueNone
 (ValueNone, ValueNone, ValueSome 100) |||> ValueOption.map3 (fun x y z -> x + y + z) // evaluates to ValueNone
 (ValueSome 5, ValueSome 100, ValueSome 10) |||> ValueOption.map3 (fun x y z -> x + y + z) // evaluates to ValueSome 115

ValueOption.ofNullable value

Full Usage: ValueOption.ofNullable value

Parameters:
    value : Nullable<'T> - The input nullable value.

Returns: 'T voption The result value option.

Convert a Nullable value to a value option.

value : Nullable<'T>

The input nullable value.

Returns: 'T voption

The result value option.

Example

 System.Nullable<int>() |> ValueOption.ofNullable // evaluates to ValueNone
 System.Nullable(42) |> ValueOption.ofNullable // evaluates to ValueSome 42

ValueOption.ofObj value

Full Usage: ValueOption.ofObj value

Parameters:
    value : 'T - The input value.

Returns: 'T voption The result value option.

Convert a potentially null value to a value option.

value : 'T

The input value.

Returns: 'T voption

The result value option.

Example

 (null: string) |> ValueOption.ofObj // evaluates to ValueNone
 "not a null string" |> ValueOption.ofObj // evaluates to (ValueSome "not a null string")

ValueOption.orElse ifNone voption

Full Usage: ValueOption.orElse ifNone voption

Parameters:
    ifNone : 'T voption - The value to use if voption is None.
    voption : 'T voption - The input option.

Returns: 'T voption The option if the option is Some, else the alternate option.

Returns voption if it is Some, otherwise returns ifNone.

ifNone : 'T voption

The value to use if voption is None.

voption : 'T voption

The input option.

Returns: 'T voption

The option if the option is Some, else the alternate option.

Example

 ((ValueNone: int ValueOption), ValueNone) ||> ValueOption.orElse // evaluates to ValueNone
 (ValueSome 99, ValueNone) ||> ValueOption.orElse // evaluates to ValueSome 99
 (ValueNone, ValueSome 42) ||> ValueOption.orElse // evaluates to ValueSome 42
 (ValueSome 99, ValueSome 42) ||> ValueOption.orElse // evaluates to ValueSome 42

ValueOption.orElseWith ifNoneThunk voption

Full Usage: ValueOption.orElseWith ifNoneThunk voption

Parameters:
    ifNoneThunk : unit -> 'T voption - A thunk that provides an alternate value option when evaluated.
    voption : 'T voption - The input value option.

Returns: 'T voption The voption if the voption is ValueSome, else the result of evaluating ifNoneThunk.

Returns voption if it is Some, otherwise evaluates ifNoneThunk and returns the result.

ifNoneThunk is not evaluated unless voption is ValueNone.

ifNoneThunk : unit -> 'T voption

A thunk that provides an alternate value option when evaluated.

voption : 'T voption

The input value option.

Returns: 'T voption

The voption if the voption is ValueSome, else the result of evaluating ifNoneThunk.

Example

 (ValueNone: int ValueOption) |> ValueOption.orElseWith (fun () -> ValueNone) // evaluates to ValueNone
 ValueNone |> ValueOption.orElseWith (fun () -> (ValueSome 99)) // evaluates to ValueSome 99
 ValueSome 42 |> ValueOption.orElseWith (fun () -> ValueNone) // evaluates to ValueSome 42
 ValueSome 42 |> ValueOption.orElseWith (fun () -> (ValueSome 99)) // evaluates to ValueSome 42

ValueOption.toArray voption

Full Usage: ValueOption.toArray voption

Parameters:
    voption : 'T voption - The input value option.

Returns: 'T[] The result array.

Convert the value option to an array of length 0 or 1.

voption : 'T voption

The input value option.

Returns: 'T[]

The result array.

Example

 (ValueNone: int ValueOption) |> ValueOption.toArray // evaluates to [||]
 ValueSome 42 |> ValueOption.toArray // evaluates to [|42|]

ValueOption.toList voption

Full Usage: ValueOption.toList voption

Parameters:
    voption : 'T voption - The input value option.

Returns: 'T list The result list.

Convert the value option to a list of length 0 or 1.

voption : 'T voption

The input value option.

Returns: 'T list

The result list.

Example

 (ValueNone: int ValueOption) |> ValueOption.toList // evaluates to []
 ValueSome 42 |> ValueOption.toList // evaluates to [42]

ValueOption.toNullable voption

Full Usage: ValueOption.toNullable voption

Parameters:
    voption : 'T voption - The input value option.

Returns: Nullable<'T> The result value.

Convert the value option to a Nullable value.

voption : 'T voption

The input value option.

Returns: Nullable<'T>

The result value.

Example

 (ValueNone: int ValueOption) |> ValueOption.toNullable // evaluates to new System.Nullable<int>()
 ValueSome 42 |> ValueOption.toNullable // evaluates to new System.Nullable(42)

ValueOption.toObj value

Full Usage: ValueOption.toObj value

Parameters:
    value : 'T voption - The input value.

Returns: 'T The result value, which is null if the input was ValueNone.

Convert an option to a potentially null value.

value : 'T voption

The input value.

Returns: 'T

The result value, which is null if the input was ValueNone.

Example

 (ValueNone: string ValueOption) |> ValueOption.toObj // evaluates to null
 ValueSome "not a null string" |> ValueOption.toObj // evaluates to "not a null string"