The Character Service Class

The service class Character 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 field Character_ErrorCode

gmCL: int Character_ErrorCode;

The field Character_ErrorCode is used to record errors that occur doing "character processing" operations.

The method Character_ApplyTemplate

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

The method Character_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 Character_Compare

gmCL: int Character_Compare(CONST char* string1,CONST char* string2,int nCompare);
gmNI: int String_Compare(CONST char* string1,CONST char* string2,int nCompare);
gmSL: string Character.Compare(string string1, string string2, int nCompare);

The method Character_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 Character_CompareStrings

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

The method Character_CompareStrings does a case-insensitive comparison between two character character strings. If all characters within the twp 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 Character_ConvertCase

gmCL: void Character_ConvertCase(char* String,int ns,int upper);
gmNI: void String_ConvertCase(char* String,int ns,int upper);
gmSL: string Character.Tolower(string strValue, int start, int length);
gmSL: string Character.Toupper(string strValue, int start, int length);

The method Character_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 Character_DigitValue

gmCL: int Character_DigitValue(int charValue);

The method Character_DigitValue returns the value of a character digit. For the actual numeric digits this is the value of that digit. For lowercase alphabetic characters it is the sequence number of the letter in the letter in the alphabet. For uppercase alphabetic characters it is the value of the corresponding lowercase letter. For some special characters if is a token type value for that character. For all other characters it is zero. The parameter charValue is the value of the character being tested. It should be between 0 and 255.

The method Character_DoubleDisplay

gmCL: int Character_DoubleDisplay(char* fiocrec,double value);

The method Character_DoubleDisplay converts a double precision value to free-form display form without any additional direction from the caller. Based on the value being displayed it selects the most appropriate display for it. The parameter fiocrec returns display form of value and the parameter value is the value to be displayed. The method returns the width in characters of the formed display.

The method Character_EditString

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

The method Character_EditString 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 Character_FindFirst

gmCL: int Character_FindFirst(char* source,int length,CONST char* substr);
gmNI: int String_FindFirst(char* source,int length,CONST char* substr);
gmSL: int Character.FindFirst(string source,int iStart,string subStr);

The method Character_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 Character_FindLast

gmCL: int Character_FindLast(char* String,int nString,CONST char* Substring);

The method Character_FindLast attempts to find a substring within a string starting at the back of the string. All character comparisons are case insensitive. The method returns when it finds a last occurrence or when it reaches the front of the string. The parameter String is the string being searched. The parameter nString is the length of the string or zero if the string is null-terminated. The parameter Substring is the substring being searched for. It must be null-terminated. 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 Character_FromDate

gmCL: int Character_FromDate(int date,char* String);

The method Character_FromDate converts a date value into a string. The format used is is mm/dd/yy. The parameter date contains the relative julian date value to be displayed. The parameter String returns the display form of the date in null terminated form. The method returns the length of the date display.

The method Character_FromDateTime

gmCL: int Character_FromDateTime(longlong datetime,char* String);

The method Character_FromDateTime converts a date/time value into a string by simply displaying the date component followed by the time component. The parameter datetime is the actual date/time value to be displayed. The parameter String returns the display form of the datetime value. The method returns the length of the date/time display.

The method Character_FromDouble

gmCL: void Character_FromDouble(double val,int ndig,int* pdecpt,int* psign, char* dspdig);

The method Character_FromDouble converts a double precision floating point value into a raw character form. ANSI C expects that all conversions of floating point values to string be performed via the "sprintf" service. Though this can be done, most generalize applications, prefer to perform their own editing operations, and require only a raw conversion be performed. The parameter val is the value to be converted to character form. The parameter ndig is the number of digits to produce. Precisely this many digits are produced. The parameter pdecpt returns the position of decimal point with respect to the beginning of the string. The parameter psign returns zero if the value was non-negative; else it returns one if the value was negative. The parameter dspdig returns the string produced. It contains precisely ndig digits followed by a null-byte. If the number of digits in val exceeds ndig then the last digit is rounded. If the number of digits is less that ndig then it is padded with zeros.

The method Character_FromLong

gmCL: int Character_FromLong(longlong Value,char* String,int nDecimal);

The method Character_FromLong converts an a long integer 8-byte value into a character string. The parameter Value contains the value to be converted and 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 Character_FromShort

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

The method Character_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 Character_FromTime

gmCL: int Character_FromTime(int TimeValue,char* String);

The method Character_FromTime converts a time value into a string. The default used is hh:mm:ss, with the leading "h" blanked out if possible. The hour value is shown in 24-hour form. The time value itself is computed via the formula 3600*hour + 60*minute + second, in other words it is the number of seconds since midnight. The parameter TimeValue is the actual time value to be displayed in the form described above. The parameter String returns the display form of the time in null-terminated form. The method returns the length of the time display.

The method Character_HexiDecimal

gmCL: int Character_HexiDecimal(ULONG Value,char* String,int base);
gmNI: int String_HexiDecimal(ULONG Value,char* String,int base);
gmSL: string Character.HexiDecimal(int iValue, int base);

The method Character_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 Character_Insert

gmCL: int Character_Insert(char* source,int iStart,char* subStr,char* buffer);
gmSL: string Character.Insert(string source, int iStart, string subStr);

The method Character_Insert forms a new string by inserting the parameter subStr into the parameter source starting at the zero-based based offset specified by the parameter iStart. The result of the insertion is stored in the parameter buffer and the method returns the length of the result string.

The method Character_IsControl

gmCL: int Character_IsControl(int charValue);

The method Character_IsControl tests for control characters. It returns a nonzero value if a character value is below 32 or above 127, else it returns zero. It does not use character type flags and will report extended identifier characters as being control characters. The parameter charValue is the value of the character being tested.

The method Character_IsDigit

gmCL: int Character_IsDigit(int charValue);

The method Character_IsDigit tests for numeric digits. It returns a nonzero value if a character is a digit; else it return zero. The parameter charValue is the value of the character being tested. It may be signed or unsigned.

The method Character_IsIdent

gmCL: int Character_IsIdent(int charValue);

The method Character_IsIdent tests for identifier characters. It returns a nonzero value if a character is a possible identifier character; else it return zero. The parameter charValue is the value of the character being tested. It must be between 0 and 255.

The method Character_IsLetter

gmCL: int Character_IsLetter(int charValue);

The method Character_IsLetter tests for alphabetic characters. It returns a nonzero value if a character is an alphabetic, upper or lower case, character; else it return zero. The parameter charValue is the value of the character being tested. It must be between 0 and 255.

The method Character_IsNothing

gmCL: int Character_IsNothing(int charValue);

The method Character_IsNothing tests for characters with no special use. It returns a nonzero value if a character has no purpose flags associated with it; else it return zero. The parameter charValue is the value of the character being tested. It must be between 0 and 255.

The method Character_IsQuote

gmCL: int Character_IsQuote(int charValue);

The method Character_IsQuote tests for quote characters. It returns a nonzero value if a character is a quote character; else it return zero. The parameter charValue is the value of the character being tested. It must be between 0 and 255.

The method Character_IsSpecial

gmCL: int Character_IsSpecial(int charValue);

The method Character_IsSpecial tests for special characters. It returns a nonzero value if a character is a special character; else it return zero. The parameter charValue is the value of the character being tested. It must be between 0 and 255.

The method Character_IsWhiteSpace

gmCL: int Character_IsWhiteSpace(int charValue);

The method Character_IsWhiteSpace tests for whitespace characters. It returns a nonzero value if a character is whitespace; else it return zero. The parameter charValue is the value of the character being tested. It must be between 0 and 255.

The method Character_Remove

gmCL: int Character_Remove(char* strValue, int iStart, int length, char* buffer);
gmSL: string Character.Remove(string strValue, int iStart, int length);

The method Character_Remove forms a new string by removing length characters from the parameter strValue starting at the zero-based offset iStart. The result string is stored in the parameter buffer and the method returns the length of the new string.

The method Character_Replace

gmCL: int Character_Replace(char* source,char* oldStr,char* newStr, char* buffer);
gmSL: string Character.Replace(string source, string oldStr, string newStr)

The method Character_Replace forms a new string from the parameter source in which all occurrences of the parameter oldStr have been replaced by the content of the parameter newStr. The parameter buffer returns the new string and the method returns the length of the new string.

The method Character_RoundValue

gmCL: int Character_RoundValue(char* dspdig,int ndigit,int length);

The method Character_RoundValue truncates and rounds a numeric string of digits. It modifies the content of parameter dspdig and returns the carry value from the round. If the input string consists of a sequence of "999.." such that all become rounded to zero, then the output string will contain "100..." and the method will return a value of 1; else it will return a value of 0. The parameter dspdig contains the string of numeric digits to be rounded. It may contain only numeric digits. The parameter ndigit specifies the number of digits desired in the rounded result. The parameter length specifies the total number of digits in the string as input. The method returns a one or a zero as described above.

The method Character_SetIdent

gmCL: int Character_SetIdent(int charValue,int status);

The method Character_SetIdent sets a character as an identifier character. It returns the previous identifier status of the character. The parameter charValue is the value of the character being set. It must be between 0 and 255. If the parameter status is nonzero, the character status is set to identifier; else it is set to not identifier.

The method Character_SetQuote

gmCL: int Character_SetQuote(int charValue,int status);

The method Character_SetQuote sets a character as a quote or not a quote. It returns the previous quote status of the character. The parameter charValue is the value of the character being set. It must be between 0 and 255. If the parameter status is nonzero, the character status is set to quote; else it is set to not quote.

The method Character_SetSpecial

gmCL: int Character_SetSpecial(int charValue,int status);

The method Character_SetSpecial sets a character as special or not special. It returns the previous special status of the character. The parameter charValue is the value of the character being set. It must be between 0 and 255.If the parameter status is nonzero, the character status is set to special; else it is set to not special.

The method Character_ShiftLeft

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

The method Character_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 Character_ShiftRight

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

The method Character_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 Character_ShortFromHex

gmCL: int Character_ShortFromHex(char* String,int Length);

The method Character_ShortFromHex converts an alphanumeric string in hexidecimal notation to a short integer 4-byte value. The parameter String contains the hexidecimal value to be determined. This string is assumed to be null-terminated only if the Length parameter is zero. The parameter Length is the length of the string represention or zero. The method returns the computed short value. If the representation was not well-formed, it the value as computed when the problem character is encountered.

The method Character_ShortFromOctal

gmCL: int Character_ShortFromOctal(char* String,int Length);

The method Character_ShortFromOctal converts an alphanumeric string to an octal integer value. The parameter String contains the integer value to be determined. The parameter Length contains the number of characters in the string. The method returns the computed integer value.

The method Character_ShortFromString

gmCL: int Character_ShortFromString(char** StringPtr,int blank);

The method Character_ShortFromString extracts a short value from a string. It converts an alphanumeric string to an integer value via a pointer to a pointer to a string. That pointer is then updated to point to the position beyond the end of the integer representation. The parameter StringPtr points to the location of a pointer to the start of the string. This location is updated to point immediately beyond the last character of the integer value. The parameter blank contains the blanks convention to be used. If it has a value of zero, then blanks terminate the string like any other nonnumeric character; if positive, then blanks are simply ignored; and if negative, then blanks have the value of "zero". The method returns the compute value.

The method Character_Substr

gmCL: int Character_Substr(char* strValue,int iStart,int length,char* buffer);
gmSL: string Character.Substr(string strValue, int iStart, int length);

The method Character_Substr forms a new string by extracting a substring from the parameter strValue. The parameter iStart is the starting offset in the source string, relative to zero, of the start of the substring. The parameter length is the desired length of the substring. If it is negative or zero, then it is added to the length of the source string to determine its final value. The parameter buffer returns the new string and the method returns the length of the new stream.

The method Character_ToDouble

gmCL: double Character_ToDouble(char *str,int nstr);

The method Character_ToDouble converts an alphanumeric string containing a number in scientific notation to a double precision floating point number. The string can contain optional leading blanks, an integer part, a fractional part, and an exponent part. The integer part consists of an optional sign followed by zero or more decimal digits. The fractional part is a decimal point followed by zero or more decimal digits. The exponent part consists of an 'E', 'e', 'D', 'd', 'Q', or 'q' followed by an optional sign and a sequence of decimal digits. The parameter str cContains the alphanumeric string to be converted. The parameter nstr contains the number of characters in the string. Note that the string need not be null-terminated. The method returns the double precision value of the string.

The method Character_ToShort

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

The method Character_ToShort obtain a short value from a character string. It converts an alphanumeric string to 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:

The method Character_ToLong

gmCL: longlong Character_ToLong(char* String,int nString,int nDecimal);

The method Character_ToLong obtains a long value from a character string. It converts an alphanumeric string to a long integer 8-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 long 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:

The method Character_ToDate

gmCL: int Character_ToDate(char* String,int nString);

The method Character_ToDate converts a variety of date-formats into an integer julian date value. The formats recognized are: mm/dd/year, mm-dd-year, Mon dd year, dd Mon year, and yyyy-mm-dd

Where:

The date value itself is computed as the number of days since the julian day zero, December 31, 1967. The parameter String contains the date to be computed. The parameter nString is the length of the date string. The value of the date computed as described above is returned.

The method Character_ToTime

gmCL: int Character_ToTime(char* String,int nString);

The method Character_ToTime converts a time string into an integer value equal to the number of seconds since midnight. The formats recognized are: hh:mm:ss and hh:mm

Where:

If ss is omitted the a value of 0 is assumed. The parameter String containing the time to be computed. The parameter nString contains the length of the time string. The value of time computed as described above is returned.

The method Character_ToDateTime

gmCL: longlong Character_ToDateTime(char* String,int nString);

The method Character_ToDateTime converts a date/time string into a long value equal to the number of seconds since December 31, 1967. The format is a valid date followed by whitespace followed by a valid time. See the methods Character_ToDate and Character_ToTime for a description of these valid formates. The parameter String contains the date/time to be computed. The parameter nString is the length of the string. The value of date/time computed as described above is returned.

The method Character_Unpack

gmCL: int Character_Unpack(UBYTE* strValue,int nStrValue,int iStart,char* buffer);
gmSL: string Character.Unpack(string strValue,int iStart);

The method Character_Unpack extracts a specified string from a set of strings packed into a single string instance. The parameter strValue contains the packed set of strings and the parameter nStrValue is its length. The parameter iStart is the index relative to one of the desired string. The parameter buffer returns the unpacked string and the method returns the length of the unpacked string.