String

3.2.15 String

String - Process or parse text. The command applies a text processing function to the argument text. While basic string "test" operations such as "contains", "startswith", "endswith" or "matches" may be performed in if/else statements through boolean expressions, the String command rather targets more complicated processing of text consisting of a sequence of one or more operations.

If the argument text contains variable calls they will be resolved (replaced with values) before the text is processed. The command populates a set of _STRING prefixed variables as follows:

Result of the operation is by default saved to the _STRING variable or to the custom variable specified through the optional 'var' parameter. If the operation produces multiple values (such as the 'split' operation), each value is saved to a numbered variable such as _STRING1, _STRING2 etc. or to similarly numbered set of variables derived from name specified by the 'var' parameter. The number of values is then stored to the _STRING_COUNT variable.

The command has a basic structure of:

String <operation> "<text>" [<parameters>]

Supported operations in alphabetical order are listed below. Their names are in most cases derived from method names of the java.lang.String Java class.

• indexof - Returns the index within the text of the first occurrence of the substring specified through the 'string' parameter. Since v3.5.2 the command may also perform a fuzzy text search similar to the functionality provided by the "tocr" comparison method. Indexing starts from zero. If the specified string is not found, the result is -1. For example, 'String indexof "Demo text" string=text'  will set the _STRING variable to 5. This operation is typically used in combination with the 'substring' one to text parsing. If you need to test the existence of a substring in the given text and you are not interested in its position it is easier to take advantage of the 'contains' Boolean operator.
• length - Returns the text length (number of characters). For example, 'String length  "Demo" '  will set the _STRING variable to 4.

• matches - Matches the text to a java.util.regex.Pattern compliant regular expression specified through the 'pattern' parameter and produces a boolean result (either 'true' or 'false'). For example, 'String matches "a20" pattern="[a-z][0-9]*" ' sets the _STRING variable to 'true' because the regular expression matches any sequence consisting of a lower case character followed by a sequence of digits. The 'matches' operation is also supported in form of a boolean operator for easy use with the if/else statements.

Since v3.5.2 the command also allows to perform fuzzy text matching. See the "matches" command for details.

• replace - Returns a new text resulting from replacing all occurrences of a value specified by the 'string' parameter in the text with the string provided in the 'replacement' parameter. The operation may be also used with 'pattern' instead of 'string' to perform replacement of all occurrences matching the specified java.util.regex.Pattern regular expression. For example, 'String replace "fox" string=f replacement=s' will set the _STRING variable to 'sox'.
• split - Splits the text into a set of strings around matches of the given string ('string' parameter) or java.util.regex.Pattern regular expression ('pattern'). For example, 'String split "brown fox" string=" " ' will produce two values, _STRING1=brown and _STRING2=fox and sets the _STRING_COUNT variable to 2.
• substring - Returns a substring of the text which is defined by the input 'start' and/or 'end' index numbers. Indexing starts from zero and the value of 0 refers to the text beginning (first character). For example, 'String substring "someone" start=4' will set the _STRING variable to 'one'.
• tostring - Creates a new text from one or more semicolon-separated numeric ASCII or Unicode values. This can be used to produce special characters and/or characters of national alphabets. For example, 'String tostring "49;43;49" ' will set the _STRING variable to '1+1'.
• trim (since 2.3.3) - Removes all leading and trailing whitespace characters (spaces, new line characters etc.). For example, 'String trim " apple   " ' will set the _STRING variable to 'apple'.

String indexof  "<text>"  string=<text> [start=<index>]  [end=<index>]  [distance=<number>]  [var=<variable_name>]
* Red colour indicates obligatory parameters

OPTIONS

text

- The text to process.

string

- The string to search for in the text.

start

- Optional start index to start the search from. It must be a number or a valid numeric expression. Indexing starts from zero where zero refers to the text beginning (the first character). The default start index value is 0. 

end

- Optional end index to end the search at. It must be a number or a valid numeric expression. The default value is the text length (the end of the text).

distance

- Optional distance used in conjunction with the "string" parameter to perform tolerant text search (supported since 3.5.2). When the parameter is set to the default value of 0 (no distance) the command falls back to plain string search where the argument text is searched for the first occurrence of the provided string. 

The tolerant (fuzzy) text search is performed for the distance values of 1 and higher. The text is searched for an occurrence of a string which is similar enough to the specified one. The tolerance (similarity) is based on the Levenshtein distance. It is defined as the minimum number of edits needed to transform one string into the other, with the allowable edit operations being insertion, deletion, or substitution of a single character. The distance approximately specifies how many characters may be omitted or not recognized properly at a maximum to consider the sample text equivalent. 
To perform fuzzy text matching instead of search, use the String matches command.

var


- Optional name of the variable to store the resulting index to. If this parameter is not specified the result will be stored to the default _STRING variable. 

RETURNS

The 'String indexof ' command returns 0 (zero) if the specified string was found in the text and 1 otherwise. The command further on stores the index (or -1 if not found) to the _STRING variable (or a custom variable specified by the 'var' parameter). Indexing starts from zero where zero refers to the text beginning (first character).

EXAMPLES

String indexof "Demo text" string="text" var=result 

- Get position (index) of "text" in "Demo text" and store the result of 5 into the "result" variable.

String indexof "Demo text" string="test" var=result  distance=1 

- Same as the previous example save that the word of "text" will be located by the specified string of "test" because it is within the distance of 1.

String length  "<text>"  [var=<variable_name>]

* Red colour indicates obligatory parameters

OPTIONS

var

- Optional name of the variable to store the resulting text length to. If this parameter is not specified the result will be stored to the default _STRING variable. 

RETURNS

The 'String length' command always returns 0 (zero) and stores the argument text length (number of characters) to the _STRING variable or a custom variable specified by the 'var' parameter.

EXAMPLES

String length "Demo text" var=len 

- Stores the length of "Demo text" (9) into the "len" variable.

 String matches "<text>" pattern="<regular_expression>" [var=<variable_name>]

String matches "<text>" string="<text>" [distance=<number>]  [var=<variable_name>]

* Red colour indicates obligatory parameters

OPTIONS

pattern

- A java.util.regex.Pattern compliant regular expression. The regular expression of "." matches by default any character except for the line terminator. This behaviour may be changed through command preferences. 
Be aware that the expression must match the whole text. The command will NOT search the text for its portion that would match the expression. For example, to search the text for the "*.test.*" word, you have to use the expression of ".test.". Meaning "the word of 'test' which may or may not contain any (.*) preceding and/or trailing text". 

string

- A string to search the text for (supported since 3.5.2). 

distance

- Optional distance used in conjunction with the "string" parameter to perform tolerant text matching (supported since 3.5.2). When the parameter is set to the default value of 0 (no distance) the command falls back to plain string comparison where the argument text is tested whether it is equal to the provided string. 
The tolerant (fuzzy) text matching is performed for the distance values of 1 and higher. The text is tested whether it is similar enough to the specified string. The tolerance (similarity) is based on the Levenshtein distance. It is defined as the minimum number of edits needed to transform one string into the other, with the allowable edit operations being insertion, deletion, or substitution of a single character. The distance approximately specifies how many characters may be omitted or not recognized properly at a maximum to consider the sample text equivalent. 
Be aware that the specified string must match the whole argument text. To perform a fuzzy text search to find a string similar to the specified one use String indexof instead.

var

- Optional name of the variable to store the resulting Boolean flag (true/false) to. If this parameter is not specified the result will be stored to the default _STRING variable.

RETURNS

The 'String matches' command returns 0 (zero) if the text matches the regular expression or 1 when not. The command further on stores the result as 'true' or 'false' to the _STRING variable or a custom variable specified by the 'var' parameter.

EXAMPLES

File open file="C:\data.txt"
Var result=-1
for (i=1; {i}<{_FILE_LINE_COUNT}+1; i={i}+1) {
   File read line={i}
   String matches "{_FILE_READ}" pattern="[a-z]*"
   if ({_EXIT_CODE} == 0) {
       Var result={i}
       Break
      }
}

- Open a data file, read it line by line and match each one against the specified regular expression. If the line matches, save the line number to the "result" variable and stop.

// Create a sample text 
Var TEXT= "this is sample text" 

// This command will return 0 (pass) because the specified 
// pattern will match any text containing "simple" or "sample" 
String "matches" "{TEXT}" pattern=".*s[ia]mple.*" 

// This will return 0 because the text does not contain "simple" 
String "matches" "{TEXT}" string="simple" 

// This will return 0 because the text contains "sample" 
// which has only one character different from "simple" 
String "matches" "{TEXT}" string="simple" distance=1 

- Test the sample text in various ways.

String replace "<text>" string="<text>"  replacement="<text>" [var=<variable_name>]

String replace  "<text>" pattern="<regular_expression>"  replacement="<text>" [var=<variable_name>]

* Red colour indicates obligatory parameters


OPTIONS

replacement

- The new string (replacement). 

string

- The old string (to be replaced in the text). 

pattern


- A java.util.regex.Pattern compliant regular expression representing the strings to be replaced. The regular expression of "." matches by default any character except for the line terminator. This behaviour may be changed through command preferences.


var


- Optional name of the variable to store the resulting new text to. If this parameter is not specified the result will be stored to the default _STRING variable.

RETURNS

The 'String replace' command returns 0 (zero) if at least one replacement has been performed or 1 when no replacement has been done and the resulting text equals to the original one. The new text is stored to the _STRING variable or a custom variable specified by the 'var' parameter regardless of whether it has been changed or not.

EXAMPLES

String replace "bad fat cat" string="b" replacement="s"

- Updates the _STRING variable with "sad fat cat" and returns 0 because the string has been updated.

String replace "bad fat cat" pattern="[bf]a[td]" replacement="cat"

- Updates the _STRING variable with "cat cat cat" and returns 0 because the string has been updated.

String split  "<text>" string="<text>"  [var=<variable_name>]
String split  "<text>" pattern="<regular_expression>"  [var=<variable_name>]
* Red colour indicates obligatory parameters

OPTIONS

string

-The delimiter (separator) to split by.

pattern

-A java.util.regex.Pattern compliant regular expression to split by. The regular expression of "." matches by default any character except for the line terminator. This behaviour may be changed through command preferences.

var

-The optional base name of the variables to store the resulting strings to. If this parameter is not specified the result will be stored to the default numbered _STRING<number> variables.

RETURNS

The 'String split' command always returns 0 (zero). Each parsed value is saved to a numbered variable such as _STRING1, _STRING2 etc. or to similarly numbered set of variables derived from name specified by the 'var' parameter. The number of values is then stored to the _STRING_COUNT variable.

EXAMPLES

String split "bad fat cat" string=" " var="s"

- Split the text by spaces. As a custom variable base name of "s" is specified the command produces a set of three variables s1="bad", s2="fat" and s3="cat". The _STRING_COUNT variable will be set to 3.

String split "bad, fat cat" pattern="[,]* "

- Split the text by spaces which may be optionally preceded by a comma. Similarly to the previous example, the command produces a set of three variables _STRING1="bad", _STRING2="fat" and _STRING3="cat". The _STRING_COUNT variable will be set to 3.

// Directory to work with.
Var DIR=/tmp

// List the directory contents (Linux/Unix).
// For Windows replace the "ls" command with "command.com /C dir /B"
Exec "ls {DIR}" 

// Split the directory listing by lines
String split "{_EXEC_OUTPUT}" pattern="\r?\n"

for (i=1; {i}<{_STRING_COUNT}+1; i={i}+1) {

  // Replace floating point from index (not needed on 2.3.3+)
  String replace "{i}" pattern="[.].*" replacement=""

  Var f="{_STRING{i}}"

  // If the file is a .png or a .jpg image display it for 3 seconds
  if ("{f}" endswith ".png" || "{f}" endswith ".jpg") {
    Connect "file://{DIR}/{f}" 
    Wait 3s 
  }
} 

- Perform an image slide show on a directory. The "String split" command is here used to split the directory listing to individual files (one file per line is expected). The parsed strings (file names) are then checked for a known image extension and displayed in the Robot's desktop view for 3 seconds.

String substring  substring "<text>" start=<index>  [end=<index>]  [var=<variable_name>]
String substring  "<text>" end=<index>  [start=<index>]  [var=<variable_name>]
* Red colour indicates obligatory parameters

OPTIONS

start

- Start index (a number or a valid numeric expression). Indexing starts from zero where zero refers to the text beginning (the first character). The default value is 0. 

end

- End index (a number or a valid numeric expression). The default value is the text length (end of text). 

var

- The optional base name of the variables to store the resulting substring to. If this parameter is not specified the result will be stored to the default _STRING variable. 

RETURNS

The 'String substring' command returns 0 (zero) when the start and end indices refer to valid positions in the text. If the start position is invalid (meaning it is less than zero or equal to or larger than the text length), the command sets the start index to 0 and returns 1. Otherwise, if the end position is invalid (meaning it is less than the start position or larger than the text length), the command sets the end index to the default value of text length and returns 2. Regardless of the returned value the _STRING variable (or the custom one passed through the 'var' parameter) is always populated with a new substring between the start and end positions.

EXAMPLES

String substring "bad fat cat" start="4" var="s"

- Removes the first four characters and sets the "s" variable to "fat cat".

String length "bad fat cat" var="len"
String substring "bad fat cat" start="{len}-3" end="{len}-2"

- Cuts the third last character ("c") into the _STRING variable.

String tostring  "<text>" unicode=<index>  [var=<variable_name>]
* Red colour indicates obligatory parameters

OPTIONS

unicode

- One numeric Unicode/ASCII code or a semicolon-separated list of codes to be converted into a string. As each code in the list is being parsed through the java.lang.Integer.decode() method, it may be a decimal number, hexadecimal (with leading '0x' or '#', such as '0xF0' or '#F0') or octal. For example, the '@'character may be specified as '64' (decimal), '0xF0', '#F0' (hexadecimal) or '0100' (octal). For the list of character, codes see the ASCII and Unicode tables on Wikipedia.

var

- The optional base name of the variables to store the resulting string to. If this parameter is not specified the result will be stored to the default _STRING variable. 

RETURNS

The 'String tostring' command returns 0 (zero) on success and 1 when one or more codes do not correspond to valid ASCII/Unicode characters. The command on success populates the _STRING variable (or the custom one passed through the 'var' parameter) with the converted string.

EXAMPLES

String tostring "104;101;101;108;111" var="s"

- Populates the "s" variable with "hello".

String tostring "0xF1" var="s"
Var tomorrow="ma{s}ana"

- Sets the "tomorrow" variable to "mañana".

String trim "<text>" [var=<variable_name>]
* Red colour indicates an obligatory parameter


OPTIONS

var

- The optional base name of the variables to store the resulting string to. If this parameter is not specified the result will be stored to the default _STRING variable.

RETURNS

The 'String trim' command always returns 0 (zero). The command on success populates the _STRING variable (or the custom one passed through the 'var' parameter) with the trimmed string.

EXAMPLES

String trim " Hello!  " var="s"

- Sets the "s" variable to "Hello!".