Struct Maybe<T>

Namespace

Trellis

Assembly

Trellis.Results.dll

Represents domain-level optionality — a value that was either provided or intentionally omitted. Unlike Nullable<T> (value types only) or T? (annotation only for reference types), Maybe<T> is a real generic type that works uniformly with both value and reference types and composes with Result<TValue> pipelines.

public readonly struct Maybe<T> : IEquatable<T>, IEquatable<Maybe<T>> where T : notnull

Type Parameters

T

The type of the optional value. Must be a non-null type.

Implements

IEquatable<T>

IEquatable<Maybe<T>>

Inherited Members

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Extension Methods

MaybeExtensions.ToResult<TValue>(TValue)

MaybeExtensions.ToResult<TValue>(in Maybe<TValue>, Func<Error>)

MaybeExtensions.ToResult<TValue>(in Maybe<TValue>, Error)

MaybeLinqExtensions.SelectMany<TSource, TCollection, TResult>(Maybe<TSource>, Func<TSource, Maybe<TCollection>>, Func<TSource, TCollection, TResult>)

MaybeLinqExtensions.Select<TIn, TOut>(Maybe<TIn>, Func<TIn, TOut>)

Examples

// Create a Maybe with a value
Maybe<string> name = Maybe.From("John");
if (name.HasValue) Console.WriteLine(name.Value);

// Create an empty Maybe
Maybe<string> noName = Maybe.None<string>();
string result = noName.GetValueOrDefault("Default");

// Transform optional values
Maybe<string> upper = name.Map(v => v.ToUpper());

// Consume with pattern matching
string display = name.Match(v => $"Hello, {v}!", () => "Hello, stranger!");

Properties

HasNoValue

Gets a value indicating whether this instance contains no value.

public bool HasNoValue { get; }

Property Value

bool

True if no value is present; otherwise false.

Remarks

This is the logical inverse of HasValue. Use whichever makes your code more readable.

HasValue

Gets a value indicating whether this instance contains a value.

public bool HasValue { get; }

Property Value

bool

True if a value is present; otherwise false.

None

Gets a Maybe<T> instance with no value.

[SuppressMessage("Design", "CA1000:Do not declare static members on generic types", Justification = "Maybe<T>.None is the idiomatic way to express 'no value' for a specific Maybe type.")]
public static Maybe<T> None { get; }

Property Value

Maybe<T>

Value

Gets the underlying value if present; otherwise throws an exception.

public T Value { get; }

Property Value

T

The underlying value of type T.

Remarks

Always check HasValue before accessing this property, or use GetValueOrDefault(T) instead.

Exceptions

InvalidOperationException

Thrown when HasValue is false.

Methods

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

Projects the value inside a Maybe<T> into a new Maybe<T> using the specified function. If no value is present, returns None.

public Maybe<TResult> Bind<TResult>(Func<T, Maybe<TResult>> selector) where TResult : notnull

Parameters

selector Func<T, Maybe<TResult>>

The function to apply to the value, returning a new Maybe.

Returns

Maybe<TResult>

The result of the selector if this instance has a value; otherwise None.

Type Parameters

TResult

The type of the projected value.

Exceptions

ArgumentNullException

Thrown when selector is null.

Equals(object?)

Indicates whether this instance and a specified object are equal.

public override bool Equals(object? obj)

Parameters

obj object

The object to compare with the current instance.

Returns

bool

true if obj and this instance are the same type and represent the same value; otherwise, false.

Equals(Maybe<T>)

Indicates whether the current object is equal to another object of the same type.

public bool Equals(Maybe<T> other)

Parameters

other Maybe<T>

An object to compare with this object.

Returns

bool

true if the current object is equal to the other parameter; otherwise, false.

Equals(T?)

Indicates whether the current object is equal to another object of the same type.

public bool Equals(T? other)

Parameters

other T

An object to compare with this object.

Returns

bool

true if the current object is equal to the other parameter; otherwise, false.

From(T?)

Creates a new Maybe<T> from a value. If the value is null, creates an empty Maybe.

[SuppressMessage("Design", "CA1000:Do not declare static members on generic types", Justification = "Maybe<T>.From(value) mirrors Maybe<T>.None for a symmetric API.")]
public static Maybe<T> From(T? value)

Parameters

value T

The value to wrap. If null, returns None.

Returns

Maybe<T>

A Maybe<T> with the value, or None if null.

GetHashCode()

Returns the hash code for this instance.

public override int GetHashCode()

Returns

int

A 32-bit signed integer that is the hash code for this instance.

GetValueOrDefault(Func<T>)

Gets the underlying value if present, otherwise evaluates and returns the result of the specified factory.

public T GetValueOrDefault(Func<T> defaultFactory)

Parameters

defaultFactory Func<T>

The factory to evaluate when HasValue is false.

Returns

T

The underlying value or the result of defaultFactory.

Exceptions

ArgumentNullException

Thrown when defaultFactory is null.

GetValueOrDefault(T)

Gets the underlying value if present, otherwise returns the specified default value.

public T GetValueOrDefault(T defaultValue)

Parameters

defaultValue T

The value to return when HasValue is false.

Returns

T

The underlying value or defaultValue.

Remarks

This is the recommended way to safely extract values from Maybe.

GetValueOrThrow(string?)

Gets the underlying value if present, otherwise throws an exception.

public T GetValueOrThrow(string? errorMessage = null)

Parameters

errorMessage string

Optional custom error message to use when throwing.

Returns

T

The underlying value of type T.

Remarks

Prefer GetValueOrDefault(T) or TryGetValue(out T) to avoid exceptions.

Exceptions

InvalidOperationException

Thrown when HasValue is false.

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

Transforms the value inside a Maybe<T> using the specified function. If no value is present, returns None.

public Maybe<TResult> Map<TResult>(Func<T, TResult> selector) where TResult : notnull

Parameters

selector Func<T, TResult>

The function to apply to the value.

Returns

Maybe<TResult>

A Maybe containing the transformed value, or None if this instance has no value.

Type Parameters

TResult

The type of the transformed value.

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

Pattern matches on the Maybe, calling some if a value is present or none if no value is present.

public TResult Match<TResult>(Func<T, TResult> some, Func<TResult> none)

Parameters

some Func<T, TResult>

The function to call when a value is present.

none Func<TResult>

The function to call when no value is present.

Returns

TResult

The result of the matched function.

Type Parameters

TResult

The return type of the match.

Or(Func<Maybe<T>>)

Returns this Maybe<T> if it has a value; otherwise evaluates the factory and returns its result.

public Maybe<T> Or(Func<Maybe<T>> fallbackFactory)

Parameters

fallbackFactory Func<Maybe<T>>

The factory to evaluate when no value is present.

Returns

Maybe<T>

This instance if it has a value; otherwise the factory result.

Exceptions

ArgumentNullException

Thrown when fallbackFactory is null.

Or(Func<T>)

Returns this Maybe<T> if it has a value; otherwise evaluates the factory and returns a Maybe containing its result.

public Maybe<T> Or(Func<T> fallbackFactory)

Parameters

fallbackFactory Func<T>

The factory to evaluate when no value is present.

Returns

Maybe<T>

This instance if it has a value; otherwise a Maybe containing the factory result.

Exceptions

ArgumentNullException

Thrown when fallbackFactory is null.

Or(Maybe<T>)

Returns this Maybe<T> if it has a value; otherwise returns the specified fallback Maybe.

public Maybe<T> Or(Maybe<T> fallback)

Parameters

fallback Maybe<T>

The fallback Maybe to return when no value is present.

Returns

Maybe<T>

This instance if it has a value; otherwise fallback.

Or(T)

Returns this Maybe<T> if it has a value; otherwise returns a Maybe containing the specified fallback value.

public Maybe<T> Or(T fallback)

Parameters

fallback T

The fallback value to use when no value is present.

Returns

Maybe<T>

This instance if it has a value; otherwise a Maybe containing fallback.

Tap(Action<T>)

Executes a side effect on the value if present, then returns this Maybe<T> unchanged.

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

Parameters

action Action<T>

The action to execute on the value.

Returns

Maybe<T>

This instance unchanged.

Exceptions

ArgumentNullException

Thrown when action is null.

ToString()

Returns the fully qualified type name of this instance.

public override string ToString()

Returns

string

The fully qualified type name.

TryGetValue(out T)

Attempts to get the underlying value without throwing an exception.

public bool TryGetValue(out T value)

Parameters

value T

When this method returns true, contains the underlying value; otherwise, the default value for type T.

Returns

bool

True if a value is present; otherwise false.

Remarks

Similar to the TryParse pattern in .NET, this provides a safe way to check for and retrieve values.

Where(Func<T, bool>)

Filters this Maybe<T> by applying a predicate to the value. Returns None if the predicate fails or if this instance has no value.

public Maybe<T> Where(Func<T, bool> predicate)

Parameters

predicate Func<T, bool>

The condition to test the value against.

Returns

Maybe<T>

This instance if the predicate passes; otherwise None.

Exceptions

ArgumentNullException

Thrown when predicate is null.

Operators

operator ==(Maybe<T>, object?)

Determines whether a Maybe<T> equals another object.

public static bool operator ==(Maybe<T> maybe, object? other)

Parameters

maybe Maybe<T>

The Maybe instance to compare.

other object

The object to compare against.

Returns

bool

True if equal; otherwise false.

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

Determines whether two Maybe<T> instances are equal.

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

Parameters

first Maybe<T>

The first Maybe instance.

second Maybe<T>

The second Maybe instance.

Returns

bool

True if both have no value, or both have equal values; otherwise false.

operator ==(Maybe<T>, T)

Determines whether a Maybe<T> equals a value of type T.

public static bool operator ==(Maybe<T> maybe, T value)

Parameters

maybe Maybe<T>

The Maybe instance to compare.

value T

The value to compare against.

Returns

bool

True if the Maybe has a value equal to value; otherwise false.

implicit operator Maybe<T>(T)

Implicitly converts a value of type T to a Maybe<T>.

public static implicit operator Maybe<T>(T value)

Parameters

value T

The value to wrap.

Returns

Maybe<T>

A Maybe containing the value.

operator !=(Maybe<T>, object?)

Determines whether a Maybe<T> does not equal another object.

public static bool operator !=(Maybe<T> maybe, object? other)

Parameters

maybe Maybe<T>

The Maybe instance to compare.

other object

The object to compare against.

Returns

bool

True if not equal; otherwise false.

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

Determines whether two Maybe<T> instances are not equal.

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

Parameters

first Maybe<T>

The first Maybe instance.

second Maybe<T>

The second Maybe instance.

Returns

bool

True if the instances are not equal; otherwise false.

operator !=(Maybe<T>, T)

Determines whether a Maybe<T> does not equal a value of type T.

public static bool operator !=(Maybe<T> maybe, T value)

Parameters

maybe Maybe<T>

The Maybe instance to compare.

value T

The value to compare against.

Returns

bool

True if the Maybe does not have a value equal to value; otherwise false.