SHIP:Sail:subStr

Function	Returns	Introduced	Description
subStr	String	v2.0	Returns the N-character substring of a string starting at an index.

See Also:

• Sail Home
• Sail Functions
• Sail String Functions
• bytesToString, charAt, codepointAt, indexOf, subString, toString

Prototype

String subStr(String s, Integer start);

String subStr(String s, Integer start, Integer size);

Parameters/Return Value

Parameter	Data Type	Description
s	String	Original string
start	Integer	Starting index (0 is the first character in a string)
size	Integer	Number of UTF8 characters to get
Return	String	the substring requested

Detailed Description

The subStr function is aligned with its JavaScript subStr cousin, and returns the number of characters specified (the size) from within in a string, starting at a specified start offset.

A negative start offset is treated as offset zero; the negative form for "from the end of the string" is not universally true in JavaScript.

If the size is negative or unspecified, all characters in the original string from the start index onwards will be returned.

subStr 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 specified is beyond the end of the original string
• the length parameter is zero

Examples

Example	Result	Notes
subStr("hello", 1);	"ello"	unspecified length means return the rest of the string
subStr("hello", 0, 1);	"h"
subStr("hello", 1, -1);	"ello"	-1 for length returns the rest of the string
subStr("hello", 10, 2);	""	index is beyond the length of the original string
subStr("hello", -1, 2);	"he"	index negative is the same as index 0
subStr("hello", 3, 0);	""	zero length always returns an empty string