String

String functions are used to manipulate and handle string variables.

charlen

Description

The charlen() function returns the number of characters (single-byte or multiple-byte) in the argument string.

• By contrast, the length() function returns the number of bytes in a string, which equals the number of characters only for single-byte character encodings.
• In contrast to the length() function, the charlen() function does not accept a list as an argument.

Syntax

result = charlen (string)

Arguments

Return values

result Contains an integer that indicates the number of characters in string.

Example

string = "BeyondTrust Software";
howLong = charlen(string);

In this example, the howLong variable contains the integer value 20.

gsub

Description

The gsub() function replaces all occurrences of the pattern within the source string.

Syntax

result = gsub (pattern, replacement, sourcestring);

Arguments

Return values

The resulting string.

Example

In this example, xyz replaces all occurrences of abc in startingstring.

newstring = gsub("abc", "xyz", startingstring)

length

Description

The length() function returns the length, in bytes, of the specified string.

For multiple-byte character sets, the number of bytes is not the same as the number of characters; use the charlen() function instead.

Syntax

result = length (string1);

Arguments

Return values

result is set to the length (as an integer value) of string1.

Example

In this example, result is an integer with a value of 10.

currentuser = "John Stone";
result = length (currentuser);

pad

Description

• The pad() function creates a new string from string1 based on the specified length (length) and pad character (padchar).
• If string1 is shorter than the specified length, then it is padded by adding the appropriate number of the specified pad character to the end of the string.
• If string1 is longer than the specified length, then it is truncated and pad characters are not added.
• If the length of string1 is equal to the specified length, no changes are made and the original contents of string1 are returned in result.

The pad() function supports both single-byte and multiple-byte character sets.

Syntax

result = pad (string1, length, padchar);

Arguments

Return values

result contains the new string.

Example

In this example, result contains Jim White1.

string = "Jim White";
result = pad (string1, 10, "123");

Example

In this example, result contains the value 書策搜文.

string1 = "書策搜";
result = pad (string1, 4, "文");

sub

Description

The sub() function replaces the first occurrence of the pattern within the source string.

Syntax

result = sub (pattern, replacement, sourcestring);

Arguments

Return values

The resulting string

Example

In this example, the first occurrence of a trailing new line is replaced with nothing, effectively chopping it off.

newstring = sub("\n$", "", textstring)

substr

Description

• The substr() function extracts a substring from the specified string variable (string1) based on the provided starting position (start) and optional length (length).
• The first character in string1 is position 1.
• If the optional length is not specified, then substr() returns all characters from the starting position through the end of the string.
• An error is generated if a negative starting position is given or if the starting position is past the end of the string (for example, if string1 is 10 characters long and the specified starting location is 12).
• The substr() function supports single-byte and multiple-byte character strings. In either case, the starting position and length are in units of characters, not bytes.

Syntax

result = substr (string1, start [, length]);

Arguments

Return values

result contains the new substring.

Example

In this example, result1 contains the value User2, and result2 contains User2, User3.

UserList = "User1, User2, User3";
result1 = substr (UserList, 8, 5);
result2 = substr (UserList, 8);

Example

In this example, result contains the value 策搜書策搜.

UserList = "書策搜書策搜書策搜書策搜書策搜書策搜書策搜";
result = substr (UserList, 8, 5);

tolower

Description

The tolower() function returns a copy of a string, converted to all lowercase.

The tolower() function supports both single-byte and multiple-byte character sets. If the character set for the locale does not distinguish uppercase and lowercase characters, the original string is returned unchanged.

Syntax

tolower (string)

Arguments

Return values

A string that contains a lowercase copy of the argument.

Example

result = tolower (variableName);
result = tolower("String Constant");

toupper

Description

The toupper() function returns a copy of a string, converted to all uppercase.

The toupper() function supports both single-byte and multiple-byte character sets. If the character set for the locale does not distinguish uppercase and lowercase characters, the original string is returned unchanged.

Syntax

toupper (string)

Arguments

Return values

A string that contains an uppercase copy of the argument.

Example

result = toupper (variableName);
result = toupper ("String Constant");