diff --git a/gitbook/result/others.md b/gitbook/result/others.md index ccb530cd..4af72e47 100644 --- a/gitbook/result/others.md +++ b/gitbook/result/others.md @@ -71,6 +71,16 @@ Returns the contained value if Ok, otherwise returns the provided value 'a -> Result<'a, 'b> -> 'a ``` +## defaultError + +Returns the contained value if Error, otherwise returns the provided value + +### Function Signature + +```fsharp +'b -> Result<'a, 'b> -> 'b +``` + ## defaultWith Returns the contained value if Ok, otherwise evaluates the given function and returns the result. @@ -92,6 +102,15 @@ Returns the Ok value or runs the specified function over the error value. ('b -> 'a) -> Result<'a, 'b> -> 'a ``` +## ignore + +Ignores the value of the input result and returns unit instead + +### Function Signature + +```fsharp +Result<'ok, 'error> -> Result +``` ## ignoreError diff --git a/src/FsToolkit.ErrorHandling/Option.fs b/src/FsToolkit.ErrorHandling/Option.fs index 681e3abc..5731a364 100644 --- a/src/FsToolkit.ErrorHandling/Option.fs +++ b/src/FsToolkit.ErrorHandling/Option.fs @@ -5,6 +5,8 @@ module Option = /// /// Binds a function to an option, applying the function to the value if the option is Some. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/option/bind /// /// The function to apply to the value. /// The input option. @@ -21,6 +23,8 @@ module Option = /// /// Applies a mapper function to the value inside an option, returning a new option with the mapped value. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/option/map /// /// The function to apply to the value inside the option. /// The input option. @@ -35,6 +39,8 @@ module Option = /// /// Applies a mapper function to the values inside two options, returning a new option with the mapped value. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/option/map2 /// /// The function to apply to the values inside the options. /// The first input option. @@ -51,6 +57,8 @@ module Option = /// /// Applies a mapper function to the values inside three options, returning a new option with the mapped value. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/option/map3 /// /// The function to apply to the values inside the options. /// The first input option. @@ -79,6 +87,8 @@ module Option = /// /// Converts a value option to a regular option. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/option/transforms/ofvalueoption /// /// The value option to convert. /// The converted regular option. @@ -89,6 +99,8 @@ module Option = /// /// Converts an option value to a value option. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/option/transforms/tovalueoption /// /// The option value to convert. /// A value option. @@ -162,6 +174,8 @@ module Option = /// /// Takes two options and returns a tuple of the pair or None if either are None + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/option/zip /// /// The input option /// The input option @@ -173,6 +187,8 @@ module Option = /// /// Converts a Result to an option. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/option/transforms/ofresult /// /// The result to convert. /// An option containing the value if the result is Ok, or None if the result is Error @@ -187,6 +203,8 @@ module Option = /// This is different from Option.ofObj where it doesn't require the value to be constrained to null. /// This is beneficial where third party APIs may generate a record type using reflection and it can be null. /// See Null-checking considerations in F# for more details. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/option/transforms/ofnull /// /// The potentially null value /// An option @@ -202,6 +220,8 @@ module Option = /// bindNull binder option evaluates to match option with None -> None | Some x -> binder x |> Option.ofNull /// /// Automatically onverts the result of binder that is pontentially null into an option. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/option/bindnull /// /// A function that takes the value of type 'value from an option and transforms it into /// a value of type 'nullableValue. @@ -222,6 +242,8 @@ module Option = /// /// Returns result of running if it is Some, otherwise returns result of running + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/option/either /// /// The function to run if is Some /// The function to run if is None @@ -240,6 +262,8 @@ module Option = /// /// If the option is Some, executes the function on the Some value and passes through the input value. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/option/teefunctions#teesome /// /// The function to execute on the Some value. /// The input option. @@ -253,6 +277,8 @@ module Option = /// /// If the option is None, executes the function and passes through the input value. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/option/teefunctions#teenone /// /// The function to execute if the input is None. /// The input option. @@ -267,6 +293,8 @@ module Option = /// /// If the result is Some and the predicate returns true, executes the function /// on the Some value and passes through the input value. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/option/teefunctions#teeif /// /// The predicate to execute on the Some value. /// The function to execute on the Some value if the predicate proves true @@ -289,6 +317,8 @@ module Option = /// Creates an option from a boolean value and a value of type 'a. /// If the boolean value is true, returns Some value. /// If the boolean value is false, returns None. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/option/transforms/ofpair /// /// A tuple containing a boolean value and a value of type 'a. /// An option value. diff --git a/src/FsToolkit.ErrorHandling/Result.fs b/src/FsToolkit.ErrorHandling/Result.fs index d08b6b19..2ced74d4 100644 --- a/src/FsToolkit.ErrorHandling/Result.fs +++ b/src/FsToolkit.ErrorHandling/Result.fs @@ -3,6 +3,14 @@ namespace FsToolkit.ErrorHandling [] module Result = + /// + /// Applies a transformation to the value of a Result to a new value using the specified mapper function. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/map + /// + /// The function to apply to the value of the Result if it is Ok. + /// The Result to map. + /// A new Resultwith the mapped value if the input Result is Ok, otherwise the original Error. let inline map ([] mapper: 'okInput -> 'okOutput) (input: Result<'okInput, 'error>) @@ -11,6 +19,14 @@ module Result = | Ok x -> Ok(mapper x) | Error e -> Error e + /// + /// Maps the error value of a Resultto a new error value using the specified error mapper function. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/maperror + /// + /// The function that maps the input error value to the output error value. + /// The Resultvalue to map the error value of. + /// A new Resultwith the same Ok value and the mapped error value. let inline mapError ([] errorMapper: 'errorInput -> 'errorOutput) (input: Result<'ok, 'errorInput>) @@ -19,6 +35,17 @@ module Result = | Ok x -> Ok x | Error e -> Error(errorMapper e) + /// + /// Takes a transformation function and applies it to the Result if it is Ok. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/bind + /// + /// The transformation function + /// The input result + /// The type of the successful result. + /// The type of the result after binding. + /// The type of the error. + /// Returns a new Result if the input is Ok, otherwise returns the original Result let inline bind ([] binder: 'okInput -> Result<'okOutput, 'error>) (input: Result<'okInput, 'error>) @@ -27,16 +54,39 @@ module Result = | Ok x -> binder x | Error e -> Error e + /// + /// Determines whether the specified Result is in a successful state. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/others#isok + /// + /// The result to check. + /// True if the result is in a successful state; otherwise, false. let inline isOk (value: Result<'ok, 'error>) : bool = match value with | Ok _ -> true | Error _ -> false + /// + /// Determines whether the specified Result is an error. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/others#iserror + /// + /// The result to check. + /// True if the result is an error; otherwise, false. let inline isError (value: Result<'ok, 'error>) : bool = match value with | Ok _ -> false | Error _ -> true + /// + /// Applies the appropriate function based on the result of the input. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/eitherfunctions#result.either + /// + /// The function to apply if the input is Ok + /// The function to apply if the input is Error + /// The input result + /// The result of applying the appropriate function. let inline either ([] onOk: 'okInput -> 'output) ([] onError: 'errorInput -> 'output) @@ -46,6 +96,15 @@ module Result = | Ok x -> onOk x | Error err -> onError err + /// + /// Maps the values of a Result to a new Result using the provided functions. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/eitherfunctions#result.eithermap + /// + /// The function to apply to the 'ok' value of the input Result. + /// The function to apply to the 'error' value of the input Result. + /// The input Resultto map. + /// A new Result with the mapped values. let inline eitherMap ([] onOk: 'okInput -> 'okOutput) ([] onError: 'errorInput -> 'errorOutput) @@ -55,6 +114,14 @@ module Result = | Ok x -> Ok(onOk x) | Error err -> Error(onError err) + /// + /// Combines two Result values and returns a new Result value. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/apply + /// + /// The Resultcontaining the function to apply. + /// The Resultcontaining the input to apply the function to. + /// A Resultcontaining the output of applying the function to the input, or an Error if either Resultis an Error let inline apply (applier: Result<'okInput -> 'okOutput, 'error>) (input: Result<'okInput, 'error>) @@ -64,6 +131,15 @@ module Result = | Error e, _ | _, Error e -> Error e + /// + /// Applies a mapper function to two input Results, producing a new Result. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/map2 + /// + /// The function to apply to the inputs. + /// The first input Result. + /// The second input Result. + /// A new Resultcontaining the output of the mapper function if both input Results are Ok, otherwise an Error Result. let inline map2 ([] mapper: 'okInput1 -> 'okInput2 -> 'okOutput) (input1: Result<'okInput1, 'error>) @@ -74,7 +150,16 @@ module Result = | Error e, _ | _, Error e -> Error e - + /// + /// Applies a mapper function to three input Results, producing a new Result. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/map3 + /// + /// The function to apply to the input results. + /// The first input result. + /// The second input result. + /// The third input result. + /// A new Result with the output of the mapper function applied to the input results, if all Results are Ok, otherwise returns the original Error let inline map3 ([] mapper: 'okInput1 -> 'okInput2 -> 'okInput3 -> 'okOutput) (input1: Result<'okInput1, 'error>) @@ -87,11 +172,26 @@ module Result = | _, Error e, _ | _, _, Error e -> Error e + /// + /// Converts a Choice to a Result + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/transforms/ofchoice + /// + /// The Choice value to convert. + /// A Result matching the types of the input Choice let inline ofChoice (input: Choice<'ok, 'error>) : Result<'ok, 'error> = match input with | Choice1Of2 x -> Ok x | Choice2Of2 e -> Error e + /// + /// Calls a TryCreate member function on a value passed in, returning a Result containing the value or an error tuple + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/trycreate + /// + /// The name of the field + /// The value to create a result from. + /// A Result containing the value or an error tuple of the field name and the original error type let inline tryCreate (fieldName: string) (x: 'a) : Result< ^b, (string * 'c) > = let tryCreate' x = (^b: (static member TryCreate: 'a -> Result< ^b, 'c >) x) @@ -99,9 +199,10 @@ module Result = tryCreate' x |> mapError (fun z -> (fieldName, z)) - /// /// Returns if it is Ok, otherwise returns + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/orelsefunctions#result.orelse /// /// The value to use if is Error /// The input result. @@ -124,11 +225,12 @@ module Result = : Result<'ok, 'errorOutput> = match result with | Ok x -> Ok x - | Error e -> ifError - + | Error _ -> ifError /// /// Returns if it is Ok, otherwise executes and returns the result. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/orelsefunctions#result.orelsewith /// /// A function that provides an alternate result when evaluated. /// The input result. @@ -154,53 +256,115 @@ module Result = | Ok x -> Ok x | Error e -> ifErrorFunc e - /// Replaces the wrapped value with unit + /// + /// Ignores the value of a Result and returns a new Result with unit as the success value. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/others#ignore + /// + /// The Result to ignore. + /// A new Result with unit as the success value. let inline ignore<'ok, 'error> (result: Result<'ok, 'error>) : Result = match result with | Ok _ -> Ok() | Error e -> Error e - /// Returns the specified error if the value is false. + /// + /// Requires a boolean value to be true, otherwise returns an error result. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/requirefunctions#requiretrue + /// + /// The error value to return if the condition is false. + /// The boolean value to check. + /// An Ok result if the condition is true, otherwise an Error result with the specified error value. let inline requireTrue (error: 'error) (value: bool) : Result = if value then Ok() else Error error - /// Returns the specified error if the value is true. + /// + /// Requires a boolean value to be false, otherwise returns an error result. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/requirefunctions#requirefalse + /// + /// The error value to return if the condition is true. + /// The boolean value to check. + /// An Ok result if the condition is false, otherwise an Error result with the specified error value. let inline requireFalse (error: 'error) (value: bool) : Result = if not value then Ok() else Error error - /// Converts an Option to a Result, using the given error if None. + /// + /// Requires a value to be Some, otherwise returns an error result. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/requirefunctions#requiresome + /// + /// The error value to return if the value is None. + /// The Option value to check. + /// An Ok result if the value is Some, otherwise an Error result with the specified error value. let inline requireSome (error: 'error) (option: 'ok option) : Result<'ok, 'error> = match option with | Some x -> Ok x | None -> Error error - /// Converts an Option to a Result, using the given error if Some. + /// + /// Requires a value to be None, otherwise returns an error result. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/requirefunctions#requirenone + /// + /// The error value to return if the value is Some. + /// The Option value to check. + /// An Ok result if the value is None, otherwise an Error result with the specified error value. let inline requireNone (error: 'error) (option: 'value option) : Result = match option with | Some _ -> Error error | None -> Ok() - /// Converts an ValueOption to a Result, using the given error if ValueNone. + /// + /// Requires a value to be ValueSome, otherwise returns an error result. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/requirefunctions#requirevaluesome + /// + /// The error value to return if the value is ValueNone. + /// The ValueOption value to check. + /// An Ok result if the value is ValueSome, otherwise an Error result with the specified error value. let inline requireValueSome (error: 'error) (voption: 'ok voption) : Result<'ok, 'error> = match voption with | ValueSome x -> Ok x | ValueNone -> Error error - /// Converts an ValueOption to a Result, using the given error if ValueSome. + /// + /// Requires a value to be ValueNone, otherwise returns an error result. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/requirefunctions#requirevaluenone + /// + /// The error value to return if the value is ValueSome. + /// The ValueOption value to check. + /// An Ok result if the value is ValueNone, otherwise an Error result with the specified error value. let inline requireValueNone (error: 'error) (voption: 'value voption) : Result = match voption with | ValueSome _ -> Error error | ValueNone -> Ok() - /// Converts a nullable value into a Result, using the given error if null + /// + /// Converts a nullable value into a Result, using the given error if null + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/requirefunctions#requirenotnull + /// + /// The error value to return if the value is null. + /// The nullable value to check. + /// An Ok result if the value is not null, otherwise an Error result with the specified error value. let inline requireNotNull (error: 'error) (value: 'ok) : Result<'ok, 'error> = match value with | null -> Error error | nonnull -> Ok nonnull - /// Returns Ok if the two values are equal, or the specified error if not. - /// Same as requireEqual, but with a signature that fits piping better than - /// normal function application. + /// + /// Returns Ok if the two values are equal, or the specified error if not. + /// Same as requireEqual, but with a signature that fits piping better than normal function application. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/requirefunctions#requireequalto + /// + /// The value to compare to. + /// The error value to return if the values are not equal. + /// The value to compare. + /// An Ok result if the values are equal, otherwise an Error result with the specified error value. let inline requireEqualTo (other: 'value) (error: 'error) @@ -208,52 +372,113 @@ module Result = : Result = if this = other then Ok() else Error error - /// Returns Ok if the two values are equal, or the specified error if not. - /// Same as requireEqualTo, but with a signature that fits normal function - /// application better than piping. + /// + /// Returns Ok if the two values are equal, or the specified error if not. + /// Same as requireEqualTo, but with a signature that fits normal function application better than piping. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/requirefunctions#requireequal + /// + /// The first value to compare. + /// The second value to compare. + /// The error value to return if the values are not equal. + /// An Ok result if the values are equal, otherwise an Error result with the specified error value. let inline requireEqual (x1: 'value) (x2: 'value) (error: 'error) : Result = if x1 = x2 then Ok() else Error error - /// Returns Ok if the sequence is empty, or the specified error if not. + /// + /// Returns Ok if the sequence is empty, or the specified error if not. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/requirefunctions#requireempty + /// + /// The error value to return if the sequence is not empty. + /// The sequence to check. + /// An Ok result if the sequence is empty, otherwise an Error result with the specified error value. let inline requireEmpty (error: 'error) (xs: #seq<'value>) : Result = if Seq.isEmpty xs then Ok() else Error error - /// Returns the specified error if the sequence is empty, or Ok if not. + /// + /// Returns Ok if the sequence is not empty, or the specified error if it is. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/requirefunctions#requirenotempty + /// + /// The error value to return if the sequence is empty. + /// The sequence to check. + /// An Ok result if the sequence is not empty, otherwise an Error result with the specified error value. let inline requireNotEmpty (error: 'error) (xs: #seq<'value>) : Result = if Seq.isEmpty xs then Error error else Ok() - /// Returns the first item of the sequence if it exists, or the specified - /// error if the sequence is empty + /// + /// Returns the first item of the sequence if it exists, or the specified error if the sequence is empty. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/requirefunctions#requirehead + /// + /// The error value to return if the sequence is empty. + /// The sequence to check. + /// An Ok result containing the first item of the sequence if it exists, otherwise an Error result with the specified error value. let inline requireHead (error: 'error) (xs: #seq<'ok>) : Result<'ok, 'error> = match Seq.tryHead xs with | Some x -> Ok x | None -> Error error + /// /// Replaces an error value with a custom error value. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/others#seterror + /// + /// The error value to replace the original error value with. + /// The input result. + /// A new Result with the same Ok value and the new error value. let inline setError (error: 'error) (result: Result<'ok, 'errorIgnored>) : Result<'ok, 'error> = result |> mapError (fun _ -> error) + /// /// Replaces a unit error value with a custom error value. Safer than setError /// since you're not losing any information. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/others#witherror + /// + /// The error value to replace the original error value with. + /// The input result. + /// A new Result with the same Ok value and the new error value. let inline withError (error: 'error) (result: Result<'ok, unit>) : Result<'ok, 'error> = result |> mapError (fun () -> error) - /// Returns the contained value if Ok, otherwise returns ifError. + /// + /// Returns the contained value if Ok, otherwise returns the provided value + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/others#defaultvalue + /// + /// The value to use if the result is Error. + /// The input result. + /// The contained value if Ok, otherwise . let inline defaultValue (ifError: 'ok) (result: Result<'ok, 'error>) : 'ok = match result with | Ok x -> x | Error _ -> ifError - // Returns the contained value if Error, otherwise returns ifOk. + /// + /// Returns the contained value if Error, otherwise returns the provided value + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/others#defaulterror + /// + /// The value to use if the result is Ok. + /// The input result. + /// The contained value if Error, otherwise . let inline defaultError (ifOk: 'error) (result: Result<'ok, 'error>) : 'error = match result with | Error error -> error | Ok _ -> ifOk - /// Returns the contained value if Ok, otherwise evaluates ifErrorThunk and - /// returns the result. + /// + /// Returns the contained value if Ok, otherwise evaluates and returns the value. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/others#defaultwith + /// + /// The function to evaluate if the result is Error. + /// The input result. + /// The contained value if Ok, otherwise the result of evaluating . let inline defaultWith ([] ifErrorThunk: 'error -> 'ok) (result: Result<'ok, 'error>) @@ -262,55 +487,88 @@ module Result = | Ok x -> x | Error e -> ifErrorThunk e - /// Same as defaultValue for a result where the Ok value is unit. The name + /// + /// Same as defaultValue for a result where the Ok value is unit. The name /// describes better what is actually happening in this case. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/others#ignoreerror + /// + /// The input result. + /// Unit if Ok, otherwise the provided value. let inline ignoreError<'error> (result: Result) : unit = defaultValue () result - /// If the result is Ok and the predicate returns true, executes the function - /// on the Ok value. Passes through the input value. + /// + /// If the result is Ok and the predicate returns true, executes the function on the Ok value. Passes through the input value. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/teefunctions#teeif + /// + /// The predicate to evaluate on the Ok value. + /// The function to execute on the Ok value if the predicate returns true. + /// The input result. + /// The input result. let inline teeIf ([] predicate: 'ok -> bool) - ([] inspector: 'ok -> unit) + ([] sideEffect: 'ok -> unit) (result: Result<'ok, 'error>) : Result<'ok, 'error> = match result with | Ok x -> if predicate x then - inspector x + sideEffect x | Error _ -> () result - /// If the result is Error and the predicate returns true, executes the - /// function on the Error value. Passes through the input value. + /// + /// If the result is Error and the predicate returns true, executes the + /// function on the Error value. Passes through the input value. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/teefunctions#teeerrorif + /// + /// The predicate to evaluate on the Error value. + /// The function to execute on the Error value if the predicate returns true. + /// The input result. + /// The input result. let inline teeErrorIf ([] predicate: 'error -> bool) - ([] inspector: 'error -> unit) + ([] sideEffect: 'error -> unit) (result: Result<'ok, 'error>) : Result<'ok, 'error> = match result with | Ok _ -> () | Error x -> if predicate x then - inspector x + sideEffect x result - /// If the result is Ok, executes the function on the Ok value. Passes through - /// the input value. + /// + /// If the result is Ok, executes the function on the Ok value. Passes through the input value. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/teefunctions#tee + /// + /// The function to execute on the Ok value. + /// The input result. + /// The input result. let inline tee - ([] inspector: 'ok -> unit) + ([] sideEffect: 'ok -> unit) (result: Result<'ok, 'error>) : Result<'ok, 'error> = - teeIf (fun _ -> true) inspector result + teeIf (fun _ -> true) sideEffect result - /// If the result is Error, executes the function on the Error value. Passes - /// through the input value. + /// + /// If the result is Error, executes the function on the Error value. Passes through the input value. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/teefunctions#teeerror + /// + /// The function to execute on the Error value. + /// The input result. + /// The input result. let inline teeError - ([] inspector: 'error -> unit) + ([] sideEffect: 'error -> unit) (result: Result<'ok, 'error>) : Result<'ok, 'error> = - teeErrorIf (fun _ -> true) inspector result + teeErrorIf (fun _ -> true) sideEffect result /// Converts a Result,_> to an Async> let inline sequenceAsync (resAsync: Result, 'error>) : Async> = @@ -322,7 +580,12 @@ module Result = | Error err -> return Error err } - /// + /// + /// Maps an Async function over a Result, returning an Async Result. + /// + /// The function to map over the Result. + /// The Result to map over. + /// An Async Result with the mapped value. let inline traverseAsync ([] f: 'okInput -> Async<'okOutput>) (res: Result<'okInput, 'error>) @@ -330,13 +593,27 @@ module Result = sequenceAsync ((map f) res) - /// Returns the Ok value or runs the specified function over the error value. + /// + /// Returns the Ok value or runs the specified function over the error value. + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/others#valueor + /// + /// The function to run over the error value. + /// The input result. + /// The Ok value if the result is Ok, otherwise the result of running the function over the error value. let inline valueOr ([] f: 'error -> 'ok) (res: Result<'ok, 'error>) : 'ok = match res with | Ok x -> x | Error x -> f x + /// /// Takes two results and returns a tuple of the pair + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/zip + /// + /// The first input result. + /// The second input result. + /// A tuple of the pair of the input results. let zip (left: Result<'leftOk, 'error>) (right: Result<'rightOk, 'error>) @@ -346,7 +623,14 @@ module Result = | Error e, _ -> Error e | _, Error e -> Error e + /// /// Takes two results and returns a tuple of the error pair + /// + /// Documentation is found here: https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/ziperror + /// + /// The first input result. + /// The second input result. + /// A tuple of the error pair of the input results. let zipError (left: Result<'ok, 'leftError>) (right: Result<'ok, 'rightError>)