String handling functions
This page applies to Harlequin v13.1r0 and later; and to Harlequin MultiRIP but not Harlequin Core
Allocation and deallocation of string records
Functions are provided in the PFI to allocate, free, open and close string records. String records can be opened as fixed length records, or as extensible records, and require different handling based on that status.
Create a new, uninitialized string record
This is the only valid way of creating a PlgFwStrRecord
: PlgFwStrRecord * PlgFwStrRecordAlloc(void);
Free a string record
This function deallocates a PlgFwStrRecord
allocated using PlgFwStrRecordAlloc
. It is an error to supply a NULL pointer, or a pointer to any area of memory not allocated from PlgFwStrRecordAlloc
. If the string record is extensible, the record's buffer should have been abandoned. See PlgFwStrRecordAbandon
before being freed using this function:
void PlgFwStrRecordFree(PlgFwStrRecord *pRecord);
Open a string record as an empty, extensible record
This function opens an existing PlgFwStrRecord
as an extensible record, initially containing an empty string. Since the record is extensible, there is no need to call PlgFwStrRecordClose
when finished with it. The record should previously have been allocated by PlgFwStrRecordAlloc
:
void PlgFwStrRecordOpen(PlgFwStrRecord *pRecord);
Open a string record as an extensible record with a specified initial size
This function opens an existing PlgFwStrRecord
as an extensible record of an initial size specified by
cbSize
. Since the record is extensible, this maximum size could increase with use:
void PlgFwStrRecordOpenSize(PlgFwStrRecord *pRecord, uint32 cbSize);
Open a string record as a fixed size record for appending to an existing buffer
This function opens an existing PlgFwStrRecord
as a fixed size record for appending to the existing content of a fixed sized buffer. The buffer to be appended to, and its size (in bytes, not characters) are also given in the arguments:
void PlgFwStrRecordOpenOn(
PlgFwStrRecord *pRecord, PlgFwByte *pb,
uint32 cbSize);Close a string record whose buffer content should be preserved
This function closes a PlgFwStrRecord
whose buffer content should be preserved. In the case of an extensible record, the buffer may be reallocated to the minimum size needed in order to hold its present content; for a fixed record this is harmless, but unnecessary. The pointer value returned is that of the (possibly reallocated) buffer:
PlgFwString PlgFwStrRecordClose(FwStrRecord *pRecord);
Close a string record whose buffer content can be discarded
This function closes a PlgFwStrRecord
whose buffer content is no longer important. In the case of an extensible record, the buffer will be freed:
void PlgFwStrRecordAbandon(PlgFwStrRecord *pRecord);
Shorten an extensible string record's buffer to a given length
This function will shorten an extensible record to a given length, returning the actual length of the record after shortening. Note that the length is in bytes, not characters. You should not attempt to truncate the record in the middle of a multi‐byte character, as this could lead to undesirable results:
uint32 PlgFwStrRecordShorten(
PlgFwStrRecord *pRecord, uint32 cbLength);Examining the contents of string records
The following functions are designed to interrogate the buffer contained within a string record in order to determine various characteristics of the string contained in the buffer, such as its length, its extensibility and how many bytes remain available within it.
Note: Length values typically refer to the number of bytes available, or used, in a buffer, not the number of characters.
Return a pointer to the buffer in the string record
This function returns a PlgFwString
pointer to the buffer in the string record:
PlgFwString PlgFwStrRecordGetBuffer(PlgFwStrRecord *pRecord);
Return a pointer to the last byte in the buffer
This function returns a pointer to the last byte in the buffer:
PlgFwByte * PlgFwStrRecordGetLast(PlgFwStrRecord *pRecord);
Return a pointer to the current terminator position in the buffer
This function returns a pointer to the current terminator position in the buffer:
PlgFwByte * PlgFwStrRecordGetTerminator(PlgFwStrRecord *pRecord);
Determine whether the buffer is fixed length or extensible
This function determines whether the buffer in the string record is fixed length or extensible. The function will return TRUE
if the buffer is of fixed length. If TRUE
, the buffer will be truncated rather than extended if more data are supplied than there is space remaining in the buffer.
uint8 PlgFwStrRecordIsFixed(PlgFwStrRecord *pRecord);
Determine whether or not the buffer is truncating further input
This function determines whether or not the buffer is full and will ignore any further input. If this function returns TRUE
, the buffer is full. It is set to truncate and all further additions to the buffer will simply be ignored.
uint8 PlgFwStrRecordIsTruncated(PlgFwStrRecord *pRecord);
Determine the current length of the string stored in the record
This function returns the number of bytes (not characters) currently in the record.
uint32 PlgFwStrRecordStringLength(PlgFwStrRecord *pRecord);
Determine the available space in the record
This function returns the number of bytes (not characters) remaining in the record.
uint32 PlgFwStrRecordUnusedSize(PlgFwStrRecord *pRecord);
Determine the maximum size of the record
This function returns the maximum number of bytes (not characters) available to the record.
uint32 PlgFwStrRecordMaxSize(PlgFwStrRecord *pRecord)
Primitive string record functions
All primitive functions append to existing contents of a record. If a record must be truncated, multi‐ byte string truncation is performed at character boundaries; raw input is truncated at byte boundaries. All of these functions return the byte length of the string actually held in the string record's buffer at the end of the operation.
Add a single HES character to the record
A single HES character is supplied by the tc
parameter and is appended to the string supplied in
*pRecord
.
uint32 PlgFwStrPutTextCharacter(
PlgFwStrRecord *pRecord, PlgFwTextCharacter tc);Add a zero-terminated HES string to the record
A zero‐terminated HES string is supplied by the ptbz
parameter and is appended to the string sup‐ plied in *pRecord
.
uint32 PlgFwStrPutTextString(
PlgFwStrRecord *pRecord, PlgFwTextString ptbz);Add a text string of a given length to the record
Bytes from the text string pointed to by the ptb
parameter are appended to the string supplied in
*pRecord
. The number of bytes to append is specified by cbLength
.
Note: The length is specified in bytes, not characters. Be careful not to supply a length which would cause only part of an HES character to be appended to the record; this could result in undesirable behavior.
uint32 PlgFwStrNPutTextString(
PlgFwStrRecord *pRecord, PlgFwTextByte *ptb, uint32 cbLength );Add a single raw byte to the record
A single raw byte is supplied by the rb
parameter and is appended to the string supplied in *pRecord
.
uint32 PlgFwStrPutRawByte(
PlgFwStrRecord *pRecord, PlgFwRawByte rb);Add a zero-terminated raw byte string to the record
A zero‐terminated string of raw bytes is supplied by the prbz
parameter and is appended to the string supplied in *pRecord
.
uint32 PlgFwStrPutRawString(
PlgFwStrRecord *pRecord, PlgFwRawString prbz);Add a raw byte string of a given length to the record
Bytes from the raw byte string pointed to by the prb
parameter are appended to the string supplied in
*pRecord
. The number of bytes to append is specified by cbLength
.
uint32 PlgFwStrNPutRawString(
PlgFwStrRecord *pRecord, PlgFwRawByte *prb, uint32 cbLength);String formatting functions
The formatting functions for manipulating HES string records operate in much the same way as do the classic C library functions (for example, sprintf()
), with some extensions. The extensions pro‐ vided can be summarized as:
Positional arguments
These take the form:
"%[<n>]<format>"
Meaning “select the <n
>the argument (numbered from zero) following the format string, and apply the conventional sprintf()
format to it”. For example, the following command writes the two arguments to the string record in reverse order:
PlgFwStrPrintf(pRecord, FALSE, "%[1]s %[0]d", 3, "string");
The string written into pRecord
from this call would be:
string 3
The following example demonstrates the use of the PLGFW_PRINTF_DUMMY
macro. This can be used to substitute for an argument which will not be used; in this case, only the second argument is
PlgFwStrPrintf(pRecord, FALSE, "%[1]s", PLGFW_PRINTF_DUMMY, "string");
The string written into pRecord
from this call would be:
string
String branching
String branching allows substrings to be selected from a set of potential candidates, specified as follows:
"%(branch0%|branch1%)"
The next unconsumed argument following the set of branch strings is an integer which selects one of the strings, indexed from zero. Branches may be nested, in which case their arguments are pulled in a depth‐first order. Positional arguments (see Positional arguments
) count argument 0
as being the first argument after the final branch argument. For example, the result of:
PlgFwStrPrintf(pRecord, FALSE, "%(branch0%|branch1%)", 0);
is "branch0"
, whereas the result of:
PlgFwStrPrintf(pRecord, FALSE, "%(branch0%|branch1%)", 1);
is "branch1"
.
Translated strings
The PFI provides support for translating strings through FrameWork's translation database. Arguments specified using a %t
tag are treated as strings to be translated.
The dummy argument macro
As described above, PLGFW_PRINTF_DUMMY
is defined to act as a dummy argument to PlgFwStrPrintf
and other functions. PLGFW_PRINTF_DUMMY
is simply defined as:
#define PLGFW_PRINTF_DUMMY
Functions that write into the string record
The following functions are provided to write data into the buffer of the string record:
Write a formatted string into a string record
This function is analogous to the standard C function sprintf()
.
ptbzFormat
specifies the base string, followed by optional formatting arguments.
If fMessage
is TRUE
, the string will be translated; otherwise not. The return value is the number of bytes actually inserted in the record.
uint32 PlgFwStrPrintf (
PlgFwStrRecord *pRecord, int32 fMessage, PlgFwTextString ptbzFormat,
... );Write a formatted string into a string record using an argument list for the formatting arguments
This function is analogous to the standard C function vsprintf()
.
ptbzFormat
specifies the base string, followed by a list of formatting arguments specified by the args
parameter, of type va_list
.
If fMessage
is TRUE
, the string will be translated; otherwise not. The return value is the number of bytes actually inserted in the record.
uint32 PlgFwStrVPrintf(
PlgFwStrRecord *pRecord, int32 fMessage, PlgFwTextString ptbzFormat, va_list args);Write a formatted string into a string record, outputting numeric values in a localized form
This function operates in the same way as PlgFwStrPrintf
() (see above), but outputs numeric values in a localized form:
uint32 PlgFwStrPrintfLocal (
PlgFwStrRecord *pRecord, int32 fMessage, PlgFwTextString ptbzFormat,
... );Write a formatted string into a string record using an argument list for the formatting arguments, outputting numeric values in a localized form
This function operates in the same way as PlgFwStrPrintf
() (see above), but outputs numeric values in a localized form:
uint32 PlgFwStrVPrintfLocal (
PlgFwStrRecord *pRecord, int32 fMessage, PlgFwTextString ptbzFormat, va_list args);Write an integer value, in a localized form, to a string record
This function provides a simple way of converting an integer value into a localized string and placing it into a string record.
Localization is controlled by fUseCLocale
. Setting fUseCLocale
to FALSE
will cause a localized form of the string to be produced; setting fUseCLocale
to TRUE
will produce a non‐localized string to be writ‐ ten to the record.
The function returns the number of bytes actually written to the string record.
uint32 PlgFwStrPutInt(
PlgFwStrRecord *pRecord, int32 value,
int32 fUseCLocale);String access functions
These two functions allow the data to be retrieved from a string record one character at a time. They both use a pointer to a text byte to indicate the ‘current' position in the string. The convention is that this points to the next character to be retrieved if the string is being read in a forwards direction.
Retrieve the next character from a string and advance the string pointer
Get the first PlgFwTextCharacter
in a PlgFwTextString
, (pointed to by *pptb
) and advance the string pointer.
PlgFwTextCharacter PlgFwStrGetTextCharacter(
PlgFwTextByte **pptb);Retrieve the previous character from a string and move the string pointer back
Get the previous character in a null‐terminated string and move the character pointer back to point to it. If *pptb
is NULL, it is treated as if it pointed to the terminating zero instead. If *pptb
points to the start of the string (that is, == ptbzStart
), the function returns 0
and does not change *pptb
.
PlgFwTextCharacter PlgFwStrGetPreviousTextCharacter(
PlgFwTextString ptbzStart, PlgFwTextByte **pptb);String property functions
These two functions are concerned with the length, either in raw bytes or in characters, of the string.
Determine the number of characters in a string
This function returns the number of PlgFwTextCharacters
in a PlgFwTextString
, not including the zero terminator.
uint32 PlgFwStrCountCharacters(PlgFwTextString ptbz);
Determine the number of bytes in a string
This function returns the number of raw bytes in a PlgFwString
, not including the zero terminator.
uint32 PlgFwStrCountBytes(PlgFwString ptbz);
String comparison functions
The following functions are provided for comparing and validating the contents of string records:
Compare two strings for bytewise equality
This function performs a bytewise comparison of two strings which do not contain HES characters. The function returns TRUE
if their contents are equal, FALSE
if not.
Note:
The comparison is only valid if neither string contains HES characters – it is meant as a quick and easy check for simple cases only. Use PlgFwStrCompare()
for cases where strings could contain HES characters.
int32 PlgFwStrEqual(PlgFwString ptbz1, PlgFwString ptbz2 );
Compare two strings for bytewise equality, length limited
This function performs a bytewise comparison of two strings which do not contain HES characters, up to a given length (specified in bytes by the parameter cbLen
). The function returns TRUE
if their contents are equal, FALSE
if not.
Note:
The comparison is only valid if neither string contains HES characters – it is meant as a quick and easy check for simple cases only. Use PlgFwStrNCompare()
for cases where strings could contain HES characters.
int32 PlgFwStrNEqual (PlgFwString ptbz1, PlgFwString ptbz2, uint32 cbLen);
Check an HES string for invalid characters
This function will only return TRUE
if all characters in an HES string are valid according to the
PLGFWSTR_TC_VALID
macro (see String handling macros
).
int32 PlgFwStrValidate(PlgFwTextString ptbz);
Compare two HES strings for equality
Compares two HES strings for string equality. Because this function can take a much longer time than
PlgFwStrEqual
, it may be preferable to use that function where possible.
This function returns zero if the two strings are equal. If the strings are not equal, the function will return 1 if the first point of inequality is of numerically higher value in ptbz1
than in ptbz2
, ‐1 if the first point of inequality is of numerically lower value in ptbz1
than in ptbz2
.
int32 PlgFwStrCompare(
PlgFwTextString ptbz1, PlgFwTextString ptbz2);Compare two HES strings for equality, length limited
This function compares the strings for equality in the same way as PlgFwStrCompare
, up to the length limit specified by cblen
. The length specified is a byte length, not a character count.
This function returns zero if the two strings are equal. If the strings are not equal, the function will return 1 if the first point of inequality is of numerically higher value in ptbz1
than in ptbz2
, ‐1 if the first point of inequality is of numerically lower value in ptbz1
than in ptbz2
.
int32 PlgFwStrNCompare(
PlgFwTextString ptbz1, PlgFwTextString ptbz2, uint32 cbLen);String searching functions
The following functions are used to search a string for the presence or absence of a given character, or to extract tokens from a string according to user‐specified delimiters:
Find the first occurrence of an HES character in a string
This function searches the string specified by ptbz
for the first occurrence of the character specified by tc
. The function returns pointer to the first occurrence of the character in the string, or NULL if the character is not found.
PlgFwTextString PlgFwStrChr(
PlgFwTextString ptbz, PlgFwTextCharacter tc);Find the last occurrence of an HES character in a string
This function searches backwards through the string specified by ptbz
for the last occurrence of the character specified by tc
. The function returns pointer to the last occurrence of the character in the string, or NULL if the character is not found.
PlgFwTextString PlgFwStrRChr(
PlgFwTextString ptbz, PlgFwTextCharacter tc);Find a token in a string
This function searches through a string to tokenize it according to the specified delimiters (ptbDelimiters)
. The string pointer *pptbz
, which points to the string to be tokenized, is supplied by reference, and will be modified by the function.
The function returns a pointer to the first token found.
The function may be repeatedly called using the same pointer‐to‐a‐pointer. A pointer to each successive token found will be returned, until no more tokens can be found, and the function returns NULL.
PlgFwTextString PlgFwStrTok(
PlgFwTextString *pptbz, PlgFwTextString ptbDelimiters);String copying functions
The following functions are used to copy the contents of one string into another entity:
Create a new copy of a string
This function creates a new object by allocating memory and copying the supplied string into it, returning a pointer to the newly created string, or NULL if heap memory is exhausted.
PlgFwTextString PlgFwStrDuplicate(PlgFwTextString ptbz);
Copy the contents of a string into another existing string
This function copies the contents of one HES string into another pre‐existing one. The function returns the number of bytes actually copied to the destination string, not including any terminating zero byte.
int32 PlgFwStrCpy(
PlgFwTextString ptbzDest, PlgFwTextString ptbzSrc);Copy the contents of a string into another existing string, length limited
This function copies the contents of one HES string into an another pre‐existing one, up to the length specified by sizeDest
. The sizeDest
parameter specifies the length as a byte count, not a character count. If the source is too long, it will be truncated at the last whole HES character. This may cause warning messages to be generated; it would be better if the code first checks for itself whether the source can fit into the destination.
The function returns the number of bytes actually copied to the destination string, not including any terminating zero byte.
int32 PlgFwStrNCpy(
PlgFwTextString ptbzDest, PlgFwTextString ptbzSrc, uint32 sizeDest);String-to-number conversion functions
The following functions are provided to enable the conversion of strings which represent numeric values back into numeric form:
Convert a string to a double
This function converts a string in the C locale into a double
. The converted value is written to the variable pointed to by prResult
. If the conversion is successful the function returns TRUE
; if the string does not contain a valid number, the function returns FALSE
.
int32 PlgFwStrToD(
PlgFwTextString *pptbz, double *prResult);Convert a string to a 32-bit integer
This function converts a string into a 32‐bit integer. The base numbering system should be specified as well as the input string. The converted value is written to the variable pointed to by prResult
. If the conversion is successful the function returns TRUE
; if the string does not contain a valid number, the function returns FALSE
.
int32 PlgFwStrToL(
PlgFwTextString *pptbz, uint32 nBase,
int32 *pnResult);Character manipulation and test functions
The following functions are concerned with upperand lower-case versions of the same character, and with detecting white‐space and digit characters:
Return the upper-case version of a character
This function accepts a character argument and returns the upper-case version of that character:
PlgFwTextCharacter PlgFwStrToUpper(PlgFwTextCharacter tc);
Return the lower-case version of a character
This function accepts a character argument and returns the lower-case version of that character:
PlgFwTextCharacter PlgFwStrToLower(PlgFwTextCharacter tc);
Determine whether the character is a white-space character
This function accepts a character argument and returns TRUE
if the character is a white‐space character, otherwise it returns FALSE
.
int32 PlgFwStrIsWhiteSpace(PlgFwTextCharacter tc);
Determine whether the character is a digit character
This function accepts a character argument and returns TRUE
if the character is a digit character, other‐ wise it returns FALSE
.
int32 PlgFwStrIsDigit(PlgFwTextCharacter tc);
Locale functions
The following functions are concerned with string locales:
Determine the application's locale
This function populates pRecord
with a string identifying the locale in which the application is running. This string is platform‐dependent.
void PlgFwStrGetLocaleIDString(PlgFwStrRecord *pRecord);