SHIP:Sail:subString

From Serious Documentation
Revision as of 23:11, 10 October 2016 by CarltonHeyer (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search
Function Returns Introduced Description
subString String v2.0 Returns the substring of a string starting at an index and (optionally) ending before an index.

See Also:

Prototype

String subString(String s, Integer start);

String subString(String s, Integer start, Integer end);

Parameters/Return Value

Parameter Data Type Description
s String Original string
start Integer Starting index (0 is the first character in a string)
end Integer Ending index (exclusive)
Return String the substring requested

Detailed Description

The subString function is aligned with its JavaScript subString cousin, and returns a number characters from within in a string, starting at a specified start offset and ending at a specified end offset, not including the ending character. The total number of characters is no more than (end - start).

If either argument specified is negative, 0 is substituted. Then, if the end specified is less than the start, the arguments are swapped.

subString works on UTF8 strings, and each character may be a multibyte UTF8 sequence.

The resulting string will be empty (zero length) if any of the following conditions are true:

  • the original string has no length
  • the start index is equal to the end index

If the second argument is unspecified, all characters in the original string from the start index onwards will be returned; this form is identical in operation to subStr(start);.

Examples

Example Result Notes
subString("hello", 1); "ello" unspecified length means return the rest of the string
subString("hello", 0, 1); "h"
subString("hello", 0, 0); ""
subString("hello", -1, 1); "h" start index negative is the same as start index 0
subString("hello", 3, -1); "hel" end index -1 is changed to 0, then the two arguments are swapped since the first is larger than the second. The result is subString("hello", 0, 3);