Struct Optional<T>

A container object which may or may not contain a value.

Implements

IEquatable<Optional<T>>

IEquatable<T>

IStructuralEquatable

IOptionMonad<T, Optional<T>>

IOptionMonad<T>

ISupplier<object>

IFunctional

Inherited Members

object.GetType()

object.Equals(object, object)

object.ReferenceEquals(object, object)

Namespace: DotNext

Assembly: DotNext.dll

Syntax

public readonly struct Optional<T> : IEquatable<Optional<T>>, IEquatable<T>, IStructuralEquatable, IOptionMonad<T, Optional<T>>, IOptionMonad<T>, ISupplier<object?>, IFunctional

Type Parameters

Name	Description
T	Type of value.

Constructors

Optional(T?)

Constructs non-empty container.

Declaration

public Optional(T? value)

Parameters

Type	Name	Description
T	value	A value to be placed into the container.

Remarks

The property IsNull of the constructed object may be true if value is null. The property IsUndefined of the constructed object is always false.

Properties

HasValue

Indicates whether the value is present.

Declaration

[MemberNotNullWhen(true, "value")]
[MemberNotNullWhen(true, "ValueOrDefault")]
public bool HasValue { get; }

Property Value

Type	Description
bool

Remarks

If this property is true then IsUndefined and IsNull equal to false.

IsNull

Indicates that the value is null.

Declaration

public bool IsNull { get; }

Property Value

Type	Description
bool

Remarks

This property returns true only if this instance was constructed using Optional(T?) with null argument.

IsUndefined

Indicates that the value is undefined.

Declaration

public bool IsUndefined { get; }

Property Value

Type	Description
bool

See Also

None

None

Represents optional container without value.

Declaration

public static Optional<T> None { get; }

Property Value

Type	Description
Optional<T>

Remarks

The property IsUndefined of returned object is always true.

Value

If a value is present, returns the value, otherwise throws an exception.

Declaration

public T Value { get; }

Property Value

Type	Description
T

Exceptions

Type	Condition
InvalidOperationException	No value is present.

ValueOrDefault

If a value is present, returns the value, otherwise default value.

Declaration

public T? ValueOrDefault { get; }

Property Value

Type	Description
T	The value, if present, otherwise default.

ValueRef

Gets an immutable reference to the value in the container.

Declaration

[UnscopedRef]
[JsonIgnore]
public ref readonly T ValueRef { get; }

Property Value

Type	Description
T

Exceptions

Type	Condition
InvalidOperationException	No value is present.

Methods

Box()

Boxes value encapsulated by this object.

Declaration

public Optional<object> Box()

Returns

Type	Description
Optional<object>	The boxed value.

Concat<TOther>(in Optional<TOther>)

Concatenates optional values.

Declaration

public Optional<(T, TOther)> Concat<TOther>(in Optional<TOther> other)

Parameters

Type	Name	Description
Optional<TOther>	other

Returns

Type	Description
Optional<(T, TOther)>	The optional value that is defined only when both containers have values.

Type Parameters

Name	Description
TOther

Convert<TResult>(delegate*<T, Optional<TResult>>)

If a value is present, apply the provided mapping function to it, and if the result is non-null, return an Optional describing the result. Otherwise, returns None.

Declaration

[CLSCompliant(false)]
public Optional<TResult> Convert<TResult>(delegate*<T, Optional<TResult>> mapper)

Parameters

Type	Name	Description
delegate*<T, Optional<TResult>>	mapper	A mapping function to be applied to the value, if present.

Returns

Type	Description
Optional<TResult>	An Optional describing the result of applying a mapping function to the value of this Optional, if a value is present, otherwise None.

Type Parameters

Name	Description
TResult	The type of the result of the mapping function.

Convert<TResult>(delegate*<T, Optional<TResult>>)

If a value is present, apply the provided mapping function to it, and if the result is non-null, return an Optional describing the result. Otherwise, returns None.

Declaration

[CLSCompliant(false)]
public Optional<TResult> Convert<TResult>(delegate*<T, Optional<TResult>> mapper)

Parameters

Type	Name	Description
delegate*<T, Optional<TResult>>	mapper	A mapping function to be applied to the value, if present.

Returns

Type	Description
Optional<TResult>	An Optional describing the result of applying a mapping function to the value of this Optional, if a value is present, otherwise None.

Type Parameters

Name	Description
TResult	The type of the result of the mapping function.

Convert<TResult>(Converter<T, Optional<TResult>>)

If a value is present, apply the provided mapping function to it, and if the result is non-null, return an Optional describing the result. Otherwise, returns None.

Declaration

public Optional<TResult> Convert<TResult>(Converter<T, Optional<TResult>> mapper)

Parameters

Type	Name	Description
Converter<T, Optional<TResult>>	mapper	A mapping function to be applied to the value, if present.

Returns

Type	Description
Optional<TResult>	An Optional describing the result of applying a mapping function to the value of this Optional, if a value is present, otherwise None.

Type Parameters

Name	Description
TResult	The type of the result of the mapping function.

Convert<TResult>(Converter<T, TResult>)

If a value is present, apply the provided mapping function to it, and if the result is non-null, return an Optional describing the result. Otherwise, returns None.

Declaration

public Optional<TResult> Convert<TResult>(Converter<T, TResult> mapper)

Parameters

Type	Name	Description
Converter<T, TResult>	mapper	A mapping function to be applied to the value, if present.

Returns

Type	Description
Optional<TResult>	An Optional describing the result of applying a mapping function to the value of this Optional, if a value is present, otherwise None.

Type Parameters

Name	Description
TResult	The type of the mapping function result.

Create<TMonad>(TMonad)

Converts the monad to Optional<T>.

Declaration

public static Optional<T> Create<TMonad>(TMonad value) where TMonad : struct, IOptionMonad<T>

Parameters

Type	Name	Description
TMonad	value	The value to convert.

Returns

Type	Description
Optional<T>	The value represented as Optional<T> or None if there is no value.

Type Parameters

Name	Description
TMonad	The type of the monad.

Equals(Optional<T>)

Determines whether this container stores the same value as the specified one.

Declaration

public bool Equals(Optional<T> other)

Parameters

Type	Name	Description
Optional<T>	other	The container to compare.

Returns

Type	Description
bool	true if this container stores the same value as other; otherwise, false.

Equals(object?)

Determines whether this container stores the same value as the specified one.

Declaration

public override bool Equals(object? other)

Parameters

Type	Name	Description
object	other	The container to compare.

Returns

Type	Description
bool	true if this container stores the same value as other; otherwise, false.

Overrides

ValueType.Equals(object)

Equals(object?, IEqualityComparer)

Performs equality check between stored value and the specified value using method Equals(object, object).

Declaration

public bool Equals(object? other, IEqualityComparer comparer)

Parameters

Type	Name	Description
object	other	Other object to compare with Value.
IEqualityComparer	comparer	The comparer implementing custom equality check.

Returns

Type	Description
bool	true if other is equal to Value using custom check; otherwise, false.

Equals(T?)

Determines whether this container stored the same value as the specified value.

Declaration

public bool Equals(T? other)

Parameters

Type	Name	Description
T	other	Other value to compare.

Returns

Type	Description
bool	true if Value is equal to other; otherwise, false.

GetHashCode()

Computes hash code of the stored value.

Declaration

public override int GetHashCode()

Returns

Type	Description
int	The hash code of the stored value.

Overrides

ValueType.GetHashCode()

Remarks

This method uses EqualityComparer<T> type to get hash code of Value.

GetHashCode(IEqualityComparer)

Computes hash code for the stored value using method GetHashCode(object).

Declaration

public int GetHashCode(IEqualityComparer comparer)

Parameters

Type	Name	Description
IEqualityComparer	comparer	The comparer implementing hash code function.

Returns

Type	Description
int	The hash code of Value.

GetReference(delegate*<Exception>)

Gets an immutable reference to the value in the container.

Declaration

[CLSCompliant(false)]
[UnscopedRef]
public ref readonly T GetReference(delegate*<Exception> exceptionFactory)

Parameters

Type	Name	Description
delegate*<Exception>	exceptionFactory	The factory used to produce exception if the container has no value.

Returns

Type	Description
T	The immutable reference to the value in the container.

GetReference(Func<Exception>)

Gets an immutable reference to the value in the container.

Declaration

[UnscopedRef]
public ref readonly T GetReference(Func<Exception> exceptionFactory)

Parameters

Type	Name	Description
Func<Exception>	exceptionFactory	The factory used to produce exception if the container has no value.

Returns

Type	Description
T	The immutable reference to the value in the container.

GetReference<TException>()

Gets an immutable reference to the value in the container.

Declaration

[UnscopedRef]
public ref readonly T GetReference<TException>() where TException : Exception, new()

Returns

Type	Description
T	The immutable reference to the value in the container.

Type Parameters

Name	Description
TException	The type of the exception to throw if the optional container has no value.

If(delegate*<T, bool>)

If a value is present, and the value matches the given predicate, return an Optional describing the value, otherwise return an empty Optional.

Declaration

[CLSCompliant(false)]
public Optional<T> If(delegate*<T, bool> condition)

Parameters

Type	Name	Description
delegate*<T, bool>	condition	A predicate to apply to the value, if present.

Returns

Type	Description
Optional<T>	An Optional describing the value of this Optional if a value is present and the value matches the given predicate, otherwise an empty Optional.

If(Predicate<T>)

If a value is present, and the value matches the given predicate, return an Optional describing the value, otherwise return an empty Optional.

Declaration

public Optional<T> If(Predicate<T> condition)

Parameters

Type	Name	Description
Predicate<T>	condition	A predicate to apply to the value, if present.

Returns

Type	Description
Optional<T>	An Optional describing the value of this Optional if a value is present and the value matches the given predicate, otherwise an empty Optional.

IsValueDefined(T?)

Determines whether the object represents meaningful value.

Declaration

public static bool IsValueDefined(T? value)

Parameters

Type	Name	Description
T	value	The value to check.

Returns

Type	Description
bool	true if value is not null, or HasValue property is true, or HasValue property is true; otherwise, false.

Or(T?)

Returns the value if present; otherwise return default value.

Declaration

public T? Or(T? defaultValue)

Parameters

Type	Name	Description
T	defaultValue	The value to be returned if there is no value present.

Returns

Type	Description
T	The value, if present, otherwise defaultValue.

OrInvoke(delegate*<T>)

Returns the value if present; otherwise invoke delegate.

Declaration

[CLSCompliant(false)]
public T OrInvoke(delegate*<T> defaultFunc)

Parameters

Type	Name	Description
delegate*<T>	defaultFunc	A delegate to be invoked if value is not present.

Returns

Type	Description
T	The value, if present, otherwise returned from delegate.

OrInvoke(Func<T>)

Returns the value if present; otherwise invoke delegate.

Declaration

public T OrInvoke(Func<T> defaultFunc)

Parameters

Type	Name	Description
Func<T>	defaultFunc	A delegate to be invoked if value is not present.

Returns

Type	Description
T	The value, if present, otherwise returned from delegate.

OrThrow(delegate*<Exception>)

If a value is present, returns the value, otherwise throw exception.

Declaration

[CLSCompliant(false)]
[MemberNotNull("ValueOrDefault")]
public T OrThrow(delegate*<Exception> exceptionFactory)

Parameters

Type	Name	Description
delegate*<Exception>	exceptionFactory	Exception factory.

Returns

Type	Description
T	The value, if present.

OrThrow(Func<Exception>)

If a value is present, returns the value, otherwise throw exception.

Declaration

[MemberNotNull("ValueOrDefault")]
public T OrThrow(Func<Exception> exceptionFactory)

Parameters

Type	Name	Description
Func<Exception>	exceptionFactory	Exception factory.

Returns

Type	Description
T	The value, if present.

OrThrow<TException>()

If a value is present, returns the value, otherwise throw exception.

Declaration

[MemberNotNull("ValueOrDefault")]
public T OrThrow<TException>() where TException : Exception, new()

Returns

Type	Description
T	The value, if present.

Type Parameters

Name	Description
TException	Type of exception to throw.

ToString()

Returns textual representation of this object.

Declaration

public override string? ToString()

Returns

Type	Description
string	The textual representation of this object.

Overrides

ValueType.ToString()

TryGet(out T?)

Attempts to extract value from this container if it is present.

Declaration

public bool TryGet(out T? value)

Parameters

Type	Name	Description
T	value	Extracted value.

Returns

Type	Description
bool	true if value is present; otherwise, false.

TryGet(out T?, out bool)

Attempts to extract value from this container if it is present.

Declaration

public bool TryGet(out T? value, out bool isNull)

Parameters

Type	Name	Description
T	value	Extracted value.
bool	isNull	true if underlying value is null; otherwise, false.

Returns

Type	Description
bool	true if value is present; otherwise, false.

Operators

operator |(in Optional<T>, in Optional<T>)

Returns non-empty container.

Declaration

public static Optional<T> operator |(in Optional<T> first, in Optional<T> second)

Parameters

Type	Name	Description
Optional<T>	first	The first container.
Optional<T>	second	The second container.

Returns

Type	Description
Optional<T>	The first non-empty container.

See Also

Coalesce<T>(in Optional<T>, in Optional<T>)

operator |(in Optional<T>, T?)

Returns the value if present; otherwise return default value.

Declaration

public static T? operator |(in Optional<T> optional, T? defaultValue)

Parameters

Type	Name	Description
Optional<T>	optional	The optional value.
T	defaultValue	The value to be returned if there is no value present.

Returns

Type	Description
T	The value, if present, otherwise defaultValue.

operator ==(in Optional<T>, in Optional<T>)

Determines whether two containers store the same value.

Declaration

public static bool operator ==(in Optional<T> first, in Optional<T> second)

Parameters

Type	Name	Description
Optional<T>	first	The first container to compare.
Optional<T>	second	The second container to compare.

Returns

Type	Description
bool	true, if both containers store the same value; otherwise, false.

operator ^(in Optional<T>, in Optional<T>)

Determines whether two containers are empty or have values.

Declaration

public static Optional<T> operator ^(in Optional<T> first, in Optional<T> second)

Parameters

Type	Name	Description
Optional<T>	first	The first container.
Optional<T>	second	The second container.

Returns

Type	Description
Optional<T>	None, if both containers are empty or have values; otherwise, non-empty container.

explicit operator T(in Optional<T>)

Extracts value stored in the Optional container.

Declaration

public static explicit operator T(in Optional<T> optional)

Parameters

Type	Name	Description
Optional<T>	optional	The container.

Returns

Type	Description
T

Exceptions

Type	Condition
InvalidOperationException	No value is present.

operator false(in Optional<T>)

Checks whether the container has no value.

Declaration

public static bool operator false(in Optional<T> optional)

Parameters

Type	Name	Description
Optional<T>	optional

Returns

Type	Description
bool	true if this container has no value; otherwise, false.

operator !=(in Optional<T>, in Optional<T>)

Determines whether two containers store the different values.

Declaration

public static bool operator !=(in Optional<T> first, in Optional<T> second)

Parameters

Type	Name	Description
Optional<T>	first	The first container to compare.
Optional<T>	second	The second container to compare.

Returns

Type	Description
bool	true, if both containers store the different values; otherwise, false.

operator !(in Optional<T>)

Checks whether the container has no value.

Declaration

public static bool operator !(in Optional<T> optional)

Parameters

Type	Name	Description
Optional<T>	optional

Returns

Type	Description
bool	true if this container has no value; otherwise, false.

operator true(in Optional<T>)

Checks whether the container has value.

Declaration

public static bool operator true(in Optional<T> optional)

Parameters

Type	Name	Description
Optional<T>	optional

Returns

Type	Description
bool	true if this container has value; otherwise, false.

Explicit Interface Implementations

implicit operator Optional<T>(T?)

Wraps value into Optional container.

Declaration

static implicit operator Optional<T>(T? value)

Parameters

Type	Name	Description
T	value	The value to convert.

Returns

Type	Description
Optional<T>

Implements

IEquatable<T>

IEquatable<T>

IStructuralEquatable

IOptionMonad<T, TSelf>

IOptionMonad<T>

ISupplier<TResult>

IFunctional

Extension Methods

BasicExtensions.IsBetween<T, TLowerBound, TUpperBound>(T, TLowerBound, TUpperBound)

BasicExtensions.IsOneOf<T>(T, params ReadOnlySpan<T>)

Enumerator.Skip<TEnumerator, T>(ref TEnumerator, int)

Optional.Coalesce<T>(in Optional<T>, in Optional<T>)