String Calculations

Included in Rulestar's calculation engine is support for a variety of string methods that can be used to perform string queries and manipulations. The following string methods are very useful for providing custom validation for users' answers and creating highly tailored field labels and rich text field guidance.

For the purpose of the following examples, @123 represents any field containing a string of text eg, a text, address and email fields.

Each of the methods summarised below (except concatenation) requires the following (case-sensitive) syntax: @123.Method. A question mark (?) indicates that the argument is optional.

IndexOf

The IndexOf() method case-insensitively finds a SearchTerm within a target string (@123) starting at the StartingIndex. StartingIndex is optional and if it is not provided or it is a field that is unanswered or hidden by logic, the search starts from the beginning of the string ie, index 1. IndexOf() will return the index of the first character of SearchTerm's first occurrence within the target string or zero if the SearchTerm is not found, including when the SearchTerm is an empty string or a field that is unanswered or hidden by logic.

For example, "Hello World".IndexOf("orld") = 2 and "Hello World".IndexOf("ABC") = 0.

Includes

The Includes() method is very similar to the IndexOf() method. The only difference is that the Includes method returns 1 (representing true) if the SearchTerm is found within the target string, instead of the index of the SearchTerm. Like IndexOf(), StartingIndex is optional and if it is not provided or is a field that is unanswered or hidden by logic, the search starts from the beginning of the string ie, index 1.

Includes() also returns zero if the SearchTerm is not found, including when the SearchTerm is an empty string or a field that is unanswered or hidden by logic. 

For example, "Hello World".Includes("orld") = 1 and "Hello World".Includes("ABC") = 0.

CharCodeAt

The CharCodeAt() method returns a UTF-16 decimal code unit of the character at the specified index. For characters with codes between 0 and 127 UTF-16 code unit is the same as the ASCII code. For example, 'A' = 65, 'Z' = 90, 'a' = 97 and 'z' = 122. If the index is out of range or a field hidden by logic or unanswered, the method returns null. CharCodeAt() is useful for validating text field answers when a specified format is required eg, a specific combination of letters and numbers or a slash '/' or dash '-' in a specific position.

For example, "Hello World".CharCodeAt(5) = 111.

SubStr

The SubStr() method extracts a substring of up to Length characters long from the target string (@123) starting at the StartingIndex. If StartingIndex is negative the index starts counting from the end of the string.

Length is optional and if it is:

• not provided,
• exceeds actual string length, or
• is a field hidden by logic or unanswered,

all characters from the StartingIndex to the end of the target string are returned. 

For example, "Hello World".SubStr(5, 4) = "o Wo".

Left/Right

The Left() (and Right()) methods return the first (or last) number of characters of a string. If the number of characters is an unanswered field or is less than zero it’s treated as if it was zero. If it exceeds the string’s length, it’s treated as if it was equal to the length. For example, "Hello World".Right(4) = "orld".

Length

Returns the strings Length property i.e. the number of characters that make up the string. For example, "Hello World".Length = 11.

Concatenation

Strings can be concatenated (joined or linked together) with the '+' operator. For example, "Hello" + " " + "World" = "Hello World". If only one operand is a string, all other operands are converted to strings.