RList
Data Structures | Defines | Typedefs | Functions
src/include/rlist/single.h File Reference
#include <stddef.h>
#include <stdbool.h>
#include <assert.h>
#include "rlist/platform.h"
#include "rlist/common.h"

Go to the source code of this file.

Data Structures

struct  srl_list
struct  srl_iterator

Defines

#define SRL_INIT   { 0, NULL, NULL }
#define SRL_INIT_WITH(free_fn)   { 0, free_fn, NULL }

Typedefs

typedef int(* srl_map_fn )(struct srl_iterator *const iter, void *const context)

Functions

static void * srl_payload (const struct srl_iterator *const iter)
static void srl_init (struct srl_list *const list, rl_free_fn free_fn)
static unsigned int srl_size (const struct srl_list *const list)
static struct srl_iteratorsrl_first (struct srl_list *const list, struct srl_iterator *const iter)
struct srl_iteratorsrl_next (struct srl_iterator *const iter)
static bool srl_is_eol (const struct srl_iterator *const iter)
bool srl_insert_before (struct srl_iterator *const iter, void *const payload)
void * srl_del (struct srl_iterator *const iter)
void srl_del_all (struct srl_list *const list)
struct srl_iteratorsrl_find (struct srl_iterator *const iter, rl_match_fn match_fn, void *const match_context)
struct srl_iteratorsrl_find_payload (struct srl_iterator *const iter, void *const payload)
int srl_map (struct srl_iterator *const iter, srl_map_fn map_fn, void *const map_context, rl_match_fn match_fn, void *const match_context)

Detailed Description

Public RList API for singly linked lists.

Definition in file single.h.


Define Documentation

#define SRL_INIT   { 0, NULL, NULL }

An initializer constant for srl_list objects.

After assigning this value to a list, it is empty and not associated with an rl_free_fn() function.

Static or local declarations of srl_list objects should be initialized in the declaration with this value (e.g., static struct srl_list list = SRL_INIT;). The srl_init() function should be used where initialization at compile time is not possible so it has to occur at runtime, e.g., for dynamically allocated srl_list objects.

Definition at line 125 of file single.h.

#define SRL_INIT_WITH (   free_fn)    { 0, free_fn, NULL }

An initializer constant for srl_list objects with a custom call-back function for de-allocating payload data.

After assigning this value to a list, it is empty and has the specified rl_free_fn() function associated.

Static or local declarations of srl_list objects should be initialized in the declaration with this value (e.g., static struct srl_list list = SRL_INIT;). The srl_init() function should be used where initialization at compile time is not possible so it has to occur at runtime, e.g., for dynamically allocated srl_list objects.

Parameters:
free_fnpoints to a function with the type rl_free_fn() for de-allocating payload data.

Definition at line 137 of file single.h.


Typedef Documentation

typedef int(* srl_map_fn)(struct srl_iterator *const iter, void *const context)

A type for call-back functions that are applied to multiple list nodes.

Typically, call-backs of this type are used to apply a certain operation (such as modifying the payload or deleting nodes) to some or all nodes in a list (

See also:
srl_map()). It is recommended to make such call-back functions efficient because they are applied to potentially large numbers of list nodes.

Using call-back functions for these operations gives the user of srl_list full customizability on the action performed on the list nodes while the generic iteration code is provided as an RList function and does not need to be re-implemented and customized over and over.

Parameters:
iterpoints to an iterator that refers to a list node. The call-back function may freely manipulate the node's payload. It may also freely manipulate the iterator via any of the RList functions, including deleting the current node.
contextpoints to a custom memory location that the call-back function requires as input or for storing data across calls.
Returns:
If the call-back function returns 0, the iteration over the list continues and the call-back function is invoked for the remaining list nodes. If a non-zero value is returned, the iteration stops and the call-back is not invoked for any further list nodes.

Definition at line 250 of file single.h.


Function Documentation

void* srl_del ( struct srl_iterator *const  iter)

Delete a node from a list.

This function deletes the node that the given iterator refers to.

Warning:
After srl_del() returns, the iterator iter is in an inconsistent state. To make the iterator consistent again, call srl_next(). The result of passing an inconsistent iterator to any other RList function is undefined. Note that when srl_del() is invoked from a srl_map_fn() call-back function, srl_next() is invoked implicitely after the call-back returns. Thus the call-back does not need to invoke srl_next() itself.

The runtime complexity of this function is O(1).

Parameters:
iterPoints to an iterator object. The iterator may not be uninitialized and must have previously been returned by one of the RList functions. The result of calling this function with iter == NULL is undefined.
Returns:
If the list is associated with an rl_free_fn() call-back function, that call-back in invoked for the payload of the node to delete and this function returns NULL. Note that if in this case the payload is present more than once in the list, it is indeed de-allocated but other list nodes with the same payload remain in the list and still point to the now de-allocated payload memory. Thus, inserting a payload more than once into a list should be avoided. If the list is not associated with an rl_free_fn() call-back function, the payload is not de-allocated and this function returns the payload of the deleted node. Note that the payload itself may be NULL.

Definition at line 207 of file single.c.

void srl_del_all ( struct srl_list *const  list)

Delete all nodes from a list.

This is a convenience function which calls srl_del() for all nodes of a list.

The runtime complexity of this function is O(n).

Parameters:
listPoints to the list object from which to delete all nodes. The result of calling this function with list == NULL is undefined.

Definition at line 252 of file single.c.

struct srl_iterator* srl_find ( struct srl_iterator *const  iter,
rl_match_fn  match_fn,
void *const  match_context 
) [read]

Find a list node based on a match call-back function.

This function iterates linearly over a list, starting at the given iterator position, and applies the given matcher call-back function to each list node. It returns an iterator for the first matching node.

The average runtime complexity of this function is O(n/2) + O(match_fn) when iter refers to the first list node.

Parameters:
iterPoints to an iterator object. The iterator indicates the list to search and the list node to begin the search at. The result of calling this function with iter == NULL or an uninitialized iterator object is undefined.
match_fnPoints to a call-back function that identifies the list node to return. The result of calling this function with match_fn == NULL is undefined.
match_contextA context object passed to match_fn on every invocation as its second parameter. The semantics of match_context depend solely on the implementation of the match_fn call-back. match_context may be NULL if match_fn supports that.
Returns:
If match_fn matches the node referred to by iter or a subsequent node, this function updates iter so that it refers to the first such matching node and returns iter. If match_fn matches no node in list, this function updates iter so that it refers to the end of the list and returns iter. If iter refers to the end of the list, this function does not update iter and returns iter. This function never returns NULL.

Definition at line 280 of file single.c.

struct srl_iterator* srl_find_payload ( struct srl_iterator *const  iter,
void *const  payload 
) [read]

Find a list node with a certain payload.

This is a convenience function implemented via srl_find().

The average runtime complexity of this function is O(n/2) when iter refers to the first list node.

Parameters:
iterPoints to an iterator object. The iterator indicates the list to search and the list node to begin the search at. The result of calling this function with iter == NULL or an uninitialized iterator object is undefined.
payloadpoints to the payload to find in list. If payload is NULL, the first list node with a NULL payload is searched for.
Returns:
If payload matches the node referred to by iter or a subsequent node, this function updates iter so that it refers to the first such matching node and returns iter. If match_fn matches no node in list, this function updates iter so that it refers to the end of the list and returns iter. If iter refers to the end of the list, this function does not update iter and returns iter. This function never returns NULL.

Definition at line 308 of file single.c.

static struct srl_iterator* srl_first ( struct srl_list *const  list,
struct srl_iterator *const  iter 
) [static, read]

Initialize an iterator object so it refers to the first node in a list.

If the list is empty, the iterator is updated so that srl_is_eol() returns true.

The runtime complexity of this function is O(1).

Parameters:
listPoints to the list from which to retrieve the first node. The result of calling this function with list == NULL is undefined.
iterPoints to the iterator object to initialize. The result of calling this function with iter == NULL is undefined.
Returns:
This function returns iter.

Definition at line 380 of file single.h.

static void srl_init ( struct srl_list *const  list,
rl_free_fn  free_fn 
) [inline, static]

Initialize a srl_list object at runtime.

This function should be used where initialization at compile time is not possible so it has to occur at runtime, e.g., for dynamically allocated srl_list objects. Static or local declarations of srl_list objects should be initialized in their declaration via SRL_INIT.

The runtime complexity of this function is O(1).

Parameters:
listpoints to the list object to initialize. The result of calling this function with list == NULL is undefined.
free_fnpoints to a rl_free_fn() call-back function for de-allocating payload data. If free_fn is NULL, the list does not automatically de-allocate payload data. Proper memory management of the payload data is then the responsibility of the user of list.

Definition at line 344 of file single.h.

bool srl_insert_before ( struct srl_iterator *const  iter,
void *const  payload 
)

Add payload as a new node at a specific location of a list.

The runtime complexity of this function is O(1).

Parameters:
iterPoints to an iterator. The new node is inserted between the iterator's node and its predecessor. If iter refers to the end of the list (i.e., when srl_is_eol(iter) returns true), the new node is inserted as the last node in the list. This also works for inserting the first node into an empty list. The result of calling this function with iter == NULL is undefined.
payloadPoints to the payload to add to the list. payload may be NULL, in which case a node with a NULL payload is prepended to the list. The same payload may be added to a list several times. In that case however, one needs to be particularly careful about when to de-allocate the payload data. Otherwise, one list node may still point to payload that has already been de-allocated for another list node.
Returns:
Returns true if the new list node was successfully inserted into the list before iter. Returns false, if the list was not modified because the meta-data for the new node could not be allocated.

Definition at line 180 of file single.c.

static bool srl_is_eol ( const struct srl_iterator *const  iter) [inline, static]

Determine whether an iterator refers to the end of a list.

This is primarily useful to determine when an iteration over a list has ended. In this state, the iterator does not refer to a valid list node and should not be passed to any RList functions except srl_is_eol().

The runtime complexity of this function is O(1).

Parameters:
iterPoints to the iterator object to check. The result of calling this function with iter == NULL is undefined.
Returns:
This function returns true if iter refers to the end of its list instead of a valid list node. It returns false if the iterator refers to a valid list node.

Definition at line 430 of file single.h.

int srl_map ( struct srl_iterator *const  iter,
srl_map_fn  map_fn,
void *const  map_context,
rl_match_fn  match_fn,
void *const  match_context 
)

Applies a call-back function to some or all nodes of a list.

This function linearly iterates over a list, starting at the given iterator. For each node, it first checks if an optional rl_match_fn() call-back matches the node. If the node is a match or no rl_match_fn() call-back is supplied, this function invokes the srl_map_fn() call-back for the node. It continues until the end of the list is reached or until the srl_map_fn() call-back returns a non-zero integer.

The average runtime complexity of this function is O(n/2) + O(match_fn) + O(map_fn) when iter refers to the first list node.

Parameters:
iterPoints to an iterator object. The iterator indicates the list to map map_fn onto and it specifies the list node to begin the map operation at. The result of calling this function with iter == NULL or an uninitialized iterator object is undefined.
map_fnpoints to the call-back function to invoke on every node matching match_fn. The result of calling this function with map_fn == NULL is undefined.
map_contextA context object passed to map_fn on every invocation as its second parameter. The semantics of map_context depend solely on the implementation of the map_fn call-back. map_context may be NULL if map_fn supports that.
match_fnpoints to the call-back function that identifies the subset of nodes that map_fn is invoked for. If match_fn is NULL, map_fn is invoked for all list nodes.
match_contextA context object passed to match_fn on every invocation as its second parameter. The semantics of match_context depend solely on the implementation of the match_fn call-back. match_context may be NULL if match_fn supports that.
Returns:
This function returns the value returned by the last invocation of map_fn(). If map_fn() is not invoked because iter did not point to any remaining list nodes or because match_fn() did not return true for any list node, this function returns 0.
See also:
srl_map()

Definition at line 314 of file single.c.

struct srl_iterator* srl_next ( struct srl_iterator *const  iter) [read]

Update an iterator object so it refers to the 'next' list node, i.e., the node following the one the iterator refers to before calling this function.

After passing an iterator to srl_del(), you must call srl_next() on the same iterator before passing it to any other RList function. This advances the iterator to the node after the deleted node.

This function is primarily intended for iterating through a list.

The runtime complexity of this function is O(1).

Parameters:
iterPoints to an iterator object. The iterator may not be uninitialized and must have previously been returned by one of the RList functions. If iter refers to the end of the list, i.e., if srl_is_eol(iter) returns true, this function does not modify iter. The result of calling this function with iter == NULL is undefined.
Returns:
This function returns iter.

Definition at line 140 of file single.c.

static void* srl_payload ( const struct srl_iterator *const  iter) [inline, static]

Retrieve the payload an iterator object is associated with.

The runtime complexity of this function is O(1).

Parameters:
iterpoints to the iterator for which to retrieve the payload pointer. The result of calling this function with iter == NULL is undefined. The result of calling this function with an inconsistent iterator (
See also:
srl_del()) is undefined.
Returns:
Returns the payload of the list node that iter refers to.

Definition at line 324 of file single.h.

static unsigned int srl_size ( const struct srl_list *const  list) [inline, static]

Retrieve the number of nodes currently held by a list.

The runtime complexity of this function is O(1).

Parameters:
listpoints to the list object of which to retrieve the node count. The result of calling this function with list == NULL is undefined.
Returns:
The number of nodes currently held by list.

Definition at line 361 of file single.h.