Gwyfile Library
Functions
Item – character array

Functions

GwyfileItem * gwyfile_item_new_char_array (const char *name, char *value, uint32_t array_length)
 Creates a new character array GWY file item. More...
 
GwyfileItem * gwyfile_item_new_char_array_copy (const char *name, const char *value, uint32_t array_length)
 Creates a new character array GWY file item. More...
 
GwyfileItem * gwyfile_item_new_char_array_const (const char *name, const char *value, uint32_t array_length)
 Creates a new character array GWY file item. More...
 
const char * gwyfile_item_get_char_array (const GwyfileItem *item)
 Gets the character array value contained in a GWY file data item. More...
 
char * gwyfile_item_take_char_array (GwyfileItem *item)
 Takes the character array value contained in a GWY file data item. More...
 
void gwyfile_item_set_char_array (GwyfileItem *item, char *value, uint32_t array_length)
 Sets the value of a character array GWY file item. More...
 
void gwyfile_item_set_char_array_copy (GwyfileItem *item, const char *value, uint32_t array_length)
 Sets the value of a character array GWY file item. More...
 
void gwyfile_item_set_char_array_const (GwyfileItem *item, const char *value, uint32_t array_length)
 Sets the value of a character array GWY file item. More...
 

Detailed Description

Function Documentation

◆ gwyfile_item_get_char_array()

const char* gwyfile_item_get_char_array ( const GwyfileItem *  item)

Gets the character array value contained in a GWY file data item.

Use gwyfile_item_array_length() to obtain the array length.

The item must be of the character array type. Use gwyfile_item_type() to check item type if the type may not match the expected type. Use gwyfile_object_get_with_type() to obtain object items ensuring the type.

Parameters
itemA character array GWY file data item.
Returns
The character array value of item. The array ownership does not change.
See also
gwyfile_item_take_char_array

◆ gwyfile_item_new_char_array()

GwyfileItem* gwyfile_item_new_char_array ( const char *  name,
char *  value,
uint32_t  array_length 
)

Creates a new character array GWY file item.

The item consumes the provided array and takes care of freeing it later. You must not touch the array any more; it can be already freed when this function returns.

Parameters
nameItem name. It must be a non-empty UTF-8-encoded string (usually, it should be an ASCII string). A copy of the string will be made.
valueItem value (to be consumed).
array_lengthArray length. It must be non-zero as GWY files do not permit empty arrays.
Returns
The newly created GWY file data item.
See also
gwyfile_item_new_char_array_copy gwyfile_item_new_char_array_const

◆ gwyfile_item_new_char_array_const()

GwyfileItem* gwyfile_item_new_char_array_const ( const char *  name,
const char *  value,
uint32_t  array_length 
)

Creates a new character array GWY file item.

The array must exist for the entire lifetime of the item. Hence this function is best for actual constant arrays, however, it can be also used with other arrays whose lifetime is guaranteed.

Parameters
nameItem name. It must be a non-empty UTF-8-encoded string (usually, it should be an ASCII string). A copy of the string will be made.
valueItem value (to be used as-is).
array_lengthArray length. It must be non-zero as GWY files do not permit empty arrays.
Returns
The newly created GWY file data item.
See also
gwyfile_item_new_char_array gwyfile_item_new_char_array_copy

◆ gwyfile_item_new_char_array_copy()

GwyfileItem* gwyfile_item_new_char_array_copy ( const char *  name,
const char *  value,
uint32_t  array_length 
)

Creates a new character array GWY file item.

This function makes a copy the provided array. You can continue doing whatever you wish with it after the function returns.

Parameters
nameItem name. It must be a non-empty UTF-8-encoded string (usually, it should be an ASCII string). A copy of the string will be made.
valueItem value (to be copied).
array_lengthArray length. It must be non-zero as GWY files do not permit empty arrays.
Returns
The newly created GWY file data item. Upon memory allocation failure NULL is returned and errno is set to ENOMEM.
See also
gwyfile_item_new_char_array gwyfile_item_new_char_array_const

◆ gwyfile_item_set_char_array()

void gwyfile_item_set_char_array ( GwyfileItem *  item,
char *  value,
uint32_t  array_length 
)

Sets the value of a character array GWY file item.

The item must be of the character array type.

The item consumes the provided character array and takes care of freeing it later. You must not touch the array any more; it can be already freed when this function returns.

Parameters
itemA character array GWY file data item.
valueNew value for the item (to be consumed).
array_lengthArray length. It must be non-zero as GWY files do not permit empty arrays.
See also
gwyfile_item_set_char_array_copy gwyfile_item_set_char_array_const

◆ gwyfile_item_set_char_array_const()

void gwyfile_item_set_char_array_const ( GwyfileItem *  item,
const char *  value,
uint32_t  array_length 
)

Sets the value of a character array GWY file item.

The item must be of the character array type.

The array must exist for the entire lifetime of the item. Hence this function is best for actual constant arrays, however, it can be also used with other arrays whose lifetime is guaranteed.

Parameters
itemA character array GWY file data item.
valueNew value for the item (to be used as-is).
array_lengthArray length. It must be non-zero as GWY files do not permit empty arrays.
See also
gwyfile_item_set_char_array gwyfile_item_set_char_array_copy

◆ gwyfile_item_set_char_array_copy()

void gwyfile_item_set_char_array_copy ( GwyfileItem *  item,
const char *  value,
uint32_t  array_length 
)

Sets the value of a character array GWY file item.

The item must be of the character array type.

This function makes a copy the provided array. You can continue doing whatever you wish with it after the function returns.

Parameters
itemA character array GWY file data item.
valueNew value for the item (to be copied).
array_lengthArray length. It must be non-zero as GWY files do not permit empty arrays.
See also
gwyfile_item_set_char_array gwyfile_item_set_char_array_const

◆ gwyfile_item_take_char_array()

char* gwyfile_item_take_char_array ( GwyfileItem *  item)

Takes the character array value contained in a GWY file data item.

The item must own the array when this function is called. The ownership is transferred to the caller who becomes responsible to freeing it later. The array can still be obtained with gwyfile_item_get_char_array() but, obviously, it cannot be taken again.

Use gwyfile_item_array_length() to obtain the array length.

The item must be of the character array type. Use gwyfile_item_type() to check item type if the type may not match the expected type. Use gwyfile_object_get_with_type() to obtain object items ensuring the type.

Parameters
itemA character array GWY file data item.
Returns
The character array value of item. The array becomes owned by the caller.
See also
gwyfile_item_get_char_array