Struct Result<T, TErr>

Result<T, TErr> is used to return the result of an operation that might fail, without throwing an exception. Either IsOk(out T) will return true and the contained result value, or else IsErr(out TErr) will return true and the contained error value.

Implements

IEquatable<Result<T, TErr>>

IComparable<Result<T, TErr>>

ISpanFormattable

IFormattable

Inherited Members

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Namespace: RustyOptions

Assembly: RustyOptions.dll

Syntax

[Serializable]
[JsonConverter(typeof(ResultJsonConverter))]
public readonly struct Result<T, TErr> : IEquatable<Result<T, TErr>>, IComparable<Result<T, TErr>>, ISpanFormattable, IFormattable where T : notnull

Type Parameters

Name	Description
T	The type of the return value.
TErr	The type of the error value.

Constructors

Result(T)

Initializes a Result<T, TErr> in the Ok state containing the given value.

Declaration

public Result(T value)

Parameters

Type	Name	Description
T	value	The value to contain.

Exceptions

Type	Condition
ArgumentNullException	Thrown if the given value is null.

Result(TErr)

Initializes a Result<T, TErr> in the Err state containing the given error value.

Declaration

public Result(TErr error)

Parameters

Type	Name	Description
TErr	error	The error value to store.

Exceptions

Type	Condition
ArgumentNullException	Thrown if the given error is null.

Methods

AsEnumerable()

Returns an IEnumerable<T> containing either zero or one value, depending on whether the result is Err or Ok.

Declaration

public IEnumerable<T> AsEnumerable()

Returns

Type	Description
IEnumerable<T>	An enumerable containing the result's value, or an empty enumerable. Error values are omitted.

AsSpan()

Converts the result into a ReadOnlySpan<T> that contains either zero or one items depending on whether the result is Err or Ok.

Declaration

public ReadOnlySpan<T> AsSpan()

Returns

Type	Description
ReadOnlySpan<T>	A span containing the result's value, or an empty span. Error values are omitted.

CompareTo(Result<T, TErr>)

Compares the current instance with another object of the same type and returns an integer that indicates whether the current instance precedes, follows, or occurs in the same position in the sort order as the other object.

Ok compares as less than any Err, while two Ok or two Err compare as their contained values would in T or TErr, respectively.

Declaration

public int CompareTo(Result<T, TErr> other)

Parameters

Type	Name	Description
Result<T, TErr>	other

Returns

Type	Description
int	-1 if this instance precendes other, 0 if they are equal, and 1 if this instance follows other.

Equals(Result<T, TErr>)

Indicates whether the current object is equal to another object.

Declaration

public bool Equals(Result<T, TErr> other)

Parameters

Type	Name	Description
Result<T, TErr>	other	An object to compare with this object.

Returns

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

Equals(object?)

Indicates whether the current object is equal to another object.

Declaration

public override bool Equals(object? obj)

Parameters

Type	Name	Description
object	obj	An object to compare with this object.

Returns

Type	Description
bool	true if the current object is equal to the obj parameter; otherwise, false.

Overrides

ValueType.Equals(object)

Expect(string)

Returns the contained value if the result is Ok. Otherwise, throws an InvalidOperationException with the given message.

Note: if the Err is Exception it will be contained as an inner exception. Otherwise, the Err value will be converted to a string and included in the exception message.

Because this function may throw an exception, its use is generally discouraged. Instead, prefer to use Match<T2>(Func<T, T2>, Func<TErr, T2>) and handle the Err case explicitly, or call UnwrapOr<T, TErr>(Result<T, TErr>, T) or UnwrapOrElse(Func<TErr, T>).

Declaration

public T Expect(string message)

Parameters

Type	Name	Description
string	message

Returns

Type	Description
T	The value inside the result, if the result is Ok.

Exceptions

Type	Condition
InvalidOperationException	Thrown if the result is in the error state.

ExpectErr(string)

Returns the contained Err value, or throws an InvalidOperationException.

Declaration

public TErr ExpectErr(string message)

Parameters

Type	Name	Description
string	message	The message for the thrown exception, if any.

Returns

Type	Description
TErr	The contained Err value.

Exceptions

Type	Condition
InvalidOperationException	Thrown when the result is in the Ok state.

GetEnumerator()

Returns an enumerator for the option.

Declaration

public IEnumerator<T> GetEnumerator()

Returns

Type	Description
IEnumerator<T>	The enumerator.

GetHashCode()

Retrieves the hash code of the object contained by the Result<T, TErr>, if any.

Declaration

public override int GetHashCode()

Returns

Type	Description
int	The hash code of the object returned by the IsOk(out T) method, or IsErr(out TErr), whichever method returns true.

Overrides

ValueType.GetHashCode()

IsErr(out TErr)

Returnd true if the result is in the Err state, and error will contain the error value.

NOTE: While in most cases error will be non-null when this method returns true, a default instance of this struct will be in the Err state, but the err value will be the default value for TErr, and therefore possibly null.

Declaration

public bool IsErr(out TErr error)

Parameters

Type	Name	Description
TErr	error	The returned error value, if any.

Returns

Type	Description
bool

IsOk(out T)

Returns true if the result is in the Ok state, and value will contain the return value.

Declaration

public bool IsOk(out T value)

Parameters

Type	Name	Description
T	value	The returned value, if any.

Returns

Type	Description
bool

Match(Action<T>, Action<TErr>)

Calls the onOk with the Ok value, or calls onErr with the Err value, as appropriate.

Declaration

public void Match(Action<T> onOk, Action<TErr> onErr)

Parameters

Type	Name	Description
Action<T>	onOk	The function to pass the value to, if the result is Ok.
Action<TErr>	onErr	The function to pass the error value to, if the result is Err.

Exceptions

Type	Condition
ArgumentNullException	Thrown if either onOk or onErr is null.

Match<T2>(Func<T, T2>, Func<TErr, T2>)

Returns the result of executing the onOk or onErr functions, depending on the state of the Result<T, TErr>.

Declaration

public T2 Match<T2>(Func<T, T2> onOk, Func<TErr, T2> onErr)

Parameters

Type	Name	Description
Func<T, T2>	onOk	The function to pass the value to, if the result is Ok.
Func<TErr, T2>	onErr	The function to pass the error value to, if the result is Err.

Returns

Type	Description
T2	The value returned by the called function.

Type Parameters

Name	Description
T2	The return type of the given functions.

Exceptions

Type	Condition
ArgumentNullException	Thrown if either onOk or onErr is null.

ToString()

Returns the text representation of the value of the current Result<T, TErr> object.

Declaration

public override string ToString()

Returns

Type	Description
string	The text representation of the value of the current Result<T, TErr> object.

Overrides

ValueType.ToString()

ToString(string?, IFormatProvider?)

Formats the value of the current Result<T, TErr> using the specified format.

Declaration

public string ToString(string? format, IFormatProvider? formatProvider)

Parameters

Type	Name	Description
string	format	The format to use, or a null reference to use the default format defined for the type of the contained value.
IFormatProvider	formatProvider	The provider to use to format the value, or a null reference to obtain the format information from the current locale setting of the operating system.

Returns

Type	Description
string	The value of the current instance in the specified format.

TryFormat(Span<char>, out int, ReadOnlySpan<char>, IFormatProvider?)

Tries to format the value of the current instance into the provided span of characters.

Declaration

public bool TryFormat(Span<char> destination, out int charsWritten, ReadOnlySpan<char> format, IFormatProvider? provider)

Parameters

Type	Name	Description
Span<char>	destination	The span in which to write this instance's value formatted as a span of characters.
int	charsWritten	When this method returns, contains the number of characters that were written in destination.
ReadOnlySpan<char>	format	A span containing the characters that represent a standard or custom format string that defines the acceptable format for destination.
IFormatProvider	provider	An optional object that supplies culture-specific formatting information for destination.

Returns

Type	Description
bool	true if the formatting was successful; otherwise, false.

Unwrap()

Returns the contained value if the result is Ok. Otherwise, throws an InvalidOperationException.

Note: if the Err is Exception it will be contained as an inner exception. Otherwise, the Err value will be converted to a string and included in the exception message.

Because this function may throw an exception, its use is generally discouraged. Instead, prefer to use Match<T2>(Func<T, T2>, Func<TErr, T2>) and handle the Err case explicitly, or call UnwrapOr<T, TErr>(Result<T, TErr>, T) or UnwrapOrElse(Func<TErr, T>).

Declaration

public T Unwrap()

Returns

Type	Description
T	The value inside the result, if the result is Ok.

Exceptions

Type	Condition
InvalidOperationException	Thrown if the result is in the error state.

UnwrapErr()

Returns the contained Err value, or throws an InvalidOperationException.

Declaration

public TErr UnwrapErr()

Returns

Type	Description
TErr	The contained Err value.

Exceptions

Type	Condition
InvalidOperationException	Thrown when the result is in the Ok state.

UnwrapOrElse(Func<TErr, T>)

Returns the contained Ok value or computes it from the provided elseFunction.

Declaration

public T UnwrapOrElse(Func<TErr, T> elseFunction)

Parameters

Type	Name	Description
Func<TErr, T>	elseFunction	The function that computes the returned value from the Err value.

Returns

Type	Description
T	The contained Ok value or the value returned by elseFunction.

Exceptions

Type	Condition
ArgumentNullException	Thrown if elseFunction is null.

Operators

operator ==(Result<T, TErr>, Result<T, TErr>)

Determines whether one Result is equal to another Result.

Declaration

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

Parameters

Type	Name	Description
Result<T, TErr>	left	The first Result to compare.
Result<T, TErr>	right	The second Result to compare.

Returns

Type	Description
bool	true if the two values are equal.

operator >(Result<T, TErr>, Result<T, TErr>)

Determines whether one Result is greater than another Result.

Ok compares as less than any Err, while two Ok or two Err compare as their contained values would in T or TErr, respectively.

Declaration

public static bool operator >(Result<T, TErr> left, Result<T, TErr> right)

Parameters

Type	Name	Description
Result<T, TErr>	left	The first Result to compare.
Result<T, TErr>	right	The second Result to compare.

Returns

Type	Description
bool	true if the left parameter is greater than the right parameter.

operator >=(Result<T, TErr>, Result<T, TErr>)

Determines whether one Result is greater than or equal to another Result.

Ok compares as less than any Err, while two Ok or two Err compare as their contained values would in T or TErr, respectively.

Declaration

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

Parameters

Type	Name	Description
Result<T, TErr>	left	The first Result to compare.
Result<T, TErr>	right	The second Result to compare.

Returns

Type	Description
bool	true if the left parameter is greater than or equal to the right parameter.

operator !=(Result<T, TErr>, Result<T, TErr>)

Determines whether one Result is not equal to another Result.

Declaration

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

Parameters

Type	Name	Description
Result<T, TErr>	left	The first Result to compare.
Result<T, TErr>	right	The second Result to compare.

Returns

Type	Description
bool	true if the two values are not equal.

operator <(Result<T, TErr>, Result<T, TErr>)

Determines whether one Result is less than another Result.

Ok compares as less than any Err, while two Ok or two Err compare as their contained values would in T or TErr, respectively.

Declaration

public static bool operator <(Result<T, TErr> left, Result<T, TErr> right)

Parameters

Type	Name	Description
Result<T, TErr>	left	The first Result to compare.
Result<T, TErr>	right	The second Result to compare.

Returns

Type	Description
bool	true if the left parameter is less than the right parameter.

operator <=(Result<T, TErr>, Result<T, TErr>)

Determines whether one Result is less than or equal to another Result.

Ok compares as less than any Err, while two Ok or two Err compare as their contained values would in T or TErr, respectively.

Declaration

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

Parameters

Type	Name	Description
Result<T, TErr>	left	The first Result to compare.
Result<T, TErr>	right	The second Result to compare.

Returns

Type	Description
bool	true if the left parameter is less than or equal to the right parameter.

Implements

IEquatable<T>

IComparable<T>

ISpanFormattable

IFormattable

Extension Methods

ResultAsyncExtensions.AndThenAsync<T1, T2, TErr>(Result<T1, TErr>, Func<T1, Task<Result<T2, TErr>>>)

ResultAsyncExtensions.AndThenAsync<T1, T2, TErr>(Result<T1, TErr>, Func<T1, ValueTask<Result<T2, TErr>>>)

ResultAsyncExtensions.MapAsync<T1, T2, TErr>(Result<T1, TErr>, Func<T1, Task<T2>>)

ResultAsyncExtensions.MapAsync<T1, T2, TErr>(Result<T1, TErr>, Func<T1, ValueTask<T2>>)

ResultAsyncExtensions.MapOrElseAsync<T1, T2, TErr>(Result<T1, TErr>, Func<T1, Task<T2>>, Func<TErr, Task<T2>>)

ResultAsyncExtensions.MapOrElseAsync<T1, T2, TErr>(Result<T1, TErr>, Func<T1, ValueTask<T2>>, Func<TErr, ValueTask<T2>>)

ResultAsyncExtensions.OrElseAsync<T, T1Err, T2Err>(Result<T, T1Err>, Func<T1Err?, Task<Result<T, T2Err>>>)

ResultAsyncExtensions.OrElseAsync<T, T1Err, T2Err>(Result<T, T1Err>, Func<T1Err?, ValueTask<Result<T, T2Err>>>)

OptionExtensions.None<T>(T)

OptionExtensions.Some<T>(T)

OptionResultExtensions.Err<T, TErr>(Result<T, TErr>)

OptionResultExtensions.Ok<T, TErr>(Result<T, TErr>)

ResultExtensions.AndThen<T1, T2, TErr>(Result<T1, TErr>, Func<T1, Result<T2, TErr>>)

ResultExtensions.And<T1, T2, TErr>(Result<T1, TErr>, Result<T2, TErr>)

ResultExtensions.MapErr<T, T1Err, T2Err>(Result<T, T1Err>, Func<T1Err, T2Err>)

ResultExtensions.MapOrElse<T1, T2, TErr>(Result<T1, TErr>, Func<T1, T2>, Func<TErr, T2>)

ResultExtensions.MapOr<T1, T2, TErr>(Result<T1, TErr>, Func<T1, T2>, T2)

ResultExtensions.Map<T1, T2, TErr>(Result<T1, TErr>, Func<T1, T2>)

ResultExtensions.OrElse<T, T1Err, T2Err>(Result<T, T1Err>, Func<T1Err, Result<T, T2Err>>)

ResultExtensions.Or<T, T1Err, T2Err>(Result<T, T1Err>, Result<T, T2Err>)

ResultExtensions.UnwrapOr<T, TErr>(Result<T, TErr>, T)