Lib:Reference Manual
From GNUpdf
pdf_status_t st;
st = pdf_i64_add (dest, addend_1, addend_2);
if (st != PDF_OK)
{
pdf_perror (st, "Couldn't do i64 addition");
}
|
- Function: void pdf_error (const pdf_status_t status, FILE *fd, const char *format, ...)
Prints a message with `fprintf (fd, format, ...)'; if status is nonzero, also prints the corresponding message.
- Parameters
- status
status code
- fd
file descriptor open for writing
- format
string format for the message
- ...
format's arguments
- Returns
nothing
- Usage example
pdf_status_t st; st = pdf_i64_add (dest, addend_1, addend_2); if (st != PDF_OK) { pdf_error (st, logfd, "Couldn't do i64 addition"); }
Debugging procedures
For each layer there is a macro procedure defined. The file name and the line number at which the error ocurred is printed to stderr followed by message.
- Macro: PDF_DEBUG_BASE (message, ...)
- Macro: PDF_DEBUG_OBJECT (message, ...)
- Macro: PDF_DEBUG_DOCUMENT (message, ...)
- Macro: PDF_DEBUG_PAGE (message, ...)
- Parameters
- message
a 'const char*' string
- ...
message's arguments
- Returns
nothing
- Usage example
PDF_DEBUG_BASE("Testing macro '%s' '%d' '%lf'", "string", 7, 10.1);
Output format
The output format for these macros is,
GNU PDF:***DEBUG <layer>***:<file-name>:<line-number>: <message>.
For example,
GNU PDF:***DEBUG BASE***:pdf-memory.c:344: insufficient memory.
Memory Allocation
The memory allocation module provides system-independent heap memory allocation and deallocation. The usual malloc/free/realloc schema is used to provide this service.
- Function: void* pdf_alloc (const pdf_size_t size)
Allocates heap memory.
- Parameters
-
- size
The requested number of octects to allocate.
- Returns
A pointer to the newly allocated memory.
If there is not enough available memory to satisfy the petition then
NULLis returned.- Usage example
int *p; p = (int *) pdf_alloc (sizeof(int)); *p = 666;
- Function: void pdf_dealloc (const void *pointer)
Deallocates heap memory.
- Parameters
-
- pointer
A pointer pointing to the memory we want to deallocate. The memory to deallocate should have been previously allocated using
pdf_alloc.
- Returns
None.
- Usage Example
-
char *p; p = (char *) pdf_alloc (21); pdf_dealloc (p);
- Function: void* pdf_realloc (const void *pointer, const pdf_size_t size)
Reallocates memory.
- Parameters
-
- pointer
A pointer to previously allocated memory.
The memory to reallocate should have been allocated using
pdf_allocorpdf_realloc.- size
The new size of the allocated memory chunk.
If the requested size is shorter than the original size of the allocated memory then it is truncated. Any previous contents in the memory will be lost.
If the requested size is larger or equal than the original size of the allocated memory then the previous contents of the allocated memory remains. The contents of newly allocated memory are undetermined.
If there is not enough available memory to satisfy the petition a fatal error is signaled killing the current process. An error status is returned to the operating system.
- Returns
A pointer to the reallocated memory.
- Usage Example
char *p; p = (char *) pdf_alloc (4); strncpy (p, "abcd", 4); /* p now points to "abcd" */ p = (char *) pdf_realloc (5); p[4] = 'e'; /* p now points to "abcde" */ p = (char *) pdf_realloc (4); /* p now points to "abcd" */ pdf_dealloc (p);
Basic Types
Boolean Types
- Data Type: pdf_bool_t
A boolean value.
The following constants defines the valid values to be hold in a
pdf_bool_t variable:
- Constant: PDF_TRUE
Logical true.
- Constant: PDF_FALSE
Logical false.
Numeric Types
- Data Type: pdf_i32_t
Signed 32 bits integer.
- Data Type: pdf_u32_t
Unsigned 32 bits integer.
The following constants are defined in order to define the valid value ranges for these data types:
- Constant: PDF_I32_MAX
Maximum value able to be stored in a
pdf_i32_tvariable.
- Constant: PDF_I32_MIN
Minimum value able to be stored in a
pdf_i32_tvariable.
- Constant: PDF_U32_MAX
Maximum value able to be stored in a
pdf_u32_tvariable.
- Constant: PDF_U32_MIN
Minimum value able to be stored in a
pdf_u32_tvariable.
Big Numbers
An implementation of Big numbers (64 bit) is also provided. These bignums can be used in machines not providing true 64 bit integers.
- Data Type: pdf_i64_t
A variable of type pdf_i64_t is capabable of representing 64 bit signed integers.
- Function: pdf_i64_t pdf_i64_new (const pdf_i32_t high, const pdf_u32_t low)
Create a new i64 variable from one 32 bit signed integer and a 32 bit unsigned integer.
- Parameters
- high
The high (signed) part of the 64 bit integer.
- low
The low (unsigned) part of the 64 bit integer.
- Returns
The newly created i64 object.
- Usage example
pdf_i64_t bignum; bignum = pdf_i64_new((32 << 1),10); /*bignum is now -10*/
- Function: void pdf_i64_assign (pdf_i64_t *bignum, const pdf_i32_t high, const pdf_u32_t low, pdf_status_t *p_status)
Assign a value coming from one 32 bit signed integer and a 32 bit unsigned integer to a i64 integer.
- Parameters
- high
The high (signed) part of the 64 bit integer.
- low
The low (unsigned) part of the 64 bit integer.
- bignum
Variable that stores 64 bit integer
- Returns
A pdf status value:
-
PDF_OK Operation successful
-
- Usage example
pdf_i64_t *bignum; pdf_i64_t result; pdf_status_t *p_status; result = pdf_i64_new(0, 0); bignum = &result; pdf_i64_assign(bignum, (32 << 1), 10, p_status); if (*p_status != PDF_OK) /*bignum is now -10*/ { /* Error code */ }
- Function: void pdf_i64_assign_quick (pdf_i64_t *bignum, const pdf_i32_t value, pdf_status_t *p_status)
Assign a value coming from one 32 bit signed integer to a i64 integer.
- Parameters
- value
A signed 32 bit integer
- bignum
Variable that stores 64 bit integer
- Returns
A pdf status value:
-
PDF_OK Operation successful
-
- Usage example
pdf_i64_t *bignum; pdf_i64_t result; pdf_status_t *p_status; result = pdf_i64_new(0, 0); bignum = &result; pdf_i64_assign_quick(bignum, -10, p_status); if (*p_status != PDF_OK) /*bignum is now -10*/ { /* Error code */ }
- Function: void pdf_i64_copy (const pdf_i64_t orig, pdf_i64_t *copy, pdf_status_t *p_status)
Copies the data from orig to copy.
- Parameters
- orig
Original variable whose data is to be copied.
- copy
Variable where data is copied to.
- Returns
A pdf status value:
-
PDF_OK Operation successful
-
- Usage example
pdf_i64_t orig; pdf_i64_t *copy; pdf_status_t *p_status; orig = pdf_i64_new(0, 10); pdf_i64_copy(orig, copy,p_status) if ( *p_status != PDF_OK) /*Now copy is also 10*/ { /* Error code */ }
- Function: void pdf_i64_add (pdf_i64_t *dest, const pdf_i64_t addend1, const pdf_i64_t addend2, pdf_status_t *p_status)
Adds two 64 bit numbers
- Parameters
- addend1
First addend of the sum
- addend2
Second addend of the sum
- dest
Where 64 bit result is stored
- Returns
A pdf status value:
-
PDF_OK Operation successful
-
- Usage example
pdf_i64_t *dest; pdf_i64_t result; pdf_i64_t addend_1; pdf_i64_t addend_2; pdf_status_t *p_status; addend_1 = pdf_i64_new(0, 25); addend_2 = pdf_i64_new(0, 35); result = pdf_i64_new(0, 0); dest = &result; pdf_i64_add (dest, addend_1, addend_2,p_status); if (*p_status != PDF_OK) /* Now dest is 60 */ { /* Error code */ }
- Function: void pdf_i64_add_i32 (pdf_i64_t *dest, const pdf_i64_t addend1, const pdf_i32_t addend2, pdf_status_t *p_status)
Adds a 64bit number and a 32bit number.
- Parameters
- addend1
First addend of the sum (64bit type)
- addend2
Second addend of the sum (32 bit)
- dest
Where 64 bit result is stored
- Returns
A pdf status value:
-
PDF_OK Operation successful
-
- Usage example
pdf_i64_t *dest; pdf_i64_t result; pdf_i64_t addend_1; pdf_status_t *p_status; addend_1 = pdf_i64_new(0, 25); result = pdf_i64_new(0, 0); dest = &result; pdf_i64_add (dest, addend_1, 35,p_status) if (*p_status != PDF_OK) /* Now dest is 60 */ { /* Error code */ }
- Function: void pdf_i64_subtraction (pdf_i64_t *dest, const pdf_i64_t minuend, const pdf_i64_t subtrahend, pdf_status_t *p_status)
Finds the difference between two 64 bit numbers
- Parameters
- minuend
The minuend of the subtraction
- subtrahend
The subtrahend of the subtraction
- dest
Where 64 bit result is stored
- Returns
A pdf status value:
-
PDF_OK Operation successful
-
- Usage example
pdf_i64_t *dest; pdf_i64_t result; pdf_i64_t minuend; pdf_i64_t subtrahend; pdf_status_t *p_status; minuend = pdf_i64_new(0, 25); subtrahend = pdf_i64_new(0, 35); result = pdf_i64_new(0, 0); dest = &result; pdf_i64_subtraction (dest, minuend, subtrahend,p_status) if (*p_status != PDF_OK) /* Now dest is -10 */ { /* Error code */ }
- Function: void pdf_i64_subtraction_i32_min (pdf_i64_t *dest, const pdf_i32_t minuend, const pdf_i64_t subtrahend, pdf_status_t *p_status)
Finds the difference between a 32bit number and a 64bit number
- Parameters
- minuend
The minuend of the subtraction (32 bits)
- subtrahend
The subtrahend of the subtraction (64 bits type)
- dest
Where 64 bit result is stored
- Returns
A pdf status value:
-
PDF_OK Operation successful
-
- Usage example
pdf_i64_t *dest; pdf_i64_t result; pdf_i64_t subtrahend; pdf_status_t *p_status; subtrahend = pdf_i64_new(0, 35); result = pdf_i64_new(0, 0); dest = &result; pdf_i64_subtraction (dest, 25, subtrahend,p_status) if (*p_status != PDF_OK) /* Now dest is -10 */ { /* Error code */ }
- Function: void pdf_i64_subtraction_i32_sub (pdf_i64_t *dest, const pdf_i64_t minuend, const pdf_i32_t subtrahend, pdf_status_t *p_status)
Finds the difference between a 64bit number and a 32bit number
- Parameters
- minuend
The minuend of the subtraction (64 bits type)
- subtrahend
The subtrahend of the subtraction (32 bits)
- dest
Where 64 bit result is stored
- Returns
A pdf status value:
-
PDF_OK Operation successful
-
- Usage example
pdf_i64_t *dest; pdf_i64_t result; pdf_i64_t minuend; pdf_status_t *p_status; minuend = pdf_i64_new(0, 25); result = pdf_i64_new(0, 0); dest = &result; pdf_i64_subtraction (dest, minuend, 35,p_status); if ( != PDF_OK) /* Now dest is -10 */ { /* Error code */ }
- Function: void pdf_i64_mult (pdf_i64_t *dest, const pdf_i64_t factor_1, const pdf_i64_t factor_2, pdf_status_t *p_status)
Multiplication of two 64 bit numbers
- Parameters
- factor_1
First factor in the multiplication
- factor_2
Second factor in the multiplication
- dest
Where 64 bit result is stored
- Returns
A pdf status value:
-
PDF_OK Operation successful
-
- Usage example
pdf_i64_t *dest; pdf_i64_t result; pdf_i64_t factor_1; pdf_i64_t factor_2; pdf_status_t *p_status; factor_1 = pdf_i64_new (0, 10); factor_2 = pdf_i64_new (0, 100); result = pdf_i64_new (0, 0); dest = &result; pdf_i64_mult (dest, factor_1, factor_2,p_status); if ( *p_status != PDF_OK) /* Now dest is 1000 */ { /* Error code */ }
- Function: void pdf_i64_mult_i32 (pdf_i64_t *dest, const pdf_i64_t factor_1, const pdf_i32_t factor_2, pdf_status_t *p_status)
Multiplication of a 64bit number and a 32bit number
- Parameters
- factor_1
First factor in the multiplication (64 bits)
- factor_2
Second factor in the multiplication (32bits)
- dest
Where 64 bit result is stored
- Returns
A pdf status value:
-
PDF_OK Operation successful
-
- Usage example
pdf_i64_t *dest; pdf_i64_t result; pdf_i64_t factor_1; factor_1 = pdf_i64_new (0, 10); result = pdf_i64_new (0, 0); dest = &result; pdf_i64_mult (dest, factor_1, 100,p_status) if (*p_status != PDF_OK) /* Now dest is 1000 */ { /* Error code */ }
- Function: void pdf_i64_div (pdf_i64_t *dest, const pdf_i64_t dividend, const pdf_i64_t divisor, pdf_status_t *p_status)
Division of two 64 bit numbers
- Parameters
- dividend
The dividend in the division
- divisor
The divisor in the division
- dest
Where 64 bit result is stored
- Returns
PDF_OK Operation successful
- Usage example
pdf_i64_t *dest; pdf_i64_t result; pdf_i64_t dividend; pdf_i64_t divisor; dividend = pdf_i64_new(0, 200); divisor = pdf_i64_new(0, 10); result = pdf_i64_new(0, 0); dest = &result; pdf_i64_div (dest, dividend, divisor,p_status); if(*p_status != PDF_OK) /* Now dest is 20 */ { /* Error code */ }
- Function: void pdf_i64_div_i32_dividend (pdf_i64_t *dest, const pdf_i32_t dividend, const pdf_i64_t divisor, pdf_status_t *p_status)
Division of a 32bit number and a 64bit number
- Parameters
- dividend
The dividend in the division (64 bits)
- divisor
The divisor in the division (32 bits)
- dest
Where 64 bit result is stored
- Returns
PDF_OK Operation successful
- Usage example
pdf_i64_t *dest; pdf_i64_t result; pdf_i64_t divisor; divisor = pdf_i64_new(0, 10); result = pdf_i64_new(0, 0); dest = &result; if (pdf_i64_div (dest, 200, divisor) != PDF_OK) /* Now dest is 20 */ { /* Error code */ }
- Function: void pdf_i64_div_i32_divisor (pdf_i64_t *dest, const pdf_i64_t dividend, const pdf_i32_t divisor, pdf_status_t *p_status)
Division of a 64bit number and a 32bit number
- Parameters
- dividend
The dividend in the division (64 bits)
- divisor
The divisor in the division (32 bits)
- dest
Where 64 bit result is stored
- Returns
PDF_OK Operation successful
- Usage example
pdf_i64_t *dest; pdf_i64_t result; pdf_i64_t dividend; dividend = pdf_i64_new(0, 200); result = pdf_i64_new(0, 0); dest = &result; if (pdf_i64_div (dest, dividend, 10) != PDF_OK) /* Now dest is 20 */ { /* Error code */ }
- Function: void pdf_i64_mod (pdf_i64_t *dest, const pdf_i64_t dividend, const pdf_i64_t divisor, pdf_status_t *p_status)
Returns the remainder of the division between two 64 bit numbers
- Parameters
- dividend
The dividend in the division
- divisor
The divisor in the division
- dest
Where 64 bit result is stored
- Returns
A pdf status value:
-
PDF_OK Operation successful
-
- Usage example
pdf_i64_t *dest; pdf_i64_t result; pdf_i64_t dividend; pdf_i64_t divisor; pdf_status_t *p_status; dividend = pdf_i64_new(0, 105); divisor = pdf_i64_new(0, 10); result = pdf_i64_new(0, 0); dest = &result; pdf_i64_mod (dest, dividend, divisor,p_status); if ( *p_status != PDF_OK) /* Now dest is 5 */ { /* Error code */ }
- Function: void pdf_i64_mod_i32_dividend (pdf_i64_t *dest, const pdf_i32_t dividend, const pdf_i64_t divisor, pdf_status_t *p_status)
Returns the remainder of the division between a 32bit number and a 64bit number
- Parameters
- dividend
The dividend in the division (32bits)
- divisor
The divisor in the division (64bits)
- dest
Where 64 bit result is stored
- Returns
A pdf status value:
-
PDF_OK Operation successful
-
- Usage example
pdf_i64_t *dest; pdf_i64_t result; pdf_i64_t divisor; divisor = pdf_i64_new(0, 10); result = pdf_i64_new(0, 0); dest = &result; if (pdf_i64_mod (dest, 105, divisor) != PDF_OK) /* Now dest is 5 */ { /* Error code */ }
- Function: void pdf_i64_mod_i32_divisor (pdf_i64_t *dest, const pdf_i64_t dividend, const pdf_i32_t divisor, pdf_status_t *p_status)
Returns the remainder of the division between a 64bit number and a 32bit number
- Parameters
- dividend
The dividend in the division (64 bits)
- divisor
The divisor in the division (32 bits)
- dest
Where 64 bit result is stored
- Returns
A pdf status value:
-
PDF_OK Operation successful
-
- Usage example
pdf_i64_t *dest; pdf_i64_t result; pdf_i64_t dividend; dividend = pdf_i64_new(0, 105); result = pdf_i64_new(0, 0); dest = &result; if (pdf_i64_mod (dest, dividend, 10) != PDF_OK) /* Now dest is 5 */ { /* Error code */ }
- Function: void pdf_i64_abs (pdf_i64_t *dest, const pdf_i64_t number, pdf_status_t *p_status)
Returns the absolute value
- Parameters
- number
pdf_i64_t type variable
- dest
Where 64 bit result is stored
- Returns
A pdf status value:
-
PDF_OK Operation successful
-
- Usage example
pdf_i64_t *dest; pdf_i65_t result; pdf_i64_t number; pdf_status_t *p_status; number = pdf_i64_new ((32 << 1), 105); /*number is -105*/ result = pdf_i64_new (0, 0); dest = &result; pdf_i64_abs (dest, number,p_status) if ( *p_status != PDF_OK) /* now dest stores 105 */ { /* Error code */ }
- Function: int pdf_i64_cmp (const pdf_i64_t number_1, const pdf_i64_t number_2)
Compares two 64 bit integers
- Parameters
- number_1
pdf_i64_t type variable
- number_2
pdf_i64_t type variable
- Returns
An integer:
-
0 If numbers are equal
-
1 If number_1 is greater than number_2
-
-1 If number_2 is greater than number_1
-
- Usage example
pdf_i65_t number_1; pdf_i64_t number_2; int result; number_1 = pdf_i64_new ((32 << 1), 10); /* number_1 is -10 */ number_2 = pdf_i64_new (0, 10); /* number_2 is 10 */ result = pdf_i64_cmp (number_1, number_2); /* Now result is -1 */
- Function: int pdf_i64_cmp_i32 (const pdf_i64_t number_1, const pdf_i32_t number_2)
Compares a 64bit number and a 32bit number
- Parameters
- number_1
pdf_i64_t type variable
- number_2
pdf_i32_t type variable
- Returns
An integer:
-
0 If numbers are equal
-
1 If number_1 is greater than number_2
-
-1 If number_2 is greater than number_1
-
- Usage example
pdf_i65_t number_1; int result; number_1 = pdf_i64_new ((32 << 1), 10); /* number_1 is -10 */ result = pdf_i64_cmp (number_1, 10); /* Now result is -1 */
- Function: void pdf_i64_neg (pdf_i64_t *dest, const pdf_i64_t number, pdf_status_t *p_status)
Changes sign of 64 bit integer
- Parameters
- number
pdf_i64_t type variable
- Returns
A pdf status value:
-
PDF_OK Operation successful
-
- Usage example
pdf_i64_t *dest; pdf_i65_t result; pdf_i64_t number; pdf_status_t *p_status; number = pdf_i64_new (0, 10); result = pdf_i64_new (0, 0); dest = &result; pdf_i64_neg (dest, number,p_status) if ( *p_status != PDF_OK) /* now dest stores -10 */ { /* Error code */ }
- Function: pdf_i32_t pdf_i64_to_i32 (const pdf_i64_t bignum)
Converts a pdf_i64_t to a 32bit value. If number can't be represented in 32 bits the result is undefined, so should be used with caution.
- Parameters
- bignum
pdf_i64_t type variable
- Returns
A pdf status value:
-
PDF_OK Operation successful
-
- Usage example
pdf_i32_t num; pdf_i64_t bignum; bignum = pdf_i64_new (0, 10); num = pdf_i64_to_i32(bignum);
Hash Tables
Hash Table Types
- Data Type: pdf_hash_t
A Hash Table able to store key/value pairs. A key may be any NULL-terminated string.
- Data Type: pdf_hash_iterator_t
An iterator over the keys of a Hash Table.
- Data Type: void (*pdf_hash_element_dispose_fn_t) (const void *elt)
A function type for disposing hash elements.
- Data Type: void (*pdf_hash_key_dispose_fn_t) (const void *key)
A function type for disposing hash keys.
Creating and Destroying Hash Tables
- Function: pdf_status_t pdf_hash_new (pdf_hash_key_dispose_fn_t dispose_key_fn, pdf_hash_t *table)
Create a new empty hash table. When some element is removed dispose_key_fn are called, can be NULL.
- Parameters
- dispose_key_fn
A pointer to a hash table element key dispose function or NULL.
- table
A pointer to a hash table.
- Returns
A pdf status value:
-
PDF_OK The operation succeeded.
-
PDF_ENOMEM Not enough memory.
-
PDF_EBADDATA Invalid table pointer.
-
- Usage example
pdf_hash_t hash; /* Create an instance of a hash without a disposal function */ if (pdf_hash_new (NULL, &hash) != PDF_OK) { /* Error creating the hash table */ }
- Function: pdf_status_t pdf_hash_destroy (pdf_hash_t table)
Destroy a hash table. The elements of the table are disposed first.
- Parameters
- table
A hash table.
- Returns
A pdf status value:
-
PDF_OK The operation succeeded.
-
- Usage example
pdf_hash_t hash; if (pdf_hash_new (NULL, &hash) == PDF_OK) { /* Destroy the hash */ pdf_hash_destroy (hash); } else { /* Error creating the hash table */ }
Hash Table properties
- Function: pdf_size_t pdf_hash_size (const pdf_hash_t table)
Returns the number of entries in table.
- Parameters
- table
A hash table.
- Returns
The number of entries.
- Usage example
pdf_hash_t hash; /* Create a new hash */ if (pdf_hash_new (NULL, &hash) == PDF_OK) { /* Add some elements to the hash */ pdf_hash_add (hash, "first-key", "first-value", NULL); pdf_hash_add (hash, "second-key", "second-value", NULL); pdf_hash_add (hash, "third-key", "third-key", NULL); /* This call should return 3 */ pdf_hash_size (hash); }
Working with keys
- Function: pdf_bool_t pdf_hash_key_p (const pdf_hash_t table, const char *key)
Returns a boolean value indicating whether an element with key key exists in table.
- Parameters
- table
A hash table.
- key
A valid key string.
- Returns
A pdf boolean value:
-
PDF_TRUE An element associated with key exists.
-
PDF_FALSE There is no element associated with key.
-
- Usage example
pdf_hash_t hash; /* Create a new hash */ if (pdf_hash_new (NULL, &hash) == PDF_OK) { /* Add some elements to the hash */ pdf_hash_add (hash, "a-key", "a-value", NULL); if (pdf_hash_key_p (hash, "a-key")) { /* The program enters here */ } if (pdf_hash_key_p (hash, "x-key")) { /* The program doesnt reach this */ } }
- Function: pdf_status_t pdf_hash_rename (pdf_hash_t table, const char *key, const char *new_key)
Renames the key key to new_key in table.
- Parameters
- table
A hash table.
- key
A valid key string.
- new_key
A valid key string.
- Returns
A pdf status value:
-
PDF_OK The operation succeded.
-
PDF_ERROR The key is not associated with any element in table.
-
PDF_EBADDATA Either table or a key string is invalid or NULL.
-
- Usage example
pdf_hash_t hash; /* Create a new hash */ if (pdf_hash_new (NULL, &hash) == PDF_OK) { /* Add an element to the hash */ pdf_hash_add (hash, "a-key", "a-value", NULL); if (pdf_hash_key_p (hash, "a-key")) { /* The program enters here */ } /* Rename the key */ pdf_hash_rename (hash, "a-key", "b-key"); if (pdf_hash_key_p (hash, "a-key")) { /* The program doesnt enter here */ } if (pdf_hash_key_p (hash, "b-key")) { /* The program enters here */ } }
Adding and removing elements
- Function: pdf_status_t pdf_hash_add (pdf_hash_t table, const char *key, const void *element, pdf_hash_element_dispose_fn_t disp_fn )
Adds the element element with the associated key key to table. If key already exists nothing is done.
- Parameters
- table
A hash table.
- key
A valid key string.
- element
A pointer to the element being added.
- disp_fn
A function called when element is removed. If NULL is given nothing is done.
- Returns
A pdf status value:
-
PDF_OK The operation succeeded.
-
PDF_ENOMEM Not enough memory.
-
PDF_EBADDATA Either table, key or element is invalid.
-
- Usage example
pdf_hash_t hash; /* Create a new hash */ if (pdf_hash_new (NULL, &hash) == PDF_OK) { /* Add some elements to the hash */ pdf_hash_add (hash, "first-key", "first-value", NULL); pdf_hash_add (hash, "second-key", "second-value", NULL); pdf_hash_add (hash, "third-key", "third-key", NULL); }
- Function: pdf_status_t pdf_hash_remove (pdf_hash_t table, const char *key)
Removes the element associated with key from table. The element is disposed first.
- Parameters
- table
A hash table.
- key
A valid key string.
- Returns
A pdf status value:
-
PDF_OK The operation succeeded.
-
PDF_EBADDATA Invalid table or key.
-
PDF_ERROR The key wasn't found.
-
- Usage example
pdf_hash_t hash; /* Create a new hash */ if (pdf_hash_new (NULL, &hash) == PDF_OK) { /* Add an element to the hash... */ pdf_hash_add (hash, "a-key", "a-value", NULL); /* And remove it */ pdf_hash_remove (hash, "a-key"); }
Searching elements
- Function: pdf_status_t pdf_hash_search (const pdf_hash_t table, const char *key, const void **elem_pointer)
Searches for the element associated with the given key in table and store it in elem_pointer.
- Parameters
- table
A hash table.
- key
A valid null-terminated string key.
- elem_pointer
A pointer where to store the element.
- Returns
A pdf status value:
-
PDF_OK The operation succeeded.
-
PDF_EBADDATA Either elem_pointer is NULL, key or the table is invalid.
-
PDF_ERROR The key wasn't found.
-
- Usage example
pdf_hash_t hash; char *elem; /* Create a new hash */ if (pdf_hash_new (NULL, &hash) == PDF_OK) { /* Add an element to the hash... */ pdf_hash_add (hash, "a-key", "a-value", NULL); /* Get the element from the hash */ pdf_hash_search (hash, "a-key", (void **) &elem); }
Working with iterators
- Function: pdf_status_t pdf_hash_iterator_new (const pdf_hash_t table, pdf_hash_iterator_t *iterator)
Creates an iterator over the keys of table and saves it in iterator. Keys composed only by numbers are returned first followed by keys in the order imposed by the "strcmp()" function.
- Parameters
- table
A hash table.
- iterator
A pointer to an iterator.
- Returns
A pdf status value:
-
PDF_OK The operation succeeded.
-
PDF_ENOMEM Not enough memory.
-
PDF_EBADDATA Either iterator is NULL or table is invalid.
-
- Usage example
pdf_hash_t hash; pdf_hash_iterator_t hash_iter; /* Create a new hash */ if (pdf_hash_new (NULL, &hash) == PDF_OK) { /* Add some elements to the hash */ pdf_hash_add (hash, "first-key", "first-value", NULL); pdf_hash_add (hash, "second-key", "second-value", NULL); pdf_hash_add (hash, "third-key", "third-key", NULL); /* Get an iterator to the first element of the hash */ pdf_hash_iterator_new (hash, &hash_iter); }
- Function: pdf_status_t pdf_hash_iterator_next (pdf_hash_iterator_t iterator, const char **key)
Retrieves the next key from iterator.
- Parameters
- iterator
A Hash Table iterator pointer.
- key
A pointer where to save the key.
- Returns
A pdf status value:
-
PDF_OK The operation succeeded.
-
PDF_EBADDATA Either iterator is invalid or key is NULL.
-
PDF_ERROR There are no more keys to traverse over.
-
- Usage example
pdf_hash_t hash; pdf_hash_iterator_t hash_iter; pdf_char_t *key; /* Create a new hash */ if (pdf_hash_new (NULL, &hash) == PDF_OK) { /* Add some elements to the hash */ pdf_hash_add (hash, "first-key", "first-value", NULL); pdf_hash_add (hash, "second-key", "second-value", NULL); pdf_hash_add (hash, "third-key", "third-key", NULL); /* Traverse all the values of the hash with an iterator */ pdf_hash_iterator_new (hash, &hash_iter); while (pdf_hash_iterator_next (hash_iter, &key) != PDF_ERROR) { /* key contains the next key */ } }
- Function: pdf_status_t pdf_hash_iterator_destroy (pdf_hash_iterator_t iterator)
Free all resources used by iterator.
- Parameters
- iterator
A Hash Table iterator pointer.
- Returns
A pdf status value:
-
PDF_OK The operation succeeded.
-
- Usage example
pdf_hash_t hash; pdf_hash_iterator_t hash_iter; /* Create a new hash */ if (pdf_hash_new (NULL, &hash) == PDF_OK) { /* Add some elements to the hash */ pdf_hash_add (hash, "first-key", "first-value", NULL); pdf_hash_add (hash, "second-key", "second-value", NULL); pdf_hash_add (hash, "third-key", "third-key", NULL); /* Get an iterator to the first element of the hash */ pdf_hash_iterator_new (hash, &hash_iter); /* Destroy the iterator */ pdf_hash_iterator_destroy (hash_iter); }
Basic dispose functions
These are the basic function implementations to free elements and keys. They should only be used if you allocated elements/keys with pdf_alloc() and don't need to free any other resource.
- Function: void pdf_hash_element_dealloc_fn (const void * elt)
Deallocates elt with pdf_dealloc().
- Parameters
- elt
A pointer to the element being freed.
- Returns
Nothing.
- Usage example
pdf_hash_t hash; pdf_char_t *elem; /* Create a new hash */ if (pdf_hash_new (NULL, &hash) == PDF_OK) { /* Allocate memory for a value to be inserted into the hash */ elem = pdf_alloc (sizeof(pdf_char_t) * 4); strcpy ((char *) elem, "abc"); /* Add an element to the hash, specifying pdf_hash_element_dealloc_fn as its disposal function */ pdf_hash_add (hash, "a-key", (void *) elem, pdf_hash_element_dealloc_fn); /* Destroy the hash (the disposal function invokes pdf_dealloc in the allocated string */ pdf_hash_destroy (hash); }
- Function: void pdf_hash_key_dealloc_fn (const void * elt)
Deallocates elt with pdf_dealloc().
- Parameters
- elt
A pointer to the element being freed.
- Returns
Nothing.
- Usage example
pdf_hash_t hash; pdf_char_t *key; /* Create a new hash */ if (pdf_hash_new (pdf_hash_key_dealloc_fn, &hash) == PDF_OK) { /* Allocate memory for a key to be used into the hash */ key = pdf_alloc (sizeof(pdf_char_t) * 4); strcpy ((char *) elem, "abc"); /* Add an element to the hash, using the key */ pdf_hash_add (hash, key, "abc", NULL); /* Destroy the hash (the key disposal function invokes pdf_dealloc in the allocated string */ pdf_hash_destroy (hash); }
Hash helper functions
These are specific functions for adding different types of elements (types defined by the library). They guarantee that when an element of one of these types is removed from a hash table the correct disposal function is called.
NOTE: If you are going to use the element after the table containing the element is destroyed, in that case don't use these functions.
- Function: pdf_status_t pdf_hash_add_text (pdf_hash_t table, const char *key, const pdf_text_t *elt)
Adds the text elt with the associated key key to table. If key already exists nothing is done.
- Parameters
- table
A hash table.
- key
A valid key string.
- elt
A pointer to the element being added.
- Returns
A pdf status value:
-
PDF_OK The operation succeeded.
-
PDF_ENOMEM Not enough memory.
-
PDF_EBADDATA Either table, key or elt is invalid.
-
- Usage example
pdf_hash_t hash; pdf_text_t elem; /* Create a new hash */ if (pdf_hash_new (NULL, &hash) == PDF_OK) { /* Create the element for the hash */ pdf_text_new_from_unicode ("abc", 3, PDF_TEXT_UTF8, &hash); /* Add an element to the hash, specifying pdf_hash_element_dealloc_fn as its disposal function */ pdf_hash_add_text (hash, "a-key", &elem); /* Destroy the hash */ pdf_hash_destroy (hash); }
- Function: pdf_status_t pdf_hash_add_time (pdf_hash_t table, const char *key, const pdf_time_t *elt)
Adds the time elt with the associated key key to table. If key already exists nothing is done.
- Parameters
- table
A hash table.
- key
A valid key string.
- elt
A pointer to the element being added.
- Returns
A pdf status value:
-
PDF_OK The operation succeeded.
-
PDF_ENOMEM Not enough memory.
-
PDF_EBADDATA Either table, key or elt is invalid.
-
- Usage example
pdf_hash_t hash; pdf_time_t elem; /* Create a new hash */ if (pdf_hash_new (NULL, &hash) == PDF_OK) { /* Create the element for the hash */ pdf_time_new (&elem); /* Add an element to the hash */ pdf_hash_add_time (hash, "a-key", &elem); /* Destroy the hash */ pdf_hash_destroy (hash); }
- Function: pdf_status_t pdf_hash_add_list (pdf_hash_t table, const char *key, const pdf_list_t *elt)
Adds the list elt with the associated key key to table. If key already exists nothing is done.
- Parameters
- table
A hash table.
- key
A valid key string.
- elt
A pointer to the element being added.
- Returns
A pdf status value:
-
PDF_OK The operation succeeded.
-
PDF_ENOMEM Not enough memory.
-
PDF_EBADDATA Either table, key or elt is invalid.
-
- Usage example
pdf_hash_t hash; pdf_list_t elem; /* Create a new hash */ if (pdf_hash_new (NULL, &hash) == PDF_OK) { /* Create the element for the hash */ pdf_list_new (&elem); /* Add an element to the hash */ pdf_hash_add_list (hash, "a-key", &elem); /* Destroy the hash */ pdf_hash_destroy (hash); }
- Function: pdf_status_t pdf_hash_add_hash (pdf_hash_t table, const char *key, const pdf_hash_t *elt)
Adds the hash table elt with the associated key key to table. If key already exists nothing is done.
- Parameters
- table
A hash table.
- key
A valid key string.
- elt
A pointer to the element being added.
- Returns
A pdf status value:
-
PDF_OK The operation succeeded.
-
PDF_ENOMEM Not enough memory.
-
PDF_EBADDATA Either table, key or elt is invalid.
-
- Usage example
pdf_hash_t hash; pdf_hash_t elem; /* Create a new hash */ if (pdf_hash_new (NULL, &hash) == PDF_OK) { /* Create the element for the hash */ pdf_hash_new (&elem); /* Add an element to the hash */ pdf_hash_add_hash (hash, "a-key", &elem); /* Destroy the hash */ pdf_hash_destroy (hash); }
- Function: pdf_status_t pdf_hash_add_stm (pdf_hash_t table, const char *key, const pdf_stm_t *elt)
Adds the stream elt with the associated key key to table. If key already exists nothing is done.
- Parameters
- table
A hash table.
- key
A valid key string.
- elt
A pointer to the element being added.
- Returns
A pdf status value:
-
PDF_OK The operation succeeded.
-
PDF_ENOMEM Not enough memory.
-
PDF_EBADDATA Either table, key or elt is invalid.
-
- Usage example
XXX
Lists
This section describes how to work with unsorted and sorted lists. In case you're going to work with a sorted list, you should use the sorted version of each function if it's available. See section Working with sorted lists.
List Data Types
- Data Type: pdf_list_t
A list composed by zero or more nodes.
- Data Type: pdf_list_node_t
A list node. Each node is able to contain a data structure via a void npointer.
- Data Type: pdf_list_iterator_t
A list iterator.
- Data Type: bool (*pdf_list_element_equals_fn_t) (const void *elt1, const void *elt2)
A function type for comparing list elements equality. Should return PDF_TRUE in case they are equal and PDF_FALSE otherwise.
- Data Type: void (*pdf_list_element_dispose_fn_t) (const void *elt)
A function type for disposing list elements.
- Data Type: int (*pdf_list_element_compar_fn_t) (const void *elt1, const void *elt2)
A function type for comparing list elements. Should return an integer less than, equal to, or greater than zero corresponding to whether the first element is considered less than, equal to, or greater than the second element.
- Data Type: pdf_size_t (*pdf_list_element_hashcode_fn_t) (const void *elt)
A function type for calculating a Hash code given a list element. Should return the corresponding hash code.
Creating and Destroying Lists
- Function: pdf_status_t pdf_list_new (pdf_list_element_equals_fn_t equals_fn, pdf_list_element_dispose_fn_t dispose_fn, const pdf_bool_t allow_duplicates, pdf_list_t *list)
Create a new list containing no elements.
- Parameters
- equals_fn
A function to compare list elements. It is used in sort operations.
- dispose_fn
A function to dispose list elements. It is used when destroying list elements.
- allow_duplicates
This parameter indicate if the list is allowed to contain duplicate elements (elements for which equals_fn evaluate to
PDF_TRUE).- list
A pointer to a list where the new one will be saved.
- Returns
A status variable:
-
PDF_OK list contains a new empty list.
-
PDF_EBADDATA list points to NULL.
-
PDF_ERROR An unexpected error or no memory available.
-
- Usage example
pdf_list_t mylist; if (pdf_list_new (list_element_equal_p, list_element_destroy, PDF_FALSE, &mylist) != PDF_OK) { /* manage the error... */ }
- Function: pdf_status_t pdf_list_destroy (pdf_list_t list)
Destroy a list freeing all used resources. The elements of the list are disposed first.
- Parameters
- list
The list to be destroyed.
- Returns
A pdf status value:
-
PDF_OK The operation succeeded.
-
- Usage example
pdf_list_t mylist; /* ...create `mylist'... */ pdf_list_destroy (mylist);
Managing List Properties
- Function: pdf_size_t pdf_list_size (const pdf_list_t list)
Get the number of elements contained into a given list.
- Parameters
- list
A list.
- Returns
The number of elements inside list.
- Usage example
pdf_list_t mylist; pdf_size_t num_elm; /* ...insert some elements into `mylist'... */ num_elm = pdf_list_size (mylist);
Searching for List Elements
- Function: pdf_status_t pdf_list_search (const pdf_list_t list, const void* element, pdf_list_node_t *node)
Search whether an element is already in the list.
- Parameters
- list
A list.
- element
The element to search for.
- node
The searched node if it was found.
- Returns
A pdf status value:
-
PDF_OK The operation succeeded.
-
PDF_ENONODE element not found.
-
PDF_EBADDATA Invalid node pointer.
-
- Usage example
pdf_list_t list; pdf_list_node_t node; int elem; /* Create the list */ if (pdf_list_new (list_element_equal_p, list_element_destroy, PDF_FALSE, /* Allow duplicates */ &list) == PDF_OK) { /* Insert an element into the list */ pdf_list_add_first (list, (void *) &elem, NULL); /* Search for that element into the list */ if (pdf_list_search (list, (void *) &elem, &node) == PDF_OK) { /* The program should reach this place */ } }
- Function: pdf_status_t pdf_list_search_from (const pdf_list_t list, const pdf_size_t start_index, const void* element, pdf_list_node_t *node)
Search whether an element is already in the list, at a position >= start_index.
- Parameters
- list
A list.
- start_index
Index indicating the begin of the search.
- node
The searched node if it was found.
- Returns
A pdf status value:
-
PDF_OK The operation succeeded.
-
PDF_ENONODE element not found.
-
PDF_EBADDATA Invalid node pointer.
-
PDF_EINVRANGE start_index is greater than the list size or less than 0.
-
- Usage example
pdf_list_t list; pdf_list_node_t node; int elem1; int elem2; int elem3; if (pdf_list_new (list_element_equal_p, list_element_destroy, PDF_FALSE, /* Allow duplicates */ &list) == PDF_OK) { /* Insert several elements into the list */ pdf_list_add_last (list, (void *) &elem1, NULL); pdf_list_add_last (list, (void *) &elem2, NULL); pdf_list_add_last (list, (void *) &elem3, NULL); /* Search for an element into the list */ if (pdf_list_search_from (list, (void *) &elem1, 1, &node) == PDF_OK) { /* The program should never reach this place, since elem1 occupies the first position (0) in the list */ } }
- Function: pdf_status_t pdf_list_search_from_to (const pdf_list_t list, const pdf_size_t start_index, const pdf_size_t end_index, const void* element, pdf_list_node_t *node)
Search whether an element is already in the list, at a position >= start_index and < end_index.
- Parameters
- list
A list.
- start_index
Index to the first list position to be searched.
- end_index
Index to the last list position to be searched.
- element
The element to search for.
- node
The seached node if it was found.
- Returns
A pdf status value:
-
PDF_OK The operation succeeded.
-
PDF_ENONODE element not found.
-
PDF_EBADDATA Invalid node pointer.
-
PDF_EINVRANGE start_index or end_index is greater than the list size or less than 0.
-
- Usage example
pdf_list_t list; pdf_list_node_t node; int elem1; int elem2; int elem3; int elem4; if (pdf_list_new (list_element_equal_p, list_element_destroy, PDF_FALSE, /* Allow duplicates */ &list) == PDF_OK) { /* Insert several elements into the list */ pdf_list_add_last (list, (void *) &elem1, NULL); pdf_list_add_last (list, (void *) &elem2, NULL); pdf_list_add_last (list, (void *) &elem3, NULL); pdf_list_add_last (list, (void *) &elem4, NULL); /* Search for an element into the list */ if (pdf_list_search_from_to (list, (void *) &elem4, 1, 3, &node) == PDF_OK) { /* The program should never reach this place, since elem4 occupies the last position (3) in the list */ } }
- Function: pdf_status_t pdf_list_next_node (const pdf_list_t list, const pdf_list_node_t node, pdf_list_node_t *next)
Return the node immediately after the given node in the list.
- Parameters
- list
A list.
- node
A node contained in list.
- prev
A pointer where the next node will be saved.
- Returns
A pdf status value:
-
PDF_OK The operation succeeded.
-
PDF_ENONODE Next node not found.
-
PDF_EBADDATA Invalid next pointer.
-
- Usage example
pdf_list_t list; pdf_list_node_t node_first; pdf_list_node_t node_second; int elem1; int elem2; if (pdf_list_new (list_element_equal_p, list_element_destroy, PDF_FALSE, /* Allow duplicates */ &list) == PDF_OK) { /* Insert several elements into the list */ pdf_list_add_last (list, (void *) &elem1, NULL); pdf_list_add_last (list, (void *) &elem2, NULL); /* Get the node containing "elem1" */ pdf_list_search (list, (void *) &elem1, &node_first); /* Get the next node in the list */ pdf_list_next_node (list, first_node, &node_second); /* Now node_second is the node containing elem2 */ }
- Function: pdf_status_t pdf_list_previous_node (const pdf_list_t list, const pdf_list_node_t node, pdf_list_node_t *prev)
Return the node immediately before the given node in the list.
- Parameters
- list
A list.
- node
A node contained in list.
- prev
A pointer where the previous node will be saved.
- Returns
A pdf status value:
-
PDF_OK The operation succeeded.
-
PDF_ENONODE Previous node not found.
-
PDF_EBADDATA Invalid prev pointer.
-
- Usage example
pdf_list_t list; pdf_list_node_t node_first; pdf_list_node_t node_second; int elem1; int elem2; if (pdf_list_new (list_element_equal_p, list_element_destroy, PDF_FALSE, /* Allow duplicates */ &list) == PDF_OK) { /* Insert several elements into the list */ pdf_list_add_last (list, (void *) &elem1, NULL); pdf_list_add_last (list, (void *) &elem2, NULL); /* Get the node containing "elem2" */ pdf_list_search (list, (void *) &elem2, &node_second); /* Get the previous node in the list */ pdf_list_previous_node (list, second_node, &node_first); /* Now node_first is the node containing elem2 */ }
- Function: pdf_status_t pdf_list_indexof (const pdf_list_t list, const void* element, pdf_size_t *position)
Search whether an element is already in the list.
- Parameters
- list
A list.
- element
A pointer to user data.
- position
A pointer where the element position will be saved.
- Returns
A pdf status value:
-
PDF_OK The operation succeeded.
-
PDF_ENONODE element not found.
-
PDF_EBADDATA Invalid or NULL pointers.
-
- Usage Example
pdf_list_t list; pdf_list_node_t node_first; pdf_list_node_t node_second; int elem1; int elem2; pdf_size_t index_of_elem2; if (pdf_list_new (list_element_equal_p, list_element_destroy, PDF_FALSE, /* Allow duplicates */ &list) == PDF_OK) { /* Insert several elements into the list */ pdf_list_add_last (list, (void *) &elem1, NULL); pdf_list_add_last (list, (void *) &elem2, NULL); /* Get the index of elem2 */ pdf_list_indexof (list, (void *) &elem2, &size_of_elem2); /* Now size_of_elem2 contains 1 */ }
- Function: pdf_status_t pdf_list_indexof_from (const pdf_list_t list, const pdf_size_t start_index, const void* element, pdf_size_t *position)
Search whether an element is already in the list, at a position >= start_index.
- Parameters
- list
A list.
- start_index
An index to a position in list.
- element
The element to search for.
- position
A pointer where the element position will be saved.
- Returns
A pdf status value:
-
PDF_OK The operation succeeded.
-
PDF_ENONODE element not found.
-
PDF_EBADDATA Invalid or NULL pointers.
-
PDF_EINVRANGE start_index or end_index is greater than the list size or less than 0.
-
- Usage example
pdf_list_t list; pdf_list_node_t node_first; pdf_list_node_t node_second; int elem1; int elem2; int elem3; int elem4; pdf_size_t index_of_elem1; if (pdf_list_new (list_element_equal_p, list_element_destroy, PDF_FALSE, /* Allow duplicates */ &list) == PDF_OK) { /* Insert several elements into the list */ pdf_list_add_last (list, (void *) &elem1, NULL); pdf_list_add_last (list, (void *) &elem2, NULL); pdf_list_add_last (list, (void *) &elem3, NULL); pdf_list_add_last (list, (void *) &elem4, NULL); /* Get the index of elem1 */ if (pdf_list_indexof_from (list, 1, (void *) &elem1, &size_of_elem1) == PDF_ENONODE) { /* The program reaches this point, since elem1 occupies the first position into the list */ } }
- Function: pdf_status_t pdf_list_indexof_from_to (const pdf_list_t list, const pdf_size_t start_index, const pdf_size_t end_index, const void* element, pdf_size_t *position)
Search whether an element is already in the list, at a position >= start_index and < end_index.
- Parameters
- list
A list.
- start_index
A position in list.
- end_index
A position in list.
- element
A pointer to some user data.
- position
A pointer where the element position will be saved.
- Returns
A pdf status value:
-
PDF_OK The operation succeeded.
-
PDF_ENONODE element not found.
-
PDF_EBADDATA Invalid or NULL pointers.
-
PDF_EINVRANGE start_index or end_index is greater than the list size or less than 0.
-
- Usage example
pdf_list_t list; pdf_list_node_t node_first; pdf_list_node_t node_second; int elem1; int elem2; int elem3; int elem4; pdf_size_t index_of_elem4; if (pdf_list_new (list_element_equal_p, list_element_destroy, PDF_FALSE, /* Allow duplicates */ &list) == PDF_OK) { /* Insert several elements into the list */ pdf_list_add_last (list, (void *) &elem1, NULL); pdf_list_add_last (list, (void *) &elem2, NULL); pdf_list_add_last (list, (void *) &elem3, NULL); pdf_list_add_last (list, (void *) &elem4, NULL); /* Get the index of elem4 */ if (pdf_list_indexof_from_to (list, 1, 3, (void *) &elem1, &size_of_elem4) == PDF_ENONODE) { /* The program reaches this point, since elem4 occupies the last position (3) into the list */ } }
Setting and Getting List Elements
- Function: void * pdf_list_node_value (const pdf_list_t list, const pdf_list_node_t node)
Get the element value represented by a list node.
- Parameters
- list
A list.
- node
A node of list.
- Returns
The element value represented by node.
- Usage example
pdf_list_t list; pdf_list_node_t node; int elem1; int *pointer_to_elem1; if (pdf_list_new (list_element_equal_p, list_element_destroy, PDF_FALSE, /* Allow duplicates */ &list) == PDF_OK) { /* Insert an element into the list */ pdf_list_add_last (list, (void *) &elem1, NULL); /* Get the node of the element of the list */ pdf_list_search (list, (void *) &elem1, &node); /* Get the value out of the node */ pointer_to_elem1 = (int *) pdf_list_node_value (list, node); }
- Function: pdf_status_t pdf_list_get_at (const pdf_list_t list, const pdf_size_t position, const void **value)
Get the element at a given position in the list.
- Parameters
- list
A list.
- position
A position in list. Must be
>= 0and< pdf_list_size (list).- value
A pointer to which the element will be saved.
- Returns
A pdf status value:
-
PDF_OK The operation succeeded.
-
PDF_EINVRANGE Invalid position
-
PDF_EBADDATA Invalid value pointer.
-
- Usage example
pdf_list_t list; int elem1; int *pointer_to_elem1; if (pdf_list_new (list_element_equal_p, list_element_destroy, PDF_FALSE, /* Allow duplicates */ &list) == PDF_OK) { /* Insert an element into the list */ pdf_list_add_last (list, (void *) &elem1, NULL); /* Get the first element of the list */ pdf_list_get_at (list, 0, &pointer_to_elem_1); }
- Function: pdf_status_t pdf_list_set_at (pdf_list_t list, const pdf_size_t position, const void* element, pdf_list_node_t *node)
Replace the element at a given position in a list.
- Parameters
- list
A list.
- position
A position in list. Must be
>= 0and< pdf_list_size (list).- element
The new element.
- node
A pointer to save the node containing the replaced element or NULL.
- Returns
A pdf status value:
-
PDF_OK The operation succeeded.
-
PDF_EINVRANGE Invalid position range.
-
PDF_BADDATA The list does not allow duplicated values and already contain element.
-
- Usage example
XXX
Adding and Removing List Elements
- Function: pdf_status_t pdf_list_add_first (pdf_list_t list, const void* element, pdf_list_node_t *node)
Add an element as the first element of the list. If node is not NULL then a reference to the newly created node is copied to it.
- Parameters
- list
A list.
- element
A pointer to the user data to be stored as a list element.
- node
If non NULL, a list node variable used to contain the added element.
- Returns
A PDF status value:
-
PDF_OK The element was inserted successfully.
-
PDF_EBADDATA The list does not allow duplicated values and already contain element.
-
- Usage example
XXX
- Function: pdf_status_t pdf_list_add_last (pdf_list_t list, const void* element, pdf_list_node_t *node)
Add an element as the last element of the list. If node is not NULL then a reference to the newly created node is copied to it.
- Parameters
- list
A list.
- element
A pointer to the user data to be stored as a list element.
- node
If non NULL, a list node variable used to contain the added element.
- Returns
A PDF status value:
-
PDF_OK The element was inserted successfully.
-
PDF_EBADDATA The list does not allow duplicated values and already contain element.
-
- Usage example
XXX
- Function: pdf_status_t pdf_list_add_at (pdf_list_t list, const pdf_size_t position, const void* element, pdf_list_node_t *node)
Add an element at a given position in the list.
- Parameters
- list
A list.
- position
A position in the list. Should be
>= 0and<= pdf_list_size (list).- element
A pointer to the user data to be stored as a list element.
- node
A pointer to the node where the given element was stored or NULL.
- Returns
A pdf status value:
-
PDF_OK The operation succeeded.
-
PDF_EINVRANGE Invalid range of given position.
-
PDF_BADDATA The list does not allow duplicated values and already contain element.
-
- Usage example
XXX
- Function: pdf_status_t pdf_list_remove_node (pdf_list_t list, const pdf_list_node_t node)
Remove an element from the list.
- Parameters
- list
A list.
- node
The node to be removed.
- Returns
A pdf status value:
-
PDF_OK
-
- Usage example
XXX
- Function: pdf_status_t pdf_list_remove_at (pdf_list_t list, const pdf_size_t position)
Remove an element at a given position from the list.
- Parameters
- list
A list.
- position
A position in list. Must be
>= 0and< pdf_list_size (list).
- Returns
A pdf status value:
-
PDF_OK The operation succeeded.
-
PDF_EINVRANGE Invalid position range.
-
- Usage example
XXX
- Function: pdf_status_t pdf_list_remove (pdf_list_t list, const void * element)
Search and remove an element from the lsit.
- Parameters
- list
A list.
- element
The element to be removed.
- Returns
A pdf status value:
-
PDF_OK element was found in the list and was removed.
-
PDF_EBADDATA element was not found in the list.
-
- Usage example
XXX
Working with sorted lists
- Function: pdf_status_t pdf_list_sorted_add (pdf_list_t list, pdf_list_element_compar_fn_t compar_fn, const void* element, pdf_list_node_t * element_node)
Add an element to the list.
- Parameters
- list
A list.
- compar_fn
A comparision function.
- element
A pointer to the user data to be stored as a list element.
- element_node
A pointer where the added element node will be saved. Can be NULL.
- Returns
A pdf status value:
-
PDF_OK The operation succeeded.
-
PDF_EBADDATA Invalid compar_fn pointer.
-
- Usage example
XXX
- Function: pdf_status_t pdf_list_sorted_remove (pdf_list_t list, pdf_list_element_compar_fn_t compar_fn, const void * element)
Search and remove an element from the list.
- Parameters
- list
A list.
- compar_fn
A comparision function.
- element
The element to be removed.
- Returns
A pdf status value:
-
PDF_OK element was found in the list and was removed.
-
PDF_ENONODE element was not found in the list.
-
PDF_EBADDATA Invalid compar_fn.
-
- Usage example
XXX
- Function: pdf_status_t pdf_list_sorted_search (const pdf_list_t list, pdf_list_element_compar_fn_t compar_fn, const void* element, pdf_list_node_t *node)
Search whether an element is already in the list.
- Parameters
- list
A list.
- compar_fn
A comparision function.
- element
The element to search for.
- node
The searched node if it was found.
- Returns
A pdf status value:
-
PDF_OK The operation succeeded.
-
PDF_ENONODE element not found.
-
PDF_EBADDATA Invalid node pointer or compar_fn.
-
- Usage example
XXX
- Function: pdf_status_t pdf_list_sorted_search_from_to (const pdf_list_t list, pdf_list_element_compar_fn_t compar_fn, const pdf_size_t start_index, const pdf_size_t end_index, const void* element, pdf_list_node_t *node)
Search whether an element is already in the list, at a position >= start_index and < end_index.
- Parameters
- list
A list.
- compar_fn
A comparision function.
- start_index
Index to the first list position to be searched.
- end_index
Index to the last list position to be searched.
- element
The element to search for.
- node
The seached node if it was found.
- Returns
A pdf status value:
-
PDF_OK The operation succeeded.
-
PDF_ENONODE element not found.
-
PDF_EBADDATA Invalid node pointer or compar_fn.
-
PDF_EINVRANGE start_index or end_index is greater than the list size or less than 0.
-
- Usage example
XXX
- Function: pdf_status_t pdf_list_sorted_indexof (const pdf_list_t list, pdf_list_element_compar_fn_t compar_fn, const