Difference between revisions of "SHIP:Sail:subString"

From Serious Documentation
Jump to: navigation, search
(Created page with "__NOTOC__ SHIP Sail Home SHIP Sail Function Home == subString== Returns the substring of a string starting at an index and ending at an ...")
 
 
(26 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
__NOTOC__
 
__NOTOC__
−
[[SHIP:Sail|SHIP Sail Home]]
+
{{SailFuncTableStart|}}<onlyinclude>
−
 
+
|{{SailFunc|subString}}||{{DataType|String}}||style="text-align:center;"|v2.0||Returns the substring of a string starting at an index and (optionally) ending before an index.</onlyinclude>
−
[[SHIP:Sail:Functions|SHIP Sail Function Home]]
+
|}
−
== subString==
+
== See Also: ==
−
Returns the substring of a string starting at an index and ending at an index
+
*[[SHIP:Sail|Sail Home]]
−
 
+
*[[SHIP:Sail:Functions|Sail Functions]]
 +
*[[SHIP:Sail:String Functions|Sail String Functions]]
 +
*{{SailFunc|charAt}}, {{SailFunc|codepointAt}}, {{SailFunc|indexOf}}, {{SailFunc|subStr}}, {{SailFunc|toString}}
 
== Prototype ==
 
== Prototype ==
 +
<code>{{DataType|String}} {{SailFunc|subString}}({{DataType|String}} s, {{DataType|Integer}} start);</code>
  
−
<code>{{DataType|String}} subString({{DataType|String}} s, {{DataType|Integer}} start);</code>
+
<code>{{DataType|String}} {{SailFunc|subString}}({{DataType|String}} s, {{DataType|Integer}} start, {{DataType|Integer}} end);</code>
−
 
 
−
<code>{{DataType|String}} subString({{DataType|String}} s, {{DataType|Integer}} start, {{DataType|Integer}} end);</code>
 
  
 
=== Parameters/Return Value ===
 
=== Parameters/Return Value ===
Line 22: Line 23:
 
|start||{{DataType|Integer}}||Starting index (0 is the first character in a string)
 
|start||{{DataType|Integer}}||Starting index (0 is the first character in a string)
 
|-
 
|-
−
|end||{{DataType|Integer}}||Ending index (inclusive)
+
|end||{{DataType|Integer}}||Ending index (exclusive)
 
|-
 
|-
 
! scope="col" style="text-align:left" | Return
 
! scope="col" style="text-align:left" | Return
Line 30: Line 31:
  
 
== Detailed Description ==
 
== Detailed Description ==
−
The <code>subString()</code> function returns a number characters from within in a string, starting at a specified offset and ending at a specified offset.
+
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'').
 +
 
 +
If either argument specified is negative, 0 is substituted. Then, if the ''end'' specified is less than the ''start'', the arguments are swapped.
  
−
Both the character at the starting and ending offset will be included in the result.
+
{{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 specified is beyond the end of the original string
+
* the ''start'' index is equal to the ''end'' index
−
* the end index is less than the start index
 
−
 
 
−
If the start index is negative, an offset of 0 will be used.
 
  
−
If the end index is unspecified, all characters in the original string from the start index onwards will be returned.
+
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 51: Line 51:
 
|<code>subString("hello", 1);</code> || "ello" || unspecified length means return the rest of the string
 
|<code>subString("hello", 1);</code> || "ello" || unspecified length means return the rest of the string
 
|-
 
|-
−
|<code>subString("hello", 0, 1);</code> || "he" ||
+
|<code>subString("hello", 0, 1);</code> || "h" ||
−
|-
 
−
|<code>subString("hello", 0, 0);</code> || "h" ||
 
 
|-
 
|-
−
|<code>subString("hello", 1, -1);</code> || "" || end index is less than start index
+
|<code>subString("hello", 0, 0);</code> || "" ||
 
|-
 
|-
−
|<code>subString("hello", 10, 2);</code> || "" || start index is beyond the length of the original string
+
|<code>subString("hello", -1, 1);</code> || "h" || start index negative is the same as start index 0
 
|-
 
|-
−
|<code>subString("hello", -1, 1);</code> || "he" || start index negative is the same as start index 0
+
|<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"