The String Service Class

The service 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.

Though the methods in the String class are implemented using the gmCL Character class, they are intentionally placed in a separate namespace. A major use of the gmNI is to implement the processing of other languages that may well have different character characteristics like case-sensitivity, identifier characters, numeric type designations, and so on. Using the methods in the String class use the characteristics in effect in the parent tool; while using the Character class would use the characteristics in effect in the library.

The method String_ApplyTemplate

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

The method String_ApplyTemplate 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 the use of the %nd notation. These templates are compatible with the language surface form strings in their simple form at least. The parameter format contains the patterned template as described above. It must be null-terminated. The parameter ident contains the identifier to be used with the template. It need not be null-terminated and its length must be specified in the parameter nIdent. The parameter buffer returns the newly formed identifier and the method returns the length of the identifier.

The method String_Compare

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

The method String_Compare 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 parameter string1 is the first character vector in the comparison. The parameter string2 is the second character vector in the comparison. The parameter nCompare specifies the number of characters to be compared.

Note that though the vectors are declared as "char*", making them signed (-127 to +127) they are retrieved here and compared as unsigned bytes. (0 to 255).

The method String_CompareStrings

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

The method String_CompareStrings does a case-insensitive comparison between two character 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 parameter string1 is the first character string in the comparison. The parameter string2 is the second character string in the comparison.

Note that though the vectors are declared as "char*", making them signed (-127 to +127) they are retrieved here and compared as unsigned bytes. (0 to 255);

The method String_ConvertCase

gmNI: void String_ConvertCase(char* String,int ns,int upper);

The method String_ConvertCase forces the case of any alphabetic characters contained in the specified string to either upper-case or lower-case depending upon what is requested. Characters that are not alphabetic or that already have the requested case are not changed. The parameter String is the string to be converted. The string is not assumed to be null-terminated. The parameter ns is the number of characters to be considered for conversion. If the parameter upper is non-zero, then upper-case is to be enforced. If it is zero, then lower-case is enforced.

The method String_Edit

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

The method String_Edit 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 and directive identifiers. These directives identifiers are marked by a leading pattern character -- a percent sign(%) or dollar sign($). The following are identifiers that are recognized (this assumes % is the pattern character):

Note the use of the %nd notation. These patterns are compatible with the language surface form strings in their simple form at least.

The parameter pattern contains the patterned editing specification as described above. It must be null-terminated only if the nPattern property below is zero. The parameter 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. The parameter buffer returns 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. The parameter params is an optional semicolon-delimited character string containing 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. The parameter 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

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

The method String_FindFirst finds the first occurrence of substring in a string starting at the front of the string. All character comparisons are case insensitive. The method returns when it finds a first occurrence or when it reaches the end of the string. The parameter source is the string which is being searched. The parameter length is the length of the search range or zero, which indicates that the entire string is to be searched. The parameter substr is 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 an 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 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 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 represention. If this is zero, then the String parameter is assumed to encompass the value and to be null-termined. 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 than may be retreived via the Character_ErrorCode field. The error codes set by this method are: