Language Elements and Reference:xpplrm

Operations with character values Foundation

Character strings are a series of ASCII characters enclosed in a set delimiting characters (see table). The operators that work with values of "character" data type include the concatenation, comparison and assignment operators. Concatenation means "addition of characters" and describes combining two character values in order to form a new character string. The following table lists all of the operators which can be used with values of "character" data type:

Operators for character values:
Operator Description
"" '' [] Delimiters for literal character values
+ Concatenation of character strings
- Concatenation of two character strings without blank spaces
== Tests whether two character strings are identical
$ .IN. Tests whether substring is contained in a character string
!= <> # Tests whether two character values are not equal
> Comparison: greater than
>= Comparison: greater than or equal
= Comparison: equal
<= Comparison: less than or equal
< Comparison: less than
= Assignment
:= Inline assignment
+= Inline concatenation of characters
-= Inline concatenation of two character strings without blank spaces

Four operators can be used for concatenating character values. Of these, two are inline operators:

cOne := "One   " 
cTwo := "Two  " 
? "|"+ cOne + cTwo + "|"         // result: |One   Two  | 
? "|"+ cOne - cTwo + "|"         // result: |OneTwo     | 

? "|"+ cOne += cTwo + "|"        // result: |One   Two  | 
? "|"+ cOne -= cTwo + "|"        // result: |One   TwoTwo     | 

Concatenating characters using the minus operator causes blank spaces at the end of the left operand to be removed and attached to the end of the resulting character string.

The operator == performs a binary comparison between two character strings and determines whether two character values cLeft and cRight are identical:

cLeft  := "Xbase++" 
cRight := "Xbase++   " 

? cLeft == cRight                // result: .F. 
? cLeft == RTrim(cRight)         // result: .T. 

The settings SET EXACT and SET LEXICAL are considered by all other comparison operators when comparing characters or character strings. When SET LEXICAL is set to OFF (default setting), characters are compared with each other based on the collation table specified via the SET COLLATION command.

With SET EXACT OFF characters are compared up to the length of the right character string cRight. When SET EXACT ON is set, the string are compared up to the length of the left character string cLeft. Blank spaces (Chr(32)) at the end of the two character strings are not considered. If cRight contains a null string ( ""), the simple equality operator = always returns the value .T. (true) when SET EXACT OFF is set. It always returns the value .F. (false) if SET EXACT ON is set,. The other comparison operators <>, >, >=, <, <= perform similar comparisons.

cLeft  := "Xbase++" 
cRight := "Xbase++   " 

SET EXACT OFF 
? cLeft = cRight                 // result: .F. 
? cLeft = ""                     // result: .T. 

SET EXACT ON 
? cLeft = cRight                 // result: .T. 
? cLeft = ""                     // result: .F. 

SET LEXICAL ON has precedence over SET EXACT ON. With SET LEXICAL ON , character comparisons are made on the basis of the lexical character value defined by the country specific settings of the operating system. The lexical value of one or more characters can be redefined using the function SetLexrule() (see the reference documentation for SetLexrule()).

When SET LEXICAL ON is set, character strings whose lexical meanings are identical but whose actual characters are different can be compared with each other. The definition of lexical comparison rules with SetLexrule() is appropriate for language specific special characters like the German umlauts or the German "ß":

SetLexrule( "ü" , "ue" )         // ü  -> ue 
SetLexrule( "ay", "ei" )         // ay -> ei 
SetLexrule( "ß" , "ss" )         // ß  -> ss 

SET LEXICAL OFF 

? "Grüße"  = "Gruesse"           // result: .F. 
? "Müller" = "Mueller"           // result: .F. 
? "Mayer"  = "Meier"             // result: .F. 

SET LEXICAL ON 
? "Grüße"  = "Gruesse"           // result: .T. 
? "Müller" = "Mueller"           // result: .T. 
? "Mayer"  = "Meier"             // result: .T. 

The following table lists all the functions of the Xbase++ runtime library that perform operations on character values or manipulate character strings. A short overview of the use of these functions follows the table.

Functions for character values:
Function Description
Alltrim() Removes blank spaces at the beginning and end of a character string
Asc() Converts a character to its numeric ASCII code
At() Determines start position of a substring in a character string
CtoD() Converts character value to date value
Descend() Converts character string for descending sorting
Empty() Tests whether character value is a null string ("") or contains only white space
FieldPut() Assigns character value to field variable
FieldGet() Reads character value from field variable
IsAlpha() Tests whether first character is a letter
IsDigit() Tests whether first character is a digit
IsLower() Tests whether first character is a lowercase letter
IsUpper() Tests whether first character is an uppercase letter
Left() Extracts characters starting at the left
Len() Determines the length of a character string
Lower() Converts character string to lowercase letters
LTrim() Removes blank spaces at the beginning of a character string
PadC() Attaches fill characters on the left and the right
PadL() Attaches fill characters on the left
PadR() Attaches fill characters on the right
Rat() Returns start position of a string within a character string searching from the right
Replicate() Repeats character string
Right() Extracts characters starting at the right
RTrim() Removes blank spaces at the end of a character string
SetLexRule() Sets lexical comparison rule for character
Space() Creates character string containing blank spaces
StrTran() Replaces multiple strings within a character string
Stuff() Replaces simple string in a character string
SubStr() Extracts a substring from a character string
Transform() Formats character string for display
Trim() Removes blank spaces at the end of a character string (same as RTrim())
Type() Determine data type via macro operator
Upper() Converts character string to uppercase letters
Val() Converts character string to numeric value
Valtype() Determines the data type

The functions in the table are categorized into groups below and short code examples are shown for each group. A detailed description of each of these functions is found in the Xbase++ reference documentation.

Extract characters

? Left("Xbase++", 2)             // result: Xb 
? Right("Xbase++", 2)            // result: ++ 
? SubStr("Xbase++", 2, 4)        // result: base 

Replace characters

? StrTran("Xbase++", "++", "-3") // result: Xbase-3 
? Stuff("Xbase++", 2, 4 , "tra") // result: Xtra++ 

Functions for blank spaces

? "|"+        "  Xbase++  " +"|" // result: |  Xbase++  | 
? "|"+Alltrim("  Xbase++  ")+"|" // result: |Xbase++| 
? "|"+  LTrim("  Xbase++  ")+"|" // result: |Xbase++  | 
? "|"+  RTrim("  Xbase++  ")+"|" // result: |  Xbase++| 
? "|"+   Trim("  Xbase++  ")+"|" // result: |  Xbase++| 
? "|"+  Space(11)           +"|" // result: |           | 

Search characters

? At("base","Xbase++")           // result: 2 
? Rat("e"  ,"Xbase++")           // result: 5 

Convert characters

? Asc("A")                       // result: 65 
? CtoD("12/06/94")               // result: 12/06/94 
? Lower("XBASE++")               // result: xbase++ 
? PadC("Xbase++", Chr(176), 11)  // result: °°Xbase++°° 
? PadL("Xbase++", Chr(176), 11)  // result: °°°°Xbase++ 
? PadR("Xbase++", Chr(176), 11)  // result: Xbase++°°°° 
? Transform("Xbase++", "@!")     // result: XBASE++ 
? Upper("Xbase++")               // result: XBASE++ 
? Val("123")                     // result:        123 

Test character strings

? Empty( Space(11) )             // result: .T. 
? IsAlpha("Xbase++")             // result: .T. 
? IsDigit("Xbase++")             // result: .F. 
? IsLower("Xbase++")             // result: .F. 
? IsUpper("Xbase++")             // result: .T. 
? Len("Xbase++")                 // result:          7 

Other functions for character values

? Replicate("Xb",5)              // result: XbXbXbXbXb 
? Type("1")                      // result: N 
? Valtype("1")                   // result: C 

Feedback

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.