The String
Service Runtime Class
The
service 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.
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 Prototype| Code Block |
|---|
| language | cpp |
|---|
| theme | Eclipse |
|---|
| linenumbers | true |
|---|
|
int String_ApplyTemplate(char* format,char* ident,int nIdent,char* buffer);
|
The method 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
. These makes these templates
are compatible with the language surface form strings
in their simple form at least. The
parameter format contains parameters are:
| Parameter | Description |
| format | Contains the patterned template as described above. It must be null-terminated. |
| 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 |
method returns the length of the identifier.
The method String_Compare
gmNI: int Prototype| Code Block |
|---|
| language | cpp |
|---|
| theme | Eclipse |
|---|
| linenumbers | true |
|---|
|
int String_Compare(CONST char* string1,CONST char* string2,int nCompare);
|
The method 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
parameter string1 is parameters are:
| Parameter | Description |
| string1 | Contains the first character vector in the comparison. |
| Contains the second character vector in the comparison. |
| Specifies the number of characters to be compared. |
The method String_CompareStrings
gmNI: int Prototype| Code Block |
|---|
| language | cpp |
|---|
| theme | Eclipse |
|---|
| linenumbers | true |
|---|
|
int String_CompareStrings(char *string1,char *string2);
|
The method String_CompareStrings method 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 parameters are:
| Parameter | Description |
| string1 | Contains the first character string in the comparison. |
| Contains the second character string in the comparison. |
The method String_
ConvertCasegmNI: 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 Edit
Prototype| Code Block |
|---|
| language | cpp |
|---|
| theme | Eclipse |
|---|
| linenumbers | true |
|---|
|
int String_Edit(CONST char* pattern,int nPattern,char* buffer,char* params,int patChar);
|
The method 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
and as directive identifiers. These
directives 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 %USR_VERSION% |
| Platform specified user version identifier | %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
. These makes these patterns
are compatible with the language surface form strings
in their simple form at least. The parameter pattern contains . Its parameters are: | Parameter | Description |
| pattern | Contains the patterned editing specification as described above. It must be null-terminated only if the 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. |
| 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. |
| 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 String_FindFirst
gmNI: int Prototype| Code Block |
|---|
| language | cpp |
|---|
| theme | Eclipse |
|---|
| linenumbers | true |
|---|
|
int String_FindFirst(char* source,int length,CONST char* substr);
|
The method 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.
The method It returns when it finds a first occurrence or when it reaches the end of the string.
The parameter source is Its parameters are:
| Parameter | Description |
| source | Contains the string which is being searched. |
| Specifies the length of the search range or zero, which indicates that the entire string is to be searched. |
| 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
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
representionrepresentation. If this is zero, then the
String parameter is assumed to encompass the value and to be null-
terminedterminated. 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 that may be
retreived 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 |