String operators - Latest

ascii

ascii(char)

char.ascii()

The return value type is an integer.

Examples

ascii("A") # value: 65

"A".ascii() # value: 65

chr

Evaluates to the character with the given ASCII code, as a single-character string. Evaluates to null if the parameter is null.

Used in the following format, where code is an integer between 0 and 255, inclusive:

chr(code)

The return value type is a string.

Examples

chr(65) # value: "A"

chr(10) # value: "\n"

format

The format function produces a string by applying the given formatString to the value arguments. The format string is composed of zero or more directives: ordinary characters, that is, not %, and conversion specifications. Ordinary characters are copied unchanged to the returned string. Each conversion specification is introduced by the character %, and ends with a type specifier. In between there may be (in this order) zero or more flags, an optional minimum field width, an optional precision and an optional length modifier. The value arguments must correspond properly (after type conversion) with the type specifier. The arguments are used in the given order. It is an error if insufficient value arguments are given. The format function has many options for flexibly creating string output. The following is a detailed description of all of the formatting options. The syntax for a conversion specification is "%[flags][width][.precision][length]type". The flags are optional. They may be any one of the following five characters:

The width specifier is an optional decimal digit string (with non-zero first digit) specifying a minimum field width. If the converted value has fewer characters than the field width, it will be padded with spaces on the left (or right, if the left-adjustment flag has been given). The precision specifier is an optional sequence of digits. This gives the minimum number of digits to appear for d, i, o, u, x, and X conversions, the number of digits to appear after the radix character for a, A, e, E, f, and F conversions, the maximum number of significant digits for g and G conversions, or the maximum number of characters to be printed from a string for s and S conversions. The length specifier is optional and can be one of the following:

The type specifier must be one of the following:

Used in the following format, where formatString must be a string and value can be any value:

format(formatString, [value+])

The return value type is a string.

Examples

format("qwerty %s - %s", 4, "hello") # value: "qwerty 4 - hello"

format("%.4d", 10) # value: "0010" format("pi = %.2f", 3.1415) # value: "pi = 3.14"

format("qwerty %s - %s", 4, "hello") # value: "qwerty 4 - hello"

format("%.4d", 10) # value: "0010" format("pi = %.2f", 3.1415) # value: "pi = 3.14"

format("%.2f", 'Dollar') # Floating point value rendered as Dollar and cents

isAlpha

Evaluates to true only if every character in the string is alphabetic (a-z, A-Z). Evaluates to null if the parameter is null.

Used in the following format, where str must be a string:

isAlpha(str)

str.isAlpha()

The return value type is a Boolean.

Examples

isAlpha("hi") # value: true

"hi".isAlpha() # value: true (isAlpha "hi there") # value: false

"hi there".isAlpha() # value: false (isAlpha "") # value: true

"".isAlpha() # value: true

isAlphaNum

Evaluates to true only if every character in the string is alphanumeric (a-z, A-Z, 0-9). Evaluates to null if the parameter is null.

Used in the following format, where str must be a string:

isAlphaNum(str)

str.isAlphaNum()

The return value type is a Boolean.

Examples

isAlphaNum("hi23") # value: true

"hi23".isAlphaNum() # value: true isAlphaNum("hi there") # value: false

"hi there".isAlphaNum() # value: false isAlphaNum("") # value: true

"".isAlphaNum() # value: true

isDate

Returns as true if the date-str is a valid representation of a date in the specified format. See date for the format information. Returns as false if the date-str is not a valid representation of a date in the specified format.

Used in the following format, where date-str and format must be strings:

isDate(date-str, format)

The return value type is a Boolean.

Examples

isDate("20061112", "YYYYMMDD") # value: true "20061112".isDate("YYYYMMDD") # value: true "2015-04-25 14:25:23".isDate("CCYYMMDD") # value: true

# Invalid dates isDate("999999911", "YYYYMMDD") # value: false "999999911".isDate("YYYYMMDD") # value: false

# Incorrect date separators isDate("2006-11-12", "CCYYMMDD") # value : false "2006-11-12".isDate("CCYYMMDD") # value : false

isDigit

Evaluates to true if every character in the string is numeric (0-9). Evaluates to null if the parameter is null.

Used in the following format, where str must be a string:

isDigit(str)

str.isDigit()

The return value type is a Boolean.

Examples

isDigit("002375") # value: true

"002375".isDigit() # value: true isDigit("3.35") # value: false

"3.35".isDigit() # value: false isDigit("") # value: true

"".isDigit() # value: true

isSpace

Evaluates to true if every character in the string is whitespace (horizontal tab, linefeed, carriage return, space). Evaluates to null if the parameter is null.

Used in the following format, where str must be a string:

isSpace(str)

str.isSpace()

The return value type is a Boolean.

Examples

isSpace(" ") # value: true

" ".isSpace() # value: true isSpace("hi") # value: false

"hi".isSpace() # value: false isSpace("") # value: true

"".isSpace() # value: true

isTime

Returns whether or not the time-str is a valid time in the specified time format. See time for the format information.

Used in the following format, where time-str and format must be strings:

isTime(time-str, format)

time-str.isTime(format)

The return value type is a Boolean.

Examples

isTime("15:30:02", "HH:MM:SS") # value: true "15:30:02".isTime("HH:MM:SS") # value: true

# Invalid Times isTime("15:30:99", "HH:MM:SS") # value false "15:30:99".isTime("HH:MM:SS") # value false

# Invalid time and not matching time format isTime("a string", "HH:MM:SS") # value: false "a string".isTime("HH:MM:SS") # value: false

# Incorrect separator characters isTime("15:30:02", "HH-MM-SS") # value: false "15:30:02".isTime("HH-MM-SS") # value: false

joinStrings

If the source parameter is not an empty string, evaluates to the concatenation of the source, delimiter, and suffix strings. If the source parameter is the empty string, evaluates to the suffix string. Used to construct delimited lists as strings. Any null parameters are interpreted as empty strings.

Used in the following format, where source , suffix and delimiter must be strings:

joinStrings(source, suffix, delimiter)

source.joinStrings(suffix, delimiter)

The return value type is a string.

Examples

myList.joinStrings("item", ", ")

left

Evaluates to a string equivalent to the first N characters of the input string. If the specified number is greater than the length of the input string, the expression evaluates to the input string. If the specified number is less than or equal to zero, the expression evaluates to the empty string. Evaluates to null if either parameter is null.

Used in the following format, where input must be a string and num must be an integer or long integer:

left(input, num)

input.left(num)

The return value type is a string.

Examples

left("abcdefg", 3) # value: "abc"

"abcdefg".left(3) # value: "abc"

ltrim

Evaluates to the string formed by removing leading whitespace from the input-string. Evaluates to null if the parameter is null.

Used in the following format, where input-string must be a string:

ltrim(input-string)

input-string.ltrim()

The return value type is a string.

Examples

ltrim(" hello ") # value: "hello "

" hello ".ltrim() # value: "hello "

pad

Pads the specified string (left or right) with a character, making it length long.

Used in the following format, where string-to-pad must be a string, length is the length to pad to (must be >+ the length of the specified string), character is a 1-char length string to pad with (defaults to "0") and direction is a boolean indicating whether to pad left (defaults to true, i.e. pads left):

pad(string-to-pad, length, [character], [direction])

string-to-pad.pad(length, [character], [direction])

The return value type is a string.

Examples

pad("abc", 4, "0", true) # value: "0abc"

"abc".pad(4, "0", true) # value: "0abc" pad("abc", 4, "a", false) # value: "abca"

"abc".pad(4, "a", false) # value: "abca" pad("abc", 5) # value: "00abc"

"abc".pad(5) # value: "00abc"

replace

Evaluates to a string formed by replacing all occurrences (case-sensitive) of the find string in the source string with the replace string. Evaluates to null if either of the first two parameters is null. Interprets the third parameter as the empty string if it is null.

Used in the following format, where find, replace and source must be strings:

replace(source, find, replace)

source.replace(find, replace)

The return value type is a string.

Examples

replace("how are we today?", "today", "this morning") # value: "how are we this morning?"

"how are we today?".replace("today", "this morning") # value: "how are we this morning?" replace("this is a string", "a string", "text") # value: "this is text"

"this is a string".replace("a string", "text") # value: "this is text"

right

Evaluates to a string equivalent to the last N characters of the input string. If the specified number is greater than the length of the input string, the expression evaluates to the input string. If the specified number is less than or equal to zero, the expression evaluates to the empty string. Evaluates to null if either parameter is null.

Used in the following format, where input must be a string and num must be an integer or long integer:

right(input, num)

input.right(num)

The return value type is a string.

Examples

right("abcdefg", 3) # value: "efg"

"abcdefg".right(3) # value: "efg"

rtrim

Evaluates to the string formed by removing trailing whitespace from the input-string. Evaluates to null if the parameter is null.

Used in the following format, where input-string must be a string:

rtrim(input-string)

input-string.rtrim()

The return value type is a string.

Examples

rtrim(" hello ") # value: " hello"

" hello ".rtrim() # value: " hello"

split

Creates a list of strings, containing the input str split by the separator character(s). Evaluates to null if the parameter is null.

Used in the following format, where str and separator must be strings:

split(str, separator)

str.split(separator)

The return value type is a list.

Examples

split("hi;a;b;c", ";") # value: { "hi" "a" "b" "c"}

"hi;a;b;c".split(";") # value: { "hi" "a" "b" "c"} split("hi;a;;b;c", ";;") # value: { "hi;a" "b;c"}

"hi;a;;b;c".split(";;") # value: { "hi;a" "b;c"}

str

Returns the value of the given expression converted to a string. Evaluates to null if the parameter is null. When one calls str() on a floating point number, the system uses the %g format. The %g format displays the whole range of floating point numbers with rounding but without truncation. Use the format() operator if you need to control more precisely how a floating point number is converted to a string. For example, when printing a floating point number as dollars and cents, you may want to use format("%.2f") to avoid unexpected rounding behavior. See format for a complete description of format options.

Used in the following format, where expr may be any expression:

str(expr)

expr.str()

The return value type is a string.

Examples

str(5) # value: "5"

5.str() # value: "5" str(long(5)) # value: "5"

long(5).str() # value: "5" str(5.0) # value: "5.000000"

5.0.str() # value: "5.000000" str(true) # value: "1"

true.str() # value: "1" str("hi") # value: "hi"

"hi".str() # value: "hi" str(date(2003, 4, 1)) # value: "2003-04-01"

date(2003, 4, 1).str() # value: "2003-04-01" str(time(14, 35, 3)) # value: "14:35:03"

time(14, 35, 3).str() # value: "14:35:03" str(list(1, 2, 3)) # value: "{1;2;3}

list(1, 2, 3).str() # value: "{1;2;3}

strcat

Concatenates the parameter strings. Ignores any null parameters.

Used in the following format, where str must be a string:

strcat({str}+)

str.strcat({str}+)

The return value type is a string.

Examples

strcat("hi", ", ", "there") # value: "hi, there"

"hi".strcat(", ", "there") # value: "hi, there" strcat("a", "bcd", null, "ef") # value: "abcdef"

"a".strcat("bcd", null, "ef") # value: "abcdef"

strFind

Attempts to find the specified substring in the string, case sensitively. If found, the expression evaluates to the offset of the substring in the string. If not found, the expression evaluates to –1. Evaluates to null if either parameter is null.

Used in the following format, where str and substr must be strings:

strFind(str, substr)

str.strFind(substr)

The return value type is an integer.

Examples

strFind("abcdefg", "ef") # value: 4

"abcdefg".strFind("ef") # value: 4 strFind("abcdefg", "EF") # value: -1

"abcdefg".strFind("EF") # value: -1

strFindI

Attempts to find the specified substring in the string, case insensitively. If found, the expression evaluates to the offset of the substring in the string. If not found, the expression evaluates to –1. Evaluates to null if either parameter is null.

Used in the following format, where str and substr must be strings:

strFindI(str, substr)

str.strFindI(substr)

The return value type is an integer.

Examples

strFindI("aBcDeFg", "Ef") # value: 4

"aBcDeFg".strFindI("Ef") # value: 4 strFindI("abcdefg", "ff") # value: -1

"abcdefg".strFindI("ff") # value: -1

strlen

Calculates the length of the input-string. Evaluates to null if the parameter is null.

Used in the following format, where input-string must be a string:

strlen(input-string)

input-string.strlen()

The return value type is an integer.

Examples

string-length("hi") # value: 2

"hi".string-length() # value: 2 string-length("") # value: 0

"".string-length() # value: 0

substr

Evaluates to the substring of the input string, starting at the specified offset (0 indexed) and including the specified number of characters. If the number of characters is not provided, uses all remaining characters. If the specified offset is less than or equal to zero, starts at the beginning of the input string. If the specified number of characters would go beyond the length of the input string, stops at the end of the input string. Evaluates to null if either of the first two parameters is null. Ignores the third parameter if it is null.

Used in the following format, where input must be a string and offset and num must be int or long:

substr(input, offset[, num])

input.substr(offset[, num])

The return value type is a string.

Examples

# Substring of "abcdefg", starting at offset 3, # containing 2 characters substr("abcdefg", 3, 2) # value: "de" "abcdefg".substr(3, 2) # value : "de"

# Substring of "abcdefg", starting at offset 2, # containing the rest of the string substr("abcdefg", 2) # value: "cdefg" "abcdefg".substr(2) # value: "cdefg"

# Offset less than 0, will start at first character, # containing 3 characters substr("abcdefg", -1, 3) # value: "abc" "abcdefg".substr(-1, 3) # value : "abc"

# Number of characters continues beyond length of string, returns # the rest of string substr("abcdefg", 3, 20) # value: "defg" "abcdefg".substr(3, 20) # value : "defg"

toLower

Evaluates to a string formed by converting all uppercase letters in the input-string to lowercase. Evaluates to null if the parameter is null.

Used in the following format, where input-string must be a string:

toLower(input-string)

input-string.toLower()

The return value type is a string.

Examples

toLower("Hi TherE") # value: "hi there"

"Hi TherE".toLower() # value: "hi there"

toUpper

Evaluates to a string formed by converting all lowercase letters in the input-string to uppercase. Evaluates to null if the parameter is null.

Used in the following format, where input-string must be a string:

toUpper(input-string)

input-string.toUpper()

The return value type is a string.

Examples

toUpper("Hi TherE") # value: "HI THERE"

"Hi TherE".toUpper() # value: "HI THERE"

trim

Evaluates to the string formed by removing leading and trailing whitespace from the input-string. Evaluates to null if the parameter is null.

Used in the following format, where input-string must be a string:

trim(input-string)

input-string.trim()

The return value type is a string.

Examples

trim(" hello ") # value: "hello"

" hello ".trim() # value: "hello"

unescape

If the unescapeString argument is a string, unescape will return the same string except that it translates any escape sequences (see String and unicode literals) into individual characters except "\u"; unescape will not translate "\u" or '\U' in string arguments. If the unescapeString argument is a Unicode value, unescape will return a Unicode value with the same set of escape sequences translated, and it will also translate '\u' and '\U'. As with Unicode literals, the double escape opts out of the escape sequence for "\u".

The 'strict' argument to the unescape function is an optional boolean value that tells the function whether to treat malformed escape sequences as errors or to ignore them. When strict is TRUE, unescape performs a strict interpretation of escape sequences, and returns an error if the first parameter contains an unescaped '\' character that is followed by something that is not a valid escape sequence. When strict is FALSE, this tells unescape to treat malformed escape sequences in the first parameter as though they were not escape sequences at all, and just leave them as-is in the return value. The default value for strict is TRUE.

Used in the following format, where unescapeString must be a string or Unicode and strict must be a boolean (TRUE or FALSE):

unescape(unescapeString, [strict])

The return value type is string or Unicode, depending on the unescapeString type.

Examples

unescape(u"abcd\\u4567") # Returns a Unicode value with five characters.

unescape(u"abcd\\\u4567") # Returns an error (because unescape will see a string with a '\' in the second-to-last position and a Unicode character in the last position, and that combination is not a legal escape sequence.)

unescape(u"abcd\\\u0061") # Returns a Unicode value of four characters, the last of which will be the ASCII bell character, because '\u0061' is the ASCII letter 'a' and '\a' is the escape sequence for the bell character.

unescape(u"abcd\\\\u4567") # Returns a Unicode value of ten characters ("abcd\u4567")

unescape("abc\n\\n") # Returns a string of five characters (both of the last two characters will be newline characters), and unescape(u"abc\n\\n" ) will return the same five characters as a Unicode value.

unescape(u"\\\u0063") # Returns an error because '\c' is not a valid escape sequence.

unescape(u"abcd\\u4567") # Returns a Unicode value with five characters.

unescape("abc\\\\z", TRUE) # Returns "abc\z".

unescape(r"\z", FALSE) # Returns "\z".

unescape(u"\\u123" # Returns a Unicode value of "\u123".

unicode

Takes a unicode string and returns it, or takes a string and converts it to a unicode string (and converts any appropriate unicode escapes), and returns it.

Used in the following format, where string is any string:

unicode(string)

string.unicode()

Optionally, you can also specify the character set in which the first argument is encoded, as follows:

unicode(field, "character set")

Examples

unicode("abcd") # return abcd (in unicode)

"abcd".unicode() # return abcd (in unicode)

unicode(field, “8859-1”) # outputs the specified field in unicode, where the field is treated as a string encoded using the 8859-1 character set.