unsure 0.3.0

A Rust library for handling unsure (optional) values that might fail, with an additional rejection variant.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70

# `Unsure<T>` Enum

`Unsure<T>` is a custom enum which is essentially
[`Option<T>`](https://doc.rust-lang.org/std/option/enum.Option.html)
with an additional `Reject` variant, for handling values that are deemed to be
wholly negative (such as a failure state or an invalid input).

## Implementation Details

### Derived Traits

- `Debug`: Allows `Unsure<T>` values to be formatted for debugging purposes.
- `Clone`: Allows `Unsure<T>` values to be explicitly cloned with `.clone()`
- `Copy`: Allows `Unsure<T>` values to be copied implicitly, allowing
  duplication without `.clone()`.
- `PartialEq`: Allows `Unsure<T>` values to be compared for equality.
- `Eq`: Allows `Unsure<T>` values to be compared for total equality.
- `Hash`: Allows `Unsure<T>` values to be used as keys in `HashMap` or
  `HashSet`.
- `PartialOrd`: Allows `Unsure<T>` values to be compared for partial ordering.
- `Ord`: Allows `Unsure<T>` values to be compared for total ordering.

### Variants

- `Reject`: An erroneous or unwanted value, used to mark a situation where an
  unsure state should be rejected or cancelled. This is the main reason for
  using `Unsure<T>` over `Option<T>` - if you don't need to manage failure
  separately from absence, just stick with `Option<T>`.
- `Nothing`: No value, like `Option<T>`'s `None`, used to mark a situation
  where an unsure state should be ignored or skipped. Takes its name after
  Haskell's `Nothing` variant of the `Maybe` type.
- `Just(T)`: Some value of type `T`, like `Option<T>`'s `Some(T)`, used to
  confirm that an unsure state is valid and confirmed. Takes its name after
  Haskell's `Just a` variant of the `Maybe` type.

### Methods

- `is_reject(&self) -> bool`: Returns `true` if the value is `Reject`, `false` otherwise.
- `is_nothing(&self) -> bool`: Returns `true` if the value is `Nothing`, `false` otherwise.
- `is_just(&self) -> bool`: Returns `true` if the value is `Just(T)`, `false` otherwise.
- `as_ref(&self) -> Option<&T>`: Returns a reference to the value as `Some(&T)` if it is `Just(T)`, `None` otherwise.
- `as_mut(&mut self) -> Option<&mut T>`: Returns a mutable reference to the value as `Some(&mut T)` if it is `Just(T)`, `None` otherwise.
- `unwrap(self) -> T`: Returns the value as `T` if it is `Just(T)`, panics otherwise.
- `unwrap_or(self, default: T) -> T`: Returns the value as `T` if it is `Just(T)`, otherwise returns `default`.
- `unwrap_or_else(self, f: impl FnOnce() -> T) -> T`: Returns the value as `T` if it is `Just(T)`, otherwise calls `f` and returns the result.
- `unwrap_or_default(self) -> T`: Returns the value as `T` if it is `Just(T)`,
  returns the default if it is `Nothing`, panics if it is `Reject`.

### From

- `From<Option<T>>`: Converts an `Option<T>` to an `Unsure<T>`. `Some(T)` maps
  onto `Just(T)`, `None` maps onto `Nothing`. It is impossible to obtain a
  `Reject` from this conversion.

## Installation

`unsure-rs` (`unsure` on crates.io) is a library crate, so you must add it to
an existing Rust project:

```
cargo add unsure
```

You can additionally type it out manually in `Cargo.toml`, but using the CLI
is easier.

## Usage

See the [docs.rs](https://docs.rs/unsure/0.1.0/unsure/) for usage instructions
and detailed explanations of the enum.