oxidized library

Defines types similar to those in Rust, such as Result and Option.

Option

Type Option<T> represents an optional value, either Some and its value, or None which does not have a value. The Option<T> primarily serves as an alternative to nullable values, the benefit being that this type requires you to explicitly deal with the optional nature of the value.

Example

Borrowing from the Rust API documentation, the function below performs numeric division, returning a None if the denominator is zero.

Option<num> divide(num numerator, num denominator) {
  if (denominator == 0.0) {
    return None();
  } else {
    return Some(numerator / denominator);
  }
}

divide(10, 0).when(
  some: (v) {
    print(v);
  },
  none: () {
    print('oops');
  },
);

Result

The Result<T, E> type is intended for representing either a value, or an error. Typical use would be for functions that perform input/output operations that may result in a failure that is expected and recoverable (i.e. the behavior is not "exceptional", thus the code does not throw an exception). Using Result<T, E> encourages taking a direct approach to dealing with the result, without worrying about forgetting to catch all possible exceptions.

Example

Again, borrowing from the Rust API documentation, the function below parses some simple input and returns the result.

enum Version { version1, version2 }

Result<Version, Exception> parse_version(List<int> header) {
  switch (header[0]) {
    case 0:
      return Err(Exception('invalid header length'));
    case 1:
      return Ok(Version.version1);
    case 2:
      return Ok(Version.version2);
    default:
      return Err(Exception('invalid version'));
  }
}

void main() {
  final version = parse_version([1, 2, 3, 4]);
  version.when(
    ok: (v) {
      print('working with version: ${v}');
    },
    err: (e) {
      print('error parsing header: ${e}');
    },
  );
}

Unit

Similar to the Rust () type, the Unit type has exactly one value (), and is used when there is no other meaningful value that could be returned. This is especially useful for Result when not returning anything other than an error, as returning void in Dart is difficult with type parameterization.

The single instance of Unit is defined as the unit constant in the package.

Classes

Err<T extends Object, E extends Object>

An Err<T, E> is a Result that represents a failure.

None<T extends Object>

Type None<T> is an Option that does not contain any value.

Ok<T extends Object, E extends Object>

An Ok<T, E> is a Result that represents the successful value.

Option<T extends Object>

Option is a type that represents either some value (Some) or none (None).

Result<T extends Object, E extends Object>

Result is a type that represents either success (Ok) or failure (Err).

Some<T extends Object>

Type Some<T> is an Option that contains a value.

Unit

The Unit type has exactly one value (), and is used when there is no other meaningful value that could be returned for a Result.

Extensions

FutureOptionOptionFlattener on Future<Option<Option<T>>>

Flat utils on Future<Option<Option<T>>>

FutureOptionResultTransposer on Future<Option<Result<T, E>>>

Utils for transposing Future<Option<Result<T, E>>> to Future<Result<Option<T>, E>>

FutureResultOptionTransposer on Future<Result<Option<T>, E>>

Utils for transposing Option<Result<T, E>> into Result<Option<T>, E> in a Future

FutureResultResultFlattener on Future<Result<Result<T, E>, E>>

Utils for flatting Result<Result<T, E>> in a Future

OptionFutureRedirector on Future<Option<T>>

Collection of utils on Future<Option<T>>

OptionLoginAsyncExtension on FutureOr<Option<T>>

Async method like and, or, xor

OptionMapFilterAsyncX on FutureOr<Option<T>>

Collection of method for async map and filter in a Option

OptionMatchAsyncX on FutureOr<Option<T>>

Collection of methods to work with Future on OptionMatchMixin

OptionOptionFlattener on Option<Option<T>>

Flat utils on Option<Option<T>>

OptionResultTransposer on Option<Result<T, E>>

Utils for transposing Option<Result<T, E>> to Result<Option<T>, E>

OptionToResultAsyncExtension on FutureOr<Option<T>>

Async method like okOrElse

OptionUnwrapAsyncX on FutureOr<Option<T>>

Async methods related to unwrap for Option

ResultFutureRedirector on Future<Result<T, E>>

enable Result<T, E> methods in a Future<Result<T, E>>

ResultOptionTransposer on Result<Option<T>, E>

Utils for transposing Result<Option<T>, E> into Option<Result<T, E>> in a Future

ResultResultFlattener on Result<Result<T, E>, E>

Utils for flatting Result<Result<T, E>>

Constants

unit → const Unit

The one instance of Unit.

Exceptions / Errors

OptionUnwrapException<T>

Exception thrown when unwrapping an Option that is None.

ResultUnwrapException<T, E>

Exception thrown when unwrapping an Option that is None.