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)

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.

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

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.

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(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<T>().

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.

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.

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.