Documentation and API Completion (#23)

* README and home page

* Option docs

* Landing page for api docs

* Result docs

* Making Option/NumericOption/Result directly enumerable

* Additional creation options

* JSON converters don't need to be public

* Generic math

* Moving Async collection methods to the Async namespace

* Stack/ImmutableStack

* Queues

* Sets

* Tuple property names

* Concurrent collections

* More documentation

* Incrementing version

Author: jtmueller

README.md

@@ -33,15 +33,16 @@ Option<int> ex3 = new Option<int>(42);
 Option<int> ex4 = Option<int>.None;
 Option<int> ex5 = Option.None<int>();
 Option<int> ex6 = default; // equivalent to Option.None<int>()
+Option<int> ex7 = 0.None(); // value is used only to determine type
 
 int? maybeNull = GetPossiblyNullInteger();
-Option<int> ex7 = Option.Create(maybeNull); // null turns into Option.None
+Option<int> ex8 = Option.Create(maybeNull); // null turns into Option.None
 
 // Or you can use 'using static' for more concise/F#/Rust-like syntax:
 using static RustyOptions.Option;
 
-var ex8 = Some(42);
-var ex9 = None<int>();
+var ex9 = Some(42);
+var ex10 = None<int>();
 ```
 
 ### Getting values from an Option

docs/api/index.md

@@ -1,2 +1,7 @@
-# PLACEHOLDER
-TODO: Add .NET projects to the *src* folder and run `docfx` to generate **REAL** *API Documentation*!
+# RustyOptions
+
+The RustyOptions library consists of two namespaces: `RustyOptions` and `RustyOptions.Async`.
+
+You'll likely want to start with the static creation methods on [Option](./RustyOptions.Option.yml) or [Result](./RustyOptions.Result.yml).
+
+For working with an instance, see the documention for [Option<T>](./RustyOptions.Option-1.yml) and [Result<T, TErr>](./RustyOptions.Result-2.yml).

docs/articles/async.md

@@ -0,0 +1,16 @@
+# Async
+
+The `RustyOptions.Async` namespace provides extension methods for `IAsyncEnumerable<T>`
+as well as async versions of RustyOptions API methods like `Map`, `OrElse`, `AndThen`.
+
+## IAsyncEnumerable<T>
+
+RustyOptions provides `FirstOrNoneAsync` for any async enumerable, as well as `Values` and `Errors` methods
+for async enumerables that return `Option<T>` or `Result<T, TErr>`.
+
+## Async Option/Result Methods
+
+RustyOptions provides asynchronous versions of most Option/Result API methods. There are 8 overloads of each
+method, for the various combinations of `Task` and `ValueTask` plus tasks that return an Option/Result vs 
+Option/Result objects that return a task. Because there are so many overloads, they are found in the 
+`RustyOptions.Async` namespace so that they don't clutter intellisense for non-async code.

docs/articles/collections.md

@@ -0,0 +1,18 @@
+# Collections
+
+RustyOptions provides extension methods that return options for collection operations that might not produce a value:
+ - `TryXXX` methods have `XXXOrNone` equivalents.
+ - `XXXOrDefault` methods have `XXXOrNone` equivalents.
+
+In addition, the `.Values()` extension method will pull all the values that exist out of a collection of `Option<T>` or `Result<T, TErr>`,
+while the `.Errors()` extension method will pull all of the errors from a collection of `Result<T, TErr>`.
+
+## Supported Collections
+ - Any type implementing `IEnumerable<T>` (First, Last, Single, ElementAt)
+ - `IDictionary<TKey, TValue>`, `IReadOnlyDictionary<TKey, TValue>`
+ - `Stack<T>`, `ImmutableStack<T>`, `ConcurrentStack<T>`
+ - `Queue<T>`, `PriorityQueue<T, TPriority>`, `ImmutableQueue<T>`, `ConcurrentQueue<T>`
+ - `HashSet<T>`, `SortedSet<T>`, `ImmutableHashSet<T>`, `ImmutableSortedSet<T>`
+ - `IProducerConsumerCollection<T>`, `ConcurrentBag<T>`
+
+For details, see the [API Documentation](../api/RustyOptions.OptionCollectionExtensions.yml).

docs/articles/formatting.md

@@ -0,0 +1,12 @@
+# Formatting Options and Results
+
+RustyOptions types implement both `IFormattable` and `ISpanFormattable` for efficient use in string-building. Any format strings
+are passed through to the contained type.
+
+```csharp
+Assert.Equal("Some(4,200.00)", Some(4200).ToString("n2", CultureInfo.InvariantCulture));
+Assert.Equal("None", None<int>().ToString("n2", CultureInfo.InvariantCulture));
+
+Assert.Equal("Ok(4,200.00)", Ok(4200).ToString("n2", CultureInfo.InvariantCulture));
+Assert.Equal("Err(oops)", Err<int>("oops").ToString("n2", CultureInfo.InvariantCulture));
+```

docs/articles/fsharp.md

@@ -0,0 +1,22 @@
+# F# Compatibility
+
+The F# language has its own built-in `Option`, `ValueOption`, and `Result` types, and both language features and
+utility functions to make these types ergonomic to work with in the context of F#.
+
+There would be little value in extensive F# support for RustyOptions. Similarly, while the F# types can be used
+from C# by referencing the FSharp.Core namespace, they are not convenient to use from C#, and the FSharp.Core
+dependency is fairly heavy-weight for just these types.
+
+RustyOptions is therefore designed to be used from C#. However, it provides the `RustyOptions.FSharp` nuget package,
+which provides convenient methods for converting between RustyOptions Option/Result types, and F# Option/Result types.
+If you are working with a mixture of F# and C# code, RustyOptions can ease the interop between these two languages:
+
+  - C# code receiving values from F# code can use `FromFSharpXXX` extension methods to convert F# Options or Results
+    into RustyOptions equivalents that are easier to work with from C#.
+  - C# code passing values to F# can use RustyOptions types for ease of working with in C#, then use `AsFSharpXXX` extension
+    methods to convert to the equivalent F# types that the F# code expects.
+  - F# code receiving values from C# that use RustyOptions types can use `Option.ofRustyOption` or `ValueOption.ofRustyOption` or
+    `Result.ofRustyResult` to convert to types that are more convenient to use in F#.
+  - F# code passing values to C# can use `Option.toRustyOption` or `ValueOption.toRustyOption` or `Result.toRustyResult` to
+    convert to any RustyOptions types expected by C# code.
+

docs/articles/intro.md

@@ -0,0 +1,33 @@
+# JSON Serialization
+
+RustyOptions types support serialization and deserialization using `System.Text.Json`.
+
+**Options:**
+ - A `Some` option will be serialized as the raw value in json.
+ - A `None` option will be serialized as explicitly null in json.
+ - When parsing, a missing property will be deserialized as `None`.
+ - An explicitly null value will be deserialized as `None`.
+ - Any other value will be deserialized as `Some`.
+
+ ```csharp
+using RustyOptions;
+using System.Text.Json;
+
+record Person(string First, Option<string> Middle, string Last, Option<int> Age);
+
+string json1 = "{ \"first\": \"James\", \"middle\": \"Tiberius\", \"last\": \"Kirk\" }";
+string json2 = "{ \"first\": \"Martin\", \"last\": \"Redshirt\", \"age\": 23 }";
+
+var options = new JsonSerializerOptions { PropertyNameCaseInsensitive = true };
+
+var person1 = JsonSerializer.Deserialize<Person>(json1, options);
+// [Person { First = James, Middle = Some(Tiberius), Last = Kirk, Age = None }]
+
+var person1 = JsonSerializer.Deserialize<Person>(json2, options);
+// [Person { First = Martin, Middle = None, Last = Redshirt, Age = Some(23) }]
+ ```
+
+ **Results:**
+   - A `Result<T, TErr>` will be serialized or parsed as an object that contains either an `ok` or an `err` property:
+     - `{ "ok": 42 }`
+     - `{ "err": "oops!" }`

docs/articles/json.md

@@ -0,0 +1,39 @@
+# Generic Math
+
+_NOTE: Generic Math is supported by .NET 7 and above only. This feature is not available in .NET 6._
+
+.NET 7 introduces new [math-related generic interfaces](https://learn.microsoft.com/en-us/dotnet/standard/generics/math) to the base class library. RustyOptions provides the `NumericOption<T>` type to support this. `NumericOption` can store any struct that implements the `INumber<T>` interface, and allows you to transparently perform math operations on these optional values.
+
+This works similarly to `Nullable<T>` which also [allows you to perform math operations on contained values](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/nullable-value-types#lifted-operators). Such operations produce `null` if one or both operands are `null` in the case of `Nullable<T>`, and they produce `None` if one or both operands are `None` in the case of `NumericOption<T>`.
+
+The difference is that this functionality in `Nullable<T>` depends on compiler support, which is not available to third-party types. This is why you can only do math with options in the .NET 7+ version of RustyOptions.
+
+`NumericOption<T>` supports implicit conversion from `T` which means you can mix, for example, `NumericOption<int>` and `int` in the same expression, and it will just work.
+
+## Example
+
+```csharp
+using RustyOptions;
+using static RustyOptions.NumericOption;
+
+var fifteen = Some(3) * 5;
+// returns Some(15)
+
+var none = Some(3) * None<int>();
+// returns None typed to int
+
+// You can even use Option<int> as the index value in a for loop!
+for (var i = Some(0); i < 5; i++)
+{
+    // If you set i to None inside the loop,
+    // the loop will exit when the current iteration completes,
+    // as None is not less than 5.
+    i = None<int>();
+}
+```
+
+As you can see from the last example above, comparison operators such as `<` and increment operators like `++` also work with `NumericOption<T>`, even when comparing an option to a concrete number.
+
+`NumericOption<T>` can be implicitly converted to and from `Option<T>` provided that the contained type is compatible with `NumericOption<T>`.
+
+This support works for any built-in type that implements `INumber<T>`, any custom type that implements `INumber<T>`, and any future built-in types that implement `INumber<T>`. Enjoy!

docs/articles/math.md

@@ -0,0 +1,109 @@
+# Options
+
+The `Option` type is used when an actual value might not exist. 
+It avoids the [billion-dollar mistake](https://en.wikipedia.org/wiki/Null_pointer#History) of null references
+by making it impossible to forget to check whether a possibly-missing value is present.
+
+## Remarks
+
+The following code illustrates a function which generates an option type.
+
+```csharp
+using RustyOptions;
+
+Option<int> KeepIfPositive(int x) => x > 0 ? Option.Some(x) : Option<int>.None;
+```
+
+You can take advantage of the `using static` feature of C# for more concise syntax that is closer to
+that of languages with built-in Option types, such as F# or Rust.
+
+```csharp
+using RustyOptions;
+using static RustyOptions.Option;
+
+Option<int> KeepIfPositive(int x) => x > 0 ? Some(x) : None<int>();
+```
+
+The value `None` is used when an option does not have the actual value.
+
+## Using Options
+
+Options are commonly used when a search does not return a matching result, as shown in the following code.
+
+```csharp
+using RustyOptions;
+using static RustyOptions.Option;
+
+Option<T> TryFindMatch<T>(IEnumerable<T> list, Func<T, bool> predicate)
+{
+    foreach (var value in list)
+    {
+        if (predicate(value))
+        {
+            return Some(value);
+        }
+    }
+
+    return None<T>();
+}
+
+// result1 is Some(100) and its type is Option<int>
+var result1 = TryFindMatch(new[] { 200, 100, 50, 25 }, x => x == 100);
+
+// result2 is None and its type is Option<char>
+var result2 = TryFindMatch(new[] { 'a', 'b', 'c', 'd' }, x => x == 'y');
+```
+
+In the previous code, the function `TryFindMatch` takes a list of values and a predicate function
+that returns a Boolean value. The function iterates the list, and if an element is found that satisfies
+the predicate, the iteration ends and the matching value is returned wrapped in a `Some` option. If
+the function reaches the end of the list without finding a match, `None` is returned.
+
+RustyOptions provides extension methods for most collection types. For more information, see [Collections](collections.md).
+
+Options can also be useful when a value might not exist, for example if it is possible that an exception will
+be thrown when you try to construct a value. The following code sample illustrates this.
+
+```csharp
+using System.IO;
+using RustyOptions;
+using static RustyOptions.Option;
+
+Option<FileStream> OpenFile(string filename)
+{
+    try
+    {
+        var file = File.Open(filename, FileMode.Create);
+        return Some(file);
+    }
+    catch (Exception ex)
+    {
+        Console.Error.WriteLine("An exception occurred opening file '{0}': {1}", 
+            filename, ex.Message);
+        return None<FileStream>();
+    }
+}
+```
+
+The `OpenFile` function in the previous example returns a `FileStream` option if the file opens successfully,
+and `None` if an exception occurs. Depending on the situation, it may not be an appropriate design choice to 
+catch an exception rather than allowing it to propagate.
+
+## Null Values
+
+Note that unlike the F# Option type, RustyOptions does not allow `Some(null)` - any attempt to create an option
+with a null value will result in `None`.
+
+## Option Properties and Methods
+
+The option type supports the [following properties and methods](../api/RustyOptions.Option-1.yml).
+
+## Converting to Other Types
+
+  - Options can be converted to [Results](result.md) using the 
+    [OkOr](../api/RustyOptions.OptionResultExtensions.yml#RustyOptions_OptionResultExtensions_OkOr__2_RustyOptions_Option___0____1_) 
+    or [OkOrElse](../api/RustyOptions.OptionResultExtensions.yml#RustyOptions_OptionResultExtensions_OkOrElse__2_RustyOptions_Option___0__Func___1__) extension methods.
+
+  - Options can be converted to `IEnumerable<T>` using the [AsEnumerable](../api/RustyOptions.Option-1.yml#RustyOptions_Option_1_AsEnumerable) method.
+
+  - Options can be converted to `ReadOnlySpan<T>` using the [AsSpan](../api/RustyOptions.Option-1.yml#RustyOptions_Option_1_AsSpan) method.