Skip to main content
Skip table of contents

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:

TEXT
    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:

TEXT
    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 .

TEXT
    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 .

TEXT
    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.

TEXT
    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 .

TEXT
    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 .

TEXT
    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 .

TEXT
    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.

TEXT
    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.

TEXT
    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:

TEXT
    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:

TEXT
    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.

TEXT
    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.

TEXT
    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 .

TEXT
    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 .

TEXT
    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 .

TEXT
    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.

TEXT
    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.

TEXT
    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.

TEXT
    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.

TEXT
    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.

TEXT
    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 .

TEXT
    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 .

TEXT
    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);

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.