libgutenprint API Reference: array

libgutenprint API Reference 5.3.3

Typedefs | Functions
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.