libsc  2.8.7
The SC library provides support for parallel scientific applications.
All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
Data Structures | Macros | Typedefs | Functions
sc_containers.h File Reference

Dynamic containers such as lists, arrays, and hash tables. More...

#include <sc.h>
Include dependency graph for sc_containers.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  sc_array
 The sc_array object provides a dynamic array of equal-size elements. More...
 
struct  sc_mstamp
 A data container to create memory items of the same size. More...
 
struct  sc_mempool
 The sc_mempool object provides a large pool of equal-size elements. More...
 
struct  sc_link
 The sc_link structure is one link of a linked list. More...
 
struct  sc_list
 The sc_list object provides a linked list. More...
 
struct  sc_hash
 The sc_hash implements a hash table. More...
 
struct  sc_hash_array
 The sc_hash_array implements an array backed up by a hash table. More...
 
struct  sc_recycle_array
 The sc_recycle_array object provides an array of slots that can be reused. More...
 

Macros

#define sc_hash_rot(x, k)   (((x) << (k)) | ((x) >> (32 - (k))))
 Bijective bit rotation as building block for hash functions. More...
 
#define sc_hash_mix(a, b, c)
 Integer bit mixer as building block for hash functions. More...
 
#define sc_hash_final(a, b, c)
 Integer bit operations as building block for hash functions. More...
 
#define SC_ARRAY_IS_OWNER(a)   ((a)->byte_alloc >= 0)
 Test whether the sc_array_t owns its array.
 
#define SC_ARRAY_BYTE_ALLOC(a)
 Return the allocated size of the array. More...
 
#define sc_array_new_size(s, c)   (sc_array_new_count ((s), (c)))
 Deprecated: use sc_array_new_count.
 

Typedefs

typedef unsigned int(* sc_hash_function_t) (const void *v, const void *u)
 Function to compute a hash value of an object. More...
 
typedef int(* sc_equal_function_t) (const void *v1, const void *v2, const void *u)
 Function to check equality of two objects. More...
 
typedef int(* sc_hash_foreach_t) (void **v, const void *u)
 Function to call on every data item of a hash table or hash array. More...
 
typedef struct sc_array sc_array_t
 The sc_array object provides a dynamic array of equal-size elements. More...
 
typedef size_t(* sc_array_type_t) (sc_array_t *array, size_t index, void *data)
 Function to determine the enumerable type of an object in an array. More...
 
typedef struct sc_mstamp sc_mstamp_t
 A data container to create memory items of the same size. More...
 
typedef struct sc_mempool sc_mempool_t
 The sc_mempool object provides a large pool of equal-size elements. More...
 
typedef struct sc_link sc_link_t
 The sc_link structure is one link of a linked list.
 
typedef struct sc_list sc_list_t
 The sc_list object provides a linked list.
 
typedef struct sc_hash sc_hash_t
 The sc_hash implements a hash table. More...
 
typedef struct sc_hash_array_data sc_hash_array_data_t
 Internal context structure for sc_hash_array.
 
typedef struct sc_hash_array sc_hash_array_t
 The sc_hash_array implements an array backed up by a hash table. More...
 
typedef struct sc_recycle_array sc_recycle_array_t
 The sc_recycle_array object provides an array of slots that can be reused. More...
 

Functions

size_t sc_array_memory_used (sc_array_t *array, int is_dynamic)
 Calculate the memory used by an array. More...
 
sc_array_tsc_array_new (size_t elem_size)
 Creates a new array structure with 0 elements. More...
 
sc_array_tsc_array_new_count (size_t elem_size, size_t elem_count)
 Creates a new array structure with a given length (number of elements). More...
 
sc_array_tsc_array_new_view (sc_array_t *array, size_t offset, size_t length)
 Creates a new view of an existing sc_array_t. More...
 
sc_array_tsc_array_new_data (void *base, size_t elem_size, size_t elem_count)
 Creates a new view of an existing plain C array. More...
 
void sc_array_destroy (sc_array_t *array)
 Destroys an array structure. More...
 
void sc_array_destroy_null (sc_array_t **parray)
 Destroys an array structure and sets the pointer to NULL. More...
 
void sc_array_init (sc_array_t *array, size_t elem_size)
 Initializes an already allocated (or static) array structure. More...
 
void sc_array_init_size (sc_array_t *array, size_t elem_size, size_t elem_count)
 Initializes an already allocated (or static) array structure and allocates a given number of elements. More...
 
void sc_array_init_count (sc_array_t *array, size_t elem_size, size_t elem_count)
 Initializes an already allocated (or static) array structure and allocates a given number of elements. More...
 
void sc_array_init_view (sc_array_t *view, sc_array_t *array, size_t offset, size_t length)
 Initializes an already allocated (or static) view from existing sc_array_t. More...
 
void sc_array_init_reshape (sc_array_t *view, sc_array_t *array, size_t elem_size, size_t elem_count)
 Initialize an already allocated (or static) view from existing sc_array_t. More...
 
void sc_array_init_data (sc_array_t *view, void *base, size_t elem_size, size_t elem_count)
 Initializes an already allocated (or static) view from given plain C data. More...
 
void sc_array_memset (sc_array_t *array, int c)
 Run memset on the array storage. More...
 
void sc_array_reset (sc_array_t *array)
 Sets the array count to zero and frees all elements. More...
 
void sc_array_truncate (sc_array_t *array)
 Sets the array count to zero, but does not free elements. More...
 
void sc_array_rewind (sc_array_t *array, size_t new_count)
 Shorten an array without reallocating it. More...
 
void sc_array_resize (sc_array_t *array, size_t new_count)
 Sets the element count to new_count. More...
 
void sc_array_copy (sc_array_t *dest, sc_array_t *src)
 Copy the contents of one array into another. More...
 
void sc_array_copy_into (sc_array_t *dest, size_t dest_offset, sc_array_t *src)
 Copy the contents of one array into some portion of another. More...
 
void sc_array_move_part (sc_array_t *dest, size_t dest_offset, sc_array_t *src, size_t src_offset, size_t count)
 Copy part of one array into another using memmove (3). More...
 
void sc_array_sort (sc_array_t *array, int(*compar)(const void *, const void *))
 Sorts the array in ascending order wrt. More...
 
int sc_array_is_sorted (sc_array_t *array, int(*compar)(const void *, const void *))
 Check whether the array is sorted wrt. More...
 
int sc_array_is_equal (sc_array_t *array, sc_array_t *other)
 Check whether two arrays have equal size, count, and content. More...
 
void sc_array_uniq (sc_array_t *array, int(*compar)(const void *, const void *))
 Removed duplicate entries from a sorted array. More...
 
ssize_t sc_array_bsearch (sc_array_t *array, const void *key, int(*compar)(const void *, const void *))
 Performs a binary search on an array. More...
 
void sc_array_split (sc_array_t *array, sc_array_t *offsets, size_t num_types, sc_array_type_t type_fn, void *data)
 Compute the offsets of groups of enumerable types in an array. More...
 
int sc_array_is_permutation (sc_array_t *array)
 Determine whether array is an array of size_t's whose entries include every integer 0 <= i < array->elem_count. More...
 
void sc_array_permute (sc_array_t *array, sc_array_t *newindices, int keepperm)
 Given permutation newindices, permute array in place. More...
 
unsigned int sc_array_checksum (sc_array_t *array)
 Computes the adler32 checksum of array data (see zlib documentation). More...
 
size_t sc_array_pqueue_add (sc_array_t *array, void *temp, int(*compar)(const void *, const void *))
 Adds an element to a priority queue. More...
 
size_t sc_array_pqueue_pop (sc_array_t *array, void *result, int(*compar)(const void *, const void *))
 Pops the smallest element from a priority queue. More...
 
void sc_mstamp_init (sc_mstamp_t *mst, size_t stamp_unit, size_t elem_size)
 Initialize a memory stamp container. More...
 
void sc_mstamp_reset (sc_mstamp_t *mst)
 Free all memory in a stamp structure and all items previously returned. More...
 
void sc_mstamp_truncate (sc_mstamp_t *mst)
 Free all memory in a stamp structure and initialize it anew. More...
 
void * sc_mstamp_alloc (sc_mstamp_t *mst)
 Return a new item. More...
 
size_t sc_mstamp_memory_used (sc_mstamp_t *mst)
 Return memory size in bytes of all data allocated in the container. More...
 
size_t sc_mempool_memory_used (sc_mempool_t *mempool)
 Calculate the memory used by a memory pool. More...
 
sc_mempool_tsc_mempool_new (size_t elem_size)
 Creates a new mempool structure with the zero_and_persist option off. More...
 
sc_mempool_tsc_mempool_new_zero_and_persist (size_t elem_size)
 Creates a new mempool structure with the zero_and_persist option on. More...
 
void sc_mempool_init (sc_mempool_t *mempool, size_t elem_size)
 Same as sc_mempool_new, but for an already allocated object. More...
 
void sc_mempool_destroy (sc_mempool_t *mempool)
 Destroy a mempool structure. More...
 
void sc_mempool_destroy_null (sc_mempool_t **pmempool)
 Destroy a mempool structure. More...
 
void sc_mempool_reset (sc_mempool_t *mempool)
 Same as sc_mempool_destroy, but does not free the pointer. More...
 
void sc_mempool_truncate (sc_mempool_t *mempool)
 Invalidates all previously returned pointers, resets count to 0. More...
 
size_t sc_list_memory_used (sc_list_t *list, int is_dynamic)
 Calculate the total memory used by a list. More...
 
sc_list_tsc_list_new (sc_mempool_t *allocator)
 Allocate a new, empty linked list. More...
 
void sc_list_destroy (sc_list_t *list)
 Destroy a linked list structure in O(N). More...
 
void sc_list_init (sc_list_t *list, sc_mempool_t *allocator)
 Initialize a list object with an external link allocator. More...
 
void sc_list_reset (sc_list_t *list)
 Remove all elements from a list in O(N). More...
 
void sc_list_unlink (sc_list_t *list)
 Unlink all list elements without returning them to the mempool. More...
 
sc_link_tsc_list_prepend (sc_list_t *list, void *data)
 Insert a list element at the beginning of the list. More...
 
sc_link_tsc_list_append (sc_list_t *list, void *data)
 Insert a list element at the end of the list. More...
 
sc_link_tsc_list_insert (sc_list_t *list, sc_link_t *pred, void *data)
 Insert an element after a given list position. More...
 
void * sc_list_remove (sc_list_t *list, sc_link_t *pred)
 Remove an element after a given list position. More...
 
void * sc_list_pop (sc_list_t *list)
 Remove an element from the front of the list. More...
 
unsigned int sc_hash_function_string (const void *s, const void *u)
 Compute a hash value from a null-terminated string. More...
 
size_t sc_hash_memory_used (sc_hash_t *hash)
 Calculate the memory used by a hash table. More...
 
sc_hash_tsc_hash_new (sc_hash_function_t hash_fn, sc_equal_function_t equal_fn, void *user_data, sc_mempool_t *allocator)
 Create a new hash table. More...
 
void sc_hash_destroy (sc_hash_t *hash)
 Destroy a hash table. More...
 
void sc_hash_destroy_null (sc_hash_t **phash)
 Destroy a hash table and set its pointer to NULL. More...
 
void sc_hash_truncate (sc_hash_t *hash)
 Remove all entries from a hash table in O(N). More...
 
void sc_hash_unlink (sc_hash_t *hash)
 Unlink all hash elements without returning them to the mempool. More...
 
void sc_hash_unlink_destroy (sc_hash_t *hash)
 Same effect as unlink and destroy, but in O(1). More...
 
int sc_hash_lookup (sc_hash_t *hash, void *v, void ***found)
 Check if an object is contained in the hash table. More...
 
int sc_hash_insert_unique (sc_hash_t *hash, void *v, void ***found)
 Insert an object into a hash table if it is not contained already. More...
 
int sc_hash_remove (sc_hash_t *hash, void *v, void **found)
 Remove an object from a hash table. More...
 
void sc_hash_foreach (sc_hash_t *hash, sc_hash_foreach_t fn)
 Invoke a callback for every member of the hash table. More...
 
void sc_hash_print_statistics (int package_id, int log_priority, sc_hash_t *hash)
 Compute and print statistical information about the occupancy. More...
 
size_t sc_hash_array_memory_used (sc_hash_array_t *ha)
 Calculate the memory used by a hash array. More...
 
sc_hash_array_tsc_hash_array_new (size_t elem_size, sc_hash_function_t hash_fn, sc_equal_function_t equal_fn, void *user_data)
 Create a new hash array. More...
 
void sc_hash_array_destroy (sc_hash_array_t *hash_array)
 Destroy a hash array. More...
 
int sc_hash_array_is_valid (sc_hash_array_t *hash_array)
 Check the internal consistency of a hash array. More...
 
void sc_hash_array_truncate (sc_hash_array_t *hash_array)
 Remove all elements from the hash array. More...
 
int sc_hash_array_lookup (sc_hash_array_t *hash_array, void *v, size_t *position)
 Check if an object is contained in a hash array. More...
 
void * sc_hash_array_insert_unique (sc_hash_array_t *hash_array, void *v, size_t *position)
 Insert an object into a hash array if it is not contained already. More...
 
void sc_hash_array_foreach (sc_hash_array_t *hash_array, sc_hash_foreach_t fn)
 Invoke a callback for every member of the hash array. More...
 
void sc_hash_array_rip (sc_hash_array_t *hash_array, sc_array_t *rip)
 Extract the array data from a hash array and destroy everything else. More...
 
void sc_recycle_array_init (sc_recycle_array_t *rec_array, size_t elem_size)
 Initialize a recycle array. More...
 
void sc_recycle_array_reset (sc_recycle_array_t *rec_array)
 Reset a recycle array. More...
 
void * sc_recycle_array_insert (sc_recycle_array_t *rec_array, size_t *position)
 Insert an object into the recycle array. More...
 
void * sc_recycle_array_remove (sc_recycle_array_t *rec_array, size_t position)
 Remove an object from the recycle array. More...
 

Detailed Description

Dynamic containers such as lists, arrays, and hash tables.

Macro Definition Documentation

◆ SC_ARRAY_BYTE_ALLOC

#define SC_ARRAY_BYTE_ALLOC (   a)
Value:
((size_t) \
(SC_ARRAY_IS_OWNER (a) ? (a)->byte_alloc : -((a)->byte_alloc + 1)))
#define SC_ARRAY_IS_OWNER(a)
Test whether the sc_array_t owns its array.
Definition: sc_containers.h:133

Return the allocated size of the array.

◆ sc_hash_final

#define sc_hash_final (   a,
  b,
 
)
Value:
((void) \
(c ^= b, c -= sc_hash_rot(b,14), \
a ^= c, a -= sc_hash_rot(c,11), \
b ^= a, b -= sc_hash_rot(a,25), \
c ^= b, c -= sc_hash_rot(b,16), \
a ^= c, a -= sc_hash_rot(c, 4), \
b ^= a, b -= sc_hash_rot(a,14), \
c ^= b, c -= sc_hash_rot(b,24)))
#define sc_hash_rot(x, k)
Bijective bit rotation as building block for hash functions.
Definition: sc_containers.h:56

Integer bit operations as building block for hash functions.

Parameters
[in,out]aFirst in/out value (32-bit integer).
[in,out]bSecond in/out value (32-bit integer).
[in,out]cThird in/out value (32-bit integer).

◆ sc_hash_mix

#define sc_hash_mix (   a,
  b,
 
)
Value:
((void) \
(a -= c, a ^= sc_hash_rot(c, 4), c += b, \
b -= a, b ^= sc_hash_rot(a, 6), a += c, \
c -= b, c ^= sc_hash_rot(b, 8), b += a, \
a -= c, a ^= sc_hash_rot(c,16), c += b, \
b -= a, b ^= sc_hash_rot(a,19), a += c, \
c -= b, c ^= sc_hash_rot(b, 4), b += a))

Integer bit mixer as building block for hash functions.

Parameters
[in,out]aFirst in/out value (32-bit integer).
[in,out]bSecond in/out value (32-bit integer).
[in,out]cThird in/out value (32-bit integer).

◆ sc_hash_rot

#define sc_hash_rot (   x,
 
)    (((x) << (k)) | ((x) >> (32 - (k))))

Bijective bit rotation as building block for hash functions.

Parameters
[in]xInput value (32-bit integer).
[in]kBit shift amount (<= 32).
Returns
Circular shifted integer.

Typedef Documentation

◆ sc_array_t

typedef struct sc_array sc_array_t

The sc_array object provides a dynamic array of equal-size elements.

Elements are accessed by their 0-based index. Their address may change. The number of elements (== elem_count) of the array can be changed by sc_array_resize and sc_array_rewind. Elements can be sorted with sc_array_sort. If the array is sorted, it can be searched with sc_array_bsearch. A priority queue is implemented with pqueue_add and pqueue_pop (untested).

◆ sc_array_type_t

typedef size_t(* sc_array_type_t) (sc_array_t *array, size_t index, void *data)

Function to determine the enumerable type of an object in an array.

Parameters
[in]arrayArray containing the object.
[in]indexThe location of the object.
[in]dataArbitrary user data.

◆ sc_equal_function_t

typedef int(* sc_equal_function_t) (const void *v1, const void *v2, const void *u)

Function to check equality of two objects.

Parameters
[in]v1Pointer to first object checked for equality.
[in]v2Pointer to second object checked for equality.
[in]uArbitrary user data.
Returns
False if *v1 is unequal *v2 and true otherwise.

◆ sc_hash_array_t

The sc_hash_array implements an array backed up by a hash table.

This enables O(1) access for array elements.

◆ sc_hash_foreach_t

typedef int(* sc_hash_foreach_t) (void **v, const void *u)

Function to call on every data item of a hash table or hash array.

Parameters
[in]vThe address of the pointer to the current object.
[in]uArbitrary user data.
Returns
Return true if the traversal should continue, false to stop.

◆ sc_hash_function_t

typedef unsigned int(* sc_hash_function_t) (const void *v, const void *u)

Function to compute a hash value of an object.

Parameters
[in]vThe object to hash.
[in]uArbitrary user data.
Returns
Returns an unsigned integer.

◆ sc_hash_t

typedef struct sc_hash sc_hash_t

The sc_hash implements a hash table.

It uses an array which has linked lists as elements.

◆ sc_mempool_t

typedef struct sc_mempool sc_mempool_t

The sc_mempool object provides a large pool of equal-size elements.

The pool grows dynamically for element allocation. Elements are referenced by their address which never changes. Elements can be freed (that is, returned to the pool) and are transparently reused. If the zero_and_persist option is selected, new elements are initialized to all zeros on creation, and the contents of an element are not touched between freeing and re-returning it.

◆ sc_mstamp_t

typedef struct sc_mstamp sc_mstamp_t

A data container to create memory items of the same size.

Allocations are bundled so it's fast for small memory sizes. The items created will remain valid until the container is destroyed. There is no option to return an item to the container. See sc_mempool_t for that purpose.

◆ sc_recycle_array_t

The sc_recycle_array object provides an array of slots that can be reused.

It keeps a list of free slots in the array which will be used for insertion while available. Otherwise, the array is grown.

Function Documentation

◆ sc_array_bsearch()

ssize_t sc_array_bsearch ( sc_array_t array,
const void *  key,
int(*)(const void *, const void *)  compar 
)

Performs a binary search on an array.

The array must be sorted.

Parameters
[in]arrayA sorted array to search in.
[in]keyAn element to be searched for.
[in]comparThe comparison function to be used.
Returns
Returns the index into array for the item found, or -1.

◆ sc_array_checksum()

unsigned int sc_array_checksum ( sc_array_t array)

Computes the adler32 checksum of array data (see zlib documentation).

This is a faster checksum than crc32, and it works with zeros as data.

◆ sc_array_copy()

void sc_array_copy ( sc_array_t dest,
sc_array_t src 
)

Copy the contents of one array into another.

Both arrays must have equal element sizes. The source array may be a view. We use memcpy (3): If the two arrays overlap, results are undefined.

Parameters
[in]destArray (not a view) will be resized and get new data.
[in]srcArray used as source of new data, will not be changed.

◆ sc_array_copy_into()

void sc_array_copy_into ( sc_array_t dest,
size_t  dest_offset,
sc_array_t src 
)

Copy the contents of one array into some portion of another.

Both arrays must have equal element sizes. Either array may be a view. The destination array must be large enough. We use memcpy (3): If the two arrays overlap, results are undefined.

Parameters
[in]destArray will be written into. Its element count must be at least dest_offset + src->elem_count.
[in]dest_offsetFirst index in dest array to be overwritten. As every index, it refers to elements, not bytes.
[in]srcArray used as source of new data, will not be changed.

◆ sc_array_destroy()

void sc_array_destroy ( sc_array_t array)

Destroys an array structure.

Parameters
[in]arrayThe array to be destroyed.

◆ sc_array_destroy_null()

void sc_array_destroy_null ( sc_array_t **  parray)

Destroys an array structure and sets the pointer to NULL.

Parameters
[in,out]parrayPointer to address of array to be destroyed. On output, *parray is NULL.

◆ sc_array_init()

void sc_array_init ( sc_array_t array,
size_t  elem_size 
)

Initializes an already allocated (or static) array structure.

Parameters
[in,out]arrayArray structure to be initialized.
[in]elem_sizeSize of one array element in bytes.

◆ sc_array_init_count()

void sc_array_init_count ( sc_array_t array,
size_t  elem_size,
size_t  elem_count 
)

Initializes an already allocated (or static) array structure and allocates a given number of elements.

This function supersedes sc_array_init_size.

Parameters
[in,out]arrayArray structure to be initialized.
[in]elem_sizeSize of one array element in bytes.
[in]elem_countNumber of initial array elements.

◆ sc_array_init_data()

void sc_array_init_data ( sc_array_t view,
void *  base,
size_t  elem_size,
size_t  elem_count 
)

Initializes an already allocated (or static) view from given plain C data.

The array view returned does not require sc_array_reset (doesn't hurt though).

Parameters
[in,out]viewArray structure to be initialized.
[in]baseThe data must not be moved while view is alive.
[in]elem_sizeSize of one array element in bytes.
[in]elem_countThe length of the view in element units. The view cannot be resized to exceed this length. It is not necessary to call sc_array_reset later.

◆ sc_array_init_reshape()

void sc_array_init_reshape ( sc_array_t view,
sc_array_t array,
size_t  elem_size,
size_t  elem_count 
)

Initialize an already allocated (or static) view from existing sc_array_t.

The total data size of the view is the same, but size and count may differ. The array view returned does not require sc_array_reset (doesn't hurt though).

Parameters
[in,out]viewArray structure to be initialized.
[in]arrayThe array must not be resized while view is alive.
[in]elem_sizeSize of one array element of the view in bytes. The product of size and count of array must be the same as elem_size * elem_count.
[in]elem_countThe length of the view in element units. The view cannot be resized to exceed this length. It is not necessary to call sc_array_reset later.

◆ sc_array_init_size()

void sc_array_init_size ( sc_array_t array,
size_t  elem_size,
size_t  elem_count 
)

Initializes an already allocated (or static) array structure and allocates a given number of elements.

Deprecated: use sc_array_init_count.

Parameters
[in,out]arrayArray structure to be initialized.
[in]elem_sizeSize of one array element in bytes.
[in]elem_countNumber of initial array elements.

◆ sc_array_init_view()

void sc_array_init_view ( sc_array_t view,
sc_array_t array,
size_t  offset,
size_t  length 
)

Initializes an already allocated (or static) view from existing sc_array_t.

The array view returned does not require sc_array_reset (doesn't hurt though).

Parameters
[in,out]viewArray structure to be initialized.
[in]arrayThe array must not be resized while view is alive.
[in]offsetThe offset of the viewed section in element units. This offset cannot be changed until the view is reset.
[in]lengthThe length of the view in element units. The view cannot be resized to exceed this length. It is not necessary to call sc_array_reset later.

◆ sc_array_is_equal()

int sc_array_is_equal ( sc_array_t array,
sc_array_t other 
)

Check whether two arrays have equal size, count, and content.

Either array may be a view. Both arrays will not be changed.

Parameters
[in]arrayOne array to be compared.
[in]otherA second array to be compared.
Returns
True if array and other are equal, false otherwise.

◆ sc_array_is_permutation()

int sc_array_is_permutation ( sc_array_t array)

Determine whether array is an array of size_t's whose entries include every integer 0 <= i < array->elem_count.

Parameters
[in]arrayAn array.
Returns
Returns 1 if array contains size_t elements whose entries include every integer 0 <= i < array->elem_count, 0 otherwise.

◆ sc_array_is_sorted()

int sc_array_is_sorted ( sc_array_t array,
int(*)(const void *, const void *)  compar 
)

Check whether the array is sorted wrt.

the comparison function.

Parameters
[in]arrayThe array to check.
[in]comparThe comparison function to be used.
Returns
True if array is sorted, false otherwise.

◆ sc_array_memory_used()

size_t sc_array_memory_used ( sc_array_t array,
int  is_dynamic 
)

Calculate the memory used by an array.

Parameters
[in]arrayThe array.
[in]is_dynamicTrue if created with sc_array_new, false if initialized with sc_array_init
Returns
Memory used in bytes.

◆ sc_array_memset()

void sc_array_memset ( sc_array_t array,
int  c 
)

Run memset on the array storage.

We pass the character to memset unchanged. Thus, care must be taken when setting values below -1 or above 127, just as with standard memset (3).

Parameters
[in,out]arrayThis array's storage will be overwritten.
[in]cCharacter to overwrite every byte with.

◆ sc_array_move_part()

void sc_array_move_part ( sc_array_t dest,
size_t  dest_offset,
sc_array_t src,
size_t  src_offset,
size_t  count 
)

Copy part of one array into another using memmove (3).

Both arrays must have equal element sizes. Either array may be a view. The destination array must be large enough. We use memmove (3): The two arrays may overlap.

Parameters
[in]destArray will be written into. Its element count must be at least dest_offset + count.
[in]dest_offsetFirst index in dest array to be overwritten. As every index, it refers to elements, not bytes.
[in]srcArray will be read from. Its element count must be at least src_offset + count.
[in]src_offsetFirst index in src array to be used. As every index, it refers to elements, not bytes.
[in]countNumber of entries copied.

◆ sc_array_new()

sc_array_t* sc_array_new ( size_t  elem_size)

Creates a new array structure with 0 elements.

Parameters
[in]elem_sizeSize of one array element in bytes.
Returns
Return an allocated array of zero length.

◆ sc_array_new_count()

sc_array_t* sc_array_new_count ( size_t  elem_size,
size_t  elem_count 
)

Creates a new array structure with a given length (number of elements).

Parameters
[in]elem_sizeSize of one array element in bytes.
[in]elem_countInitial number of array elements.
Returns
Return an allocated array with allocated but uninitialized elements.

◆ sc_array_new_data()

sc_array_t* sc_array_new_data ( void *  base,
size_t  elem_size,
size_t  elem_count 
)

Creates a new view of an existing plain C array.

Parameters
[in]baseThe data must not be moved while view is alive.
[in]elem_sizeSize of one array element in bytes.
[in]elem_countThe length of the view in element units. The view cannot be resized to exceed this length.

◆ sc_array_new_view()

sc_array_t* sc_array_new_view ( sc_array_t array,
size_t  offset,
size_t  length 
)

Creates a new view of an existing sc_array_t.

Parameters
[in]arrayThe array must not be resized while view is alive.
[in]offsetThe offset of the viewed section in element units. This offset cannot be changed until the view is reset.
[in]lengthThe length of the viewed section in element units. The view cannot be resized to exceed this length.

◆ sc_array_permute()

void sc_array_permute ( sc_array_t array,
sc_array_t newindices,
int  keepperm 
)

Given permutation newindices, permute array in place.

The data that on input is contained in array[i] will be contained in array[newindices[i]] on output. The entries of newindices will be altered unless keepperm is true.

Parameters
[in,out]arrayAn array.
[in,out]newindicesPermutation array (see sc_array_is_permutation).
[in]keeppermIf true, newindices will be unchanged by the algorithm; if false, newindices will be the identity permutation on output, but the algorithm will only use O(1) space.

◆ sc_array_pqueue_add()

size_t sc_array_pqueue_add ( sc_array_t array,
void *  temp,
int(*)(const void *, const void *)  compar 
)

Adds an element to a priority queue.

Note
PQUEUE FUNCTIONS ARE UNTESTED AND CURRENTLY DISABLED. This function is not allowed for views. The priority queue is implemented as a heap in ascending order. A heap is a binary tree where the children are not less than their parent. Assumes that elements [0]..[elem_count-2] form a valid heap. Then propagates [elem_count-1] upward by swapping if necessary.
Parameters
[in,out]arrayValid priority queue object.
[in]tempPointer to unused allocated memory of elem_size.
[in]comparThe comparison function to be used.
Returns
Returns the number of swap operations.
Note
If the return value is zero for all elements in an array, the array is sorted linearly and unchanged.

◆ sc_array_pqueue_pop()

size_t sc_array_pqueue_pop ( sc_array_t array,
void *  result,
int(*)(const void *, const void *)  compar 
)

Pops the smallest element from a priority queue.

Note
PQUEUE FUNCTIONS ARE UNTESTED AND CURRENTLY DISABLED. This function is not allowed for views. This function assumes that the array forms a valid heap in ascending order.
Parameters
[in,out]arrayValid priority queue object.
[out]resultPointer to unused allocated memory of elem_size.
[in]comparThe comparison function to be used.
Returns
Returns the number of swap operations.
Note
This function resizes the array to elem_count-1.

◆ sc_array_reset()

void sc_array_reset ( sc_array_t array)

Sets the array count to zero and frees all elements.

This function turns a view into a newly initialized array.

Parameters
[in,out]arrayArray structure to be reset.
Note
Calling sc_array_init, then any array operations, then sc_array_reset is memory neutral. As an exception, the two functions sc_array_init_view and sc_array_init_data do not require a subsequent call to sc_array_reset. Regardless, it is legal to call sc_array_reset anyway.

◆ sc_array_resize()

void sc_array_resize ( sc_array_t array,
size_t  new_count 
)

Sets the element count to new_count.

If the array is not a view, reallocation takes place occasionally. If the array is a view, new_count must not be greater than the element count of the view when it was created. The original offset of the view cannot be changed.

Parameters
[in,out]arrayThe element count and address is modified.
[in]new_countNew element count of the array. If it is zero and the array is not a view, the effect equals sc_array_reset.

◆ sc_array_rewind()

void sc_array_rewind ( sc_array_t array,
size_t  new_count 
)

Shorten an array without reallocating it.

Parameters
[in,out]arrayThe element count of this array is modified.
[in]new_countMust be less or equal than the array's count. If it is less, the number of elements in the array is reduced without reallocating memory. The exception is a new_count of zero specified for an array that is not a view: In this case sc_array_reset is equivalent.

◆ sc_array_sort()

void sc_array_sort ( sc_array_t array,
int(*)(const void *, const void *)  compar 
)

Sorts the array in ascending order wrt.

the comparison function.

Parameters
[in]arrayThe array to sort.
[in]comparThe comparison function to be used.

◆ sc_array_split()

void sc_array_split ( sc_array_t array,
sc_array_t offsets,
size_t  num_types,
sc_array_type_t  type_fn,
void *  data 
)

Compute the offsets of groups of enumerable types in an array.

Parameters
[in]arrayArray that is sorted in ascending order by type. If k indexes array, then 0 <= type_fn (array, k, data) < num_types.
[in,out]offsetsAn initialized array of type size_t that is resized to num_types + 1 entries. The indices j of array that contain objects of type k are offsets[k] <= j < offsets[k + 1]. If there are no objects of type k, then offsets[k] = offset[k + 1].
[in]num_typesThe number of possible types of objects in array.
[in]type_fnReturns the type of an object in the array.
[in]dataArbitrary user data passed to type_fn.

◆ sc_array_truncate()

void sc_array_truncate ( sc_array_t array)

Sets the array count to zero, but does not free elements.

Not allowed for views.

Parameters
[in,out]arrayArray structure to be truncated.
Note
This is intended to allow an sc_array to be used as a reusable buffer, where the "high water mark" of the buffer is preserved, so that O(log (max n)) reallocs occur over the life of the buffer.

◆ sc_array_uniq()

void sc_array_uniq ( sc_array_t array,
int(*)(const void *, const void *)  compar 
)

Removed duplicate entries from a sorted array.

This function is not allowed for views.

Parameters
[in,out]arrayThe array size will be reduced as necessary.
[in]comparThe comparison function to be used.

◆ sc_hash_array_destroy()

void sc_hash_array_destroy ( sc_hash_array_t hash_array)

Destroy a hash array.

Parameters
[in,out]hash_arrayValid hash array is deallocated.

◆ sc_hash_array_foreach()

void sc_hash_array_foreach ( sc_hash_array_t hash_array,
sc_hash_foreach_t  fn 
)

Invoke a callback for every member of the hash array.

Parameters
[in,out]hash_arrayValid hash array.
[in]fnCallback executed on every hash array element.

◆ sc_hash_array_insert_unique()

void* sc_hash_array_insert_unique ( sc_hash_array_t hash_array,
void *  v,
size_t *  position 
)

Insert an object into a hash array if it is not contained already.

The object is not copied into the array. Use the return value for that. New objects are guaranteed to be added at the end of the array.

Parameters
[in,out]hash_arrayValid hash array.
[in]vA pointer to the object. Used for search only.
[out]positionIf position != NULL, *position is set to the array position of the already contained, or if not present, the new object.
Returns
Returns NULL if the object is already contained. Otherwise returns its new address in the array.

◆ sc_hash_array_is_valid()

int sc_hash_array_is_valid ( sc_hash_array_t hash_array)

Check the internal consistency of a hash array.

Parameters
[in]hash_arrayHash array structure is checked for validity.
Returns
True if and only if hash_array is valid.

◆ sc_hash_array_lookup()

int sc_hash_array_lookup ( sc_hash_array_t hash_array,
void *  v,
size_t *  position 
)

Check if an object is contained in a hash array.

Parameters
[in,out]hash_arrayValid hash array.
[in]vA pointer to the object.
[out]positionIf position != NULL, *position is set to the array position of the already contained object if found.
Returns
True if object is found, false otherwise.

◆ sc_hash_array_memory_used()

size_t sc_hash_array_memory_used ( sc_hash_array_t ha)

Calculate the memory used by a hash array.

Parameters
[in]haThe hash array.
Returns
Memory used in bytes.

◆ sc_hash_array_new()

sc_hash_array_t* sc_hash_array_new ( size_t  elem_size,
sc_hash_function_t  hash_fn,
sc_equal_function_t  equal_fn,
void *  user_data 
)

Create a new hash array.

Parameters
[in]elem_sizeSize of one array element in bytes.
[in]hash_fnFunction to compute the hash value.
[in]equal_fnFunction to test two objects for equality.
[in]user_dataAnonymous context data stored in the hash array.

◆ sc_hash_array_rip()

void sc_hash_array_rip ( sc_hash_array_t hash_array,
sc_array_t rip 
)

Extract the array data from a hash array and destroy everything else.

Parameters
[in]hash_arrayThe hash array is destroyed after extraction.
[in]ripArray structure that will be overwritten. All previous array data (if any) will be leaked. The filled array can be freed with sc_array_reset.

◆ sc_hash_array_truncate()

void sc_hash_array_truncate ( sc_hash_array_t hash_array)

Remove all elements from the hash array.

Parameters
[in,out]hash_arrayHash array to truncate.

◆ sc_hash_destroy()

void sc_hash_destroy ( sc_hash_t hash)

Destroy a hash table.

If the allocator is owned, this runs in O(1), otherwise in O(N).

Note
If allocator was provided in sc_hash_new, it will not be destroyed.

◆ sc_hash_destroy_null()

void sc_hash_destroy_null ( sc_hash_t **  phash)

Destroy a hash table and set its pointer to NULL.

Destruction is done using sc_hash_destroy.

Parameters
[in,out]phashAddress of pointer to hash table. On output, pointer is NULLed.

◆ sc_hash_foreach()

void sc_hash_foreach ( sc_hash_t hash,
sc_hash_foreach_t  fn 
)

Invoke a callback for every member of the hash table.

The hashing and equality functions are not called from within this function.

Parameters
[in,out]hashValid hash table.
[in]fnCallback executed on every hash table element.

◆ sc_hash_function_string()

unsigned int sc_hash_function_string ( const void *  s,
const void *  u 
)

Compute a hash value from a null-terminated string.

This hash function is NOT cryptographically safe! Use libcrypt then.

Parameters
[in]sNull-terminated string to be hashed.
[in]uNot used.
Returns
The computed hash value as an unsigned integer.

◆ sc_hash_insert_unique()

int sc_hash_insert_unique ( sc_hash_t hash,
void *  v,
void ***  found 
)

Insert an object into a hash table if it is not contained already.

Parameters
[in,out]hashValid hash table.
[in]vThe object to be inserted.
[out]foundIf found != NULL, *found is set to the address of the pointer to the already contained, or if not present, the new object. You can assign to **found to override.
Returns
Returns true if object is added, false if it is already contained.

◆ sc_hash_lookup()

int sc_hash_lookup ( sc_hash_t hash,
void *  v,
void ***  found 
)

Check if an object is contained in the hash table.

Parameters
[in]hashValid hash table.
[in]vThe object to be looked up.
[out]foundIf found != NULL, *found is set to the address of the pointer to the already contained object if the object is found. You can assign to **found to override.
Returns
Returns true if object is found, false otherwise.

◆ sc_hash_memory_used()

size_t sc_hash_memory_used ( sc_hash_t hash)

Calculate the memory used by a hash table.

Parameters
[in]hashThe hash table.
Returns
Memory used in bytes.

◆ sc_hash_new()

sc_hash_t* sc_hash_new ( sc_hash_function_t  hash_fn,
sc_equal_function_t  equal_fn,
void *  user_data,
sc_mempool_t allocator 
)

Create a new hash table.

The number of hash slots is chosen dynamically.

Parameters
[in]hash_fnFunction to compute the hash value.
[in]equal_fnFunction to test two objects for equality.
[in]user_dataUser data passed through to the hash function.
[in]allocatorMemory allocator for sc_link_t, can be NULL.

◆ sc_hash_print_statistics()

void sc_hash_print_statistics ( int  package_id,
int  log_priority,
sc_hash_t hash 
)

Compute and print statistical information about the occupancy.

Parameters
[in]package_idLibrary package id for logging.
[in]log_priorityPriority for logging; see sc_log.
[in]hashValid hash table.

◆ sc_hash_remove()

int sc_hash_remove ( sc_hash_t hash,
void *  v,
void **  found 
)

Remove an object from a hash table.

Parameters
[in,out]hashValid hash table.
[in]vThe object to be removed.
[out]foundIf found != NULL, *found is set to the object that is removed if that exists.
Returns
Returns true if object is found, false if is not contained.

◆ sc_hash_truncate()

void sc_hash_truncate ( sc_hash_t hash)

Remove all entries from a hash table in O(N).

If the allocator is owned, it calls sc_hash_unlink and sc_mempool_truncate. Otherwise, it calls sc_list_reset on every hash slot which is slower.

◆ sc_hash_unlink()

void sc_hash_unlink ( sc_hash_t hash)

Unlink all hash elements without returning them to the mempool.

If the allocator is not owned, this runs faster than sc_hash_truncate, but is dangerous because of potential memory leaks.

Parameters
[in,out]hashHash structure to be unlinked.

◆ sc_hash_unlink_destroy()

void sc_hash_unlink_destroy ( sc_hash_t hash)

Same effect as unlink and destroy, but in O(1).

This is dangerous because of potential memory leaks.

Parameters
[in]hashHash structure to be unlinked and destroyed.

◆ sc_list_append()

sc_link_t* sc_list_append ( sc_list_t list,
void *  data 
)

Insert a list element at the end of the list.

Parameters
[in,out]listValid list object.
[in]dataA new link is created holding this data.
Returns
The link that has been created for data.

◆ sc_list_destroy()

void sc_list_destroy ( sc_list_t list)

Destroy a linked list structure in O(N).

Parameters
[in,out]listAll memory allocated for this list is freed.
Note
If allocator was provided in sc_list_new, it will not be destroyed.

◆ sc_list_init()

void sc_list_init ( sc_list_t list,
sc_mempool_t allocator 
)

Initialize a list object with an external link allocator.

Parameters
[in,out]listList structure to be initialized.
[in]allocatorExternal memory allocator for sc_link_t, which must exist already.

◆ sc_list_insert()

sc_link_t* sc_list_insert ( sc_list_t list,
sc_link_t pred,
void *  data 
)

Insert an element after a given list position.

Parameters
[in,out]listValid list object.
[in,out]predThe predecessor of the element to be inserted.
[in]dataA new link is created holding this data.
Returns
The link that has been created for data.

◆ sc_list_memory_used()

size_t sc_list_memory_used ( sc_list_t list,
int  is_dynamic 
)

Calculate the total memory used by a list.

Parameters
[in]listThe list.
[in]is_dynamicTrue if created with sc_list_new, false if initialized with sc_list_init
Returns
Memory used in bytes.

◆ sc_list_new()

sc_list_t* sc_list_new ( sc_mempool_t allocator)

Allocate a new, empty linked list.

Parameters
[in]allocatorMemory allocator for sc_link_t, can be NULL in which case an internal allocator is created.
Returns
Pointer to a newly allocated, empty list object.

◆ sc_list_pop()

void* sc_list_pop ( sc_list_t list)

Remove an element from the front of the list.

Parameters
[in,out]listValid, non-empty list object.
Returns
Returns the data of the removed first list element.

◆ sc_list_prepend()

sc_link_t* sc_list_prepend ( sc_list_t list,
void *  data 
)

Insert a list element at the beginning of the list.

Parameters
[in,out]listValid list object.
[in]dataA new link is created holding this data.
Returns
The link that has been created for data.

◆ sc_list_remove()

void* sc_list_remove ( sc_list_t list,
sc_link_t pred 
)

Remove an element after a given list position.

Parameters
[in,out]listValid, non-empty list object.
[in]predThe predecessor of the element to be removed. If pred == NULL, the first element is removed, which is equivalent to calling sc_list_pop (list).
Returns
The data of the removed and freed link.

◆ sc_list_reset()

void sc_list_reset ( sc_list_t list)

Remove all elements from a list in O(N).

Parameters
[in,out]listList structure to be emptied.
Note
Calling sc_list_init, then any list operations, then sc_list_reset is memory neutral.

◆ sc_list_unlink()

void sc_list_unlink ( sc_list_t list)

Unlink all list elements without returning them to the mempool.

This runs in O(1) but is dangerous because the link memory stays alive.

Parameters
[in,out]listList structure to be unlinked.

◆ sc_mempool_destroy()

void sc_mempool_destroy ( sc_mempool_t mempool)

Destroy a mempool structure.

All elements that are still in use are invalidated.

Parameters
[in,out]mempoolIts memory is freed.

◆ sc_mempool_destroy_null()

void sc_mempool_destroy_null ( sc_mempool_t **  pmempool)

Destroy a mempool structure.

All elements that are still in use are invalidated.

Parameters
[in,out]pmempoolAddress of pointer to memory pool. Its memory is freed, pointer is NULLed.

◆ sc_mempool_init()

void sc_mempool_init ( sc_mempool_t mempool,
size_t  elem_size 
)

Same as sc_mempool_new, but for an already allocated object.

Parameters
[out]mempoolAllocated memory is overwritten and initialized.
[in]elem_sizeSize of one element in bytes.

◆ sc_mempool_memory_used()

size_t sc_mempool_memory_used ( sc_mempool_t mempool)

Calculate the memory used by a memory pool.

Parameters
[in]mempoolThe memory pool.
Returns
Memory used in bytes.

◆ sc_mempool_new()

sc_mempool_t* sc_mempool_new ( size_t  elem_size)

Creates a new mempool structure with the zero_and_persist option off.

The contents of any elements returned by sc_mempool_alloc are undefined.

Parameters
[in]elem_sizeSize of one element in bytes.
Returns
Returns an allocated and initialized memory pool.

◆ sc_mempool_new_zero_and_persist()

sc_mempool_t* sc_mempool_new_zero_and_persist ( size_t  elem_size)

Creates a new mempool structure with the zero_and_persist option on.

The memory of newly created elements is zero'd out, and the contents of an element are not touched between freeing and re-returning it.

Parameters
[in]elem_sizeSize of one element in bytes.
Returns
Returns an allocated and initialized memory pool.

◆ sc_mempool_reset()

void sc_mempool_reset ( sc_mempool_t mempool)

Same as sc_mempool_destroy, but does not free the pointer.

Parameters
[in,out]mempoolValid mempool object is deallocated. The structure memory itself stays alive.

◆ sc_mempool_truncate()

void sc_mempool_truncate ( sc_mempool_t mempool)

Invalidates all previously returned pointers, resets count to 0.

Parameters
[in,out]mempoolValid mempool is truncated.

◆ sc_mstamp_alloc()

void* sc_mstamp_alloc ( sc_mstamp_t mst)

Return a new item.

The memory returned will stay legal until container is destroyed or truncated.

Parameters
[in,out]mstProperly initialized stamp container.
Returns
Pointer to an item ready to use. Legal until sc_mstamp_reset or sc_mstamp_truncate is called on mst.

◆ sc_mstamp_init()

void sc_mstamp_init ( sc_mstamp_t mst,
size_t  stamp_unit,
size_t  elem_size 
)

Initialize a memory stamp container.

We provide allocation of fixed-size memory items without allocating new memory in every request. Instead we block the allocations in what we call a stamp of multiple items. Even if no allocations are done, the container's internal memory must be freed eventually by sc_mstamp_reset.

Parameters
[in,out]mstLegal pointer to a stamp structure.
[in]stamp_unitSize of each memory block that we allocate. If it is larger than the element size, we may place more than one element in it. Passing 0 is legal and forces stamps that hold one item each.
[in]elem_sizeSize of each item. Passing 0 is legal. In that case, sc_mstamp_alloc returns NULL.

◆ sc_mstamp_memory_used()

size_t sc_mstamp_memory_used ( sc_mstamp_t mst)

Return memory size in bytes of all data allocated in the container.

Parameters
[in]mstProperly initialized stamp container.
Returns
Total container memory size in bytes.

◆ sc_mstamp_reset()

void sc_mstamp_reset ( sc_mstamp_t mst)

Free all memory in a stamp structure and all items previously returned.

Parameters
[in,out]mstProperly initialized stamp container. On output, the structure is undefined.

◆ sc_mstamp_truncate()

void sc_mstamp_truncate ( sc_mstamp_t mst)

Free all memory in a stamp structure and initialize it anew.

Equivalent to calling sc_mstamp_reset followed by sc_mstamp_init with the same stamp_unit and elem_size.

Parameters
[in,out]mstProperly initialized stamp container. On output, its elements have been freed and it is ready for further use.

◆ sc_recycle_array_init()

void sc_recycle_array_init ( sc_recycle_array_t rec_array,
size_t  elem_size 
)

Initialize a recycle array.

Parameters
[out]rec_arrayUninitialized turned into a recycle array.
[in]elem_sizeSize of the objects to be stored in the array.

◆ sc_recycle_array_insert()

void* sc_recycle_array_insert ( sc_recycle_array_t rec_array,
size_t *  position 
)

Insert an object into the recycle array.

The object is not copied into the array. Use the return value for that.

Parameters
[in,out]rec_arrayValid recycle array.
[out]positionIf position != NULL, *position is set to the array position of the inserted object.
Returns
The new address of the object in the array.

◆ sc_recycle_array_remove()

void* sc_recycle_array_remove ( sc_recycle_array_t rec_array,
size_t  position 
)

Remove an object from the recycle array.

It must be valid.

Parameters
[in,out]rec_arrayValid recycle array.
[in]positionIndex into the array for the object to remove.
Returns
The pointer to the removed object. Will be valid as long as no other function is called on this recycle array.

◆ sc_recycle_array_reset()

void sc_recycle_array_reset ( sc_recycle_array_t rec_array)

Reset a recycle array.

As with all _reset functions, calling _init, then any array operations, then _reset is memory neutral.