result.h File Reference

Declaration of the Result enumeration type, related constants and functions. More...

#include <stdbool.h>
#include "ds/helpers.h"
#include "ds/usize.h"

Include dependency graph for result.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	DS_RESULT_BYTES   ((ds_usize_t)sizeof (ds_result_t))
	The size of Result in bytes. More...
#define	DS_RESULT_PROPAGATE_ERR(result)    DS_RESULT_PROPAGATE_ERR_INTERNAL_INTERFACE (result, __COUNTER__)
	Propagates (instantly, possibly early, returns) evaluated result to the calling function only if it is a DS_RESULT_ERR* variant. More...
#define	DS_RESULT_PROPAGATE_IF_NULL(ptr)
	Propagates (instantly, possibly early, returns) DS_RESULT_ERR_PTR_IS_NULL if and only if ptr is NULL. More...

Enumerations
enum	ds_result_t {   DS_RESULT_OK ,   DS_RESULT_ERR_PTR_IS_NULL ,   DS_RESULT_ERR_MEM_ALLOC_FAILED ,   DS_RESULT_ERR_OUT_OF_RANGE }
	Result is a type that represents either success (Ok) or failure (a DS_RESULT_ERR_* variant). More...

Functions
bool	ds_result_is_ok (ds_result_t self)
	Returns true if self is Ok. More...
bool	ds_result_is_err (ds_result_t self)
	Returns true if self is a DS_RESULT_ERR_* variant. More...

Detailed Description

Declaration of the Result enumeration type, related constants and functions.

Author

Avinash Maddikonda (svass.nosp@m.saka.nosp@m.vi@gm.nosp@m.ail..nosp@m.com)

Since

0.6.0

Date

2023-08-01

Definition in file result.h.

Macro Definition Documentation

DS_RESULT_BYTES

#define DS_RESULT_BYTES   ((ds_usize_t)sizeof (ds_result_t))

The size of Result in bytes.

Examples

Basic usage:

assert (DS_RESULT_BYTES == sizeof (ds_result_t));

Definition at line 91 of file result.h.

DS_RESULT_PROPAGATE_ERR

#define DS_RESULT_PROPAGATE_ERR

(

result

)

DS_RESULT_PROPAGATE_ERR_INTERNAL_INTERFACE (result, __COUNTER__)

Propagates (instantly, possibly early, returns) evaluated result to the calling function only if it is a DS_RESULT_ERR* variant.

Parameters

result

The Result variant to be returned if and only if it is a DS_RESULT_ERR* variant (i.e., not DS_RESULT_OK).

Warning

Please refrain from using and passing identifiers matching ds_result_propagate_err_internal_result_*. Their usage may cause unintended or undefined behavior, as they are reserved for internal use only.

Returns

result if and only if it is a DS_RESULT_ERR_* variant, else does not return at all.

Examples

Basic usage:

ds_result_t get_some_result()
{
  DS_RESULT_PROPAGATE_ERR (get_some_other_result ());
  do_something ();
 
  return DS_RESULT_OK;
}

Definition at line 140 of file result.h.

DS_RESULT_PROPAGATE_IF_NULL

#define DS_RESULT_PROPAGATE_IF_NULL

(

ptr

)

Value:

  do                                                                          \
    {                                                                         \
      if (ds_helpers_is_null (ptr))                                           \
        {                                                                     \
          return DS_RESULT_ERR_PTR_IS_NULL;                                   \
        }                                                                     \
    }                                                                         \
  while (false)

Propagates (instantly, possibly early, returns) DS_RESULT_ERR_PTR_IS_NULL if and only if ptr is NULL.

Parameters

ptr	The pointer to check if NULL.

Returns

DS_RESULT_ERR_PTR_IS_NULL if and only if ptr is NULL, else does not return at all.

Examples

Basic usage:

ds_result_t get_some_result(ds_usize_t *const size_ptr)
{
  DS_RESULT_PROPAGATE_IF_NULL (size_ptr);
 
  *size_ptr = DS_USIZE_MIN;
  return DS_RESULT_OK;
}

Definition at line 162 of file result.h.

Enumeration Type Documentation

ds_result_t

enum ds_result_t

Result is a type that represents either success (Ok) or failure (a DS_RESULT_ERR_* variant).

Enumerator
DS_RESULT_OK	Represents success.
DS_RESULT_ERR_PTR_IS_NULL	Represents failure due to an unexpected NULL pointer.
DS_RESULT_ERR_MEM_ALLOC_FAILED	Represents a memory allocation failure (usually due to lack of sufficient available memory).
DS_RESULT_ERR_OUT_OF_RANGE	Represents failure due to encountering an invalid value outside the expected range of valid values.

Definition at line 25 of file result.h.

Function Documentation

ds_result_is_err()

bool ds_result_is_err

(

ds_result_t

self

)

Returns true if self is a DS_RESULT_ERR_* variant.

Parameters

self	The value to check.

Returns

true if self is a DS_RESULT_ERR_* variant. false otherwise.

Examples

Basic usage:

ds_result_t const x = DS_RESULT_OK;
assert (!ds_result_is_err (x));
 
ds_result_t const y = DS_RESULT_ERR_PTR_IS_NULL;
assert (ds_result_is_err (y));

Definition at line 19 of file result.c.

Here is the call graph for this function:

ds_result_is_ok()

bool ds_result_is_ok

(

ds_result_t

self

)

Returns true if self is Ok.

Parameters

self	The value to check.

Returns

true if self is Ok, and false otherwise.

Examples

Basic usage:

ds_result_t const x = DS_RESULT_OK;
assert (ds_result_is_ok (x));
 
ds_result_t const y = DS_RESULT_ERR_PTR_IS_NULL;
assert (!ds_result_is_ok (y));

Definition at line 13 of file result.c.

Here is the caller graph for this function: