Item – string

Functions
GwyfileItem *	gwyfile_item_new_string (const char *name, char *value)
	Creates a new string GWY file item. More...
GwyfileItem *	gwyfile_item_new_string_copy (const char *name, const char *value)
	Creates a new string GWY file item. More...
GwyfileItem *	gwyfile_item_new_string_const (const char *name, const char *value)
	Creates a new string GWY file item. More...
const char *	gwyfile_item_get_string (const GwyfileItem *item)
	Gets the string value contained in a GWY file data item. More...
char *	gwyfile_item_take_string (GwyfileItem *item)
	Takes the string value contained in a GWY file data item. More...
void	gwyfile_item_set_string (GwyfileItem *item, char *value)
	Sets the value of a string GWY file item. More...
void	gwyfile_item_set_string_copy (GwyfileItem *item, const char *value)
	Sets the value of a string GWY file item. More...
void	gwyfile_item_set_string_const (GwyfileItem *item, const char *value)
	Sets the value of a string GWY file item. More...

Detailed Description

Function Documentation

gwyfile_item_get_string()

const char* gwyfile_item_get_string

(

const GwyfileItem *

item

)

Gets the string value contained in a GWY file data item.

The item must be of the string 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 GWY file data item.

Returns

The string value of item. The string ownership does not change.

See also

gwyfile_item_take_string

gwyfile_item_new_string()

GwyfileItem* gwyfile_item_new_string	(	const char *	name,
		char *	value
	)

Creates a new string GWY file item.

The item consumes the provided string and takes care of freeing it later. You must not touch the string 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). It must be a UTF-8-encoded string.

Returns

The newly created GWY file data item.

See also

gwyfile_item_new_string_copy gwyfile_item_new_string_const

gwyfile_item_new_string_const()

GwyfileItem* gwyfile_item_new_string_const	(	const char *	name,
		const char *	value
	)

Creates a new string GWY file item.

The string must exist for the entire lifetime of the item and its length must not change. Hence this function is best for actual constant strings, however, it can be also used with other strings whose lifetime is 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). It must be a UTF-8-encoded string.

Returns

The newly created GWY file data item.

See also

gwyfile_item_new_string gwyfile_item_new_string_copy

gwyfile_item_new_string_copy()

GwyfileItem* gwyfile_item_new_string_copy	(	const char *	name,
		const char *	value
	)

Creates a new string GWY file item.

This function makes a copy the provided string. 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). It must be a UTF-8-encoded string.

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 gwyfile_item_new_string_const

gwyfile_item_set_string()

void gwyfile_item_set_string	(	GwyfileItem *	item,
		char *	value
	)

Sets the value of a string GWY file item.

The item must be of the string type.

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

Parameters

item	A string GWY file data item.
value	New value for the item (to be consumed).

See also

gwyfile_item_set_string_copy gwyfile_item_set_string_const

gwyfile_item_set_string_const()

void gwyfile_item_set_string_const	(	GwyfileItem *	item,
		const char *	value
	)

Sets the value of a string GWY file item.

The item must be of the string type.

The string must exist for the entire lifetime of the item and its length must not change. Hence this function is best for actual constant strings, however, it can be also used with other strings whose lifetime is guaranteed.

Parameters

item	A string GWY file data item.
value	New value for the item (to be used as-is).

See also

gwyfile_item_set_string gwyfile_item_set_string_copy

gwyfile_item_set_string_copy()

void gwyfile_item_set_string_copy	(	GwyfileItem *	item,
		const char *	value
	)

Sets the value of a string GWY file item.

The item must be of the string type.

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

Parameters

item	A string GWY file data item.
value	New value for the item (to be copied).

See also

gwyfile_item_set_string gwyfile_item_set_string_const

gwyfile_item_take_string()

char* gwyfile_item_take_string

(

GwyfileItem *

item

)

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

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

The item must be of the string 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 GWY file data item.

Returns

The string value of item. The string becomes owned by the caller.

See also

gwyfile_item_get_string