String Functions¶

String functions are the mechanism for the manipulation of strings in scripts.

CountSubString¶

Declaration¶

int CountSubString(string str, string subStr)

Syntax¶

CountSubString(<str>, <subStr>)

Required Parameters¶

• str: A string to be searched
• subStr: The string to search with

Description¶

Returns the number of times a sub-string appears in a string.

Examples¶

CountSubString("Mississippi", "iss"); // Returns 2

DQuote¶

Declaration¶

string DQuote(string str)

Syntax¶

DQuote(<str>)

Required Parameters¶

• str: A string to be double quoted

Description¶

Places a string in double quotes and returns the result. Embedded double quotes are not escaped.

Examples¶

DQuote("any str"); // Returns ""any str""

DQuote('any "text" str');
// Returns ""any "text" str"" -- note that the embedded double quotes are not escaped

Format¶

Declaration¶

string Format(string formatStr, type de)

Syntax¶

Format(<formatStr>, <de>)

Required Parameters¶

• formatStr: The format string to be used when formatting the string
• de: A data element; if necessary it will be converted to a string prior to being formatted

Description¶

Returns a string in the format specified by a format string.

The format specification is the same as used in the Date and Time Functions; see its section on format strings. It is similar to the standard C library printf format specification.

This function can be used to set the output format for a target. It is useful when Jitterbit's default output format for a data type (such as date or double) is not as desired. The call to the Format function must be the last call in a mapping formula to have it be the mapped value.

Examples¶

Format("'%5d'", 2); // Returns "'    2'"

Index¶

Declaration¶

int Index(string str, string subStr[, int n])

Syntax¶

Index(<str>, <subStr>[, <n>])

Required Parameters¶

• str: A string to be searched
• subStr: The string to search with

Optional Parameters¶

• n: The specific instance of interest if more than one match

Description¶

Returns the position of a sub-string within a string.

In cases where the sub-string appears more than once in the main string, the third argument (n) is used to determine which specific instance of the sub-string is of interest.

• If n < 0, the instance counting starts from the end of the main string.
• If |n| > the maximum number of times the sub-string appears in the main string, the function returns -1.

Otherwise, the function returns the sub-string's first character's position within the main string (starting at position 0).

Special cases to consider:

• n = 0 returns the same result as n = 1

• If subStr is an empty string (""):

  • n >= 0 always returns 0

  • n < 0 always returns Length(str)

Examples¶

Index("Mississippi", "s"); // Returns 2
// When called with only two arguments
// the optional third argument defaults to 1,
// resulting in the index of the first match being returned

Index("Mississippi", "iss", 3); // Returns -1
// Searching for the 3rd instance of "iss" within Mississippi

Index("Mississippi", "si", 2); // Returns 6
// The 2nd instance of the sub-string
// "si" starts at position 6 as the
// first letter "M" starts at position 0

Index("Mississippi", "", 1); // Returns 0
Index("Mississippi", "", -1); // Returns 11

IsValidString¶

Declaration¶

bool IsValidString(string str)

Syntax¶

IsValidString(<str>)

Required Parameters¶

• str: A string to be validated

Description¶

Returns true if each character in a string is valid. Valid characters are ASCII codes 32 through 126 inclusive and any of linefeed (LF), carriage return (CR), or tab (TAB) characters.

Examples¶

IsValidString("An Invalid String™");
// Returns 0 (false), as the trademark symbol in this font is a code greater than 128

IsValidString("A Valid Broken
String");
// Returns 1 (true)

Left¶

Declaration¶

string Left(string str, int n)

Syntax¶

Left(<str>, <n>)

Required Parameters¶

• str: A string
• n: The number of characters from the left end to be returned

Description¶

Returns n characters of a string, counting from the left (the beginning) of a string.

See also the Mid and Right functions.

Examples¶

Left("01234567890", 4);
// Returns "0123"

LPad¶

Declaration¶

string LPad(string str, int n)

Syntax¶

LPad(<str>, <n>)

Required Parameters¶

• str: A string
• n: The number of characters from the left end to be returned

Description¶

Adds spaces to the left (the beginning) of a string until the string contains n characters. Strings containing n or more characters are truncated to n characters.

LPad(str, -n) is the same as RPad(str, n). See the RPad function.

Examples¶

LPad("01234567", 9);
// Returns " 01234567"
// Adds one space to the left side
// of the original string

LPad("1234567890", 9);
// Returns "123456789"

LPadChar¶

Declaration¶

string LPadChar(string str, string padChar, int n)

Syntax¶

LPadChar(<str>, <padChar>, <n>)

Required Parameters¶

• str: A string
• padChar: A string to be used to pad characters; if more than one character, the first character is used
• n: The number of characters from the left end to be returned

Description¶

Adds a padding character to the left (the beginning) of a string until the string contains n characters. Strings containing n or more characters are truncated to n characters.

LPadChar(str, " ", n) is the same as LPad(str, n). See the LPad function.

Examples¶

LPadChar(1234567, "0", 10);
// Returns "0001234567"
LPadChar(1234567, ".0", 10);
// Returns "...1234567"

LTrim¶

Declaration¶

string LTrim(string str)

Syntax¶

LTrim(<str>)

Required Parameters¶

• str: A string

Description¶

Removes whitespace (spaces, tabs) from the left (the beginning) of a string and returns the remaining characters.

Examples¶

LTrim(" Hello World!  ");
// Returns "Hello World!  "

LTrim("    Hello World!");
// Removes the leading tab character
// and returns "Hello World!"

LTrimChars¶

Declaration¶

string LTrimChars(string str, string trimChars)

Syntax¶

LTrimChars(<str>, <trimChars>)

Required Parameters¶

• str: A string to be trimmed from the left (the beginning)**
  
• trimChars: A string of trimming characters to be matched; the order does not matter

Description¶

Removes any leading characters in a string from the left (the beginning) that match those in the trimming characters and returns the remaining characters.

This function tests each leading character of a string, beginning on the left edge, and sees if it is found in the trim characters. If it does, it is removed, and the process repeated until there is no longer a match.

This can be used to trim characters other than the default whitespace characters, such as trimming leading colons.

See also the RTrimChars and TrimChars functions.

Examples¶

LTrimChars("::StartMsg :: Hello :: EndMsg::", ":");
// Returns "StartMsg :: Hello :: EndMsg::"

LTrimChars("// This is a comment", " /");
// Returns "This is a comment"

LTrimChars("// This is a comment", "/ ");
// Returns "This is a comment"

LTrimChars("// This is a comment", "/");
// Returns " This is a comment"

LTrimChars("// This is a comment", " ");
// Returns "// This is a comment"
// Returns the string unchanged as a space
// was not a leading character

Mid¶

Declaration¶

string Mid(string str, int m, int n)

Syntax¶

Mid(<str>, <m>, <n>)

Required Parameters¶

• str: A string from which to extract a sub-string

• m: The zero-based starting character position to begin extracting the sub-string

• n: The length (number of characters) of the sub-string to be extracted

Description¶

Returns a portion of a string, starting with the character at position m for a length of n characters.

See also the Left and Right functions.

Examples¶

Mid("Jitterbit", 2, 3);
// Returns "tte"

Mid("01234567890", 7, 3);
// Returns "789"

// Passing the same string as an
// integer with a leading zero
// returns a different result
Mid(01234567890, 7, 3);
// Returns "890"

ParseURL¶

Declaration¶

array ParseURL(string url)

Syntax¶

ParseURL(<url>)

Required Parameters¶

• url: A string containing a URL for parsing

Description¶

Parses a URL string and returns an array of decoded values. The values are tagged so that they can be retrieved either by index or by field name.

When retrieving values from the result, the case of a field name is ignored. See also the URLDecode and URLEncode functions.

Examples¶

url = "http://hostname/user?email=john1990%40example.com&name=John%20Smith";
arr = ParseURL(url);

email = arr[0];
// "email" will be john1990@example.com
email = arr["email"];
// same as previous

name = arr["name"];
// "name" will be "John Smith"
name = arr["Name"];
// Same as previous;
// case is ignored for field names

Quote¶

Declaration¶

string Quote(string str)

Syntax¶

Quote(<str>)

Required Parameters¶

• str: A string to be single quoted

Description¶

Places a string in single quotes and returns the result. Embedded single quotes are not escaped.

Examples¶

Quote("Any string");
// Returns "'Any string'"

Quote("Ain't escaped");
// Returns "'Ain't escaped'" -- note that the embedded quote is not escaped.

RegExMatch¶

Declaration¶

int RegExMatch(string str, string exp[, type var1,... type varN])

Syntax¶

RegExMatch(<str>, <exp>[, <var1>,... <varN>])

Required Parameters¶

• str: A string to be single quoted

• exp: A regular expression that consists of groups

Optional Parameters¶

• var1...varN: One or more variable names, to be matched to the marked sub-expressions of the expression

Description¶

Matches a regular expression with an input string, stores the marked sub-expressions in variables, and returns the number of matches.

Returns the total number of marked sub-expressions (which could be more or less than the number of variables actually supplied). Any additional matches that exceed the number of variables supplied are discarded. If there are no matches, -1 is returned.

The regular expression follows the Boost regular expression library syntax. It is a variation of the Perl regular expression syntax.

Unicode characters, including symbols such as emoji, must be matched using their literal characters and not using Unicode escape sequences. For example, the range "[😀-🤯]" (U+1F600 to U+1F92F) successfully captures the 🤔 (U+1F914) symbol in between.

See also the RegExReplace function.

Examples¶

result = RegExMatch("[abc]", "(\\[)(.*)(\\])", "dummy", "value");
// Sets the global variable "$dummy" to "[".
// Sets the global variable "$value" to "abc".
// Returns 3 because the character "]"
// also matched the last sub-expression.
// However, as there are only two variable names,
// the last match is not saved to a variable.

RegExReplace¶

Declaration¶

string RegExReplace(string str, string exp, string format)

Syntax¶

RegExReplace(<str>, <exp>, <format>)

Required Parameters¶

• str: A string to be searched and have any matching sub-strings replaced

• exp: The regular expression in the Boost regular expression library syntax to be used to match for sub-strings of the string

• format: A format string in the Boost-Extended Format String Syntax

Description¶

Replaces all sub-strings in a string that match an expression, using a specifed format to replace each sub-string. Any sections of the string that do not match the expression are passed through to the returned string unchanged.

The regular expression follows the Boost regular expression library syntax. It is a variation of the Perl regular expression syntax.

Unicode characters, including symbols such as emoji, must be matched using their literal characters and not using Unicode escape sequences. For example, the range "[😀-🤯]" (U+1F600 to U+1F92F) successfully captures the 🤔 (U+1F914) symbol in between.

The format string follows the Boost-Extended Format String Syntax. If the format string is an empty string ("") then a match produces no result for that sub-string.

See also the RegExMatch function.

Examples¶

// To remove any whitespace from a string:
RegExReplace(" t e st ss s", "\\s", "");
// Returns "testsss"

// To swap the order of sub-strings:
RegExReplace("abc(first)123(second)xyz",
             "(.*)(\\(.*\\))(.*)(\\(.*\\))(.*)",
             "\\1aaa\\4\\2\\3\\5");
// Returns "abcaaa(second)(first)123xyz"

// To pass backslashes in matches, multiple instances may be required.
// In the "r" example, three backslashes are used and then doubled.
// The first two backslashes convert into a single backslash,
// which then escapes the next backslash.
// All three backslashes are then doubled for Jitterbit script.
s = "test\\ing";  // "test\ing";
t = RegExReplace(s, "\\\\", "!");  // "test\ing" -> "test!ing"
r = RegExReplace(t, "!", "\\\\\\");  // "test!ing" ->  "test\\ing"

Replace¶

Declaration¶

string Replace(string str, string old, string new)

Syntax¶

Replace(<str>, <old>, <new>)

Required Parameters¶

• str: A string to be searched and matching sub-strings replaced

• old: A string to be used for the match

• new: A string to be used as a replacement for any matches found

Description¶

Searches a string for sub-strings matching the "old" argument and replaces a matching sub-string with the "new" argument.

For more complex search and replace operations, see the RegExReplace function.

Examples¶

Replace("Monday Tuesday", "day", "day night,");
// Returns "Monday night, Tuesday night,"

Right¶

Declaration¶

string Right(string str, int n)

Syntax¶

Right(<str>, <n>)

Required Parameters¶

• str: A string

• n: The number of characters from the right end to be returned

Description¶

Returns n characters of a string, counting from the right (the end) of a string.

See also the Left and Mid functions.

Examples¶

Right("01234567890",4);
// Returns "7890"

RPad¶

Declaration¶

string RPad(string s, int n)

Syntax¶

string RPad(string s, int n)

Required Parameters¶

• str: A string

• n: The number of characters from the right end to be returned

Description¶

Adds spaces to the right (the end) of a string until the string contains n characters. Strings containing n or more characters are truncated to n characters.

RPad(str, -n) is the same as LPad(str, n). See the LPad function.

Examples¶

RPad("01234567",9);
// Returns "01234567 "

RPadChar¶

Declaration¶

string RPadChar(string str, string padChar, int n)

Syntax¶

RPadChar(<str>, <padChar>, <n>)

Required Parameters¶

• str: A string
• padChar: A string to be used to pad characters; if more than one character, the first character is used
• n: The number of characters from the right end to be returned

Description¶

Adds a padding character to the right (the end) of a string until the string contains n characters. Strings containing n or more characters are truncated to n characters.

RPadChar(str, " ", n) is the same as RPad(str, n). See the RPad function.

Examples¶

RPadChar(1234567, "0", 10);
// Returns "1234567000"

RTrim¶

Declaration¶

string RTrim(string str)

Syntax¶

RTrim(<str>)

Required Parameters¶

• str: A string

Description¶

Removes whitespace (spaces, tabs) from the right (the end) of a string and returns the remaining characters.

Examples¶

RTrim(" Hello World!  ");
// Returns " Hello World!"

RTrim("Hello World!    ");
// Removes the trailing tab character
// and returns "Hello World!"

RTrimChars¶

Declaration¶

string RTrimChars(string str, string trimChars)

Syntax¶

RTrimChars(<str>, <trimChars>)

Required Parameters¶

• str: A string, to be trimmed from the right (the end)**
  
• trimChars:** A string of trimming characters to be matched; the order does not matter

Description¶

Removes any trailing characters in a string from the end that match those in the trimming characters and returns the remaining characters.

This function tests each trailing character of a string, beginning on the right edge, and sees if it is found in the trim characters. If it does, it is removed, and the process repeated until there is no longer a match.

This can be used to trim characters other than the default whitespace characters, such as trimming trailing colons.

See also the LTrimChars and TrimChars functions.

Examples¶

RTrimChars("::StartMsg :: Hello :: EndMsg::", ":");
// Returns "::StartMsg :: Hello :: EndMsg"

RTrimChars("// This is a comment //", " /");
// Returns "// This is a comment"

RTrimChars("// This is a comment //", "/");
// Returns "// This is a comment "

RTrimChars("// This is a comment //", " ");
// Returns "// This is a comment //"
// Returns the string unchanged as a space
// was not a trailing character

Split¶

Declaration¶

array Split(string str, string delimiter)

Syntax¶

Split(<str>, <delimiter>)

Required Parameters¶

• str: A string to be split
• delimiter: A string of to be matched as the split between each array element

Description¶

Splits a string using a delimiter string, returning the result as an array.

Returns the result in an array of size equal to the number of delimiters plus one. If the expression ends with the delimiter, the array size is equal to the number of delimiters (the last empty value is ignored). If the string contains no delimiters, an array of size one is returned containing the original string.

Examples¶

arr = Split("Donald,Minnie,Goofy", ",");
donald = arr[0];
minnie = arr[1];
goofy = arr[2];

Split("Donald.,Minnie.,Goofy.,", ".,");
// Returns the array {Donald, Minnie, Goofy}

This example converts an IP address ("10.6.10.1") to a single integer (168167937):

// Logic: (first octet * 16777216) + (second octet * 65536) +
//   (third octet * 256) + (fourth octet)
ip = "10.6.10.1";
ipList = Split(ip, ".");
(Int(ipList[0]) * 16777216) + (Int(ipList[1]) * 65536) +
    (Int(ipList[2]) * 256) + (Int(ipList[3]));

SplitCSV¶

Declaration¶

array Split(string str[, string delimiter, int qualifier])

Syntax¶

Split(<str>[, <delimiter>, <qualifier>])

Required Parameters¶

• str: A string to be split

Optional Parameters¶

• delimiter: A string of to be matched as the split between each array element
• qualifier: A string of to be matched as the split between each array element

Description¶

Splits a CSV-formatted string and returns an array with the individual column values.

By default, the delimiter is a comma (,) and the string qualifier is a double quote ("). This can be changed by specifying the optional second and third arguments respectively.

Examples¶

arr = SplitCSV('"Donald","Minnie ""The Mouse""", Goofy');
donald = arr[0];
// Returns "Donald"
minnie = arr[1];
// Returns "Minnie ""The Mouse"""
goofy = arr[2];
// Returns "Goofy"

StringLength¶

Declaration¶

int StringLength(string str)

array StringLength(array arr)

Syntax¶

StringLength(string str)

StringLength(array arr)

Required Parameters¶

• str: (First form) A string

• arr: (Second form) An array

Description¶

Returns the length of a string.

The function returns an array if the argument is an array, with each element of the returned array the length of the corresponding element of the argument array. The Length function returns the length of an array rather than the length of the individual elements.

Examples¶

arr = {a="abcd", b="e"};

StringLength(arr);
// Returns the array {4,1}

Length(arr);
// Returns 2

ToLower¶

Declaration¶

string ToLower(string str)

Syntax¶

ToLower(<str>)

Required Parameters¶

• str: A string

Description¶

Converts all ASCII uppercase characters (A through Z, ASCII 65 through 90) in a string to lowercase.

Examples¶

ToLower("Hello World!");
// Returns "hello world!"

ToProper¶

Declaration¶

string ToProper(string str)

Syntax¶

ToProper(<str>)

Required Parameters¶

• str: A string

Description¶

Converts a string to proper case (the first letter of every word being capitalized). This is distinct from title case, which only capitalizes selected and longer words in a string.

s = "mccartney, paul";
s = Right( ToProper( " " + s), Length(s));

Examples¶

ToProper("bob dylan");
// Returns "Bob Dylan"
ToProper("arthur c. Clarke");
// Returns "Arthur C. Clarke"
ToProper("Peter o'toole");
// Returns "Peter O'Toole"

ToUpper¶

Declaration¶

string ToUpper(string <str>)

Syntax¶

ToUpper(<str>)

Required Parameters¶

• str: A string

Description¶

Converts all ASCII lowercase characters (a through z, ASCII 97 through 122) in a string to uppercase.

Examples¶

ToUpper("Hello World!");
// Returns "HELLO WORLD!"

Trim¶

Declaration¶

string Trim(string str)

Syntax¶

Trim(<str>)

Required Parameters¶

• str: A string

Description¶

Removes whitespace from the beginning and end of a string and returns the remaining characters.

Examples¶

Trim(" Hello World! ");
// Returns "Hello World!"

TrimChars¶

Declaration¶

string TrimChars(string str, string trimChars)

Syntax¶

TrimChars(<str>, <trimChars>)

Required Parameters¶

• str: A string to be trimmed
• trimChars: A string of trimming characters to be matched; the order does not matter

Description¶

Removes any leading or trailing characters in a string that match those in the trimming characters and returns the remaining characters.

This function tests each leading and trailing character of a string and sees if it is found in the trim characters. If it does, it is removed, and the process repeated until there are no longer any matches.

This can be used to trim characters other than the default whitespace characters, such as trimming colons.

See also the LTrimChars and RTrimChars functions.

Examples¶

TrimChars("::StartMsg :: Hello :: EndMsg::", ":");
// Returns "StartMsg :: Hello :: EndMsg"

TrimChars("/* This is a comment */", " /*");
// Returns "This is a comment"

Truncate¶

Declaration¶

string Truncate(string str, int firstChars, int lastChars)

Syntax¶

Truncate(<str>, <firstChars>, <lastChars>)

Required Parameters¶

• str: A string
• firstChars: The number of characters to delete from the left (the beginning) of the string
• lastChars: The number of characters to delete from the right (the end) of the string

Description¶

Deletes firstChar characters from the left (the beginning) and lastChars characters from the right (the end) of a string and returns the remaining string.

See also the Left and Right functions.

Examples¶

Truncate("a,b,c,", 2, 1);
// Returns "b,c"

URLDecode¶

Declaration¶

string URLDecode(string url, string paramName)

Syntax¶

URLDecode(<url>, <paramName>)

Required Parameters¶

• url: A string containing a URL
• paramName: The name of a parameter in the URL whose value is to be returned

Description¶

Parse a URL string and return the decoded value of the URL parameter with the specified name. The case of the name is ignored. If the name is not found in parameters of the URL, an empty string ("") is returned.

See also the ParseURL and URLEncode functions.

Examples¶

url = "http://hostname/user?email=john1990%40gmail.com&name=John%20Smith";
URLDecode(url, "name");
// Returns "John Smith"

URLEncode¶

Declaration¶

string URLEncode(string str[, int encodingOption])

Syntax¶

URLEncode(<str>[, <encodingOption>])

Required Parameters¶

• url: A string containing a value to encoded following the rules of RFC 1738

Optional Parameters¶

• encodingOption: An integer (0 - 3) that specifies the encoding to be used. Default value is 0. See the list below.

Description¶

Encodes a string following RFC 1738.

Valid values for the optional encoding option are:

• 0: Standard URL encoding. Encodes ASCII control characters, non-ASCII characters, "reserved" characters, and "unsafe" characters. This is the default encoding if the option is omitted.
• 1: Don't encode "unsafe" characters: " \< ;> ; # % { } | \ ^ \~ [ ] ` and the space character
• 2: Don't encode "reserved" characters: ; / ? : @ & =
• 3: Don't encode "unsafe" characters and "reserved" characters

These characters are considered "safe" and are never encoded: $ - _ . + ! * ' ( ) ,

See also the ParseURL and URLDecode functions.

Examples¶

value1 = "FIRST#"; value2 = "<LAST>";
url = "http://hostname/get_doc?" +
    "name1=" + URLEncode(value1) +
    "&name2=" + URLEncode(value2);
// Returns
// http://hostname/get_doc?name1=FIRST%23&name2=%3CLAST%3E