For the latest version of JMP Help, visit JMP.com/help.


Publication date: 06/21/2023

Character Functions

Most character functions take character arguments and quoted return character strings, although some take numeric arguments or return numeric data. Arguments that are literal character strings must be enclosed in quotation marks.

Work with Character Functions in the Scripting Guide provides more information about some of the functions.

BLOB To Char(blob, <Encoding="enc">)

Description

Reinterpret binary data as a quoted Unicode string.

Returns

A quoted string.

Required Argument

blob

A binary large object.

Optional Argument

Encoding

A quoted string that specifies an encoding. The default encoding for the character string is "utf-8". "utf-16le", "utf-16be", "us-ascii", "iso-8859-1", "ascii~hex", "shift-jis", and "euc-jp" are also supported.

Notes

The optional argument "ascii~hex" is intended to make conversions of blobs containing normal ASCII data simpler when the data might contain CR, LF, or TAB characters (for example) and those characters do not need any special attention.

See Also

Hexadecimal and BLOB Functions in the Scripting Guide

BLOB To Matrix(blob, type, bytes, endian, <nCols>)

Description

Creates a matrix by converting each byte in the blob to numbers.

Returns

A matrix that represents the blob.

Required Arguments

blob

A blob or reference to a blob.

type

A quoted string that contains the named type of number. The options are "int", "uint", or "float".

bytes

Byte size of the data in the blob. Options are 1, 2, 4, or 8.

endian

The quoted endian-ness of your system: "Big" (the first byte is most significant), "Little" (the first byte is the least significant), or "Native" (the machine’s native format).

Optional Argument

<nCols>

The number of columns in the matrix. The default value is 1.

See Also

Hexadecimal and BLOB Functions in the Scripting Guide

Char(x, <width>, <decimal>, < <<Use Locale(Boolean)>)

Description

Converts an expression or numeric value into a quoted character string.

Returns

A quoted string.

Required Argument

x

an expression or a numeric value. An expression must be quoted with Expr(). Otherwise, its evaluated value is converted to a quoted string.

Optional Arguments

width

A number that sets the maximum number of characters in the quoted string.

decimal

A number that sets the maximum number of places after the decimal that is included in the quoted string.

Use Locale(Boolean)

Preserves locale-specific numeric formatting.

Example

Char( Pi(), 10, 4)

"3.1416"

Char( Pi(), 3, 4)

"3.1"

Notes

The width argument overrides the decimal argument.

See Also

Numbers and Strings in the Scripting Guide

Char To BLOB(string, <encoding="enc">)

Description

Converts a quoted string of characters into a binary (blob).

Returns

A binary object.

Required Argument

string

A quoted string or a reference to a string.

Optional Argument

encoding

A quoted string that specifies an encoding. The default encoding for the blob is "utf-8". "utf-16le", "utf-16be", "us-ascii", "iso-8859-1", "ascii~hex", "shift-jis", and "euc-jp" are also supported.

Notes

Converting BLOBs into printable format escapes \ (in addition to ~ " ! and characters outside of the printable ASCII range) into hex notation (~5C for the backslash character).

x = Char To BLOB( "abc\def\!n" );
y = BLOB To Char( x, encoding = "ASCII~HEX" );
If(
	y == "abc~5Cdef~0A", "JMP 12.2 and later behavior",
	y == "abc\def~0A", "Pre-JMP 12.2 behavior"
);

"JMP 12.2 and later behavior" // output

See Also

Hexadecimal and BLOB Functions in the Scripting Guide

Char To Hex(value, <integer|encoding="enc">)

Hex(value, <integer|encoding="enc"|Base(number)|Pad To(number)>)

Description

Returns the hexadecimal (or other base number system) text corresponding to the given value and encoding, which can be a number a quoted string or a blob. If the value is a number, IEEE 754 64-bit encoding is used unless one of the optional arguments, integer, or Base, is provided.

Required Argument

value

Any number, quoted string, or blob.

Optional Arguments

integer

A quoted switch that causes the value to be interpreted as an integer.

encoding

A quoted string that specifies an encoding. The default encoding is "utf-8". "utf-16le", "utf-16be", "us-ascii", "iso-8859-1", "ascii~hex", "shift-jis", and "euc-jp" are also supported.

Base(number)

An integer value between 2 and 36 inclusive. If base is specified, the function returns the text corresponding to the specified number in that base number system instead of hexadecimal.

Pad To(number)

A value to specify the padded width of the hex output.

See Also

Hexadecimal and BLOB Functions in the Scripting Guide

Collapse Whitespace(text)

Description

Trims leading and trailing whitespace and replaces interior whitespace with a single space. That is, if more than one white space character is present, the Collapse Whitespace function replaces the two spaces with one space.

Returns

A quoted string.

Required Argument

text

A quoted string.

Concat(a, b)

Concat(A, B)

a||b

A||B

Description

For quoted strings: Appends the string b to the string a. Neither argument is changed.

For lists: Appends the list b to the list a. Neither argument is changed.

For matrices: Horizontal concatenation of two matrices, A and B.

Returns

For quoted strings: A quoted string composed of the string a directly followed by the string b.

For lists: A list composed of the list a directly followed by the list b.

For matrices: A matrix.

Arguments

Two or more quoted strings, quoted string variables, lists, or matrices.

Example

a = "Hello"; b = " "; c = "World"; a || b || c;

"Hello World"

d = {"apples", "bananas"}; e = {"peaches", "pears"}; Concat( d, e );

{"apples", "bananas", "peaches", "pears"}

A = [1 2 3]; B = [4 5 6]; Concat( A, B );

[1 2 3 4 5 6]

Notes

More than two arguments can be strung together. Each additional quoted string is appended to the end, in left to right order. Each additional matrix is appended in left to right order.

See Also

Hexadecimal and BLOB Functions in the Scripting Guide

Concat Items

See Concat Items({string1, string2, ...}, <delimiter>}).

Concat To(a, b)

Concat To(a, b)

a||=b

A||=B

Description

For quoted strings: Appends the string b to the string a and places the new concatenated string into a.

For matrices: Appends the matrix b to the matrix a and places the new concatenated matrix into a.

For lists: Appends the list b to the list and places the new concatenated list into a.

Returns

For quoted strings: A string composed of the string a directly followed by the string b.

For matrices: A matrix.

For lists: A list composed of the list a directly followed by the list b.

Arguments

Two or more quoted strings, quoted string variables, matrices, or lists. The first variable must be a variable whose value can be changed.

Notes

More than two arguments can be strung together. Each additional quoted string, matrix, or list is appended to the end, in left to right order.

Example

a = "Hello"; b = " "; c = "World"; Concat To( a, b, c ); Show( a );

a = "Hello World"

A = [1 2 3]; B = [4 5 6]; Concat To( A, B ); Show( A );

A = [1 2 3 4 5 6];

d = {"apples", "bananas"}; e = {"peaches", "pears"}; Concat to(d,e); Show( d );

d = {"apples", "bananas", "peaches", "pears"};

See Also

Concatenate Lists in the Scripting Guide

Contains(whole, part, <start>)

Description

Determines whether part is contained within whole.

Returns

If part is found: For lists, quoted strings, and namespaces, the numeric position where the first occurrence of part is located. For associative arrays, 1.

If part is not found, 0 is returned in all cases.

Required Arguments

whole

A quoted string, list, namespace, or associative array.

part

For a quoted string or namespace, a string that can be part of the string whole. For a list, an item that can be an item in the list whole. For an associative array, a key that can be one of the keys in the map whole.

Optional Argument

start

A numeric argument that specifies a starting point within whole. If start is negative, contains searches whole for part backwards, beginning with the position specified by the length of wholestart. Note that start is meaningless for associative arrays and is ignored.

Example

nameList={"Katie", "Louise", "Jane", "Jaclyn"};
r = Contains(nameList, "Katie");

The example returns a 1 because “Katie” is the first item in the list.

See Also

Locate Items in a List in the Scripting Guide

Find Keys or Values in an Associative Array in the Scripting Guide

Contains Item(x, <item | {list} | pattern>, <delimiter>)

Description

Identifies multiple responses by searching for the specified item, list, pattern, or delimiter. The function can be used on columns with the Multiple Response modeling type or column property.

Returns

Returns a Boolean that indicates whether the word (item), one of a list of words (list), or pattern (pattern) matches one of the words in the text represented by x. Words are delimited by the characters in the optional quoted delimiter (delimiter) string. A comma is the default delimiter. Blanks are trimmed from the ends of each extracted word from the input text string (x).

Example

The following example searches for “pots” followed by a comma and then outputs the result.

x = "Franklin Garden Supply is a leading online store featuring garden decor, statues, pots, shovels, benches, and much more.";
b = Contains Item( x, "pots", "," );
If( b,
	Write( "The specified items were found."  ), Write( "No match." )
);

The specified items were found.

Ends With(string, substring)

Description

Determines whether the quoted substring appears at the end of string.

Returns

1 if quoted string ends with a quoted substring, otherwise 0.

Required Arguments

string

A quoted string or a quoted string variable. Can also be a list.

substring

A quoted string or a quoted string variable. Can also be a list.

Equivalent Expression

Right(string, Length(substring)) == substring

Hex(value, <integer|encoding="enc"|Base(number)|Pad To(number)>)

See Char To Hex(value, <integer|encoding="enc">).

Hex To BLOB(string)

Description

Converts the quoted hexadecimal string (including whitespace characters) to a blob (binary large object).

Example

Hex To BLOB( "4A4D50" );

Char To BLOB("JMP", "ascii~hex")

See Also

Hexadecimal and BLOB Functions in the Scripting Guide

Hex To Char(string, <encoding>)

Description

Converts the quoted hexadecimal string to its character equivalent.

Example

Hex To Char( "30" ) results in “0”.

Notes

The default quoted encoding for character string is "utf-8". "utf-16le", "utf-16be", "us-ascii", "iso-8859-1", "ascii~hex", "shift-jis", and "euc-jp" are also supported.

See Also

Hexadecimal and BLOB Functions in the Scripting Guide

Hex To Number(string, <Base(number)>)

Description

Returns the number corresponding to the hexadecimal (or other base number system) text.

Required Argument

string

A quoted hexadecimal string.

Optional Argument

Base(number)

An integer between 2 and 36 inclusive. If base is specified, the text is treated as a quoted string representing the number in that base.

Example

Hex To Number( "80" );

128

Notes

16-digit hexadecimal numbers are converted as IEEE 754 64-bit floating point numbers. Otherwise, the input is treated as a hexadecimal integer.

Whitespace between bytes (or pairs of digits) and in the middle of bytes is permitted (for example, FF 1919 and F F1919).

Insert

See Insert(source, item, <position>).

Insert Into

See Insert Into(source, item, <position>).

Item(n|[first last], string, <delimiter>, <Unmatched(result string)>, <Include Boundary Delimiters(Boolean)>)

Description

Returns the nth item or the span from the first to last item of the quoted string according to the quoted string delimiters given. If you include a third argument, any and all characters in that argument are taken to be delimiters.

Required Arguments

n

The position of the word being extracted.

[first last]

A matrix that defines the beginning and end word range to return.

string

The quoted string that is evaluated.

Optional Arguments

delimiter

The character used as a boundary. If delimiter is absent, an ASCII space is used. If delimiter is the quoted empty string, each character is treated as a separate word.

Unmatched(result string)

The quoted string to print if no match is found.

Include Boundary Delimiters(Boolean)

Determines how delimiters on the front and back of string are treated. The default value is false, which means that the delimiters on these boundaries are ignored. If the value is true, delimiters on these boundaries produce an empty element (similar to consecutive delimiters within a string).

Example

Consecutive delimiters are treated as though they have a word between them. In this example, the delimiters are a comma and a space.

Item( 4,"the  quick, brown fox", ", " ); // quick is preceded by two spaces

The expression is processed as follows:

the<delim[space]><word2><delim[space]>quick<delim[comma]><word 4><delim[space]>brown<delim[space]>fox

Because word4 is empty, this expression returns a quoted empty string.

Item() is the same as Word() except that Item() treats each delimiter character as a separate delimiter, and Word() treats several adjacent delimiters as a single delimiter.

Word( 4,"the  quick, brown fox", ", " ); // quick is preceded by two spaces

This expression is processed as follows:

the<delim[2 spaces]>quick<delim[comma + space]>brown<delim[space]>fox

It returns "fox".

Left(string, n, <filler>)

Left({list}, n, <filler>)

Description

Returns a truncated or padded version of the original quoted string or list. The result contains the left n characters or list items, padded with any filler on the right if the length of string is less than n.

Length(string)

Description

Returns the length of the given quoted string (in characters), list (in items), associative array (in number of keys), BLOB (in bytes), matrix (in elements), namespace (in number of functions and variables), or class (in number of methods, functions, and variables).

See Also

Hexadecimal and BLOB Functions in the Scripting Guide

Lowercase(string)

Description

Converts any uppercase character found in quoted string to the equivalent lowercase character.

Matrix to BLOB(matrix, type, bytesEach, endian(value))

Description

Makes a BLOB from a matrix by converting the matrix elements to 1-byte, 2-byte, or 4-byte signed or unsigned integers or 4-byte or 8-byte floating point numbers.

Required Arguments

matrix

The matrix.

type

The quoted type of BLOB: int, uint, or float.

bytesEach

The number of bytes in each int, uint, or float. Integers can be 1, 2, or 4 bytes each, and floats can be 4 or 8 bytes each.

endian(value)

The quoted endian-ness of your system: "Big" (the first byte is most significant), "Little" (the first byte is the least significant), or "Native" (the machine’s native format).

Munger(string, start position, find|length, <replacement string>)

Description

Computes new quoted character strings from the quoted string by inserting or deleting characters. It can also produce substrings, calculate indexes, and perform other tasks depending on how you specify its arguments.

Required Arguments

start position

A numeric expression that specifies the starting position to search in the quoted string. If the start position is greater than the position of the first instance of the find argument, the first instance is disregarded. If the start position is greater than the search string’s length, Munger() uses the string’s length as the start position.

find|length

Specifies the string or number of characters to find.

Optional Argument

replacement string

The quoted replacement string. If replacement string is omitted, a substring between start position, and position and length, is returned.

See Also

Munger Function in the Scripting Guide

Num(string)

Description

Converts a quoted character string into a number.

See Also

Numbers and Strings in the Scripting Guide

Regex(source, pattern, (<replacement string>, <format, "GLOBALREPLACE", "IGNORECASE">>)

Description

Searches for the quoted pattern within the quoted source string.

Returns

The matched text as a quoted string or numeric missing if there was no match.

Required Arguments

source

A quoted string.

pattern

A quoted regular expression.

replacement string

The replacement string.

Optional Arguments

format

A backreference to the capturing group. The default is \0, which is the entire matched quoted string. \n returns the nth match.

"IGNORECASE"

The search is case sensitive, unless you specify "IGNORECASE".

"GLOBALREPLACE"

Applies the regular expression to the quoted source string repeatedly until all matches are found.

See Also

Regular Expressions in the Scripting Guide

Remove

See Remove(source, position, <n>).

Remove From

See Remove From(source, position, <n>).

Repeat(source, a)

Repeat(matrix, a, b)

Description

Returns a copy of source concatenated with itself a times. Or returns a matrix composed of a row repeats and b column repeats. The source can be text, a matrix, or a list.

See Also

Repeat Function in the Scripting Guide

Reverse

See Reverse(source).

Reverse Into

See Reverse Into(source).

Right(string, n, <filler>)

Right({list}, n, <filler>)

Description

Returns a truncated or padded version of the original quoted string or list. The result contains the right n characters or list items, padded with any optional filler on the left if the length of string is less than n.

Shift

See Shift(source, <n>).

Shift Into

See Shift Into(source, <n>).

Starts With(string, substring)

Description

Determines whether the quoted substring appears at the start of the quoted string.

Returns

1 if string starts with substring, otherwise 0.

Arguments

string

A quoted string or a reference to one. Can also be a list.

substring

A quoted string or a reference to one. Can also be a list.

Equivalent Expression

Left(string, Length("substring")) = = "substring"

Substitute

See Substitute(string, "substring", "replacementString", ...).

Substitute Into

See Substitute Into(string, substring, replacementString, ...).

Substr(string, start, length)

Description

Extracts the characters that are the portion of the first argument beginning at the position given by the second argument and ending based on the number of characters specified in the third argument. The first argument can be a character column or value, or an expression evaluating to same. The starting argument and the length argument can be numbers or expressions that evaluate to numbers.

Example

This example extracts the first name:

Substr( "Katie Layman", 1, 5 );

The function starts at position 1, reads through position 5, and ignores the remaining characters, which yields “Katie.”

See Also

Numbers and Strings in the Scripting Guide

Text Score(text column, text-to-number, <weighting>, <{support vectors}>, <text explorer setup>)

Description

Used to create scoring formulas in Text Explorer. Not supported for use with the Stem for Combining option.

Returns

Returns a vector of scores.

Required Arguments

text column

The data table column.

text-to-number

An associative array that maps lowercase words to numbers.

Optional Arguments

weighting

The quoted "Count", "Binary", "Ternary", "LogCount", "LCA", or an array of inverse document frequency weights for TFLogIDF. "Count" is the default value. The default value is "Count".

support vectors

A list of vectors that are used in the text scoring. The number and length of the vectors depends on the weighting argument.

text explorer setup

An expression that contains a block of Text Explorer setup information.

Titlecase(string)

Description

Converts the quoted string to title case; each word in the string has an initial uppercase character and subsequent lowercase characters.

Returns

A quoted string.

Argument

string

A quoted string.

Example

The following function capitalizes the name:

Titlecase( "veronica layman ")

"Veronica Layman"

Trim(string,<"Left"|"Right"|"Both">)

Trim Whitespace(string,<"Left"|"Right"|"Both">)

Description

Removes leading and trailing whitespace from the specified string.

Returns

A quoted string.

Required Argument

string

A quoted string.

Optional Argument

"Left"|"Right"|"Both"

A quoted string that specifies whether whitespace is removed from the left, the right, or both ends of the string. If omitted, whitespace is removed from both ends.

Example

For example, the following command returns "John":

Trim( "  John    ", Both )

"John"

Uppercase(string)

Description

Converts any lowercase character found in the quoted string to the equivalent uppercase character.

Word(n|[first last], string, <delimiter>, <Unmatched(result string)>)

Description

Returns the nth item of the string, where words are substrings separated by any number of any characters in the delimiter argument.

Required Arguments

n

The position of the word being extracted.

[first last]

A matrix that defines the beginning and end word range to return.

string

The quoted string that is evaluated.

Optional Arguments

delimiter

The character used as a boundary. If delimiter is absent, an ASCII space is used. If delimiter is the empty quoted string, each character is treated as a separate word.

Unmatched(result string)

The quoted string to print if no match is found.

Examples

This example returns the last name:

Word( 2, "Katie Layman" );

"Layman"

See Also

See Item(n|[first last], string, <delimiter>, <Unmatched(result string)>, <Include Boundary Delimiters(Boolean)>) for examples of how Word() differs from Item().

Words

See Words(string, <delimiter>).

XPath Query(xml, xpath_expression)

Description

Runs an XPath expression on an XML document.

Returns

A list.

Required Arguments

xml

A valid XML document.

xpath_expression

A quoted XPath 1.0 expression.

Example

Suppose that you created a report of test results in JMP and exported important details to an XML document. The test results are enclosed in <result> tags.

The following example stores the XML document in a variable. The XPath Query expression parses the XML to find the text nodes inside the <result> tags. The results are returned in a list.

rpt =
"\[<?xml version="1.0" encoding="utf-8"?>
<JMP><report><title>Production Report</title>
<result>November 21st: Pass</result>
<result>November 22nd: Fail</result>
<note>Tests ran at 3:00 a.m.</note></report>
</JMP> ]\";
results = XPath Query( rpt, "//result/text()" );

{"November 21st: Pass", "November 22nd: Fail"}

Want more information? Have questions? Get answers in the JMP User Community (community.jmp.com).