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

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:

The method returns the length of the identifier.

The method String_Compare

Prototype

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:

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

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:

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

The method String_Edit

Prototype

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

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

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

The method String_FindFirst

Prototype

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:

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: