Product Documentation

Basic Operations on Text

Aug 31, 2016

Basic operations on text include operations for string matching, calculating the length of a string, and controlling case sensitivity. You can include white space in a string that is passed as an argument to an expression, but the string cannot exceed 255 characters.

String Comparison Functions

The following table lists basic string matching operations in which the functions return a Boolean TRUE or FALSE.

Table 1. String Comparison Functions

Function

Description

<text>.CONTAINS(<string>)

Returns a Boolean TRUE value if the target contains <string>.

Following is an example:

http.req.url.contains(".jpeg")

<text>.EQ(<string>)

Returns a Boolean TRUE value if the target is an exact match with <string>.

For example, the following expression returns a Boolean TRUE for a URL with a host name of “myhostabc”:

http.req.url.hostname.eq("myhostabc")

<text>.STARTSWITH(<string>)

Returns a Boolean TRUE value if the target begins with <string>.

For example, the following expression returns a Boolean TRUE for a URL with a host name of “myhostabc”:

http.req.url.hostname.startswith("myhost")

<text>.ENDSWITH(<string>)

Returns a Boolean TRUE value if the target ends with <string>.

For example, the following expression returns a Boolean TRUE for a URL with a host name of “myhostabc”:

http.req.url.hostname.endswith("abc")

<text>.NE(<string>)

Returns a Boolean TRUE value if the prefix is not equal to the string argument.

If the prefix returns a non-string value, the function argument is compared to the string representation of the value returned by the prefix. You can use the functions with SET_TEXT_MODE(IGNORECASE) or SET_TEXT_MODE(NOIGNORECASE), and with both ASCII and UTF-8 character sets.

<text>.GT(<string>)

Returns a Boolean TRUE value if the prefix is alphabetically greater than the string argument.

If the prefix returns a non-string value, the function argument is compared to the string representation of the value returned by the prefix. You can use the functions with SET_TEXT_MODE(IGNORECASE) or SET_TEXT_MODE(NOIGNORECASE), and with both ASCII and UTF-8 character sets.

<text>.GE(<string>)

Returns a Boolean TRUE value if the prefix is alphabetically greater than or equal to the string argument.

If the prefix returns a non-string value, the function argument is compared to the string representation of the value returned by the prefix. You can use the functions with SET_TEXT_MODE(IGNORECASE) or SET_TEXT_MODE(NOIGNORECASE), and with both ASCII and UTF-8 character sets.

<text>.LT(<string>)

Returns a Boolean TRUE value if the prefix is alphabetically lesser than the string argument.

If the prefix returns a non-string value, the function argument is compared to the string representation of the value returned by the prefix. You can use the functions with SET_TEXT_MODE(IGNORECASE) or SET_TEXT_MODE(NOIGNORECASE), and with both ASCII and UTF-8 character sets.

<text>.LE(<string>)

Returns a Boolean TRUE value if the prefix is alphabetically lesser than or equal to the string argument.

If the prefix returns a non-string value, the function argument is compared to the string representation of the value returned by the prefix. You can use the functions with SET_TEXT_MODE(IGNORECASE) or SET_TEXT_MODE(NOIGNORECASE), and with both ASCII and UTF-8 character sets.

Calculating the Length of a String

The <text>.LENGTH operation returns a numeric value that is equal to the number of characters (not bytes) in a string:

<text>.LENGTH

For example, you may want to identify request URLs that exceed a particular length. Following is an expression that implements this example:

HTTP.REQ.URL.LENGTH < 500

After taking a count of the characters or elements in a string, you can apply numeric operations to them. For more information, see "Default Syntax Expressions: Working with Dates, Times, and Numbers."

Considering, Ignoring, and Changing Text Case

The following functions operate on the case (upper-case or lower-case) of the characters in the string.

Table 2. Functions for Considering, Ignoring, and Changing Text Case

Function

Description

<text>.SET_TEXT_MODE(IGNORECASE| NOIGNORECASE)

This function turns case sensitivity on or off for all text operations.

<text>.TO_LOWER

Converts the target to lowercase for a text block of up to 2 kilobyte (KB). Returns UNDEF if the target exceeds 2 KB.

For example, the string “ABCd:” is converted to “abcd:”.

<text>.TO_UPPER

Converts the target to uppercase. Returns UNDEF if the target exceeds 2 KB.

For example, the string “abcD:” is converted to “ABCD:”.

Stripping Specific Characters from a String

You can use the STRIP_CHARS(<string>) function to remove specific characters from the text that is returned by a default syntax expression prefix (the input string). All instances of the characters that you specify in the argument are stripped from the input string. You can use any text method on the resulting string, including the methods used for matching the string with a pattern set.

For example, in the expression CLIENT.UDP.DNS.DOMAIN.STRIP_CHARS(".-_"), the STRIP_CHARS(<string>) function strips all periods (.), hyphens (-), and underscores (_) from the domain name returned by the prefix CLIENT.UDP.DNS.DOMAIN. If the domain name that is returned is "a.dom_ai_n-name", the function returns the string "adomainname".

In the following example, the resulting string is compared with a pattern set called "listofdomains":

CLIENT.UDP.DNS.DOMAIN.STRIP_CHARS(".-_").CONTAINS_ANY("listofdomains")

Note: You cannot perform a rewrite on the string that is returned by the STRIP_CHARS(<string>) function.

The following functions strip matching characters from the beginning and end of a given string input.

Table 3. Functions for Stripping Characters From the Beginning or End of a String
Function Description

<text>.STRIP_START_CHARS(s)

Strips matching characters from the beginning of the input string until the first non-matching character is found and returns the remainder of the string. You must specify the characters that you want to strip as a single string within quotation marks.

For example, if the name of a header is TestLang and ://_en_us: is its value, HTTP.RES.HEADER("TestLang").STRIP_START_CHARS(":/_") strips the specified characters from the beginning of the value of the header until the first non-matching character e is found and returns en_us: as a string.

<text>.STRIP_END_CHARS(s)

Strips matching characters from the end of the input string to the first non-matching character is found and returns the remainder of the string. You must specify the characters that you want to strip as a single string within quotation marks.

For example, if the name of a header is TestLang and ://_en_us: is its value, HTTP.RES.HEADER("TestLang").STRIP_START_CHARS(":/_") strips the specified characters from the end of the value of the header until the first non-matching character s is found and returns ://_en_us as a string.

Appending a String to Another String

You can use the APPEND() function to append the string representation of the argument to the string representation of the value returned by the preceding function. The preceding function can be one that returns a number, unsigned long, double, time value, IPv4 address, or IPv6 address. The argument can be a text string, number, unsigned long, double, time value, IPv4 address, or IPv6 address. The resulting string value is the same string value that is obtained by using the + operator.