String Functions
The ability to modify and concatenate strings is a powerful feature of many programming languages, and Crystal syntax doesn’t disappoint. This section breaks out the different categories of string functions and summarizes how they work. The categories are: Analyzing a String, and Manipulating Strings.
Throughout this section, many of the functions listed use one or both of the arguments called compare and start. Rather than repetitively list their descriptions throughout the chapter, they are explained here for your reference.
The compare argument determines when string comparisons are supposed to be case sensitive. If compare is 0, the search is case-sensitive. If it is 1, the search is not case-sensitive. Case sensitivity means that even if two strings consist of the exact same letters, they will be treated as different strings if one is upper-case and the other is lower-case. For example, “Joe” would not be the same as “joe”. If the comparison is not case-sensitive, then “Joe” would be the same as “joe”. The compare argument is optional. If it is left out, the comparison defaults to 0 (case sensitive).
The start argument tells the function to process characters starting at a specified position. Any characters that are prior to that position are ignored. This argument is optional. If it is left out, then the function is performed for the entire string.
Analyzing a String
Strings are used to store a variety of data displayed in a report. They can come from a variety of sources such as database tables, user input or even XML. Most of the time, you will want to output the string directly to the report. But there are times when the information you want is stored as part of a larger string and you need to extract that data. To do this, it is necessary to analyze and parse a string’s contents. Crystal syntax gives you many functions for doing this. Table 6-1 shows the functions for analyzing a string’s contents. Table 6-3 shows the functions for extracting sub-strings from a string.
Table 6-1. String Analysis Functions
| Function Name | Description |
|---|---|
| AscW(str) | Returns the ASCII value of a character. |
| ChrW(val) | Returns the character equivalent of an ASCII value. |
| Len(str) | Gets the number of characters in the string. |
| IsNumeric(str) | Tells if the string can be properly converted to a number. |
| InStr(start, str1, str2, compare) | Determines if str2 is a sub-string of str1. The start and compare arguments are both optional. |
| InStrRev(start, str1, str2, compare) | Same as InStr() except that it starts at the end of the string and searches towards the beginning. |
| StrCmp(str1, str2, compare) | Compares two strings to each other. The compare argument is optional. |
| Val(str) | Returns the numeric equivalent of the string. |
The StrCmp() function returns a value based upon how the two strings compare to each other. Table 6-2 summarizes what these results mean. Just like the Instr() functions, you can pass a compare argument to set case sensitivity.
Table 6-2. StrCmp(str1, str2) Return Values
| Return Value | Description |
|---|---|
| -1 | str1 < str2 |
| 0 | str1 = str2 |
| 1 | str1 > str2 |
Table 6-3. String Parsing Functions
| Function Name | Description |
|---|---|
| Trim(str) | Trim the spaces from both sides of a string. |
| LTrim(str) | Trim the spaces from the left side of a string. |
| RTrim(str) | Trim the spaces from the right side of a string. |
| Mid(str, start, length) | Return a given number of characters starting at a specified position. The start and length arguments are optional. |
| Left(str, length) | Return a given number of characters starting with the leftmost character. |
| Right(str, length) | Return a given number of characters starting with the rightmost character. |
The Trim() function deletes all extraneous spaces from either side of the string, depending on which function you call. Trimming space from a string is useful for fields that involve data entry. This is because users will accidentally hit the space bar either before or after entering a value. Since a space is effectively invisible to the user, they will not realize that they did this. When you use this field in comparisons with other text, Crystal Reports will say that the two fields are different because they have different lengths (even though they look identical). You must use the Trim() function to get rid of any extraneous space before and after the field when doing the comparison.
Sometimes when my reports are not coming out right and I’m doing text comparisons, I like to test if there are extraneous spaces by concatenating the letter “x” before and after the field. For example, I would use the following formula:
"x" & {Customer.CusomterName} & "x"
Then I would scan the report to see if there are any spaces between each “x” and the field. This lets me quickly see if spaces might be causing problems.
The Mid(), Left(), and Right() functions return a partial string where the number of characters returned is based on the length argument. If you don’t pass a length argument to the Mid() function, it returns all characters starting with the first one you specified.
