Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Excerpt

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

CountSubString

Declaration

Code Block
int CountSubString(string str, string subStr)

Syntax

Code Block
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

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

Backtotop

DQuote

Declaration

Code Block
string DQuote(string str)

Syntax

Code Block
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

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

DQuote('any "text" str');
// Returns ""any "text" str"" -- note that the embedded double quotes are not escaped
Info
NOTE: The outer pair of double quotes in the above example examples is the indication of a string data type and is not returned as part of the string itself.

Backtotop

Format

Declaration

Code Block
string Format(string formatStr, type de)

Syntax

Code Block
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

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

Backtotop

Index

Declaration

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

Syntax

Code Block
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

Code Block
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

Backtotop

IsValidString

Declaration

Code Block
bool IsValidString(string str)

Syntax

Code Block
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

Code Block
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)

Backtotop

Left

Declaration

Code Block
string Left(string str, int n)

Syntax

Code Block
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.

Note
NOTE: If the string is a numeric string that begins with a leading zero, it must be enclosed within quotes or it will be interpreted as an integer and a different starting character index may result.

Examples

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

Backtotop

LPad

Declaration

Code Block
string LPad(string str, int n)

Syntax

Code Block
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

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

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

Backtotop

LPadChar

Declaration

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

Syntax

Code Block
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

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

Backtotop

LTrim

Declaration

Code Block
string LTrim(string str)

Syntax

Code Block
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

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

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

Backtotop

LTrimChars

Declaration

Code Block
string LTrimChars(string str, string trimChars)

Syntax

Code Block
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

Code Block
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

Backtotop

Mid

Declaration

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

Syntax

Code Block
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.

Note
NOTE: If the string is a numeric string that begins with a leading zero, it must be enclosed within quotes or it will be interpreted as an integer and a different starting character index may result.

Examples

Code Block
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"

Backtotop

ParseURL

Declaration

Code Block
array ParseURL(string url)

Syntax

Code Block
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

Code Block
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

Backtotop

Quote

Declaration

Code Block
string Quote(string str)

Syntax

Code Block
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

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

Quote("Ain't escaped");
// Returns "'Ain't escaped'" -- note that the embedded quote is not escaped.
Info
NOTE: The outer pair of double quotes in the above examples is the indication of a string data type and is not returned as part of the string itself.

Backtotop

RegExMatch

Declaration

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

Syntax

Code Block
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.

See also the RegExReplace() function.

Examples

Code Block
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.
Info
NOTE: "\" (backslash) has to be escaped in literal strings since it is the escape character. To use a "\", use a doubled backslash: "\\".

Backtotop

RegExReplace

Declaration

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

Syntax

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

Required Parameters

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.

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

Code Block
// 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"
Info
NOTE: "\" (backslash) has to be escaped in literal strings since it is the escape character. To use a "\", use a doubled backslash: "\\".

Backtotop

Replace

Declaration

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

Syntax

Code Block
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

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

Backtotop

Right

Declaration

Code Block
string Right(string str, int n)

Syntax

Code Block
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.

Note
NOTE: If the string is a numeric string that begins with a leading zero, it must be enclosed within quotes or it will be interpreted as an integer and a different starting character index may result.

Examples

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

Backtotop

RPad

Declaration

Code Block
string RPad(string s, int n)

Syntax

Code Block
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

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

Backtotop

RPadChar

Declaration

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

Syntax

Code Block
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

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

Backtotop

RTrim

Declaration

Code Block
string RTrim(string str)

Syntax

Code Block
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

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

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

Backtotop

RTrimChars

Declaration

Code Block
string RTrimChars(string str, string trimChars)

Syntax

Code Block
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

Code Block
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

Backtotop

Split

Declaration

Code Block
array Split(string str, string delimiter)

Syntax

Code Block
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

Code Block
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):

Code Block
// 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]));

Backtotop

SplitCSV

Declaration

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

Syntax

Code Block
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.

Info
NOTE: The optional parameters (delimiter and qualifier) can be specified with an integer corresponding to the ASCII code of the delimiter or qualifier character.

Examples

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

Backtotop

StringLength

Declaration

Code Block
int StringLength(string str)

array StringLength(array arr)

Syntax

Code Block
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

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

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

Length(arr); 
// Returns 2

Backtotop

ToLower

Declaration

Code Block
string ToLower(string str)

Syntax

Code Block
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

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

Backtotop

ToProper

Declaration

Code Block
string ToProper(string str)

Syntax

Code Block
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.

Warning

WARNING: The ToProper() function is such that names such as "mccartney" beginning with "mc" are only converted correctly to "McCartney" if the word is preceded by a space character. To have a string that begins with "mc" such as "mccartney, paul" converted correctly to "McCartney, Paul", use code such as this to add a preceding space and then immediately remove it:

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

Examples

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

Backtotop

ToUpper

Declaration

Code Block
string ToUpper(string <str>)

Syntax

Code Block
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

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

Backtotop

Trim

Declaration

Code Block
string Trim(string str)

Syntax

Code Block
Trim(<str>)

Required Parameters

  • str: A string

Description

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

Examples

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

Backtotop

TrimChars

Declaration

Code Block
string TrimChars(string str, string trimChars)

Syntax

Code Block
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

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

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

Backtotop

Truncate

Declaration

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

Syntax

Code Block
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

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

Backtotop

URLDecode

Declaration

Code Block
string URLDecode(string url, string paramName)

Syntax

Code Block
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

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

Backtotop

URLEncode

Declaration

Code Block
string URLEncode(string str[, int encodingOption])

Syntax

Code Block
string 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

Code Block
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

Backtotop

Panel
borderColor#8C9CB4
titleColor#FFFFFF
titleBGColor#8C9CB4
titleSearch in This Topic
Page Tree Search
rootPageFormula Builder
Panel
borderColor#65379B
titleColor#FFFFFF
titleBGColor#65379B
titleOn This Page
Table of Content Zone

Table of Contents
maxLevel3
minLevel2
indent20px
excludeSyntax|Declaration|Description|Example|Examples

Panel
borderColor#00B886
titleColor#FFFFFF
titleBGColor#00B886
titleRelated Topics
Content by Label
showLabelsfalse
max1000
showSpacefalse
sorttitle
cqllabel = "formula-builder-overview" and space = currentSpace()

HideElements
metastrue

Last updated: 

Lastmodifieddate