Lib:Reference Manual

From GNUpdf

Example sunflower image
Note: This page is automatically generated


Contents

GNU PDF Library Reference

GNU PDF Library Reference

This is the first edition of the GNU PDF Library Reference, updated for libgnupdf version 0.1.

Copyright © 2007, 2008 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".


Overview

Base Layer

Overview

The base layer of the GNU PDF Library provide system-independent access to several facilities.

The implemented facilities are organized into modules. Each module export an API to be used by the client application or other layers of the library. Some modules make use of the facilities implemented in other modules (such as allocation or error functions).

Error Management

The Error module provides procedures for error reporting to the client as well as for error tracing (via debug messages) to developers. Here we also define status types returned by most procedures (there are exceptions though).


Status types

Data Type: pdf_status_t

A status variable. This type of variable is returned by many library functions in order to communicate the status of the performed operation.

The following constants defines the valid values to be hold in a pdf_status_t variable:

Constant: PDF_OK

Success

Constant: PDF_ERROR

A serious error

Constant: PDF_EBADDATA

Invalid or bad arguments

Constant: PDF_ENOMEM

Insufficient memory

Constant: PDF_EEOF

End of file

Constant: PDF_EDIVBYZERO

Divison by zero

Constant: PDF_ENONODE

No node found

Constant: PDF_EINVRANGE

Invalid range

Constant: PDF_ETEXTENC

Error in text encoding

Constant: PDF_ENOMATCH

No matching found

This list will grow as we get closer to a mature state of development.


Error Reporting procedures

Function: void pdf_perror (const pdf_status_t status, const char *str)

Prints the message corresponding to status to stderr followed by str.

Parameters
status

status code

str

a user-defined message

Returns

nothing

Usage example

 
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 NULL is 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_alloc or pdf_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_t variable.

Constant: PDF_I32_MIN

Minimum value able to be stored in a pdf_i32_t variable.

Constant: PDF_U32_MAX

Maximum value able to be stored in a pdf_u32_t variable.

Constant: PDF_U32_MIN

Minimum value able to be stored in a pdf_u32_t variable.


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 >= 0 and < 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 >= 0 and < 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 >= 0 and <= 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 >= 0 and < 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