# 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.