gdsl  1.6
2D-Arrays manipulation module

Typedefs

typedef struct gdsl_2darray * gdsl_2darray_t
 GDSL 2D-array type.

Functions

gdsl_2darray_t gdsl_2darray_alloc (const char *NAME, const ulong R, const ulong C, const gdsl_alloc_func_t ALLOC_F, const gdsl_free_func_t FREE_F)
 Create a new 2D-array.
void gdsl_2darray_free (gdsl_2darray_t A)
 Destroy a 2D-array.
const char * gdsl_2darray_get_name (const gdsl_2darray_t A)
 Get the name of a 2D-array.
ulong gdsl_2darray_get_rows_number (const gdsl_2darray_t A)
 Get the number of rows of a 2D-array.
ulong gdsl_2darray_get_columns_number (const gdsl_2darray_t A)
 Get the number of columns of a 2D-array.
ulong gdsl_2darray_get_size (const gdsl_2darray_t A)
 Get the size of a 2D-array.
gdsl_element_t gdsl_2darray_get_content (const gdsl_2darray_t A, const ulong R, const ulong C)
 Get an element from a 2D-array.
gdsl_2darray_t gdsl_2darray_set_name (gdsl_2darray_t A, const char *NEW_NAME)
 Set the name of a 2D-array.
gdsl_element_t gdsl_2darray_set_content (gdsl_2darray_t A, const ulong R, const ulong C, void *VALUE)
 Modify an element in a 2D-array.
void gdsl_2darray_write (const gdsl_2darray_t A, const gdsl_write_func_t WRITE_F, FILE *OUTPUT_FILE, void *USER_DATA)
 Write the content of a 2D-array to a file.
void gdsl_2darray_write_xml (const gdsl_2darray_t A, const gdsl_write_func_t WRITE_F, FILE *OUTPUT_FILE, void *USER_DATA)
 Write the content of a 2D array to a file into XML.
void gdsl_2darray_dump (const gdsl_2darray_t A, const gdsl_write_func_t WRITE_F, FILE *OUTPUT_FILE, void *USER_DATA)
 Dump the internal structure of a 2D array to a file.

Typedef Documentation

typedef struct gdsl_2darray* gdsl_2darray_t

GDSL 2D-array type.

This type is voluntary opaque. Variables of this kind could'nt be directly used, but by the functions of this module.

Definition at line 53 of file gdsl_2darray.h.


Function Documentation

gdsl_2darray_t gdsl_2darray_alloc ( const char *  NAME,
const ulong  R,
const ulong  C,
const gdsl_alloc_func_t  ALLOC_F,
const gdsl_free_func_t  FREE_F 
)

Create a new 2D-array.

Allocate a new 2D-array data structure with R rows and C columns and its name is set to a copy of NAME. The functions pointers ALLOC_F and FREE_F could be used to respectively, alloc and free elements in the 2D-array. These pointers could be set to NULL to use the default ones:

  • the default ALLOC_F simply returns its argument
  • the default FREE_F does nothing
Note:
Complexity: O( 1 )
Precondition:
nothing
Parameters:
NAMEThe name of the new 2D-array to create
RThe number of rows of the new 2D-array to create
CThe number of columns of the new 2D-array to create
ALLOC_FFunction to alloc element when inserting it in a 2D-array
FREE_FFunction to free element when removing it from a 2D-array
Returns:
the newly allocated 2D-array in case of success.
NULL in case of insufficient memory.
See also:
gdsl_2darray_free()
gdsl_alloc_func_t
gdsl_free_func_t

Destroy a 2D-array.

Flush and destroy the 2D-array A. The FREE_F function passed to gdsl_2darray_alloc() is used to free elements from A, but no check is done to see if an element was set (ie. != NULL) or not.It's up to you to check if the element to free is NULL or not into the FREE_F function.

Note:
Complexity: O( R x C ), where R is A's rows count, and C is A's columns count
Precondition:
A must be a valid gdsl_2darray_t
Parameters:
AThe 2D-array to destroy
See also:
gdsl_2darray_alloc()
const char* gdsl_2darray_get_name ( const gdsl_2darray_t  A)

Get the name of a 2D-array.

Note:
Complexity: O( 1 )
Precondition:
A must be a valid gdsl_2darray_t
Postcondition:
The returned string MUST NOT be freed.
Parameters:
AThe 2D-array from which getting the name
Returns:
the name of the 2D-array A.
See also:
gdsl_2darray_set_name()

Get the number of rows of a 2D-array.

Note:
Complexity: O( 1 )
Precondition:
A must be a valid gdsl_2darray_t
Parameters:
AThe 2D-array from which getting the rows count
Returns:
the number of rows of the 2D-array A.
See also:
gdsl_2darray_get_columns_number()
gdsl_2darray_get_size()

Get the number of columns of a 2D-array.

Note:
Complexity: O( 1 )
Precondition:
A must be a valid gdsl_2darray_t
Parameters:
AThe 2D-array from which getting the columns count
Returns:
the number of columns of the 2D-array A.
See also:
gdsl_2darray_get_rows_number()
gdsl_2darray_get_size()

Get the size of a 2D-array.

Note:
Complexity: O( 1 )
Precondition:
A must be a valid gdsl_2darray_t
Parameters:
AThe 2D-array to use.
Returns:
the number of elements of A (noted |A|).
See also:
gdsl_2darray_get_rows_number()
gdsl_2darray_get_columns_number()
gdsl_element_t gdsl_2darray_get_content ( const gdsl_2darray_t  A,
const ulong  R,
const ulong  C 
)

Get an element from a 2D-array.

Note:
Complexity: O( 1 )
Precondition:
A must be a valid gdsl_2darray_t & R <= gdsl_2darray_get_rows_number( A ) & C <= gdsl_2darray_get_columns_number( A )
Parameters:
AThe 2D-array from which getting the element
RThe row indix of the element to get
CThe column indix of the element to get
Returns:
the element of the 2D-array A contained in row R and column C.
See also:
gdsl_2darray_set_content()
gdsl_2darray_t gdsl_2darray_set_name ( gdsl_2darray_t  A,
const char *  NEW_NAME 
)

Set the name of a 2D-array.

Change the previous name of the 2D-array A to a copy of NEW_NAME.

Note:
Complexity: O( 1 )
Precondition:
A must be a valid gdsl_2darray_t
Parameters:
AThe 2D-array to change the name
NEW_NAMEThe new name of A
Returns:
the modified 2D-array in case of success.
NULL in case of failure.
See also:
gdsl_2darray_get_name()
gdsl_element_t gdsl_2darray_set_content ( gdsl_2darray_t  A,
const ulong  R,
const ulong  C,
void *  VALUE 
)

Modify an element in a 2D-array.

Change the element at row R and column C of the 2D-array A, and returns it. The new element to insert is allocated using the ALLOC_F function passed to gdsl_2darray_create() applied on VALUE. The previous element contained in row R and in column C is NOT deallocated. It's up to you to do it before, if necessary.

Note:
Complexity: O( 1 )
Precondition:
A must be a valid gdsl_2darray_t & R <= gdsl_2darray_get_rows_number( A ) & C <= gdsl_2darray_get_columns_number( A )
Parameters:
AThe 2D-array to modify on element from
RThe row number of the element to modify
CThe column number of the element to modify
VALUEThe user value to use for allocating the new element
Returns:
the newly allocated element in case of success.
NULL in case of insufficient memory.
See also:
gdsl_2darray_get_content()
void gdsl_2darray_write ( const gdsl_2darray_t  A,
const gdsl_write_func_t  WRITE_F,
FILE *  OUTPUT_FILE,
void *  USER_DATA 
)

Write the content of a 2D-array to a file.

Write the elements of the 2D-array A to OUTPUT_FILE, using WRITE_F function. Additionnal USER_DATA argument could be passed to WRITE_F.

Note:
Complexity: O( R x C ), where R is A's rows count, and C is A's columns count
Precondition:
WRITE_F != NULL & OUTPUT_FILE != NULL
Parameters:
AThe 2D-array to write
WRITE_FThe write function
OUTPUT_FILEThe file where to write A's elements
USER_DATAUser's datas passed to WRITE_F
See also:
gdsl_2darray_write_xml()
gdsl_2darray_dump()
void gdsl_2darray_write_xml ( const gdsl_2darray_t  A,
const gdsl_write_func_t  WRITE_F,
FILE *  OUTPUT_FILE,
void *  USER_DATA 
)

Write the content of a 2D array to a file into XML.

Write all A's elements to OUTPUT_FILE, into XML language. If WRITE_F != NULL, then uses WRITE_F to write A's elements to OUTPUT_FILE. Additionnal USER_DATA argument could be passed to WRITE_F.

Note:
Complexity: O( R x C ), where R is A's rows count, and C is A's columns count
Precondition:
A must be a valid gdsl_2darray_t & OUTPUT_FILE != NULL
Parameters:
AThe 2D-array to write
WRITE_FThe write function
OUTPUT_FILEThe file where to write A's elements
USER_DATAUser's datas passed to WRITE_F
See also:
gdsl_2darray_write()
gdsl_2darray_dump()
void gdsl_2darray_dump ( const gdsl_2darray_t  A,
const gdsl_write_func_t  WRITE_F,
FILE *  OUTPUT_FILE,
void *  USER_DATA 
)

Dump the internal structure of a 2D array to a file.

Dump A's structure to OUTPUT_FILE. If WRITE_F != NULL, then uses WRITE_F to write A's elements to OUTPUT_FILE. Additionnal USER_DATA argument could be passed to WRITE_F.

Note:
Complexity: O( R x C ), where R is A's rows count, and C is A's columns count
Precondition:
A must be a valid gdsl_2darray_t & OUTPUT_FILE != NULL
Parameters:
AThe 2D-array to dump
WRITE_FThe write function
OUTPUT_FILEThe file where to write A's elements
USER_DATAUser's datas passed to WRITE_F
See also:
gdsl_2darray_write()
gdsl_2darray_write_xml()