Files | |
| file | array.c |
| Dynamic arrays implementation. | |
| file | array.h |
| Dynamic arrays header. | |
Functions | |
| void | array_init (array *_a) |
| Initialize an array. | |
| array * | array_create () |
| Create and initialize a new array. | |
| void * | array_allocate (array *_a, size_t _sz, int _pos) |
| Allocate more space. | |
| void * | array_get (array *_a, size_t _sz, int _pos) |
| Get an object from the array. | |
| size_t | array_length (array *_a, size_t _sz) |
| Computes the size of an array. | |
| void | array_truncate (array *_a, size_t _sz, int _len) |
| Reduces the number of initialized bytes. | |
| void | array_reset (array *_a) |
| Reset an array as if it has just been created. | |
| void | array_delete (array *_a) |
| Deletes an array. | |
| int | array_equal (array *_a, array *_b) |
| Compare two arrays. | |
| void | array_sort (array *_a, size_t _sz, int(*_cmp)(const void *, const void *)) |
| Sort an array. | |
An array variable keeps track of
The array library provides various allocation and inspection functions.
| void array_init | ( | array * | _a | ) |
Initialize an array.
This function initializes an array, setting all values to 0 or NULL respectively. This function is here for portability, because not all systems handle NULL as a seris of binary zeros.
| _a | an array |
Definition at line 71 of file array.c.
References array::data, array::sz_alloc, and array::sz_init.
Referenced by array_create().
| array* array_create | ( | ) |
Create and initialize a new array.
NULL on failure Definition at line 86 of file array.c.
References array_init().
| void* array_allocate | ( | array * | _a, | |
| size_t | _sz, | |||
| int | _pos | |||
| ) |
Allocate more space.
array_allocate() makes sure that enough bytes are allocated in _a for at least _pos+1 objects of size _sz. If not enough bytes are allocated, array_allocate() allocates more bytes, moving the dynamically allocated region if necessary. array_allocate() often allocates somewhat more bytes than necessary, to save time later.
array_allocate() then makes sure that the number of bytes initialized covers at least those _pos+1 objects. If not enough bytes are initialized, array_allocate() initializes more bytes (setting them to 0), up to exactly the end of the _pos+1st object.
array_allocate() then returns a pointer to the _pos+1st object; i.e., object number pos, with objects numbered starting at 0. This pointer can be used to change or inspect the object. The pointer can continue to be used through subsequent calls to array_get(), array_start(), array_length(), and array_bytes(), but it must not be used after any other operations on this array (FIXME: see if this is still correct).
If something goes wrong, array_allocate() returns NULL, setting errno appropriately, without touching _a. In particular, array_allocate() returns 0 if:
| _a | an array | |
| _sz | object size | |
| _pos | position |
_pos+1st object on success, NULL on failure Definition at line 129 of file array.c.
References array_initialize(), array::data, array::sz_alloc, and array::sz_init.
Referenced by array_catb(), and main().
| void* array_get | ( | array * | _a, | |
| size_t | _sz, | |||
| int | _pos | |||
| ) |
Get an object from the array.
array_get() is similar to array_allocate(), but it does not allocate any extra bytes, and it does not initialize any extra bytes. It returns NULL if _a is unallocated, for example, or if fewer than (_pos+1)*_sz bytes are initialized.
| _a | an array | |
| _sz | object size | |
| _pos | object position |
NULL on failure Definition at line 190 of file array.c.
References array::data, and array::sz_init.
| size_t array_length | ( | array * | _a, | |
| size_t | _sz | |||
| ) |
Computes the size of an array.
array_length() returns the number of initialized bytes in _a, divided by the object size _sz. In other words, array_get() will succeed for positions 0 through array_length()-1; it will fail for position array_length().
| _a | an array | |
| _sz | object size |
Definition at line 212 of file array.c.
References array::sz_init.
Referenced by array_sort().
| void array_truncate | ( | array * | _a, | |
| size_t | _sz, | |||
| int | _len | |||
| ) |
Reduces the number of initialized bytes.
array_truncate() reduces the number of initialized bytes in _a to exactly _len*_sz. If the number of initialized bytes was already this small (or smaller), array_truncate() has no effect. If _len is negative, array_truncate() has no effect.
array_truncate() does not change the allocation in _a. If you want to free the memory used by _a, use array_reset(), array_delete() or array_destroy().
| _a | an array | |
| _sz | object size | |
| _len | new length of the array |
Definition at line 233 of file array.c.
References array::sz_init.
| void array_reset | ( | array * | _a | ) |
Reset an array as if it has just been created.
array_reset() frees the region that _a points to and adjusts sz_init and sz_alloc.
| _a | an array |
Definition at line 249 of file array.c.
References array::data, array::sz_alloc, and array::sz_init.
Referenced by array_delete().
| void array_delete | ( | array * | _a | ) |
Deletes an array.
This function frees the region that _a points to and adjusts sz_init and sz_alloc. Additionally, it frees the array itself.
The memory region that the argument pointer points to is undefined after a call to array_delete(), don't use this pointer and/or set it to NULL.
| _a | an array |
Definition at line 269 of file array.c.
References array_reset().
Compare two arrays.
This function compares two arrays, returning nonzero if _a and _b have the same contents, i.e., _a and _b have the same sequence of initialized bytes. Otherwise it returns 0.
| _a | an array | |
| _b | another array |
Definition at line 285 of file array.c.
References array::data, and array::sz_init.
| void array_sort | ( | array * | _a, | |
| size_t | _sz, | |||
| int(*)(const void *, const void *) | _cmp | |||
| ) |
Sort an array.
This function sorts the array _a with objects of size _sz using the comparison function _cmp.
The contents of the array _a with objects of size _sz are sorted in ascending order according to a comparison function pointed to by _cmp, which is called with two arguments that point to the objects being compared.
The comparison function must return an integer less than, equal to, or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second. If two members compare as equal, their order in the sorted array is undefined.
| _a | an array | |
| _sz | object size | |
| _cmp | comparison function |
Definition at line 324 of file array.c.
References array_length(), and array::data.
1.5.1-p1. Thank you,