JScript - Working With Strings

Basics

Special characters

Getting the string length

Concatenating strings

Comparing strings

Accessing individual character of a string

Searching for characters and substrings

Getting a substring

Splitting strings

Removing extra spaces from a string

Replacing characters and substrings

Changing the letter case

Working with string lists

A String is a sequence of symbols or digits. Strings are among the most frequently used data types. Like any other data types, strings in TestComplete are represented as OLE-compatible variants.

In JScript, a sequence of literal characters enclosed in a matching pair of quotation marks is recognized as a string. The quotation marks could be either single (') or double ("). The quotation characters are allowed within a string if they do not match the enclosing pair. All the following strings are valid:

To deal with strings, TestComplete has a special aqString scripting object. The object is available for all supported scripting languages, so that you can use it to operate with string values regardless of the chosen language.

Another scripting object that is useful for string manipulation is aqConvert. This object has several methods that convert values of different types to a string representation and vice versa.

Furthermore, JScript has its own inherent object String, that is, a wrapper for a string data type. The strings that are used in TestComplete are compatible with this object, moreover, the String objects are created implicitly for every string. That is, you can call the object methods not only for object instances but for any TestComplete string. For example, the following method call is correct:

A detailed description for the String object is provided in the MSDN library, the table below lists its major properties and methods:

There are several pairs of symbols that are used to represent special characters in JScript strings. They all start with a backslash character (\), and are often called escape characters. The following escape characters are allowed in JScript.

To obtain the total number of characters in a string you can either read the length property of the JScript String object, or call the aqString.GetLength method. The character position in JScript is zero-based, so the maximum position number in a string is Length-1. The following code demonstrates both ways of obtaining the string length:

Using TestComplete, you can limit the length of string parameters returned by functions of the tested application. For this purpose, use the Maximum string length of [out] parameters project property. If the length of the string returned from the application via one of its out parameters exceeds the property’s value, TestComplete treats the returned string as a null one.

The operation that forms a string out of several others is called concatenation. The native String object of JScript, and the aqString object have special methods (respectively, String.concat and aqString.Concat) that perform this operation.

However, it is much more convenient to use the addition operator (+) for this purpose. If one of the addition operands is a string, then the performed operation is considered to be string concatenation rather than number addition. In this case all other operands are converted to a string and the resulting string is formed.

This sample code shows how to use all three techniques:

The comparison of two strings is widely used during testing. Generally a test procedure obtains textual data (user input, file contents, property value and so on) and then compares it with the expected data. The TestComplete aqString and native JScript String objects have their methods for comparing one string value to another. These methods are: aqString.Compare and String.localeCompare.

The aqString.Compare method has three parameters: two of them - String 1 and String2 specify the strings to be compared, while the last parameter defines whether the comparison should be case-sensitive or not.

JScript’s native Str1.localeCompare(Str2) method compares the text of a current object instance (Str1) against another string specified by Str2 parameter. The comparison is case-sensitive and is made according to local settings. The method returns -1 if Str1 is less than Str2, 1 if Str1 is greater than Str2 and 0 if the strings are the same.

Both of the methods can compare strings holding specific national symbols, for example characters with diacritical marks ( , , and others).

The code below demonstrates how to use both of mentioned methods:

The JScript scripting language does not have a data type that is intended for storing single symbols. However, this is not a problem, since the string type can hold a series of characters as well as individual characters. Moreover, you can extract a single character out of the string using the aqString.GetChar and String.charAt methods. The sample routine below illustrates their usage, it posts the given text to the TestComplete log in two different ways: as a whole string and by a single letter.

One of the most common tasks that one has to perform when working with string values is determining whether specific text is part of a string. To perform such tasks, the aqString object has the Find method. If the specified substring was found, the method returns the number of the first occurrence of the substring within the source string. If the specified substring was not found, the method returns -1:

You can also get the position where the specified substring occurs using the native method indexOf of the JScript String object. If the substring was found, the method returns the initial position (from 0) of the first substring match. If no occurrences were found, the method returns -1. The code below demonstrates how to use it:

The aqString object and the native String object of JScript have several methods that extract a substring out of a string. They are SubString, substring, substr and slice. These methods vary in how the extracted substring is defined.

The String.substring method returns a text fragment that lies between starting and ending character positions. The character at the ending position is not included. The position is zero-based. If starting position is greater than ending position, then these values are swapped. The negative values are considered as zeros.

The String.slice method is similar to substring, yet, it has its own specifics. In this method the substring is also specified by the starting and ending positions. However the ending position can be omitted, in this case the substring lasts until the end of the initial string. If the starting position is greater than the ending position, then the empty string is returned. The negative values are allowed and are interpreted as position calculated as a given absolute value subtracted from the string length.

The SubString returns a text fragment of the input string that starts at the given position and has the specified length. The String.substr method works in a similar way, however it does not require the input string to be passed as the parameter since every String object instance already refers to a string. Thus the String.substr method has only two parameters, the first one specifies a starting position, while the second defines the length of the retrieved fragment. The length parameter is optional, and if it is omitted then the resulting substring continues up to the end of the source string. If length parameter is negative or zero then the empty string is returned. Undefined, negative and zero values of the position parameter are interpreted as the first character in a string.

The sample code below demonstrates how to use all these methods:

Sometimes it is required to make several strings out of a single string. This operation splits a string into substrings. It can be performed by the native split method of JScript. This method searches the string for delimiter character(s) (defined either as string or as a regular expression), separates the string and returns an array holding the constituent strings. Also you can constrain the maximal array length with the third parameter. It is not obligatory and can be omitted. The same method can be used to split a string onto substrings, sentences and even separate words, it all depends on the specified delimiter. The first sample routine below uses a space character as a delimiter to extract words out of a string and the second routine splits the string by line breaks:

TestComplete has a similar method called aqString.GetListItem. It extracts a substring with the specified index out of the input string. It was designed to read the items from string lists, see Working with string lists for more information. However, it also redefines the delimiter characters and, like the split method, can be used to get sentences, separate words and so forth.

The aqString object has a special routine aqString.Trim that excludes the leading, trailing spaces, or both, from a string. Generally this method is applied to remove the "useless" spaces in the beginning or end of the strings obtained from the user input.

Another function that can be useful when handling user input strings is excluding extra inner spaces out of the string. This function seems to be similar to Trim, but the latter only removes spaces at the beginning or end of the string and does not affect the spaces inside the string. The general idea of the function is for the string to be parsed into separate words and then a new string is constructed. The new string consists of the same words but is separated with a single space between words.

Quite often we need to find and replace a character or substring within a string. There are two ways to do this: by using the aqString.Replace method or using the replace method of a String object.

The aqString object method is much easier to use and can be applied when you need to change a definite character or string. It allows you to set whether the search should be case-sensitive or not. Here is an example of how to use this method:

The String.replace method is a little more complicated, but it offers more flexibility. You can change not only a definite character or string, but all fragments matching the specified regular expression pattern. The regular expression pattern is defined between two backslash ("/") characters, additionally you can set the following flags that can be combined: g - perform global search for all occurrences of pattern, i - ignore letter case and m - perform a multiline search. For a full description of how to use regular expressions refer to the Introduction to Regular Expressions article in the MSDN library.

The first sample demonstrates how to change a definite string using the replace method.

The second example shows how to replace a substring with alternative parts. The patterns of alternative parts are separated by pipe characters (" | "). For instance in the sample below the /ht(ml|m)/ pattern matches both html and htm:

Furthermore, using regular expressions you can search for the text fragments matching the specified format. In the next sample, all dates written in the DD/MM/YYYY format are substituted with the Some Date string. This operation can be useful, for example, when comparing two reports that contain the generation date.

Capital and lower case letters can be included in a string. The TestComplete aqString object and native String object have methods that convert uppercased letters to lower case and vice versa. They are: aqString.ToLower, aqString.ToUpper, String.toLowerCase and String.toUpperCase.

The code below demonstrates how all of these methods are applied.

Some scripting objects, generally, controls like ListBoxes, ComboBoxes, Memos, return data about their state or contents as string lists. The individual data elements (or items) in this list are separated by commas, line breaks, carriage returns or some other delimiter characters.

The aqString object has a number of specific methods (AddListItem, ChangeListItem, DeleteListItem, GetListItem and GetListLength) that are intended to deal with such lists of textual data. The AddListItem and DeleteListItem append the item to the list and remove the item from the list. The GetListItem method retrieves the item with the given index, and ChangeListItem assigns a new value to the given item. The GetListLength method returns the total number of items in the string list.

The symbol that is used as the separator of list items is defined by the ListSeparator property. By default the list separator is a pipe character "|", but it can be reassigned to comma, column, line break, carriage return, tabulation, and any other printable and non-printable character, or even to several characters.

Here is the sample code that shows how to operate with the string lists returned by scripting objects.