Option<T> Struct

Definition

Namespace

Bodu.Functional

Assembly

Bodu.Core.dll

Package

Bodu.Core 1.0.1

Source

Option{T}.Factories.cs

Represents an optional value: either Some(value) carrying a non-null value of type T, or None carrying nothing.

public readonly struct Option<T> : IEquatable<Option<T>>

Type Parameters

T

The type of the contained value.

Implements

IEquatable<Option<T>>

Inherited Members

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Extension Methods

ComparableExtensions.AtLeast<T>(T, T, IComparer<T>)

ComparableExtensions.AtMost<T>(T, T, IComparer<T>)

ComparableExtensions.Clamp<T>(T, T?, T?, IComparer<T>)

ComparableExtensions.IsBetween<T>(T, T?, T?, IComparer<T>)

ComparableExtensions.IsEqualTo<T>(T, T, IComparer<T>)

ComparableExtensions.IsGreaterThanOrEqual<T>(T, T?, IComparer<T>)

ComparableExtensions.IsGreaterThan<T>(T, T?, IComparer<T>)

ComparableExtensions.IsLessThanOrEqual<T>(T, T?, IComparer<T>)

ComparableExtensions.IsLessThan<T>(T, T?, IComparer<T>)

ComparableExtensions.IsOutside<T>(T, T?, T?, IComparer<T>)

ComparableExtensions.Max<T>(T, T, IComparer<T>)

ComparableExtensions.Min<T>(T, T, IComparer<T>)

OptionAsyncExtensions.BindAsync<T, TResult>(Option<T>, Func<T, Task<Option<TResult>>>)

OptionAsyncExtensions.MapAsync<T, TResult>(Option<T>, Func<T, Task<TResult>>)

OptionAsyncExtensions.MatchAsync<T, TResult>(Option<T>, Func<T, Task<TResult>>, Func<Task<TResult>>)

Remarks

Option<T> makes the possible absence of a value explicit in a signature, replacing null returns and bool Try…(out …) pairs with a single composable value. Chain transformations with Map<TResult>(Func<T, TResult>) and Bind<TResult>(Func<T, Option<TResult>>), and collapse to a final value with Match<TResult>(Func<T, TResult>, Func<TResult>) or the GetValueOrDefault overloads.

default(Option<T>) equals None - an option that was never assigned behaves exactly like an explicit None, so the type is total and safe to use as a field or array element without initialization.

The type distinguishes a strict and a lenient lift: Some(T) rejects null with ArgumentNullException (a present null is treated as a bug), while the implicit conversion from T maps null to None (absence).

Properties

IsNone

Gets a value indicating whether this option carries no value.

public bool IsNone { get; }

Property Value

bool

true if no value is present; otherwise, false.

IsSome

Gets a value indicating whether this option carries a value.

public bool IsSome { get; }

Property Value

bool

true if a value is present; otherwise, false.

None

Gets the option that carries no value.

public static Option<T> None { get; }

Property Value

Option<T>

An Option<T> whose IsNone is true. Equal to default(Option<T>).

Value

Gets the contained value.

public T Value { get; }

Property Value

T

The value carried by this option.

Remarks

Prefer TryGetValue(out T), Match<TResult>(Func<T, TResult>, Func<TResult>), or the GetValueOrDefault overloads over direct access when absence is an expected state; Value is intended for call sites that have already established IsSome.

Exceptions

InvalidOperationException

The option does not contain a value.

Methods

Bind<TResult>(Func<T, Option<TResult>>)

Projects the contained value into another option using the specified option-returning selector.

public Option<TResult> Bind<TResult>(Func<T, Option<TResult>> selector)

Parameters

selector Func<T, Option<TResult>>

The option-returning projection applied to the contained value.

Returns

Option<TResult>

The option produced by the selector when a value is present; otherwise None.

Type Parameters

TResult

The value type of the resulting option.

Remarks

The selector is not invoked when this option is None.

Exceptions

ArgumentNullException

selector is null.

Equals(Option<T>)

Determines whether the specified option is equal to the current instance.

public bool Equals(Option<T> other)

Parameters

other Option<T>

The option to compare with this instance.

Returns

bool

true if both are None, or both carry values that compare equal using Default; otherwise, false.

Equals(object?)

Determines whether the specified object is equal to the current option.

public override bool Equals(object? obj)

Parameters

obj object

The object to compare. Only another Option<T> can be equal; all other types, including null, return false.

Returns

bool

true if obj is an Option<T> equal to this instance; otherwise, false.

Filter(Func<T, bool>)

Retains the contained value only when it satisfies the specified predicate.

public Option<T> Filter(Func<T, bool> predicate)

Parameters

predicate Func<T, bool>

The condition the contained value must satisfy.

Returns

Option<T>

This option when a value is present and satisfies predicate; otherwise None.

Remarks

The predicate is not invoked when this option is None.

Exceptions

ArgumentNullException

predicate is null.

GetHashCode()

Returns a hash code for the current instance consistent with Equals(Option<T>).

public override int GetHashCode()

Returns

int

The contained value's hash code when present; otherwise 0.

GetValueOrDefault()

Returns the contained value, or the default value of T when none is present.

public T? GetValueOrDefault()

Returns

T

The contained value, or default(T).

GetValueOrDefault(Func<T>)

Returns the contained value, or the value produced by the specified factory when none is present.

public T GetValueOrDefault(Func<T> defaultFactory)

Parameters

defaultFactory Func<T>

The factory invoked to produce the fallback value.

Returns

T

The contained value, or the factory's result.

Remarks

The factory is not invoked when a value is present.

Exceptions

ArgumentNullException

defaultFactory is null.

GetValueOrDefault(T)

Returns the contained value, or the specified fallback when none is present.

public T GetValueOrDefault(T defaultValue)

Parameters

defaultValue T

The value returned when no value is present.

Returns

T

The contained value, or defaultValue.

Map<TResult>(Func<T, TResult>)

Projects the contained value into a new option using the specified selector.

public Option<TResult> Map<TResult>(Func<T, TResult> selector)

Parameters

selector Func<T, TResult>

The projection applied to the contained value.

Returns

Option<TResult>

Some(selector(value)) when a value is present and the projection is non-null; otherwise None.

Type Parameters

TResult

The type produced by the selector.

Examples

var length = Option<string>.Some("railway").Map(s => s.Length); // Some(7)
var none = Option<string>.None.Map(s => s.Length);              // None - selector not invoked

Remarks

The selector is not invoked when this option is None. A null projection result maps to None (the lenient lift), so a mapping chain can never produce a present null.

Exceptions

ArgumentNullException

selector is null.

Match(Action<T>, Action)

Invokes the matching action for the state of the option.

public void Match(Action<T> onSome, Action onNone)

Parameters

onSome Action<T>

The action invoked with the contained value when one is present.

onNone Action

The action invoked when no value is present.

Exceptions

ArgumentNullException

onSome or onNone is null.

Match<TResult>(Func<T, TResult>, Func<TResult>)

Collapses the option to a single value by invoking the matching branch.

public TResult Match<TResult>(Func<T, TResult> onSome, Func<TResult> onNone)

Parameters

onSome Func<T, TResult>

The projection invoked with the contained value when one is present.

onNone Func<TResult>

The factory invoked when no value is present.

Returns

TResult

The value produced by the invoked branch.

Type Parameters

TResult

The type produced by both branches.

Examples

var label = option.Match(v => $"got {v}", () => "nothing");

Exceptions

ArgumentNullException

onSome or onNone is null.

Some(T)

Creates an option carrying the specified non-null value.

public static Option<T> Some(T value)

Parameters

value T

The value to wrap. Must not be null.

Returns

Option<T>

An Option<T> whose IsSome is true.

Examples

var some = Option<string>.Some("value"); // Some(value)
var none = Option<string>.None;          // None

Remarks

This is the strict lift: a null argument is rejected because a present null value defeats the purpose of the type. To map null to None instead, use the implicit conversion from T (the lenient lift).

Exceptions

ArgumentNullException

value is null.

Tap(Action<T>)

Invokes the specified action with the contained value when a value is present.

public Option<T> Tap(Action<T> action)

Parameters

action Action<T>

The side effect invoked with the contained value.

Returns

Option<T>

This option, unchanged, so calls can be chained.

Remarks

The action is not invoked when this option is None; the option itself is always returned.

Exceptions

ArgumentNullException

action is null.

ToResult(ResultError)

Converts the option to a result, using the specified error when no value is present.

public Result<T> ToResult(ResultError error)

Parameters

error ResultError

The error carried by the failure produced when this option is None.

Returns

Result<T>

Success(value) when a value is present; otherwise Failure(error).

Examples

var found = Option<string>.Some("value").ToResult("missing"); // Success(value)
var missing = Option<string>.None.ToResult("missing");        // Failure(missing)

Remarks

This is the bridge from the absence-shaped Option<T> onto the failure-shaped Result<T> railway: the caller names the error that absence represents. The inverse direction is ToOption(), which discards the error.

ToString()

Returns a string representation of the option.

public override string ToString()

Returns

string

"Some(value)" when a value is present; otherwise "None".

TryGetValue(out T)

Attempts to retrieve the contained value.

public bool TryGetValue(out T value)

Parameters

value T

When this method returns, the contained value if one is present; otherwise the default value.

Returns

bool

true if a value is present; otherwise, false.

Operators

operator ==(Option<T>, Option<T>)

Determines whether two options are equal.

public static bool operator ==(Option<T> left, Option<T> right)

Parameters

left Option<T>

The first option to compare.

right Option<T>

The second option to compare.

Returns

bool

true if both are None, or both carry values that compare equal using the default equality comparer; otherwise, false.

implicit operator Option<T>(T?)

Converts a value to an option, mapping null to None.

public static implicit operator Option<T>(T? value)

Parameters

value T

The value to lift.

Returns

Option<T>

Some(value) when value is not null; otherwise None.

Examples

string? found = lookup.TryGet(key);
Option<string> option = found; // null becomes None, a value becomes Some

Remarks

This is the lenient lift: null means absence. To treat null as a bug instead, use the strict Some(T) factory, which throws ArgumentNullException. To lift a Nullable<T> value type, use Option.FromNullable.

operator !=(Option<T>, Option<T>)

Determines whether two options are not equal.

public static bool operator !=(Option<T> left, Option<T> right)

Parameters

left Option<T>

The first option to compare.

right Option<T>

The second option to compare.

Returns

bool

true if the options differ; otherwise, false.

Applies to

Product	Versions
.NET	8, 10