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.
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?
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. |
||
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.
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.
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>
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.
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>
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/>
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.)
W3C substring function description.