String functions

Defines
#define	sat3_strlen(cstr)   (sat3_strsize(cstr)>>1)
	Get the number of characters in a string.
Functions
SAT_OBJECT	sat3_createcstr_bytes (SAT_OBJECT where, char *data, int nbytes)
	Create a string object from a sequence of bytes.
BOOL	sat3_convertcstr_bytes (SAT_OBJECT cstr, char *data, int maxbytes)
	Extract a sequence of bytes from a calculator string.
SAT_OBJECT	sat3_createcstr_str (SAT_OBJECT where, char *string)
	Create a string object from a C-style string.
BOOL	sat3_convertcstr_str (SAT_OBJECT cstr, char *string, int maxchars)
	Extract a C-style string from a calculator string.
SAT_OBJECT	sat3_createcstr_substr (SAT_OBJECT where, char *string, int startpos, int nchars)
	Create a string object from a C-style string.
BOOL	sat3_convertcstr_substr (SAT_OBJECT cstr, char *string, int startpos, int nchars)
	Extract a C-style string from a calculator string.
int	sat3_strsize (SAT_OBJECT obj)
	Get the number of nibbles in a string.

---

Detailed Description

This group includes all functions used to create/convert (character) string objects.

---

Define Documentation

#define sat3_strlen

(

cstr

)

(sat3_strsize(cstr)>>1)

Get the number of characters in a string.

Parameters:

cstr	Calculator string.

Returns:

Number of characters in the given string, or 0 if not a string.

Definition at line 1989 of file sat3.h.

---

Function Documentation

BOOL sat3_convertcstr_bytes	(	SAT_OBJECT	cstr,
		char *	data,
		int	maxbytes
	)

Extract a sequence of bytes from a calculator string.

Useful for strings that include the null character, or to read arbitrary data from a calculator string.

Parameters:

cstr	Calculator string to get bytes from.
data	Pointer to a preallocateed buffer that is to receive the bytes.
maxbytes	Size of the preallocated buffer.

Returns:

TRUE if successful, FALSE otherwise. If the size of the string is greater than the buffer size, only up to maxbytes will be extracted.

See also:

sat3_convertcstr_str sat3_convertcstr_substr sat3_strlen Object creation and manipulation

BOOL sat3_convertcstr_str	(	SAT_OBJECT	cstr,
		char *	string,
		int	maxchars
	)

Extract a C-style string from a calculator string.

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

Parameters:

cstr	Calculator string.
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 string is greater than the buffer size, the string will be truncated at maxchars.

See also:

sat3_convertcstr_bytes sat3_convertcstr_substr sat3_strlen Object creation and manipulation

BOOL sat3_convertcstr_substr	(	SAT_OBJECT	cstr,
		char *	string,
		int	startpos,
		int	nchars
	)

Extract a C-style string from a calculator string.

Stores the string on a preallocated buffer and appends a null char at the end. It starts at the given position (0-based index) and copies up to the given number of characters. The buffer size must be be at least nchars+1.

Parameters:

cstr	Calculator string.
string	Pointer to a preallocateed buffer that is to receive the string.
startpos	Position of the first character to copy. First char on the string is at position 0.
nchars	Number of characters to extract.

Returns:

TRUE if successful, FALSE otherwise.

See also:

sat3_convertcstr_bytes sat3_convertcstr_str Object creation and manipulation

SAT_OBJECT sat3_createcstr_bytes	(	SAT_OBJECT	where,
		char *	data,
		int	nbytes
	)

Create a string object from a sequence of bytes.

Useful for strings that include the null character, or to include arbitrary data on a calculator 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).
data	Pointer to the buffer containing the bytes to extract.
nbytes	Number of bytes to include on the string.

Returns:

SAT_OBJECT with the new string, 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:

sat3_createcstr_str sat3_createcstr_substr Object creation and manipulation

SAT_OBJECT sat3_createcstr_str	(	SAT_OBJECT	where,
		char *	string
	)

Create a string object from a C-style string.

Create a string object from the given string, without the ending null char.

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).
string	Pointer to a null-terminated string.

Returns:

SAT_OBJECT with the new string, 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:

sat3_createcstr_bytes sat3_createcstr_substr Object creation and manipulation

SAT_OBJECT sat3_createcstr_substr	(	SAT_OBJECT	where,
		char *	string,
		int	startpos,
		int	nchars
	)

Create a string object from a C-style string.

Create a string object from a portion of the given string, starting at the given position (0-based index) and with the given length.

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).
string	Pointer to a null-terminated string.
startpos	Position of the first character to extract. First character is 0.
nchars	Number of characters to extract.

Returns:

SAT_OBJECT with the new string, 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:

sat3_createcstr_bytes sat3_createcstr_str Object creation and manipulation

int sat3_strsize

(

SAT_OBJECT

obj

)

Get the number of nibbles in a string.

Parameters:

obj	Calculator string.

Returns:

Number of nibbles in the given string, or 0 if not a string.