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. Though not required all current implementations of this class use ASCII or UTF-8 variable length encoding and the descriptions of the methods assume that encoding. Internally the character values have character type flags associated with them as follows:

The field Character_ErrorCode

Prototype

The Character_ErrorCode field is used to record errors that occur doing character processing operations. In addition there are two additional fields that supply support information. The Character_Ihist specifies the particular position with a string that contains a bad character which string conversion operations are being performed. The Character_Ndec specifies the number of explicit decimal digits used when a string is being converted to a decimal value. The actual error codes are as follows:

The field Character_Separator

Prototype

The Character_Separator field specifies the character use to separate the parameter substrings used by the editing methods. Its default value is a semi-colon.

The method Character_ApplyTemplate

Prototype

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

Prototype

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

Prototype

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

Prototype

The Character_DigitValue method 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 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 is:

The method Character_DoubleDisplay

Prototype

The Character_DoubleDisplay method converts a double precision value into a free-form display without any additional direction from the caller. Based on the value being displayed it selects the most appropriate display format for it. The parameters are:

The method returns the length in characters of the formed display.

The method Character_EditString

Prototype

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

Prototype

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

Prototype

The Character_FindLast method 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. 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 Character_FromDate

Prototype

The Character_FromDate method converts a date value into a string. The format used is either mm/dd/yy or yyyy/mm/dd depending upon the YearMonthDay display flag. Its parameters are:

The method returns the length of the date display.

The method Character_FromDateTime

Prototype

The Character_FromDateTime method converts a date/time value into a string by simply displaying the date component in yyyy/mm/dd form followed by the time component in hh:mm form. Its parameters are:

The method returns the length of the date/time display.

The method Character_FromDouble

Prototype

The Character_FromDouble method 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 generalized applications, prefer to perform their own editing operations, and require only a raw conversion be performed. Its parameters are:

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

Prototype

The Character_FromLong method converts a long integer 8-byte value into a character string. Its parameters are:

The method returns the length of the character representation, not counting the null.

The method Character_FromShort

Prototype

The Character_FromShort method converts a short integer 4-byte value into a character string. Its parameters are:

The method returns the length of the character representation, not counting the null.

The method Character_FromTime

Prototype

The Character_FromTime method 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 seconds value is omitted if the OmitSeconds display flag is set. 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. Its parameters are:

The method returns the length of the time display.

The method Character_Hexidecimal

Prototype

The Character_HexiDecimal method 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. Its parameters are:

The method returns length of the character representation, not counting the null.

The method Character_Insert

Prototype

The Character_Insert method inserts a substring into a base string starting at a zero-based offset. Its parameters are:

The method returns the length of the result string.

The method Character_IsControl

Prototype

The Character_IsControl method tests for control characters. Its parameter is:

The method 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 method Character_IsDigit

Prototype

The Character_IsDigit method tests for numeric digits. Its parameter is:

The method returns a nonzero value if a character is a digit else it return zero.

The method Character_IsIdent

Prototype

The Character_IsIdent method tests for identifier characters. Its parameter is:

The method returns a nonzero value if a character is a possible identifier character else it returns zero. It does use character type flags and will report extended identifier characters as being identifiers.

The method Character_IsLetter

Prototype

The Character_IsLetter method tests for alphabetic characters. Its parameter is:

The method returns a nonzero value if a character is an alphabetic, upper or lower case, character; else it returns zero.

The method Character_IsLower

Prototype

The Character_IsLower method tests for lower case alphabetic characters. Since this test is typically made to do a case conversion, it returns the equivalent upper case value. Its parameter is:

The method returns the equivalent non-zero upper case value of the character if it is lower case; else it returns zero.

The method Character_IsUpper

Prototype

The Character_IsUpper method tests for upper case alphabetic characters. Since this test is typically made to do a case conversion, it returns the equivalent lower case value. Its parameter is:

The method returns the equivalent non-zero lower case value of the character if it is upper case; else it returns zero.

The method Character_IsNothing

Prototype

The Character_IsNothing method tests for characters with no special use. Its parameter is:

The method returns a nonzero value if a character has no purpose flags associated with it and it is in the range 0 to 255; else it returns zero.

The method Character_IsQuote

Prototype

The method Character_IsQuote tests for quote characters. Its parameter is:

The method returns a nonzero value if the character is a quote character; else it returns zero.

The method Character_IsSpecial

Prototype

The Character_IsSpecial method tests for special characters. Its parameter is:

The method returns a nonzero value if the character is a special character; else it returns zero.

The method Character_HasSpecial

Prototype

The Character_HasSpecial method tests for the special character value. Its parameter is:

The method returns the special character value if the character is a special character; else it returns zero.

The method Character_IsWhiteSpace

Prototype

The Character_IsWhiteSpace method tests for whitespace characters. Its parameter is:

The method returns a nonzero value if the character is whitespace; else it returns zero.

The method Character_Remove

Prototype

The Character_Remove method forms a new string by removing a specified number of characters from a string starting at a zero-based offset into the string. Its parameters are:

The method returns the length of the new string.

The method Character_Replace

Prototype

The Character_Replace method forms a new string from an existing one in which all occurrences of a specified substring have been replace by a new substring. Its parameters are:

The method returns the length of the new string.

The method Character_RoundValue

Prototype

The Character_RoundValue method truncates and rounds a numeric string of digits. It modifies the content of that digit string 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. Its parameters are:

The method returns a one or a zero as described above.

The method Character_SetIdent

Prototype

The Character_SetIdent method sets a character as an identifier character. Its parameters are:

The method returns the previous identifier status of the character.

The method Character_SetQuote

Prototype

The Character_SetQuote method sets a character as a quote character. Its parameters are:

The method returns the previous quote status of the character.

The method Character_SetSpecial

Prototype

The Character_SetSpecial method sets a character as a special character. Its parameters are:

The method returns the previous special status of the character.

The method Character_Shiftleft

Prototype

The Character_ShifLeft method 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. Its parameters are:

The method Character_ShiftRight

Prototype

The Character_ShiftRight method 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 the 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. Its parameters are:

The method Character_ShortFromHex

Prototype

The Character_ShortFromHex method converts an alphanumeric string in hexadecimal notation to a short integer 4-byte value. The actual computation of the value is done using a longlong internal value. If the string is longer than 7 characters and begins with "8", then it is assumed to be negative. Its parameters are:

The method returns the computed short value. If the representation is not well-formed, it returns the value as computed when a problem character is encountered.

The method Character_ShortFromOctal

Prototype

The Character_ShortFromOctal method converts an alphanumeric string to an octal short integer 4-byte value. Its parameters are:

The method returns the computed integer value.

The method Character_ShortFromString

Prototype

The Character_ShortFromString method extracts a short integer 4-byte 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. Its parameters are:

The method updates the string pointer and returns the computed integer value.

The method Character_Substr

Prototype

The Character_Substr method forms a new string by extracting a substring from a supplied one. Its parameters are:

The method returns the length of the new string.

The method Character_ToDate

Prototype

The Character_ToDate method converts a variety of date-formats into an integer Julian date value. The five formats recognized are:

Where:

The date value itself is computed as the number of days since the Julian day zero, by default December 31, 1967 (see the DateTime service class for details). Its parameters are:

The method returns the integer value of the date computed as described above.

The method Character_ToDateTime

Prototype

The Character_ToDateTime method converts a date/time string into a long value equal to the number of seconds since the Julian day zero, by default December 31, 1967 (see the DateTime service class for details). 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 formats. Its parameters are:

The method returns the long 8-byte integer value of date/time computed as described above.

The method Character_ToDouble

Prototype

The Character_ToDouble method converts an alphanumeric string containing a number in scientific notation to a double precision floating point value. 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. Its parameters are:

The method returns the double precision value of the string.

The method Character_ToLong

Prototype

The Character_ToLong method 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 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. Its parameters are:

The method returns the computed long 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:

The method Character_ToLower

Prototype

The Character_ToLower method forces the case of any alphabetic characters contained in a specified string to be lower-case. Characters that are not alphabetic or that already have lower-case are not changed. Its parameters are:

The method Character_ToShort

Prototype

The Character_ToShort method obtains 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 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. Its parameters are:

The method returns the computed short 4-byte integer 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:

The method Character_ToTime

Prototype

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

Where:

If ss is omitted, a value of 0 is assumed. Its parameters are:

The method returns the value of time computed as described above. If the representation was not well-formed, then an error code is set than may be retrieved via the Character_ErrorCode field. The error codes set by this method are:

The method Character_ToUpper

Prototype

The Character_ToUpper method forces the case of any alphabetic characters contained in a specified string to be upper-case. Characters that are not alphabetic or that already have upper-case are not changed. Its parameters are:

The method Character_Unpack

Prototype

The Character_Unpack method extracts a specified string from a set of strings packed into a single string instance. Its parameters are:

The method returns the length of the unpacked string.