xf:substring

Get a substring of $string-var at a particular index location.

If a positive integer is not passed into $decimal-var or $optional-decimal-var, the TransformException exception is raised with the RT_ILLEGAL_INDEX fault code. In the mapper the following error message is displayed:

Error occurred while executing XQuery: Index "-1" out of bounds (0, 5) 

If the integer passed into $decimal-var is greater then the length of the $string-var, the TransformException exception is raised with the RT_ILLEGAL_INDEX fault code. In the mapper the following error message is displayed:

Error occurred while executing XQuery: Index "6" out of bounds (0, 5) 

Where X is the out of bounds index, Y is the starting index, and Z is the ending index, for example Index "6" out of bounds (0, 5).

To learn more about using fault codes, see Getting the TransformException Fault Code Programmatically.

Signatures

xf:substring(xs:string? $string-var, xs:decimal? $decimal-var) —> xs:string?

xf:substring(xs:string? $string-var, xs:decimal? $decimal-var, xs:decimal? $decimal-var) —> xs:string?

Arguments

Data Type
Argument
Description

xs:string?

$string-var

Represents the source string.

xs:decimal?

$decimal-var

Represents the starting location to start extracting the substring to return.

Note: Use 1 to specify the first character of the string and not 0.

xs:decimal?

$optional-decimal-var

Optional—Represents the length of the extracted substring.

Returns

substring($string-var, $decimal-var)

Returns the part of the $string-var source string from the starting location specified by $decimal-var.

If the value of any of the two arguments is an empty sequence, the empty sequence is returned. The empty sequence is a sequence containing zero items (), which is similar to null in SQL.

substring($string-var, $decimal-var, $optional-decimal-var)

Returns the part of the $string-var source string from the starting location specified by $decimal-var and continuing for the number of characters specified by $optional-decimal-var.

If the value of any of the three arguments is an empty sequence, the empty sequence is returned. The empty sequence is a sequence containing zero items (), which is similar to null in SQL.

Examples

Specify Just the Starting Position

Invoking substring("supercalifragilistic", 15) returns the string: listic, as shown in the following example query:

<result>{xf:substring("supercalifragilistic", 15)}</result> 

The preceding query generates the following result:

<result>listic</result> 

Specify the Starting Position and Length

Invoking substring("supercalifragilistic", 1, 5) returns the string: super, as shown in the following example query:

<result>{xf:substring("supercalifragilistic", 1, 5)}</result> 

The preceding query generates the following result:

<result>super</result> 

Note: To specify the first character in a string, use 1 and not 0.

From the Middle of the String

Invoking substring("supercalifragilistic", 6, 4) returns the string: cali, as shown in the following example query:

<result>{xf:substring("supercalifragilistic", 6, 4)}</result> 

The preceding query generates the following result:

<result>cali</result> 

Pass in Null

Invoking substring((), 1) returns the null string as shown in the following example query:

<result>{xf:substring((), 1)}</result> 

Note: The string: () is the empty sequence (similar to a SQL null) which is a sequence containing zero items.

The preceding query generates the following result:

<result/> 

Error—Out of Bounds

Invoking substring("super", 6) outputs an error because the index specified (6) is longer than the string: super.

For example, the following example query:

<result>{xf:substring("super", 6)}</result> 
Produces the following error: 
Error occurred while executing XQuery: Index "6" out of bounds (0, 5) 

Note: Indexing starts with the number 1 and not 0, so the index 6 is beyond the last character in the string: super. (The character r in the string: super is at index 5.)

Related Topics

W3C substring function description.