diff --git a/CHANGELOG.md b/CHANGELOG.md index 9dc9fdc..f16985f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1 +1,7 @@ # Version `1.1.0-pre` + +- Rewrite and update a lot of documentation. + +- Rename `Result.HasValue` to `IsOk`. + +- Add `Result.IsError`. diff --git a/src/Rascal.Tests/AsyncMappingTests.cs b/src/Rascal.Tests/AsyncMappingTests.cs index 08b5b1c..6257e8b 100644 --- a/src/Rascal.Tests/AsyncMappingTests.cs +++ b/src/Rascal.Tests/AsyncMappingTests.cs @@ -8,7 +8,7 @@ public async Task MapAsync_ReturnsOk_ForOk() var r = Ok(2); var x = await r.MapAsync(x => Task.FromResult(x.ToString())); - x.HasValue.ShouldBeTrue(); + x.IsOk.ShouldBeTrue(); x.value.ShouldBe("2"); } @@ -18,7 +18,7 @@ public async Task MapAsync_ReturnsErr_ForErr() var r = Err("error"); var x = await r.MapAsync(x => Task.FromResult(x.ToString())); - x.HasValue.ShouldBeFalse(); + x.IsOk.ShouldBeFalse(); x.error?.Message.ShouldBe("error"); } @@ -28,7 +28,7 @@ public async Task ThenAsync_ReturnsOk_ForOkAndMappingReturningOk() var r = Ok(2); var x = await r.ThenAsync(x => Task.FromResult(Ok(x.ToString()))); - x.HasValue.ShouldBeTrue(); + x.IsOk.ShouldBeTrue(); x.value.ShouldBe("2"); } @@ -38,7 +38,7 @@ public async Task ThenAsync_ReturnsErr_ForOkAndMappingReturningErr() var r = Ok(2); var x = await r.ThenAsync(_ => Task.FromResult(Err("error"))); - x.HasValue.ShouldBeFalse(); + x.IsOk.ShouldBeFalse(); x.error?.Message.ShouldBe("error"); } @@ -48,7 +48,7 @@ public async Task ThenAsync_ReturnsErr_ForErr() var r = Err("error"); var x = await r.ThenAsync(x => Task.FromResult(Ok(x.ToString()))); - x.HasValue.ShouldBeFalse(); + x.IsOk.ShouldBeFalse(); x.error?.Message.ShouldBe("error"); } @@ -58,7 +58,7 @@ public async Task TryMapAsync_ReturnsOk_ForOkWithoutException() var r = Ok(2); var x = await r.TryMapAsync(x => Task.FromResult(x.ToString())); - x.HasValue.ShouldBeTrue(); + x.IsOk.ShouldBeTrue(); x.value.ShouldBe("2"); } @@ -68,7 +68,7 @@ public async Task TryMapAsync_ReturnsErr_ForErrWithoutException() var r = Err("error"); var x = r.TryMap(x => Task.FromResult(x.ToString())); - x.HasValue.ShouldBeFalse(); + x.IsOk.ShouldBeFalse(); x.error?.Message.ShouldBe("error"); } @@ -78,7 +78,7 @@ public async Task TryMapAsync_ReturnsErr_ForOkWithException() var r = Ok(2); var x = await r.TryMapAsync(_ => throw new TestException()); - x.HasValue.ShouldBeFalse(); + x.IsOk.ShouldBeFalse(); var e = x.error.ShouldBeOfType(); e.Exception.ShouldBeOfType(); } @@ -89,7 +89,7 @@ public async Task TryMapAsync_ReturnsErr_ForErrWithException() var r = Err("error"); var x = await r.TryMapAsync(_ => throw new TestException()); - x.HasValue.ShouldBeFalse(); + x.IsOk.ShouldBeFalse(); var e = x.error.ShouldBeOfType(); e.Message.ShouldBe("error"); } @@ -100,7 +100,7 @@ public async Task ThenTryAsync_ReturnsOk_ForOkAndMappingReturningOk() var r = Ok(2); var x = await r.ThenTryAsync(x => Task.FromResult(Ok(x.ToString()))); - x.HasValue.ShouldBeTrue(); + x.IsOk.ShouldBeTrue(); x.value.ShouldBe("2"); } @@ -110,7 +110,7 @@ public async Task ThenTryAsync_ReturnsErr_ForOkAndMappingReturningErr() var r = Ok(2); var x = await r.ThenTryAsync(_ => Task.FromResult(Err("error"))); - x.HasValue.ShouldBeFalse(); + x.IsOk.ShouldBeFalse(); x.error?.Message.ShouldBe("error"); } @@ -120,7 +120,7 @@ public async Task ThenTryAsync_ReturnsErr_ForErrAndMappingReturningErr() var r = Err("error"); var x = await r.ThenTryAsync(x => Task.FromResult(Ok(x.ToString()))); - x.HasValue.ShouldBeFalse(); + x.IsOk.ShouldBeFalse(); x.error?.Message.ShouldBe("error"); } @@ -130,7 +130,7 @@ public async Task ThenTryAsync_ReturnsErr_ForOkAndMappingThrowing() var r = Ok(2); var x = await r.ThenTryAsync(_ => throw new TestException()); - x.HasValue.ShouldBeFalse(); + x.IsOk.ShouldBeFalse(); var e = x.error.ShouldBeOfType(); e.Exception.ShouldBeOfType(); } @@ -141,7 +141,7 @@ public async Task ThenTryAsync_ReturnsErr_ForErrAndMappingThrowing() var r = Err("error"); var x = await r.ThenTryAsync(_ => throw new TestException()); - x.HasValue.ShouldBeFalse(); + x.IsOk.ShouldBeFalse(); var e = x.error.ShouldBeOfType(); e.Message.ShouldBe("error"); } diff --git a/src/Rascal.Tests/MappingTests.cs b/src/Rascal.Tests/MappingTests.cs index f5d95fe..bde4ae5 100644 --- a/src/Rascal.Tests/MappingTests.cs +++ b/src/Rascal.Tests/MappingTests.cs @@ -8,7 +8,7 @@ public void Map_ReturnsOk_ForOk() var r = Ok(2); var x = r.Map(x => x.ToString()); - x.HasValue.ShouldBeTrue(); + x.IsOk.ShouldBeTrue(); x.value.ShouldBe("2"); } @@ -18,7 +18,7 @@ public void Map_ReturnsErr_ForErr() var r = Err("error"); var x = r.Map(x => x.ToString()); - x.HasValue.ShouldBeFalse(); + x.IsOk.ShouldBeFalse(); x.error?.Message.ShouldBe("error"); } @@ -28,7 +28,7 @@ public void Then_ReturnsOk_ForOkAndMappingReturningOk() var r = Ok(2); var x = r.Then(x => Ok(x.ToString())); - x.HasValue.ShouldBeTrue(); + x.IsOk.ShouldBeTrue(); x.value.ShouldBe("2"); } @@ -38,7 +38,7 @@ public void Then_ReturnsErr_ForOkAndMappingReturningErr() var r = Ok(2); var x = r.Then(_ => Err("error")); - x.HasValue.ShouldBeFalse(); + x.IsOk.ShouldBeFalse(); x.error?.Message.ShouldBe("error"); } @@ -48,7 +48,7 @@ public void Then_ReturnsErr_ForErr() var r = Err("error"); var x = r.Then(x => Ok(x.ToString())); - x.HasValue.ShouldBeFalse(); + x.IsOk.ShouldBeFalse(); x.error?.Message.ShouldBe("error"); } @@ -60,7 +60,7 @@ public void SelectMany_2_ReturnsOk_ForOkAndOtherReturningOk() x => Ok(x.ToString()), (x, s) => (x, s)); - x.HasValue.ShouldBeTrue(); + x.IsOk.ShouldBeTrue(); x.value.ShouldBe((2, "2")); } @@ -72,7 +72,7 @@ public void SelectMany_2_ReturnsErr_ForOkAndOtherReturningErr() x => Err("error"), (x, s) => (x, s)); - x.HasValue.ShouldBeFalse(); + x.IsOk.ShouldBeFalse(); x.error?.Message.ShouldBe("error"); } @@ -84,7 +84,7 @@ public void SelectMany_2_ReturnsErr_ForErrAndOtherReturningErr() x => Ok(x.ToString()), (x, s) => (x, s)); - x.HasValue.ShouldBeFalse(); + x.IsOk.ShouldBeFalse(); x.error?.Message.ShouldBe("error"); } @@ -94,7 +94,7 @@ public void TryMap_ReturnsOk_ForOkWithoutException() var r = Ok(2); var x = r.TryMap(x => x.ToString()); - x.HasValue.ShouldBeTrue(); + x.IsOk.ShouldBeTrue(); x.value.ShouldBe("2"); } @@ -104,7 +104,7 @@ public void TryMap_ReturnsErr_ForErrWithoutException() var r = Err("error"); var x = r.TryMap(x => x.ToString()); - x.HasValue.ShouldBeFalse(); + x.IsOk.ShouldBeFalse(); x.error?.Message.ShouldBe("error"); } @@ -114,7 +114,7 @@ public void TryMap_ReturnsErr_ForOkWithException() var r = Ok(2); var x = r.TryMap(_ => throw new TestException()); - x.HasValue.ShouldBeFalse(); + x.IsOk.ShouldBeFalse(); var e = x.error.ShouldBeOfType(); e.Exception.ShouldBeOfType(); } @@ -125,7 +125,7 @@ public void TryMap_ReturnsErr_ForErrWithException() var r = Err("error"); var x = r.TryMap(_ => throw new TestException()); - x.HasValue.ShouldBeFalse(); + x.IsOk.ShouldBeFalse(); var e = x.error.ShouldBeOfType(); e.Message.ShouldBe("error"); } @@ -136,7 +136,7 @@ public void ThenTry_ReturnsOk_ForOkAndMappingReturningOk() var r = Ok(2); var x = r.ThenTry(x => Ok(x.ToString())); - x.HasValue.ShouldBeTrue(); + x.IsOk.ShouldBeTrue(); x.value.ShouldBe("2"); } @@ -146,7 +146,7 @@ public void ThenTry_ReturnsErr_ForOkAndMappingReturningErr() var r = Ok(2); var x = r.ThenTry(_ => Err("error")); - x.HasValue.ShouldBeFalse(); + x.IsOk.ShouldBeFalse(); x.error?.Message.ShouldBe("error"); } @@ -156,7 +156,7 @@ public void ThenTry_ReturnsErr_ForErrAndMappingReturningErr() var r = Err("error"); var x = r.ThenTry(x => Ok(x.ToString())); - x.HasValue.ShouldBeFalse(); + x.IsOk.ShouldBeFalse(); x.error?.Message.ShouldBe("error"); } @@ -166,7 +166,7 @@ public void ThenTry_ReturnsErr_ForOkAndMappingThrowing() var r = Ok(2); var x = r.ThenTry(_ => throw new TestException()); - x.HasValue.ShouldBeFalse(); + x.IsOk.ShouldBeFalse(); var e = x.error.ShouldBeOfType(); e.Exception.ShouldBeOfType(); } @@ -177,7 +177,7 @@ public void ThenTry_ReturnsErr_ForErrAndMappingThrowing() var r = Err("error"); var x = r.ThenTry(_ => throw new TestException()); - x.HasValue.ShouldBeFalse(); + x.IsOk.ShouldBeFalse(); var e = x.error.ShouldBeOfType(); e.Message.ShouldBe("error"); } @@ -188,7 +188,7 @@ public void MapError_ReturnsOk_ForOk() var r = Ok(2); var x = r.MapError(_ => new TestError()); - x.HasValue.ShouldBeTrue(); + x.IsOk.ShouldBeTrue(); x.value.ShouldBe(2); } @@ -198,7 +198,7 @@ public void MapError_ReturnsErr_ForErr() var r = Err("error"); var x = r.MapError(_ => new TestError()); - x.HasValue.ShouldBeFalse(); + x.IsOk.ShouldBeFalse(); x.error.ShouldBeOfType(); } } diff --git a/src/Rascal.Tests/PreludeTests.cs b/src/Rascal.Tests/PreludeTests.cs index f372b50..aaa6988 100644 --- a/src/Rascal.Tests/PreludeTests.cs +++ b/src/Rascal.Tests/PreludeTests.cs @@ -9,7 +9,7 @@ public void Ok_ReturnsOk() { var r = Ok(2); - r.HasValue.ShouldBeTrue(); + r.IsOk.ShouldBeTrue(); r.value.ShouldBe(2); } @@ -18,7 +18,7 @@ public void Err_ReturnsErr() { var r = Err("error"); - r.HasValue.ShouldBeFalse(); + r.IsOk.ShouldBeFalse(); r.error?.Message.ShouldBe("error"); } @@ -27,7 +27,7 @@ public void ParseR_String_ReturnsOk_ForValidString() { var r = ParseR("123", CultureInfo.InvariantCulture); - r.HasValue.ShouldBeTrue(); + r.IsOk.ShouldBeTrue(); r.value.ShouldBe(123); } @@ -36,7 +36,7 @@ public void ParseR_String_ReturnsErr_ForInvalidString() { var r = ParseR("24a", CultureInfo.InvariantCulture); - r.HasValue.ShouldBeFalse(); + r.IsOk.ShouldBeFalse(); r.error.ShouldNotBeNull(); } @@ -46,7 +46,7 @@ public void ParseR_Span_ReturnsOk_ForValidString() var s = "123".AsSpan(); var r = ParseR(s, CultureInfo.InvariantCulture); - r.HasValue.ShouldBeTrue(); + r.IsOk.ShouldBeTrue(); r.value.ShouldBe(123); } @@ -56,7 +56,7 @@ public void ParseR_Span_ReturnsErr_ForInvalidString() var s = "24a".AsSpan(); var r = ParseR(s, CultureInfo.InvariantCulture); - r.HasValue.ShouldBeFalse(); + r.IsOk.ShouldBeFalse(); r.error.ShouldNotBeNull(); } @@ -65,7 +65,7 @@ public void Try_ReturnsOk_ForNoException() { var r = Try(() => 2); - r.HasValue.ShouldBeTrue(); + r.IsOk.ShouldBeTrue(); r.value.ShouldBe(2); } @@ -74,7 +74,7 @@ public void Try_ReturnsErr_ForException() { var r = Try(() => throw new TestException()); - r.HasValue.ShouldBeFalse(); + r.IsOk.ShouldBeFalse(); var e = r.error.ShouldBeOfType(); e.Exception.ShouldBeOfType(); } diff --git a/src/Rascal.Tests/ResultExtensionsTests.cs b/src/Rascal.Tests/ResultExtensionsTests.cs index 9cf03b2..3af0a5f 100644 --- a/src/Rascal.Tests/ResultExtensionsTests.cs +++ b/src/Rascal.Tests/ResultExtensionsTests.cs @@ -8,7 +8,7 @@ public void Unnest() var r = Ok(Ok(2)); var x = r.Unnest(); - x.HasValue.ShouldBeTrue(); + x.IsOk.ShouldBeTrue(); x.value.ShouldBe(2); } @@ -18,7 +18,7 @@ public void NotNull_Class_ReturnsOk_ForNotNull() var x = "uwu"; var r = x.NotNull("error"); - r.HasValue.ShouldBeTrue(); + r.IsOk.ShouldBeTrue(); r.value.ShouldBe("uwu"); } @@ -28,7 +28,7 @@ public void NotNull_Class_ReturnsErr_ForNull() var x = null as string; var r = x.NotNull("error"); - r.HasValue.ShouldBeFalse(); + r.IsOk.ShouldBeFalse(); r.error?.Message.ShouldBe("error"); } @@ -38,7 +38,7 @@ public void NotNull_Struct_ReturnsOk_ForNotNull() var x = 2 as int?; var r = x.NotNull("error"); - r.HasValue.ShouldBeTrue(); + r.IsOk.ShouldBeTrue(); r.value.ShouldBe(2); } @@ -48,7 +48,7 @@ public void NotNull_Struct_ReturnsErr_ForNull() var x = null as int?; var r = x.NotNull("error"); - r.HasValue.ShouldBeFalse(); + r.IsOk.ShouldBeFalse(); r.error?.Message.ShouldBe("error"); } @@ -77,7 +77,7 @@ public void Sequence_ReturnsAllOk_ForSequenceContainingAllOks() var result = xs.Sequence(); - result.HasValue.ShouldBeTrue(); + result.IsOk.ShouldBeTrue(); result.value.ShouldBe([1, 2, 3, 4, 5]); } @@ -88,7 +88,7 @@ public void Sequence_ReturnsFirstError_ForSequenceContainingErrors() var result = xs.Sequence(); - result.HasValue.ShouldBeFalse(); + result.IsOk.ShouldBeFalse(); result.error?.Message.ShouldBe("error 1"); } @@ -99,7 +99,7 @@ public void Sequence_ReturnsOk_ForEmptySequence() var result = xs.Sequence(); - result.HasValue.ShouldBeTrue(); + result.IsOk.ShouldBeTrue(); result.value.ShouldBeEmpty(); } @@ -109,7 +109,7 @@ public void TryGetValueR_ReturnsOk_IfKeyExists() var dict = new Dictionary() { ["a"] = 2 }; var r = dict.TryGetValueR("a", "error"); - r.HasValue.ShouldBeTrue(); + r.IsOk.ShouldBeTrue(); r.value.ShouldBe(2); } @@ -119,7 +119,7 @@ public void TryGetValueR_ReturnsErr_IfKeyIsMissing() var dict = new Dictionary(); var r = dict.TryGetValueR("a", "error"); - r.HasValue.ShouldBeFalse(); + r.IsOk.ShouldBeFalse(); r.error?.Message.ShouldBe("error"); } @@ -129,7 +129,7 @@ public void Index_ReturnsOk_IfWithinRange() var xs = new[] { 2 }; var r = xs.Index(0, "error"); - r.HasValue.ShouldBeTrue(); + r.IsOk.ShouldBeTrue(); r.value.ShouldBe(2); } @@ -139,7 +139,7 @@ public void Index_ReturnsErr_IfOutsideRange() var xs = Array.Empty(); var r = xs.Index(0, "error"); - r.HasValue.ShouldBeFalse(); + r.IsOk.ShouldBeFalse(); r.error?.Message.ShouldBe("error"); } @@ -148,7 +148,7 @@ public async Task CatchCancellation_ReturnsOk_IfFinished() { var r = await Task.FromResult(2).CatchCancellation(); - r.HasValue.ShouldBeTrue(); + r.IsOk.ShouldBeTrue(); r.value.ShouldBe(2); } @@ -161,7 +161,7 @@ public async Task CatchCancellation_ReturnsErr_IfCanceled() await cts.CancelAsync(); var r = await task.CatchCancellation(); - r.HasValue.ShouldBeFalse(); + r.IsOk.ShouldBeFalse(); r.error.ShouldBeOfType(); return; diff --git a/src/Rascal.Tests/ResultTests.cs b/src/Rascal.Tests/ResultTests.cs index 20285bf..13cd2f7 100644 --- a/src/Rascal.Tests/ResultTests.cs +++ b/src/Rascal.Tests/ResultTests.cs @@ -7,7 +7,8 @@ public void New_T_HasValue() { var r = new Result(2); - r.HasValue.ShouldBeTrue(); + r.IsOk.ShouldBeTrue(); + r.IsError.ShouldBeFalse(); r.value.ShouldBe(2); r.error.ShouldBeNull(); } @@ -17,7 +18,8 @@ public void New_Error_HasError() { var r = new Result(new TestError()); - r.HasValue.ShouldBeFalse(); + r.IsOk.ShouldBeFalse(); + r.IsError.ShouldBeTrue(); r.value.ShouldBe(default); r.error.ShouldBeOfType(); } @@ -27,7 +29,8 @@ public void Default_IsDefault() { var r = default(Result); - r.HasValue.ShouldBeFalse(); + r.IsOk.ShouldBeFalse(); + r.IsError.ShouldBeTrue(); r.value.ShouldBe(default); r.error.ShouldBe(default); r.Error.ShouldBe(Error.DefaultValueError); diff --git a/src/Rascal.Tests/UtilityTests.cs b/src/Rascal.Tests/UtilityTests.cs index 211dd2e..a75c3dd 100644 --- a/src/Rascal.Tests/UtilityTests.cs +++ b/src/Rascal.Tests/UtilityTests.cs @@ -10,7 +10,7 @@ public void ImplicitConversion() Result x = 2; x.value.ShouldBe(2); - x.HasValue.ShouldBeTrue(); + x.IsOk.ShouldBeTrue(); } [Fact] @@ -20,7 +20,7 @@ public void Combine_ReturnsOk_ForOkAndOk() var b = Ok("uwu"); var r = a.Combine(b); - r.HasValue.ShouldBeTrue(); + r.IsOk.ShouldBeTrue(); r.value.ShouldBe((2, "uwu")); } @@ -31,7 +31,7 @@ public void Combine_ReturnsErr_ForOkAndErr() var b = Err("error"); var r = a.Combine(b); - r.HasValue.ShouldBeFalse(); + r.IsOk.ShouldBeFalse(); r.error?.Message.ShouldBe("error"); } @@ -42,7 +42,7 @@ public void Combine_ReturnsErr_ForErrAndOk() var b = Ok("uwu"); var r = a.Combine(b); - r.HasValue.ShouldBeFalse(); + r.IsOk.ShouldBeFalse(); r.error?.Message.ShouldBe("error"); } @@ -53,7 +53,7 @@ public void Combine_ReturnsErr_ForErrAndErr() var b = Err("error b"); var r = a.Combine(b); - r.HasValue.ShouldBeFalse(); + r.IsOk.ShouldBeFalse(); var error = r.error.ShouldBeOfType(); error.Errors.Select(x => x.Message).ShouldBe(["error a", "error b"]); } @@ -63,7 +63,7 @@ public void OfType_ReturnsOk_ForOkToValidType() { var r = Ok("uwu").ToType(); - r.HasValue.ShouldBeTrue(); + r.IsOk.ShouldBeTrue(); r.value.ShouldBe("uwu"); } @@ -72,7 +72,7 @@ public void OfType_ReturnsErr_ForOkToInvalidType() { var r = Ok("uwu").ToType(); - r.HasValue.ShouldBeFalse(); + r.IsOk.ShouldBeFalse(); r.error?.Message.ShouldNotBeNull(); } @@ -81,7 +81,7 @@ public void OfType_ReturnsErr_ForErr() { var r = Err("error").ToType(); - r.HasValue.ShouldBeFalse(); + r.IsOk.ShouldBeFalse(); r.error?.Message.ShouldBe("error"); } @@ -90,7 +90,7 @@ public void Validate_ReturnsErrWithDefaultError_ForOkAndFalse() { var r = Ok(2).Validate(_ => false); - r.HasValue.ShouldBeFalse(); + r.IsOk.ShouldBeFalse(); r.error?.Message.ShouldNotBeNull(); } @@ -99,7 +99,7 @@ public void Validate_ReturnsErrWithError_ForOkAndFalse() { var r = Ok(2).Validate(_ => false, _ => "error"); - r.HasValue.ShouldBeFalse(); + r.IsOk.ShouldBeFalse(); r.error?.Message.ShouldBe("error"); } @@ -108,7 +108,7 @@ public void Validate_ReturnsOk_ForOk() { var r = Ok(2).Validate(_ => true, _ => "error"); - r.HasValue.ShouldBeTrue(); + r.IsOk.ShouldBeTrue(); r.value.ShouldBe(2); } @@ -117,7 +117,7 @@ public void Validate_ReturnsErr_ForErr() { var r = Err("error a").Validate(_ => false, _ => "error b"); - r.HasValue.ShouldBeFalse(); + r.IsOk.ShouldBeFalse(); r.error?.Message.ShouldBe("error a"); } diff --git a/src/Rascal/Error.cs b/src/Rascal/Error.cs index 4fa9ac3..6b03f29 100644 --- a/src/Rascal/Error.cs +++ b/src/Rascal/Error.cs @@ -1,8 +1,17 @@ namespace Rascal; /// -/// An abstract error. +/// An error containing a simple message. +/// Makes up the other half of a which might be an error. /// +/// +/// An error is conceptually akin to an exception but without the ability to be thrown, +/// meant to be a more lightweight type meant to be wrapped in a . +/// An error fundamentally only contains a single string message, however other more concrete types such as +/// or may define other properties. +/// Errors are meant to be small, specific, and descriptive, such that they are easy to match over +/// and provide specific handling for specific kinds of errors. +/// public abstract class Error { /// diff --git a/src/Rascal/Prelude.cs b/src/Rascal/Prelude.cs index 27eb218..2b54051 100644 --- a/src/Rascal/Prelude.cs +++ b/src/Rascal/Prelude.cs @@ -10,10 +10,10 @@ namespace Rascal; public static class Prelude { /// - /// Creates a result containing a value. + /// Creates a result containing an ok value. /// - /// The type of the value in the result. - /// The value to create the result from. + /// The type of the ok value. + /// The ok value to create the result from. [Pure] public static Result Ok(T value) => new(value); @@ -21,7 +21,7 @@ public static Result Ok(T value) => /// /// Creates a result containing an error. /// - /// The type of the value in the result. + /// The type of an ok value in the result. /// The error to create the result from. [Pure] public static Result Err(Error error) => diff --git a/src/Rascal/Result.cs b/src/Rascal/Result.cs index 0c994b9..2e0c0a5 100644 --- a/src/Rascal/Result.cs +++ b/src/Rascal/Result.cs @@ -3,29 +3,42 @@ namespace Rascal; /// -/// A type which contains either a successful value or an error. +/// A type which contains either an ok value or an error. /// -/// The type of a successful value. +/// The type of an ok value. [DebuggerTypeProxy(typeof(ResultDebugProxy<>))] public readonly partial struct Result { internal readonly T? value; internal readonly Error? error; + /// + /// Same as but returns + /// in case is null. This is primarily meant as a fail-safe in case + /// the result is . + /// internal Error Error => error ?? Error.DefaultValueError; /// - /// Whether the result has a value or not. + /// Whether the result is ok. + /// + public bool IsOk { get; } + + /// + /// Whether the result is an error. /// - public bool HasValue { get; } + /// + /// This is always the inverse of but is more specific about intent. + /// + public bool IsError => !IsOk; /// - /// Creates a new result with a successful value. + /// Creates a new result with an ok value. /// - /// The successful value. + /// The ok value. public Result(T value) { - HasValue = true; + IsOk = true; this.value = value; error = null; } @@ -36,7 +49,7 @@ public Result(T value) /// The error of the result. public Result(Error error) { - HasValue = false; + IsOk = false; value = default; this.error = error; } @@ -46,7 +59,7 @@ public Result(Error error) /// [Pure] public override string ToString() => - HasValue + IsOk ? $"Ok {{ {value} }}" : $"Error {{ {Error.Message} }}"; } diff --git a/src/Rascal/ResultDebugProxy.cs b/src/Rascal/ResultDebugProxy.cs index 6184d17..7ee4a6b 100644 --- a/src/Rascal/ResultDebugProxy.cs +++ b/src/Rascal/ResultDebugProxy.cs @@ -2,9 +2,9 @@ namespace Rascal; internal sealed class ResultDebugProxy(Result result) { - public bool HasValue { get; } = result.HasValue; + public bool IsOk { get; } = result.IsOk; - public object? Value { get; } = result.HasValue + public object? Value { get; } = result.IsOk ? result.value! : result.Error; } diff --git a/src/Rascal/ResultExtensions.cs b/src/Rascal/ResultExtensions.cs index 959f80a..94fffc7 100644 --- a/src/Rascal/ResultExtensions.cs +++ b/src/Rascal/ResultExtensions.cs @@ -1,7 +1,7 @@ namespace Rascal; /// -/// Class containing extensions for or relating to . +/// Extensions for or relating to . /// public static class ResultExtensions { @@ -12,14 +12,14 @@ public static class ResultExtensions /// This operation is the same as applying /// with the identity function, eg. r.Then(x => x). /// - /// The type of the value in the result. + /// The type of the ok value in the result. /// The result to un-nest. [Pure] public static Result Unnest(this Result> result) => result.Then(x => x); /// - /// Turns a nullable value into a result containing a non-null value + /// Turns a nullable value into a result containing a non-null ok value /// or an error if the value is . /// /// @@ -47,32 +47,32 @@ x is not null : new(error ?? new NullError("Value was null.")); /// - /// Gets the value within the result, - /// or if the result does not contain a value. + /// Gets the ok value of the result, + /// or if the result is an error. /// /// /// This method differs from in that /// it specifically targets value types and returns as opposed - /// to the default value for the type in case the result does not contain a value. + /// to the default value for the type in case the result is an error. /// Can also be understood as mapping the value to T? and calling /// on the returned result. /// - /// The type of the value in the result. - /// The result to get the value in. - /// The value contained in , - /// or if does not contain a value. + /// The type of the ok value of the result. + /// The result to get the ok value of. + /// The ok value of , + /// or if is an error. [Pure] public static T? GetValueOrNull(this Result result) where T : struct => result.Map(x => (T?)x).GetValueOrDefault(); /// - /// Turns a sequence of results into a single result containing the values in the sequence - /// only if all the results have a value. + /// Turns a sequence of results into a single result containing the ok values in the results + /// only if all the results are ok. /// Can also been seen as turning an IEnumerable<Result<T>> "inside out". /// /// The results to turn into a single sequence. - /// The type of the values in the results. - /// A single result containing a sequence of all the values from the original sequence of results, + /// The type of the ok values in the results. + /// A single result containing a sequence of all the ok values from the original sequence of results, /// or the first error encountered within the sequence. /// /// This method completely enumerates the input sequence before returning and is not lazy. @@ -97,7 +97,7 @@ public static Result> Sequence(this IEnumerable> r /// or an error if the key is not present. /// /// The type of keys in the dictionary. - /// The type of values in the dictionary. + /// The type of values in the dictionary. /// The dictionary to try locate the key in. /// The key to locate. /// The error to return if the key is not present. @@ -130,7 +130,7 @@ public static Result Index(this IReadOnlyList list, int index, Error? e $"which has a count of {list.Count}.")); /// - /// Catches the cancellation of a task and wraps the value or exception in a result. + /// Catches the cancellation of a task and wraps the returned value or thrown exception in a result. /// /// The task to catch. /// A function which produces an error in case of a cancellation. diff --git a/src/Rascal/Result_Equality.cs b/src/Rascal/Result_Equality.cs index 0fbdef9..e51a57d 100644 --- a/src/Rascal/Result_Equality.cs +++ b/src/Rascal/Result_Equality.cs @@ -10,23 +10,23 @@ namespace Rascal; #endif { /// - /// Checks whether the result has a value and the value is equal to another value. + /// Checks whether the result is ok and the ok value is equal to another value. /// - /// The value to check for equality with the value in the result. + /// The value to check for equality with the ok value of the result. [Pure] public bool Equals(T? other) => - HasValue && (other?.Equals(value) ?? value is null); + IsOk && (other?.Equals(value) ?? value is null); /// /// Checks whether the result is equal to another result. - /// Results are equal if both results have values which are equal, + /// Results are equal if both results are ok and the ok values are equal, /// or if both results are errors. /// /// The result to check for equality with the current result. [Pure] public bool Equals(Result other) => - HasValue && other.HasValue && (other.value?.Equals(value) ?? value is null) || - !HasValue && !other.HasValue; + IsOk && other.IsOk && (other.value?.Equals(value) ?? value is null) || + !IsOk && !other.IsOk; /// [Pure] @@ -37,13 +37,13 @@ public override bool Equals(object? other) => /// [Pure] public override int GetHashCode() => - HasValue + IsOk ? value?.GetHashCode() ?? 0 : 0; /// /// Checks whether two results are equal. - /// Results are equal if both results have values which are equal, + /// Results are equal if both results are ok and the ok values are equal, /// or if both results are errors. /// /// The first result to compare. @@ -54,7 +54,7 @@ public override int GetHashCode() => /// /// Checks whether two results are not equal. - /// Results are equal if both results have values which are equal, + /// Results are equal if both results are ok and the ok values are equal, /// or if both results are errors. /// /// The first result to compare. @@ -64,10 +64,10 @@ public override int GetHashCode() => !a.Equals(b); /// - /// Checks whether a result has a value and the value is equal to another value. + /// Checks whether a result is ok and the ok value is equal to another value. /// /// The result to compare. - /// The value to check for equality with the value in the result. + /// The value to check for equality with the ok value in the result. [Pure] public static bool operator ==(Result a, T? b) => a.Equals(b); @@ -76,7 +76,7 @@ public override int GetHashCode() => /// Checks whether a result either does not have a value, or the value is not equal to another value. /// /// The result to compare. - /// The value to check for inequality with the value in the result. + /// The value to check for inequality with the ok value in the result. [Pure] public static bool operator !=(Result a, T? b) => !a.Equals(b); diff --git a/src/Rascal/Result_Mapping.cs b/src/Rascal/Result_Mapping.cs index fbc41dc..f7e2116 100644 --- a/src/Rascal/Result_Mapping.cs +++ b/src/Rascal/Result_Mapping.cs @@ -3,30 +3,30 @@ namespace Rascal; public readonly partial struct Result { /// - /// Maps the value of the result using a mapping function, - /// or does nothing if the result is an error. + /// Maps the ok value of the result using a mapping function, + /// or does nothing if the result is an error. /// - /// The function used to map the value. + /// The function used to map the ok value. /// The type of the new value. - /// A new result containing either the mapped value + /// A new result containing either the mapped ok value /// or the error of the original result. [Pure] public Result Map(Func mapping) => - HasValue + IsOk ? new(mapping(value!)) : new(Error); /// - /// Maps the value of the result to a new result using a mapping function, + /// Maps the ok value of the result to a new result using a mapping function, /// or does nothing if the result is an error. /// - /// The function used to map the value to a new result. + /// The function used to map the ok value to a new result. /// The type of the new value. /// A result which is either the mapped result /// or a new result containing the error of the original result. [Pure] public Result Then(Func> mapping) => - HasValue + IsOk ? mapping(value!) : new(Error); @@ -41,44 +41,45 @@ public Result SelectMany(Func> mapping) => Then(mapping); /// - /// Maps the value of the result to an intermediate result using a mapping function, - /// then applies another mapping function onto the values of the original and intermediate results, + /// Maps the ok value of the result to an intermediate result using a mapping function, + /// then applies another mapping function onto the ok values of the original and intermediate results, /// or does nothing if either of the results is an error. /// /// /// The expression r.SelectMany(x => f(x), (x, y) => g(x, y)) can be written as /// r.Bind(x => f(x).Map(y => g(x, y))). /// - /// The function used to map the value to an intermediate result. - /// The function used to map the value to a new result. + /// The function used to map the ok value to an intermediate result. + /// The function used to map the ok value + /// and ok value of the intermediate result to a new result. /// The type of the intermediate value. /// The type of the new value. /// A result constructed by applying - /// onto the value contained in the result returned by - /// as well as the value in the original result, + /// onto the ok value contained in the result returned by + /// as well as the ok value in the original result, /// or a new result containing the error of the original or intermediate results. [Pure] public Result SelectMany( Func> other, Func mapping) { - if (!HasValue) return new(Error); + if (!IsOk) return new(Error); var a = value; var br = other(a!); - if (!br.HasValue) return new(br.Error); + if (!br.IsOk) return new(br.Error); var b = br.value; return new(mapping(a!, b!)); } /// - /// Tries to map the value of the result using a mapping function, + /// Tries to map the ok value of the result using a mapping function, /// or does nothing if the result is an error. /// If the mapping function throws an exception, the exception will be returned wrapped in an /// . /// - /// The function used to map the value. + /// The function used to map the ok value. /// The type of the new value. /// A new result containing either the mapped value, /// the exception thrown by wrapped in an , @@ -97,12 +98,12 @@ public Result TryMap(Func mapping) } /// - /// Tries to map the value of the result to a new result using a mapping function, + /// Tries to map the ok value of the result to a new result using a mapping function, /// or does nothing if the result is an error. /// If the mapping function throws an exception, the exception will be returned wrapped in an /// . /// - /// The function used to map the value to a new result. + /// The function used to map the ok value to a new result. /// The type of the new value. /// A result which is either the mapped result, /// the exception thrown by wrapped in an , @@ -121,16 +122,16 @@ public Result ThenTry(Func> mapping) } /// - /// Maps the error in the result if it contains one + /// Maps the error in the result if it is an error /// and returns a new result containing the mapped error. /// Otherwise, returns the current result. /// /// The function used to map the error. /// A result which contains either the mapped error - /// or the value of the original result. + /// or the ok value of the original result. [Pure] public Result MapError(Func mapping) => - !HasValue + !IsOk ? new(mapping(Error)) : this; } diff --git a/src/Rascal/Result_Mapping_Async.cs b/src/Rascal/Result_Mapping_Async.cs index 7d1d563..3346f2c 100644 --- a/src/Rascal/Result_Mapping_Async.cs +++ b/src/Rascal/Result_Mapping_Async.cs @@ -6,19 +6,19 @@ public readonly partial struct Result #if NETCOREAPP /// - /// Maps the value of the result using an asynchronous mapping function, + /// Maps the ok value of the result using an asynchronous mapping function, /// or does nothing if the result is an error. /// - /// The function used to map the value. + /// The function used to map the ok value. /// The type of the new value. /// A which either completes asynchronously - /// by invoking the mapping function on the value of the result and constructing a new result + /// by invoking the mapping function on the ok value of the result and constructing a new result /// containing the mapped value, or completes synchronously by returning a new result /// containing the error of the original result. [Pure] public ValueTask> MapAsync(Func> mapping) { - if (!HasValue) return new(new Result(Error)); + if (!IsOk) return new(new Result(Error)); var task = mapping(value!); return new(CreateResult(task)); @@ -31,34 +31,34 @@ static async Task> CreateResult(Task task) } /// - /// Maps the value of the result to a new result using an asynchronous mapping function, + /// Maps the ok value of the result to a new result using an asynchronous mapping function, /// or does nothing if the result is an error. /// - /// The function used to map the value to a new result. + /// The function used to map the ok value to a new result. /// The type of the new value. /// A which either completes asynchronously - /// by invoking the mapping function on the value of the result, + /// by invoking the mapping function on the ok value of the result, /// or completes synchronously by returning a new result /// containing the error of the original result. [Pure] public ValueTask> ThenAsync(Func>> mapping) { - if (!HasValue) return new(new Result(Error)); + if (!IsOk) return new(new Result(Error)); var task = mapping(value!); return new(task); } /// - /// Maps the value of the result using an asynchronous mapping function, + /// Maps the ok value of the result using an asynchronous mapping function, /// or does nothing if the result is an error. /// If the mapping function throws an exception, the exception will be returned wrapped in an /// . /// - /// The function used to map the value. + /// The function used to map the ok value. /// The type of the new value. /// A which either completes asynchronously - /// by invoking the mapping function on the value of the result and constructing a new result + /// by invoking the mapping function on the ok value of the result and constructing a new result /// containing the mapped value, /// returning any exception thrown by /// wrapped in an , @@ -66,7 +66,7 @@ public ValueTask> ThenAsync(Func>> mappi [Pure] public ValueTask> TryMapAsync(Func> mapping) { - if (!HasValue) return new(new Result(Error)); + if (!IsOk) return new(new Result(Error)); try { @@ -93,15 +93,15 @@ static async Task> CreateResult(Task task) } /// - /// Maps the value of the result to a new result using an asynchronous mapping function, + /// Maps the ok value of the result to a new result using an asynchronous mapping function, /// or does nothing if the result is an error. /// If the mapping function throws an exception, the exception will be returned wrapped in an /// . /// - /// The function used to map the value to a new result. + /// The function used to map the ok value to a new result. /// The type of the new value. /// A which either completes asynchronously - /// by invoking the mapping function on the value of the result, + /// by invoking the mapping function on the ok value of the result, /// returning any exception thrown by /// wrapped in an , /// or completes synchronously by returning a new result @@ -109,7 +109,7 @@ static async Task> CreateResult(Task task) [Pure] public ValueTask> ThenTryAsync(Func>> mapping) { - if (!HasValue) return new(new Result(Error)); + if (!IsOk) return new(new Result(Error)); try { @@ -125,48 +125,48 @@ public ValueTask> ThenTryAsync(Func>> ma #else /// - /// Maps the value of the result using an asynchronous mapping function, + /// Maps the ok value of the result using an asynchronous mapping function, /// or does nothing if the result is an error. /// - /// The function used to map the value. + /// The function used to map the ok value. /// The type of the new value. - /// A new result containing either the mapped value + /// A new result containing either the mapped ok value /// or the error of the original result. [Pure] public async Task> MapAsync(Func> mapping) => - HasValue + IsOk ? new(await mapping(value!)) : new(Error); /// - /// Maps the value of the result to a new result using an asynchronous mapping function, + /// Maps the ok value of the result to a new result using an asynchronous mapping function, /// or does nothing if the result is an error. /// - /// The function used to map the value to a new result. + /// The function used to map the ok value to a new result. /// The type of the new value. /// A result which is either the mapped result /// or a new result containing the error of the original result. [Pure] public async Task> ThenAsync(Func>> mapping) => - HasValue + IsOk ? await mapping(value!) : new(Error); /// - /// Tries to map the value of the result using an asynchronous mapping function, + /// Tries to map the ok value of the result using an asynchronous mapping function, /// or does nothing if the result is an error. /// If the mapping function throws an exception, the exception will be returned wrapped in an /// . /// - /// The function used to map the value. + /// The function used to map the ok value. /// The type of the new value. - /// A new result containing either the mapped value, + /// A new result containing either the mapped ok value, /// the exception thrown by wrapped in an , /// or the error of the original result. [Pure] public async Task> TryMapAsync(Func> mapping) { - if (!HasValue) return new(Error); + if (!IsOk) return new(Error); try { @@ -180,12 +180,12 @@ public async Task> TryMapAsync(Func> mapping) } /// - /// Tries to map the value of the result to a new result using an asynchronous mapping function, + /// Tries to map the ok value of the result to a new result using an asynchronous mapping function, /// or does nothing if the result is an error. /// If the mapping function throws an exception, the exception will be returned wrapped in an /// . /// - /// The function used to map the value to a new result. + /// The function used to map the ok value to a new result. /// The type of the new value. /// A result which is either the mapped result, /// the exception thrown by wrapped in an , @@ -193,7 +193,7 @@ public async Task> TryMapAsync(Func> mapping) [Pure] public async Task> ThenTryAsync(Func>> mapping) { - if (!HasValue) return new Result(Error); + if (!IsOk) return new Result(Error); try { diff --git a/src/Rascal/Result_Matching.cs b/src/Rascal/Result_Matching.cs index 448522e..4f167da 100644 --- a/src/Rascal/Result_Matching.cs +++ b/src/Rascal/Result_Matching.cs @@ -5,44 +5,39 @@ namespace Rascal; public readonly partial struct Result { /// - /// Matches over the value or error of the result and returns another value. + /// Matches over the ok value or error of the result and returns another value. /// Can be conceptualized as an exhaustive switch expression matching /// all possible values of the type. /// /// The type to return from the match. - /// The function to apply to the - /// value of the result if it does contain a value. - /// The function to apply to the - /// result's error if it does not contain a value. + /// The function to apply to the ok value of the result if the result is ok. + /// The function to apply to the result's error if the result is an error. /// The result of applying either /// or - /// on the value or error of the result. + /// on the ok value or error of the result. [Pure] public TResult Match(Func ifValue, Func ifError) => - HasValue + IsOk ? ifValue(value!) : ifError(Error); /// - /// Matches over the value or error of the result and invokes an effectful action onto the value or error. - /// Can be conceptualized as an exhaustive switch statement matching - /// all possible values of the type. + /// Matches over the ok value or error of the result and invokes an effect-ful action onto the ok value or error. + /// Can be conceptualized as an exhaustive switch statement matching all possible values of the type. /// - /// The function to call with the - /// value of the result if it does contain a value. - /// The function to call with the - /// result's error if it does not contain a value. + /// The function to call with the ok value of the result if the result is ok. + /// The function to call with the result's error if the result is an error. public void Switch(Action ifValue, Action ifError) { - if (HasValue) ifValue(value!); + if (IsOk) ifValue(value!); else ifError(Error); } /// - /// Tries to get the value from the result. + /// Tries to get the ok value from the result. /// - /// The value of the result. - /// Whether the result contains a value. + /// The ok value of the result. + /// Whether the result is ok. [Pure] #if NETCOREAPP public bool TryGetValue([MaybeNullWhen(false)] out T value) @@ -51,15 +46,15 @@ public bool TryGetValue(out T value) #endif { value = this.value!; - return HasValue; + return IsOk; } /// - /// Tries to get the value from the result. + /// Tries to get the ok value from the result. /// - /// The value of the result. + /// The ok value of the result. /// The error of the result. - /// Whether the result contains a value. + /// Whether the result is ok. [Pure] #if NETCOREAPP public bool TryGetValue([MaybeNullWhen(false)] out T value, [MaybeNullWhen(true)] out Error error) @@ -68,18 +63,18 @@ public bool TryGetValue(out T value, out Error error) #endif { value = this.value!; - error = !HasValue + error = !IsOk ? Error : null!; - return HasValue; + return IsOk; } /// /// Tries to get an error from the result. /// /// The error of the result. - /// Whether the result contains an error. + /// Whether the result is an error. [Pure] #if NETCOREAPP public bool TryGetError([MaybeNullWhen(false)] out Error error) @@ -87,19 +82,19 @@ public bool TryGetError([MaybeNullWhen(false)] out Error error) public bool TryGetError(out Error error) #endif { - error = !HasValue + error = !IsOk ? Error : null!; - return !HasValue; + return !IsOk; } /// /// Tries to get an error from the result. /// /// The error of the result. - /// The value of the result. - /// Whether the result contains an error. + /// The ok value of the result. + /// Whether the result is an error. [Pure] #if NETCOREAPP public bool TryGetError([MaybeNullWhen(false)] out Error error, [MaybeNullWhen(true)] out T value) @@ -107,61 +102,58 @@ public bool TryGetError([MaybeNullWhen(false)] out Error error, [MaybeNullWhen(t public bool TryGetError(out Error error, out T value) #endif { - error = !HasValue + error = !IsOk ? Error : null!; value = this.value!; - return !HasValue; + return !IsOk; } /// - /// Gets the value within the result, - /// or if the result does not contain a value. + /// Gets the ok value of the result, or if the result is not ok. /// [Pure] public T? GetValueOrDefault() => - HasValue + IsOk ? value : default; /// - /// Gets the value within the result, - /// or a default value if the result does not contain a value. + /// Gets the ok value of the result, or a default value if the result is not ok. /// - /// The default value to return if the result does not contain a value. + /// The default value to return if the result is not ok. [Pure] public T GetValueOrDefault(T @default) => - HasValue + IsOk ? value! : @default; /// - /// Gets the value within the result, - /// or a default value if the result does not contain a value. + /// Gets the ok value of the result, or a default value if the result is not ok. /// /// A function to get a default value to return - /// if the result does not contain a value. + /// if the result is not ok. [Pure] public T GetValueOrDefault(Func getDefault) => - HasValue + IsOk ? value! : getDefault(); /// - /// Unwraps the value in the result. - /// Throws an if the result does not contain a value. + /// Unwraps the ok value of the result. + /// Throws an if the result is not ok. /// /// /// This API is unsafe in the sense that it might intentionally throw an exception. /// Please only use this API if the caller knows without a reasonable shadow of a doubt /// that this operation is safe, or that an exception is acceptable to be thrown. /// - /// The value in the result. - /// The result does not contain a value. + /// The ok value of the result. + /// The result is not ok. [Pure] public T Unwrap() => - HasValue + IsOk ? value! : throw new UnwrapException(); @@ -171,21 +163,21 @@ public static explicit operator T(Result result) => result.Unwrap(); /// - /// Expects the result to contain a value, throwing an - /// with a specified message if the result does not contain a value. + /// Expects the result to be ok, throwing an + /// with a specified message if the result is not ok. /// /// The message to construct the - /// to throw using if the result does not contain a value. + /// to throw using if the result is not ok. /// /// This API is unsafe in the sense that it might intentionally throw an exception. /// Please only use this API if the caller knows without a reasonable shadow of a doubt /// that this operation is safe, or that an exception is acceptable to be thrown. /// - /// The value in the result. - /// The result does not contain a value. + /// The ok value of the result. + /// The result is not ok. [Pure] public T Expect(string error) => - HasValue + IsOk ? value! : throw new UnwrapException(error); } diff --git a/src/Rascal/Result_Utility.cs b/src/Rascal/Result_Utility.cs index 3934f12..b887e98 100644 --- a/src/Rascal/Result_Utility.cs +++ b/src/Rascal/Result_Utility.cs @@ -6,7 +6,7 @@ namespace Rascal; public readonly partial struct Result { /// - /// Implicitly constructs a result from a value. + /// Implicitly constructs a result from an ok value. /// /// The value to construct the result from. [Pure] @@ -16,15 +16,15 @@ public static implicit operator Result(T value) => /// /// Combines the result with another result. /// - /// The type of the value in the other result. + /// The type of the ok value in the other result. /// The result to combine the current result with. - /// A result containing a tuple of the value - /// of the current result and the value of . - /// If either of the results do contain an error, returns a result containing - /// that error, or both errors if both results contain errors. + /// A result containing a tuple of the ok value of the current result + /// and the ok value of . + /// If either of the results are errors, returns a result containing + /// that error, or both errors if both results are errors. [Pure] public Result<(T first, TOther second)> Combine(Result other) => - (HasValue, other.HasValue) switch + (IsOk, other.IsOk) switch { (true, true) => new((value!, other.value!)), (false, true) => new(Error), @@ -33,17 +33,19 @@ public static implicit operator Result(T value) => }; /// - /// Tries to convert the result value to another type. + /// Tries to convert the ok value of the result to another type. /// /// The type derived from - /// to which to try convert the value. - /// The error to return - /// A result which contains the current result's value converted to - /// , + /// to which to try convert the ok value. + /// The error to return + /// if the ok value cannot be converted to . + /// A result which contains the ok value converted to , + /// if the ok value cannot be converted to , + /// or the error of the result if it is an error. [Pure] public Result ToType(string? error = null) where TDerived : T => - HasValue + IsOk ? value is TDerived derived ? new(derived) : new(new ValidationError( @@ -53,18 +55,18 @@ public Result ToType(string? error = null) #if NETCOREAPP /// - /// Checks whether the value in the result matches a predicate, + /// Checks whether the ok value of the result matches a predicate, /// and if not replaces the value with an error. /// - /// The predicate to match the value against. + /// The predicate to match the ok value against. /// A function to produce an error - /// if the value doesn't match the predicate. + /// if the ok value doesn't match the predicate. /// The caller argument expression for . /// Should not be specified explicitly, instead letting the compiler fill it in. - /// A result which contains the value of the original result - /// if the value matches , otherwise an + /// A result which contains the ok value of the original result + /// if said value matches , otherwise an /// error produced by . - /// If the original result does not contain a value, that result will be returned. + /// If the original result is an error, that error will be returned. [Pure] public Result Validate( Func predicate, @@ -72,22 +74,22 @@ public Result Validate( [CallerArgumentExpression(nameof(predicate))] string expr = "") => #else /// - /// Checks whether the value in the result matches a predicate, + /// Checks whether the ok value in the result matches a predicate, /// and if not replaces the value with an error. /// - /// The predicate to match the value against. + /// The predicate to match the ok value against. /// A function to produce an error - /// if the value doesn't match the predicate. - /// A result which contains the value of the original result - /// if the value matches , otherwise an + /// if the ok value doesn't match the predicate. + /// A result which contains the ok value of the original result + /// if said value matches , otherwise an /// error produced by . - /// If the original result does not contain a value, that result will be returned. + /// If the original result is an error, that error will be returned. [Pure] public Result Validate( Func predicate, Func? getError = null) => #endif - HasValue + IsOk ? predicate(value!) ? this : new(getError?.Invoke(value!) @@ -100,15 +102,15 @@ public Result Validate( #if NETCOREAPP /// - /// Checks whether the value in the result matches a predicate, + /// Checks whether the ok value of the result matches a predicate, /// and if not replaces the value with an error. /// - /// The predicate to match the value against. + /// The predicate to match the ok value against. /// The caller argument expression for . /// Should not be specified explicitly, instead letting the compiler fill it in. - /// A result which contains the value of the original result - /// if the value matches , otherwise an error. - /// If the original result does not contain a value, that result will be returned. + /// A result which contains the ok value of the original result + /// if said value matches , otherwise an error. + /// If the original result is an error, that error will be returned. [Pure] public Result Where( Func predicate, @@ -116,13 +118,13 @@ public Result Where( Validate(predicate, null, expr); #else /// - /// Checks whether the value in the result matches a predicate, + /// Checks whether the ok value of the result matches a predicate, /// and if not replaces the value with an error. /// - /// The predicate to match the value against. - /// A result which contains the value of the original result - /// if the value matches , otherwise an error. - /// If the original result does not contain a value, that result will be returned. + /// The predicate to match the ok value against. + /// A result which contains the ok value of the original result + /// if said value matches , otherwise an error. + /// If the original result is an error, that error will be returned. [Pure] public Result Where( Func predicate) => @@ -132,20 +134,19 @@ public Result Where( /// /// Creates a from the result. /// - /// A - /// containing either only the value of the result, - /// or no values at all if the result does not contain a value + /// A containing either only the ok value of the result, + /// or no values at all if the result is an error. [Pure] public IEnumerable ToEnumerable() => - HasValue + IsOk ? [value!] : []; /// - /// Gets an immutable reference to the value of the result. + /// Gets an immutable reference to the ok value of the result. /// - /// An immutable reference to the result's value. - /// The value might be if the result does not contain a value. + /// An immutable reference to the ok value. + /// The value of the reference might be if the result is an error. [UnscopedRef] [Pure] public ref readonly T? AsRef() => diff --git a/src/Rascal/UnwrapException.cs b/src/Rascal/UnwrapException.cs index 4fe978d..1c40598 100644 --- a/src/Rascal/UnwrapException.cs +++ b/src/Rascal/UnwrapException.cs @@ -1,8 +1,7 @@ namespace Rascal; /// -/// The exception thrown when a -/// is attempted to be unwraped but does not contain a value. +/// The exception thrown when a is attempted to be unwrapped but is an error. /// public sealed class UnwrapException : Exception {