Error Handling » CnxOption module

CnxOption(T) is a "struct template" for an Enum representing an optional value. It enables a simple, type-safe way of working with values that may or may not exist or be valid, without resorting to heap-allocation and pointers or out-parameters.

Instantiating CnxOption(T) for a given T is simple, and follows the same methodology as other Cnx templates:

Example:

// have the template automatically undef macro template parameters
#define OPTION_UNDEF_PARAMS

// instantiate the declarations of the `CnxOption(T)` template
#define T MyType
#define OPTION_DECL TRUE
#include <Cnx/Option.h>

// instantiate the definitions of the `CnxOption(T)` template
#define T MyType
#define OPTION_DECL TRUE
#include <Cnx/Option.h>

Once instantiated, CnxOption(T) can be easily used: Example:

CnxOption(u32) checked_add(u32 left, u32 right) {
    return left <= cnx_max_value(u32) - right ?
            Some(u32, left + right) :
            None(u32);
}

void do_thing(void) {
    let_mut left = 0;
    let right = 10;
    // do something with left and/or right ...
    let_mut maybe_added = checked_add(left, right);

    match(maybe_added) {
        variant(Some, added) {
            // do something with added
        }
        variant(None) {
            maybe_added was the `None` variant, do something to recover
        }
    }
}

Defines

#define CnxOption(T)
Macro alias for CnxOption holding the type T
#define Some(T, value)
Creates a CnxOption(T) holding the given value.
#define None(T)
Creates a CnxOption(T) holding no value.
#define cnx_option_is_some(self)
Returns whether this CnxOption(T) is holding a value.
#define cnx_option_is_none(self)
Returns whether this CnxOption(T) isn't holding a value.
#define cnx_option_as_const(self)
Returns a const reference to the value stored in this CnxOption(T)
#define cnx_option_as_mut(self)
Returns a reference to the value stored in this CnxOption(T)
#define cnx_option_unwrap(self)
Returns the value stored in this CnxOption(T)
#define cnx_option_unwrap_or(self, default_value)
Returns the value stored in this CnxOption(T) , or default_value if this is None(T)
#define cnx_option_unwrap_or_else(self, default_generator)
Returns the value stored in this CnxOption(T) , or the value returned by default_generator if this is None(T)
#define cnx_option_expect(self, panic_message)
Returns the value stored in this CnxOption(T)
#define cnx_option_map(self, MapType, map_func)
Maps the value stored in this CnxOption(T)
#define cnx_option_map_or(self, map_func, default_value)
Maps the value stored in this CnxOption(T)
#define cnx_option_map_or_else(self, map_func, default_generator)
Maps the value stored in this CnxOption(T)
#define cnx_option_and(self, option_b)
Returns option_b if self is Some. Otherwise, returns None
#define cnx_option_and_then(self, next_func)
Returns the result of calling next_func with the contained value if this is Some, otherwise returns None.
#define cnx_option_or(self, option_b)
Returns self if it is Some, otherwise returns option_b
#define cnx_option_or_else(self, func)
Returns self if it is Some, otherwise returns the result of calling func
#define cnx_option_as_bool(self)
Converts the given CnxOption(T) to a bool

Define documentation

#define CnxOption(T)
#include <include/Cnx/option/OptionDef.h>

Macro alias for CnxOption holding the type T

Parameters
T - The type to store in the CnxOption(T)

Used to generate and refer to a typedef name for CnxOption(T) instantiations of type T

#define Some(T, value)
#include <include/Cnx/option/OptionDef.h>

Creates a CnxOption(T) holding the given value.

Parameters
T - The held type of the CnxOption(T)
value - The value to store in the CnxOption(T)
Returns a CnxOption(T) containing the given value

#define None(T)
#include <include/Cnx/option/OptionDef.h>

Creates a CnxOption(T) holding no value.

Parameters
T - The held type of the CnxOption(T)
Returns a CnxOption(T) containing no value

#define cnx_option_is_some(self)
#include <include/Cnx/option/OptionDef.h>

Returns whether this CnxOption(T) is holding a value.

Parameters
self - The CnxOption(T) to check
Returns true if this CnxOption(T) is holding a value, false otherwise

#define cnx_option_is_none(self)
#include <include/Cnx/option/OptionDef.h>

Returns whether this CnxOption(T) isn't holding a value.

Parameters
self - The CnxOption(T) to check
Returns true if this CnxOption(T) isn't holding a value, false otherwise

#define cnx_option_as_const(self)
#include <include/Cnx/option/OptionDef.h>

Returns a const reference to the value stored in this CnxOption(T)

Parameters
self - The CnxOption(T) to get the stored value from
Returns a const reference to the contained value

#define cnx_option_as_mut(self)
#include <include/Cnx/option/OptionDef.h>

Returns a reference to the value stored in this CnxOption(T)

Parameters
self - The CnxOption(T) to get the stored value from
Returns a reference to the contained value

#define cnx_option_unwrap(self)
#include <include/Cnx/option/OptionDef.h>

Returns the value stored in this CnxOption(T)

Parameters
self - The CnxOption(T) to get the stored value from
Returns the contained value

#define cnx_option_unwrap_or(self, default_value)
#include <include/Cnx/option/OptionDef.h>

Returns the value stored in this CnxOption(T) , or default_value if this is None(T)

Parameters
self - The CnxOption(T) to get the stored value from
default_value - The value to return if this is None(T)
Returns the contained value, or default_value

#define cnx_option_unwrap_or_else(self, default_generator)
#include <include/Cnx/option/OptionDef.h>

Returns the value stored in this CnxOption(T) , or the value returned by default_generator if this is None(T)

Parameters
self - The CnxOption(T) to get the stored value from
default_generator - The function to generate the value to return if this is None(T)
Returns the contained value, or the one generated by default_generator

#define cnx_option_expect(self, panic_message)
#include <include/Cnx/option/OptionDef.h>

Returns the value stored in this CnxOption(T)

Parameters
self - The CnxOption(T) to get the stored value from
panic_message - The custom panic message to use if self is not the Some(T, value) variant
Returns the contained value

#define cnx_option_map(self, MapType, map_func)
#include <include/Cnx/option/OptionDef.h>

Maps the value stored in this CnxOption(T)

Parameters
self - The CnxOption(T) to map
MapType - The type to map to. This is the type that will be held by the returned CnxOption, and map_func must return this type.
map_func - The function to map the value stored in self to a MapType.
Returns The CnxOption(MapType) resulting from the mapping

If self is Some, maps the value stored in it by calling map_func on it. Otherwise, returns None.

map_func must be a function type callable with T and returning MapType.

#define cnx_option_map_or(self, map_func, default_value)
#include <include/Cnx/option/OptionDef.h>

Maps the value stored in this CnxOption(T)

Parameters
self - The CnxOption(T) to map
map_func - The function to map the value stored in self.
default_value - The value to return if self is None.
Returns The value resulting from the mapping

If self is Some, maps the value stored in it by calling map_func on it. Otherwise, returns default_value.

map_func must be a function type callable with T and returning the same type as default_value.

#define cnx_option_map_or_else(self, map_func, default_generator)
#include <include/Cnx/option/OptionDef.h>

Maps the value stored in this CnxOption(T)

Parameters
self - The CnxOption(T) to map
map_func - The function to map the value stored in self.
default_generator - The function to generate the returned value if self is None.
Returns The value resulting from the mapping

If self is Some, maps the value stored in it by calling map_func on it. Otherwise, returns the result of calling default_generator.

map_func must be a function type callable with T. default_generator must be a function type taking no arguments. Both map_func and default_generator must return the same type.

#define cnx_option_and(self, option_b)
#include <include/Cnx/option/OptionDef.h>

Returns option_b if self is Some. Otherwise, returns None

Parameters
self - The CnxOption(T) to "and" with option_b.
option_b - another CnxOption to "and" with self.
Returns option_b if both self is Some. Otherwise, None.

#define cnx_option_and_then(self, next_func)
#include <include/Cnx/option/OptionDef.h>

Returns the result of calling next_func with the contained value if this is Some, otherwise returns None.

Parameters
self - The CnxOption(T) to operate on.
next_func - The function type to call with the value stored in self.
Returns The result of calling next_func with the value stored in self. Otherwise, None.

#define cnx_option_or(self, option_b)
#include <include/Cnx/option/OptionDef.h>

Returns self if it is Some, otherwise returns option_b

Parameters
self - The CnxOption(T) to "or" with option_b.
option_b - another CnxOption to "or" with self.
Returns self if is is Some Otherwise, option_b.

#define cnx_option_or_else(self, func)
#include <include/Cnx/option/OptionDef.h>

Returns self if it is Some, otherwise returns the result of calling func

Parameters
self - The CnxOption(T).
func - The function to call if self is None.
Returns self if is is Some Otherwise, func()

#define cnx_option_as_bool(self)
#include <include/Cnx/option/OptionDef.h>

Converts the given CnxOption(T) to a bool

Parameters
self - The CnxOption(T) to convert to a bool
Returns self as a bool

This is equivalent to calling Cnx_option_is_some(self)