Difference between revisions of "SHIP:Sail:subString"

From Serious Documentation
Jump to: navigation, search
(→‎Examples)
 
(8 intermediate revisions by 2 users not shown)
Line 31: Line 31:
  
 
== Detailed Description ==
 
== Detailed Description ==
−
The {{SailFunc|subString}} function is aligned with its [http://www.w3schools.com/jsref/jsref_substring.asp JavaScript subString cousin], and returns a number characters from within in a string, starting at a specified offset and ending at a specified offset, not including the ending character.  The total number of characters is no more than (end - begin).
+
The {{SailFunc|subString}} function is aligned with its [http://www.w3schools.com/jsref/jsref_substring.asp 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'').
  
−
{{SailFunc|subString}}works on UTF8 strings, and each character may be a multibyte UTF8 sequence.
+
If either argument specified is negative, 0 is substituted. Then, if the ''end'' specified is less than the ''start'', the arguments are swapped.
  
−
If the end is specified less than the start, the arguments are swapped.
+
{{SailFunc|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 resulting string will be empty (zero length) if any of the following conditions are true:
 
* the original string has no length
 
* the original string has no length
−
* the start index is equal to the end index
+
* the ''start'' index is equal to the ''end'' index
  
−
If the end index is unspecified, all characters in the original string from the start index onwards will be returned; this form is identical in operation to {{SailFunc|subStr}}<code>(start);</code>.
+
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 {{SailFunc|subStr}}<code>(start);</code>.
  
 
== Examples ==
 
== Examples ==
 
{| class="wikitable" style="margin: 1em 1em;"  
 
{| class="wikitable" style="margin: 1em 1em;"  
−
! scope="col" style="text-align:left" | Example
+
! scope="col" style="text-align:left" width="30%" | Example
 
! scope="col" style="text-align:left" | Result
 
! scope="col" style="text-align:left" | Result
 
! scope="col" style="text-align:left" | Notes
 
! scope="col" style="text-align:left" | Notes
Line 59: Line 59:
 
|<code>subString("hello", 3, -1);</code> || "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 <code>subString("hello", 0, 3);</code>
 
|<code>subString("hello", 3, -1);</code> || "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 <code>subString("hello", 0, 3);</code>
 
|}
 
|}
 +
 +
[[Category:String Functions]]

Latest revision as of 16:11, 10 October 2016

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);
Retrieved from "https://techref.myserious.com/index.php?title=SHIP:Sail:subString&oldid=6003"