gmNIStringClass

The String Runtime Class

The runtime class String processes character strings in various ways. Internally, this class assumes that all character strings are sequences of 8-bit unsigned bytes — i.e., with values in the range 0-255. Note that the ANSI-C char type is a signed value, so care must be taken.

The method String_ApplyTemplate

Prototype

int String_ApplyTemplate(char* format,char* ident,int nIdent,char* buffer);

The String_ApplyTemplate method applies a template string to an identifier to form a new identifier. The template string uses the embedded “%1d” notation to mark the position where the identifier is to be inserted. A template like “%1d_RowIndex” when applied to an identifier “myRecord” would produce “myRecord_RowIndex”. Note that the use of the %nd notation makes these templates compatible with the language surface form strings. The parameters are:

Parameter	Description
format	Contains the patterned template as described above. It must be null-terminated.
ident	Contains the identifier used with the template. It need not be null-terminated and its length must be specified.
nIdent	Specifies the length of the identifier.
buffer	Receives the newly formed identifier.

The method returns the length of the identifier.

The method String_Compare

Prototype

int String_Compare(CONST char* string1,CONST char* string2,int nCompare);

The String_Compare method does a case-insensitive comparison between two character vectors. This is a bounded comparison. The null-character is treated exactly like any other special character. If all characters within the specified range are identical, up to case distinctions, then the method returns a zero. If two characters within the specified range disagree, then the value of the character in the first vector minus that in the second vector is returned. The parameters are:

Parameter	Description
string1	Contains the first character vector in the comparison.
string2	Contains the second character vector in the comparison.
nCompare	Specifies the number of characters to be compared.

Note that the characters within the strings are retrieved and compared as byte values in the range 0 to 255.

The method String_CompareStrings

Prototype

int String_CompareStrings(char *string1,char *string2);

The String_CompareStrings method does a case-insensitive comparison between two character strings. If all characters within the two strings are identical, up to case distinctions, then the method returns a zero. If two characters within the specified strings disagree, then the value of the character in the first string minus that in the second string is returned. The parameters are:

Parameter	Description
string1	Contains the first character string in the comparison.
string2	Contains the second character string in the comparison.

Note the string characters are retrieved here and compared as byte values (0 to 255).

The method String_Edit

Prototype

int String_Edit(CONST char* pattern,int nPattern,char* buffer,char* params,int patChar);

The String_Edit method forms a character string based on an input pattern string that specifies how the target string is to be formed. The editing pattern consists of characters that are simply copied into the result string as directive identifiers. These directive identifiers are marked by a leading pattern character — usually a percent sign (%) or dollar sign ($). The following are identifiers that are recognized (this assumes % is the pattern character):

Directive	Meaning
%%	Enter a percent sign
%PRM_VERSION%	Platform specified system version identifier
%PRM_BUILDID%	Platform build signature string
%DATE%	Current date using currently selected formatting options
%TIME%	Current time using currently selected formatting options
%nd	Enter the nth (1-based) parameter string

Note that the use of the %nd notation makes these patterns compatible with the language surface form strings. Its parameters are:

Parameter	Description
pattern	Contains the patterned editing specification as described above. It must be null-terminated only if the nPattern parameter is zero.
nPattern	Specifies the length of the editing string. If it is zero, then the editing string is assumed to be null-terminated and its length is computed accordingly.
buffer	Receives the edited string. It is null-terminated. This method does not check to make certain that the buffer is large enough to contain the result.
params	Contains an optional Character_Separator-delimited character string specifying the parameter strings to be used. If the edit strings contains no references to parameter strings then this parameter may be NULL. If a given reference parameter is missing, then no entry is made for it. Note that Character_Separator is normally a semicolon.
patChar	Specifies the character used to mark the directive identifiers. It is typically % or $.

The method returns the number of characters entered into the character result buffer not counting the terminating null.

The method String_FindFirst

Prototype

int String_FindFirst(char* source,int length,CONST char* substr);

The String_FindFirst method finds the first occurrence of substring in a string starting at the front of the string. All character comparisons are case insensitive. It returns when it finds a first occurrence or when it reaches the end of the string. Its parameters are:

Parameter	Description
source	Contains the string which is being searched.
length	Specifies the length of the search range or zero, which indicates that the entire string is to be searched.
substr	Contains the substring which is being searched for.

If all characters within the substring are identical to a sequence of characters within the string, up to case distinctions, then the method returns the position, relative to one, of the start of the matching sequence in the string. If no matching sequence can be located in the string, then a zero is returned.

The method String_FromShort

gmNI: int String_FromShort(int Value,char* String,int nDecimal);

The method String_FromShort converts a short integer 4-byte value into a character string. The parameter Value is the value to be converted. The parameter String returns the character representation of the value in null-terminated string form. The parameter nDecimal is the number of assumed decimal places in the value. The method returns the length of the character representation, not counting the null.

The method String_HexiDecimal

gmNI: int String_HexiDecimal(ULONG Value,char* String,int base);

The method String_HexiDecimal converts an unsigned integer value into a character string using hexadecimal, decimal, octal, or binary notation. Note that the decimal, octal, and binary notation digits are simply subsets of the hexadecimal digits. The parameter Value is the integer value to be converted. The parameter String returns the string representation in the appropriate base, and the parameter base is the base to be used — 2, 8, 10, or 16. The method returns the length of the character representation, not counting the null.

The method String_ShiftLeft

gmNI: void String_ShiftLeft(char* String, int nShift);

The method String_ShifLeft shifts a null-terminated character string left a specified number of positions; thus removing the characters that are overwritten. The most common error in using this method involves forgetting that the string must be null-terminated. The parameter String is the string to be shifted and the parameter nShift is the number of positions to shift.

The method String_ShiftRight

gmNI: void String_ShiftRight(char* String, int nShift, int fill);

The method String_ShiftRight shifts a character string right a specified number of places. The spaces thus created are set equal to the specified fill character. This method is typically used during detailed editing of displays during various numeric conversions. The most common error in using this service involves forgetting that the string must be null-terminated. The parameter String is the string to be shifted and the parameter nShift is the number of positions to shift. The parameter fill is the fill character to be used.

The method String_ToShort

gmNI: int String_ToShort(char* String,int nString,int nDecimal);

The method String_ToShort obtains a short value from a character string. It converts an alphanumeric string into a short integer 4-byte value. If the string contains no decimal point the value is increased by the power of ten indicated. If the string contains decimal places then they must match the number specified. Note that this method accepts negative value representations; however, a leading minus sign must be used. The parameter String contains the integer value to be determined. This string is assumed to be null-terminated only if the nString parameter is zero. The parameter nString is the length of the string representation. If this is zero, then the String parameter is assumed to encompass the value and to be null-terminated. The parameter nDecimal is the number of assumed decimal places in the value. The string must contain either no decimal places or exactly this many decimal places. The method returns the computed short value. If the representation was not well-formed, then an error code is set that may be retrieved via the Character_ErrorCode field. The error codes set by this method are:

Code	Meaning
CharacterError_WrongDec	The string had the wrong number of decimal places
CharacterError_BadDigits	The string contained non-numeric digits