array

The array is a simple "two-dimensional array of numbers" data structure. More...

Typedefs
typedef struct stp_array	stp_array_t
	The array opaque data type. More...

Functions
stp_array_t *	stp_array_create (int x_size, int y_size)
	Create a new array. More...
void	stp_array_destroy (stp_array_t *array)
	Destroy an array. More...
void	stp_array_copy (stp_array_t *dest, const stp_array_t *source)
	Copy an array. More...
stp_array_t *	stp_array_create_copy (const stp_array_t *array)
	Copy and allocate an array. More...
void	stp_array_set_size (stp_array_t *array, int x_size, int y_size)
	Resize an array. More...
void	stp_array_get_size (const stp_array_t *array, int *x_size, int *y_size)
	Get the size of an array. More...
void	stp_array_set_data (stp_array_t *array, const double *data)
	Set the data in an array. More...
void	stp_array_get_data (const stp_array_t *array, size_t *size, const double **data)
	Get the data in an array. More...
int	stp_array_set_point (stp_array_t *array, int x, int y, double data)
	Set the data at a single point in the array. More...
int	stp_array_get_point (const stp_array_t *array, int x, int y, double *data)
	Get the data at a single point in the array. More...
const stp_sequence_t *	stp_array_get_sequence (const stp_array_t *array)
	Get the underlying stp_sequence_t. More...
int	stp_array_write (FILE *file, const stp_array_t *array)
	Write an array to a file. More...
char *	stp_array_write_string (const stp_array_t *array)
	Write an array to a string. More...
stp_array_t *	stp_array_create_from_stream (FILE *fp)
	Create an array from a stream. More...
stp_array_t *	stp_array_create_from_file (const char *file)
	Create an array from a stream. More...
stp_array_t *	stp_array_create_from_string (const char *string)
	Create an array from a string. More...

Detailed Description

The array is a simple "two-dimensional array of numbers" data structure.

array "inherits" from the sequence data structure (implemented via containment).

Typedef Documentation

stp_array_t

typedef struct stp_array stp_array_t

The array opaque data type.

Function Documentation

stp_array_copy()

void stp_array_copy	(	stp_array_t *	dest,
		const stp_array_t *	source
	)

Copy an array.

Both dest and source must be valid arrays previously created with stp_array_create().

Parameters

dest	the destination array.
source	the source array.

stp_array_create()

stp_array_t* stp_array_create	(	int	x_size,
		int	y_size
	)

Create a new array.

The total size of the array will be (x_size * y_size).

Parameters

x_size	the number of "columns".
y_size	the number of "rows".

Returns

the newly created array.

stp_array_create_copy()

stp_array_t* stp_array_create_copy

(

const stp_array_t *

array

)

Copy and allocate an array.

dest will be created, and then the contents of source will be copied into it. dest must not have been previously allocated with stp_array_create().

Parameters

array

the source array.

Returns

the new copy of the array.

stp_array_create_from_file()

stp_array_t* stp_array_create_from_file

(

const char *

file

)

Create an array from a stream.

Warning

NOTE that these calls are not thread-safe! These routines may manipulate the locale to achieve a safe representation.

Parameters

file	the file to read.

Returns

the newly created array, or NULL if an error occurred.

stp_array_create_from_stream()

stp_array_t* stp_array_create_from_stream

(

FILE *

fp

)

Create an array from a stream.

Warning

NOTE that these calls are not thread-safe! These routines may manipulate the locale to achieve a safe representation.

Parameters

fp	the stream to read.

Returns

the newly created array, or NULL if an error occurred.

stp_array_create_from_string()

stp_array_t* stp_array_create_from_string

(

const char *

string

)

Create an array from a string.

Warning

NOTE that these calls are not thread-safe! These routines may manipulate the locale to achieve a safe representation.

Parameters

string

the string to read.

Returns

the newly created array, or NULL if an error occurred.

stp_array_destroy()

void stp_array_destroy

(

stp_array_t *

array

)

Destroy an array.

It is an error to destroy the array more than once.

Parameters

array

the array to destroy.

stp_array_get_data()

void stp_array_get_data	(	const stp_array_t *	array,
		size_t *	size,
		const double **	data
	)

Get the data in an array.

Parameters

array	the array to get the data from.
size	the number of elements in the array (x_size * y_size) are stored in the size_t pointed to.
data	a pointer to the first element of an array of doubles is stored in a pointer to double*. stp_array_t *array; size_t size; double *data; stp_array_get_data(array, &size, &data);

stp_array_get_point()

int stp_array_get_point	(	const stp_array_t *	array,
		int	x,
		int	y,
		double *	data
	)

Get the data at a single point in the array.

Parameters

array	the array to use.
x	the x location.
y	the y location.
data	the datum is stored in the double pointed to.

Returns

1 on success, 0 on failure.

stp_array_get_sequence()

const stp_sequence_t* stp_array_get_sequence

(

const stp_array_t *

array

)

Get the underlying stp_sequence_t.

Parameters

array

the array to use.

Returns

the (constant) stp_sequence_t.

stp_array_get_size()

void stp_array_get_size	(	const stp_array_t *	array,
		int *	x_size,
		int *	y_size
	)

Get the size of an array.

The current x and y sizes are stored in the integers pointed to by x_size and y_size.

Parameters

array	the array to get the size of.
x_size	a pointer to an integer to store the x size in.
y_size	a pointer to an integer to store the y size in.

stp_array_set_data()

void stp_array_set_data	(	stp_array_t *	array,
		const double *	data
	)

Set the data in an array.

Parameters

array	the array to set.
data	a pointer to the first member of an array containing the data to set. This array must be at least as long as (x_size y_size).

stp_array_set_point()

int stp_array_set_point	(	stp_array_t *	array,
		int	x,
		int	y,
		double	data
	)

Set the data at a single point in the array.

Parameters

array	the array to use.
x	the x location.
y	the y location.
data	the datum to set.

Returns

1 on success, 0 on failure.

stp_array_set_size()

void stp_array_set_size	(	stp_array_t *	array,
		int	x_size,
		int	y_size
	)

Resize an array.

Resizing an array will destroy all data stored in the array.

Parameters

array	the array to resize.
x_size	the new number of "columns".
y_size	the new number of "rows".

stp_array_write()

int stp_array_write	(	FILE *	file,
		const stp_array_t *	array
	)

Write an array to a file.

The printable representation is guaranteed to contain only 7-bit printable ASCII characters, and is null-terminated. The array will not contain any space, newline, single quote, or comma characters. Furthermore, a printed array will be read back correctly in all locales. These calls are not guaranteed to provide more than 6 decimal places of precision or +/-0.5e-6 accuracy, whichever is less.

Warning

NOTE that these calls are not thread-safe! These routines may manipulate the locale to achieve a safe representation.

Parameters

file	the file to write.
array	the array to use.

Returns

1 on success, 0 on failure.

stp_array_write_string()

char* stp_array_write_string

(

const stp_array_t *

array

)

Write an array to a string.

The printable representation is guaranteed to contain only 7-bit printable ASCII characters, and is null-terminated. The array will not contain any space, newline, or comma characters. Furthermore, a printed array will be read back correctly in all locales. These calls are not guaranteed to provide more than 6 decimal places of precision or +/-0.5e-6 accuracy, whichever is less.

Warning

NOTE that these calls are not thread-safe! These routines may manipulate the locale to achieve a safe representation.

Parameters

array

the array to use.

Returns

a pointer to a string. This is allocated on the heap, and it is the caller's responsibility to free it.