Item – string array

Functions
GwyfileItem *	gwyfile_item_new_string_array (const char *name, char **value, uint32_t array_length)
	Creates a new string array GWY file item. More...
GwyfileItem *	gwyfile_item_new_string_array_copy (const char *name, const char *const *value, uint32_t array_length)
	Creates a new string array GWY file item. More...
GwyfileItem *	gwyfile_item_new_string_array_const (const char *name, const char *const *value, uint32_t array_length)
	Creates a new string array GWY file item. More...
const char *const *	gwyfile_item_get_string_array (const GwyfileItem *item)
	Gets the string array value contained in a GWY file data item. More...
char **	gwyfile_item_take_string_array (GwyfileItem *item)
	Takes the string array value contained in a GWY file data item. More...
void	gwyfile_item_set_string_array (GwyfileItem *item, char **value, uint32_t array_length)
	Sets the value of a string array GWY file item. More...
void	gwyfile_item_set_string_array_copy (GwyfileItem *item, const char *const *value, uint32_t array_length)
	Sets the value of a string array GWY file item. More...
void	gwyfile_item_set_string_array_const (GwyfileItem *item, const char *const *value, uint32_t array_length)
	Sets the value of a string array GWY file item. More...

Detailed Description

Function Documentation

gwyfile_item_get_string_array()

const char* const* gwyfile_item_get_string_array

(

const GwyfileItem *

item

)

Gets the string 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 string 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

item	A string array GWY file data item.

Returns

The string array value of item. The array and the strings inside remain owned by item.

gwyfile_item_new_string_array()

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

Creates a new string array GWY file item.

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

Parameters

name	Item 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.
value	Item value (to be consumed).
array_length	Array 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_string_array_copy gwyfile_item_new_string_array_const

gwyfile_item_new_string_array_const()

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

Creates a new string array GWY file item.

The array and the strings must exist for the entire lifetime of the item. Furthermore, the number of strings and their lengths may not change. Hence this function is best for actual constant arrays, however, it can be also used with other arrays whose lifetime and content are guaranteed.

Parameters

name	Item 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.
value	Item value (to be used as-is).
array_length	Array 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_string_array gwyfile_item_new_string_array_copy

gwyfile_item_new_string_array_copy()

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

Creates a new string array GWY file item.

This function makes copies of both the provided array and the strings inside. You can continue doing whatever you wish with it after the function returns.

Parameters

name	Item 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.
value	Item value (to be copied).
array_length	Array 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_string_array gwyfile_item_new_string_array_const

gwyfile_item_set_string_array()

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

Sets the value of a string array GWY file item.

The item must be of the string array type.

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

Parameters

item	A string array GWY file data item.
value	New value for the item (to be consumed).
array_length	Array length. It must be non-zero as GWY files do not permit empty arrays.

See also

gwyfile_item_set_string_array_copy gwyfile_item_set_string_array_const

gwyfile_item_set_string_array_const()

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

Sets the value of a string array GWY file item.

The item must be of the string array type.

The array and the strings must exist for the entire lifetime of the item. Furthermore, the number of strings and their lengths may not change (more precisely, you must call this function again with the same array to update the item if you change them). Hence this function is best for actual constant arrays, however, it can be also used with other arrays whose lifetime and content are guaranteed.

Parameters

item	A string array GWY file data item.
value	New value for the item (to be used as-is).
array_length	Array length. It must be non-zero as GWY files do not permit empty arrays.

See also

gwyfile_item_set_string_array gwyfile_item_set_string_array_copy

gwyfile_item_set_string_array_copy()

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

Sets the value of a string array GWY file item.

The item must be of the string array type.

This function makes copies of both the provided array and the strings inside. You can continue doing whatever you wish with it after the function returns.

Parameters

item	A string array GWY file data item.
value	New value for the item (to be copied).
array_length	Array length. It must be non-zero as GWY files do not permit empty arrays.

See also

gwyfile_item_set_string_array gwyfile_item_set_string_array_const

gwyfile_item_take_string_array()

char** gwyfile_item_take_string_array

(

GwyfileItem *

item

)

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

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

Use gwyfile_item_array_length() to obtain the array length.

The item must be of the string 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

item	A string array GWY file data item.

Returns

The string array value of item. The array and the strings become owned by the caller.

See also

gwyfile_item_get_string_array