Optional Library

Introduction

A general-purpose Maybe type for representing missing values in C without NULL or sentinel values.

Note

Schrödinger's cat is inside a box. Until you look, you don't know if it's alive or dead. A Maybe type works the same way. It either contains a cat, meaning you have a value, or it's empty, meaning you have nothing. Instead of risking errors when there's no cat, OPTIONAL makes you handle both cases explicitly, eliminating the need for null checks or sentinel values.

Getting Started

Adding Optionals to Your Project

This library consists of one header file only. All you need to do is copy optional.h into your project, and include it.

#include <optional.h>

Since it's a header-only library, there is no library code to link against.

Remarks

Optionals are useful for representing values that may or may not be present. To indicate why a value is absent, you may want to use Results instead.

Optional Types and Variables

• OPTIONAL_STRUCT Declares an Optional struct with a default tag and the supplied type.

  OPTIONAL_STRUCT(pet_status);

• OPTIONAL Returns the type specifier for Optionals with the supplied type name.

  OPTIONAL(pet_status) optional;

Creating Optional Objects

• OPTIONAL_PRESENT Initializes a new Optional containing the supplied value.

  OPTIONAL(pet_status) optional = OPTIONAL_PRESENT(AVAILABLE);
  assert(OPTIONAL_IS_PRESENT(optional));

• OPTIONAL_EMPTY Initializes a new empty Optional.

  OPTIONAL(pet_status) optional = OPTIONAL_EMPTY;

• OPTIONAL_OF_NULLABLE Initializes a new Optional based on a possibly null pointer.

  Pet pet = NULL;
  OPTIONAL(Pet) optional = OPTIONAL_OF_POSSIBLY_FALSY(pet);
  assert(OPTIONAL_IS_EMPTY(optional));

• OPTIONAL_OF_POSSIBLY_FALSY Initializes a new Optional based on a possibly falsy value.

  int age = 0;
  OPTIONAL(int) optional = OPTIONAL_OF_POSSIBLY_FALSY(age);
  assert(OPTIONAL_IS_EMPTY(optional));

Basic Usage

Checking for Presence

• OPTIONAL_IS_PRESENT Checks if an Optional contains a value.

  OPTIONAL(pet_status) optional = OPTIONAL_PRESENT(AVAILABLE);
  bool is_present = OPTIONAL_IS_PRESENT(optional);
  assert(is_present == true);

• OPTIONAL_IS_EMPTY Checks if an Optional is empty.

  OPTIONAL(pet_status) optional = OPTIONAL_EMPTY;
  bool is_empty = OPTIONAL_IS_EMPTY(optional);
  assert(is_empty == true);

Unwrapping Values

• OPTIONAL_USE_VALUE Returns an Optional's value.

  OPTIONAL(pet_status) optional = OPTIONAL_PRESENT(AVAILABLE);
  pet_status value = OPTIONAL_USE_VALUE(optional);
  assert(value == AVAILABLE);

• OPTIONAL_GET_VALUE Returns an Optional's value as a possibly-null pointer.

  OPTIONAL(pet_status) optional = OPTIONAL_PRESENT(AVAILABLE);
  const pet_status *value = OPTIONAL_GET_VALUE(optional);
  assert(*value == AVAILABLE);

• OPTIONAL_OR_ELSE Returns an Optional's value, or the supplied one.

  OPTIONAL(pet_status) optional = OPTIONAL_EMPTY;
  pet_status value = OPTIONAL_OR_ELSE(optional, PENDING);
  assert(value == PENDING);

Conditional Actions

• OPTIONAL_IF_PRESENT Performs the supplied action with an Optional's value.

  OPTIONAL(int) optional = OPTIONAL_PRESENT(123);
  side_effect = 0;
  OPTIONAL_IF_PRESENT(optional, set_side_effect);
  assert(side_effect == 123);

• OPTIONAL_IF_PRESENT_OR_ELSE Performs either of the supplied actions with an Optional's value.

  OPTIONAL(int) optional = OPTIONAL_EMPTY;
  side_effect = 0;
  last_error = OK;
  OPTIONAL_IF_PRESENT_OR_ELSE(optional, set_side_effect, log_error(PET_NOT_FOUND));
  assert(side_effect == 0);
  assert(last_error == PET_NOT_FOUND);

Advanced Usage

Screening Optionals

• OPTIONAL_FILTER Conditionally transforms an Optional into an empty one.

  struct pet sold = {.status = SOLD};
  OPTIONAL(Pet) optional = OPTIONAL_PRESENT(&sold);
  OPTIONAL(Pet) filtered = OPTIONAL_FILTER(optional, is_available);
  assert(OPTIONAL_IS_EMPTY(filtered));

• OPTIONAL_FILTER_FALSY Transforms an Optional containing a falsy value into an empty one.

  int age = 0;
  OPTIONAL(int) optional = OPTIONAL_PRESENT(age);
  OPTIONAL(int) filtered = OPTIONAL_FILTER_FALSY(optional);
  assert(OPTIONAL_IS_EMPTY(filtered));

• OPTIONAL_FILTER_NULL Transforms an Optional containing a null pointer into an empty one.

  Pet pet = NULL;
  OPTIONAL(Pet) optional = OPTIONAL_PRESENT(pet);
  OPTIONAL(Pet) filtered = OPTIONAL_FILTER_NULL(optional);
  assert(OPTIONAL_IS_EMPTY(filtered));

Transforming Values

• OPTIONAL_MAP Transforms the value of an Optional.

  struct pet sold = {.status = SOLD};
  OPTIONAL(Pet) optional = OPTIONAL_PRESENT(&sold);
  OPTIONAL(pet_status) mapped = OPTIONAL_MAP(optional, PET_STATUS, typeof(mapped));
  assert(OPTIONAL_USE_VALUE(mapped) == SOLD);

• OPTIONAL_FLAT_MAP Transforms an empty Optional into a different one.

  struct pet sold = {.status = SOLD};
  OPTIONAL(Pet) optional = OPTIONAL_PRESENT(&sold);
  OPTIONAL(Pet) mapped = OPTIONAL_FLAT_MAP(optional, buy_pet);
  assert(OPTIONAL_IS_EMPTY(mapped));

• OPTIONAL_OR Transforms an empty Optional into a different one.

  OPTIONAL(Pet) optional = OPTIONAL_EMPTY;
  OPTIONAL(Pet) mapped = OPTIONAL_OR(optional, pet_get_default(PET_NOT_FOUND));
  assert(strcmp(PET_NAME(OPTIONAL_USE_VALUE(mapped)), "Default pet") == 0);

Additional Info

Compatibility

Optionals rely on modern C features such as designated initializers, compound literals, and typeof.

Releases

This library adheres to Semantic Versioning. All notable changes for each version are documented in a change log.

Head over to GitHub for the latest release.

Source Code

The source code is available on GitHub.