String functions

The following table provides a list of string functions.
Note: Functions can be written in Legacy Script Language or in ECMAScript. For details, see Scripts within tests and stubs. All the examples given in the following table are in Legacy, unless otherwise specified.
Function Usage
Create text

The Create Text function returns a string of text.

createText(data size in bytes, [repeated character sequence])
Note: The character sequence is repeated until the returned string reaches the size that is specified.
Format date UTC

The Format date UTC function returns the number of milliseconds that passed between January 1, 1970 and the supplied date and time. This data can be used for mathematical operations or functions. For example, if a test receives a message that was published with a timestamp in it, you would have two dates that are expressed as strings: the one in the message and the system tag that contains the current. You could run formatDateUTC against the two numbers and subtract the results from one another to determine the latency of the message.

formatDateUTC(date, inputFormat)

Legacy Example:

formatDateUTC("Jan 01, 2009 08:15:30 -0700 ","MMM dd, yyyy HH:mm:ssZ")
Returns 1230822930000
  • If the date parameter contains spaces, it must be enclosed in quotes.
  • The time zone must be set to Mountain Standard Time (MST) (-0700) to see the result 1230822930000.
Get token

The Get Token function extracts a token from a tokenized string. It takes a portion of a larger string as determined by the delimiters in use and a specified index value.

getToken ( "Delimiter", Index [>=0] , Data, [includeEmptyStrings true|false] )
  • Delimiter: Enclosed in quotes, one or more characters that are used to separate values in the data string.
  • Index: Starting from zero, the delimited position within the string from which the token can be extracted. For example, "0" indicates the position before the first delimiter, "1" indicates the position before the second delimiter.
  • Data: A string that contains a set of values that are separated by the specified delimiter.
  • includeEmptyStrings: Set to true or false, indicates whether empty strings (that is, two successive delimiters) are included when calculating the index position. This is an optional parameter and the default value is set to false.


Note the following examples:

getToken ( ",", 2 , "aaa,bbb,,,ccc,ddd", true )
Returns an empty string, since empty strings are included and the third position (index 2) is null.
getToken ( ",", 2 , "aaa,bbb,,,ccc,ddd", false )
Returns "ccc", since empty strings are ignored, meaning that the third position (index 2) is "ccc".
Regular expression

The Regular Expression function executes a regular expression extraction against a source string. By default, the first group that is returned, however an optional fourth parameter can be used to extract other groups.

regex(string, expr, [instance], [extractionGroup])
  • string is the source string against which the regular expression will be run.
  • expr is the regular expression.
  • instance is the optional instance to be extracted – without this parameter, true or false is returned based on whether the match succeeds.
  • extractionGroup is the optional extraction group that controls how content is returned. A value of 0 (default) returns all text, 1 returns only the first match, 2 returns only the second match, and so on.


The simplest case is to see if a pattern exists within the string:

regex ( "hello world", "h")
Returns 'true'.
regex ( "hello world", "xxx")
Returns 'false'.
regex ( "hello world", "l.",1)
Returns 'll'.

ECMAScript Example:

If a time field (hh:mm:ss) is extracted from a message and is held in a tag named "timeField", the following function returns the value for the hours as instance 1:

regex ( timeField, "\d\d", 1);

Increasing the instance argument to "2" or "3" provides access to the minute and second values.


It is possible to specify multiple sections of text within ( ) brackets. In this case, the function extracts some words from the following tag in an XML document that is specified by %%XML%%:

<tag_name>Here is some writing to be transformed.</tag_name>
regex("%%XML%%", "<tag_name>.* (t\w*).*(t\w*).*</tag_name>",1,1)
Finds the first ( ) match – the word that begins with 't' – and returns 'to'.
regex("%%XML%%", "<tag_name>.* (t\w*).*(t\w*).*</tag_name>",1,2)
Finds the second ( ) match and returns 'transformed'.
Note: If extractionGroup is set to zero, the whole string match is returned.

Using Modifiers

Modifiers can be used in regular expression (for example, to process strings that span multiple lines). Modifiers are placed in front of the regular expression in round brackets, as follows:

(?s)\<\?xml.* extracts an XML string over multiple lines.

Modifiers can be combined in the same brackets by using a single '?', as follows:

(?si)\<\?xml.* extracts an XML string over multiple lines while it ignores case.

The following is a list of commonly used modifiers:

  • ?i case insensitive
  • ?x comment mode
  • ?d line mode
  • ?m multiple line mode
  • ?s single-line mode

Modifiers can be used anywhere that regular expressions are used in HCL OneTest API, for example in tagging operations. For more information, see the Perl regular expression documentation.