HPGCC3 Documentation 3.0 R003

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:
cstrCalculator 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:
cstrCalculator string to get bytes from.
dataPointer to a preallocateed buffer that is to receive the bytes.
maxbytesSize 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:
cstrCalculator string.
stringPointer to a preallocateed buffer that is to receive the string.
maxcharsSize 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:
cstrCalculator string.
stringPointer to a preallocateed buffer that is to receive the string.
startposPosition of the first character to copy. First char on the string is at position 0.
ncharsNumber 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:
whereDefines 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).
dataPointer to the buffer containing the bytes to extract.
nbytesNumber 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:
whereDefines 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).
stringPointer 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:
whereDefines 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).
stringPointer to a null-terminated string.
startposPosition of the first character to extract. First character is 0.
ncharsNumber 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:
objCalculator string.
Returns:
Number of nibbles in the given string, or 0 if not a string.