Tagged objects functions

Defines
#define	sat3_taglen(tag)   sat3_idlen(tag)
	Get the number of characters in the tag of a tagged object.
Functions
SAT_OBJECT	sat3_createtag_str (SAT_OBJECT where, char *tag, SAT_OBJECT obj)
	Create a tagged object from a C-style string and an arbitrary object.
BOOL	sat3_converttag_str (SAT_OBJECT tagged, char *string, int maxchars)
	Extract a C-style string from a tagged object.
SAT_OBJECT	sat3_striptag (SAT_OBJECT obj)
	Isolate the object on a tagged object.

---

Detailed Description

This group includes all functions used to create/convert tagged objects.

---

Define Documentation

#define sat3_taglen

(

tag

)

sat3_idlen(tag)

Get the number of characters in the tag of a tagged object.

Parameters:

tag	Tagged object.

Returns:

Number of characters in the given tag, or 0 if not a tagged object.

Definition at line 2268 of file sat3.h.

---

Function Documentation

BOOL sat3_converttag_str	(	SAT_OBJECT	tagged,
		char *	string,
		int	maxchars
	)

Extract a C-style string from a tagged object.

Stores the string on a preallocated buffer and appends a null char at the end.

Parameters:

tagged	Object to extract the tag from.
string	Pointer to a preallocateed buffer that is to receive the string.
maxchars	Size of the preallocated buffer.

Returns:

TRUE if successful, FALSE otherwise. If the size of the tag is greater than the buffer size, the tag will be truncated at maxchars.

See also:

sat3_taglen Object creation and manipulation

SAT_OBJECT sat3_createtag_str	(	SAT_OBJECT	where,
		char *	tag,
		SAT_OBJECT	obj
	)

Create a tagged object from a C-style string and an arbitrary object.

Creates a new object, consisting of a copy of the given object, tagged with the given string.

Parameters:

where	Defines where to allocate memory from. Can be one of the following constants: ALLOC_HEAP Allocates from the C-heap using malloc() ALLOC_TEMPOB Allocates memory from the TEMPOB calculator area or... it can be an element (SAT_OBJECT) within a composite object, (array, list or any other).
tag	Pointer to a null-terminated string.
obj	Object to tag. Must be a valid object.

Returns:

SAT_OBJECT with the new tagged object, or zero if it fails. When a SAT_OBJECT is given to the 'where' parameter, the same SAT_OBJECT is returned or 0 if error.

See also:

Object creation and manipulation

SAT_OBJECT sat3_striptag

(

SAT_OBJECT

obj

)

Isolate the object on a tagged object.

Get a SAT_OBJECT pointer to the object being tagged. The tagged object is not modified in memory, the returned pointer will be within the same tagged object. Only one tag level is stripped, nested tags need to be stripped one by one.

Parameters:

obj	Tagged object to strip tag.
string	Pointer to a preallocateed buffer that is to receive the string.
maxchars	Size of the preallocated buffer.

Returns:

SAT_OBJECT pointing to the object, or null if not a tagged object.