Difference between revisions of "SHIP:Sail:subStr"

From Serious Documentation
Jump to: navigation, search
(Created page with "__NOTOC__ SHIP Sail Home SHIP Sail Function Home == subStr == Returns the N-character substring of a string starting at an index == Pro...")
 
 
(20 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
__NOTOC__
 
__NOTOC__
−
[[SHIP:Sail|SHIP Sail Home]]
+
{{SailFuncTableStart|}}<onlyinclude>
−
 
+
|{{SailFunc|subStr}}||{{DataType|String}}||style="text-align:center;"|v2.0||Returns the N-character substring of a string starting at an index.</onlyinclude>
−
[[SHIP:Sail:Functions|SHIP Sail Function Home]]
+
|}
−
== subStr ==
+
== See Also: ==
−
Returns the N-character substring of a string starting at an index
+
*[[SHIP:Sail|Sail Home]]
 +
*[[SHIP:Sail:Functions|Sail Functions]]
 +
*[[SHIP:Sail:String Functions|Sail String Functions]]
 +
*{{SailFunc|bytesToString}}, {{SailFunc|charAt}}, {{SailFunc|codepointAt}}, {{SailFunc|indexOf}}, {{SailFunc|subString}}, {{SailFunc|toString}}
  
 
== Prototype ==
 
== Prototype ==
 +
<code>{{DataType|String}} {{SailFunc|subStr}}({{DataType|String}} s, {{DataType|Integer}} start);</code>
  
−
<code>{{DataType|String}} subStr({{DataType|String}} s, {{DataType|Integer}} index);</code>
+
<code>{{DataType|String}} {{SailFunc|subStr}}({{DataType|String}} s, {{DataType|Integer}} start, {{DataType|Integer}} size);</code>
−
 
 
−
<code>{{DataType|String}} subStr({{DataType|String}} s, {{DataType|Integer}} index, {{DataType|Integer}} length);</code>
 
  
 
=== Parameters/Return Value ===
 
=== Parameters/Return Value ===
Line 20: Line 22:
 
|s||{{DataType|String}}||Original string
 
|s||{{DataType|String}}||Original string
 
|-
 
|-
−
|index||{{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)
 
|-
 
|-
−
|length||{{DataType|Integer}}||number of characters to get
+
|size||{{DataType|Integer}}||Number of UTF8 characters to get
 
|-
 
|-
 
! scope="col" style="text-align:left" | Return
 
! scope="col" style="text-align:left" | Return
Line 30: Line 32:
  
 
== Detailed Description ==
 
== Detailed Description ==
−
The <code>subStr ()</code> function returns a number characters from within in a string, starting at a specified offset.
+
The {{SailFunc|subStr}} function is aligned with its [http://www.w3schools.com/jsref/jsref_substr.asp 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.
 +
 
 +
{{SailFunc|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 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 index specified is beyond the end of the original string
+
* the ''start'' index specified is beyond the end of the original string
 
* the length parameter is zero
 
* the length parameter is zero
−
 
−
If the index is negative, an offset of 0 will be used.
 
−
 
−
If the length is negative or unspecified, all characters in the original string from the index onwards will be returned.
 
  
 
== Examples ==
 
== Examples ==
Line 47: Line 51:
 
! scope="col" style="text-align:left" | Notes
 
! scope="col" style="text-align:left" | Notes
 
|-
 
|-
−
|<code>subStr ("hello", 1);</code> || "ello" || unspecified length means return the rest of the string
+
|<code>subStr("hello", 1);</code> || "ello" || unspecified length means return the rest of the string
 
|-
 
|-
−
|<code>subStr ("hello", 0, 1);</code> || "h" ||
+
|<code>subStr("hello", 0, 1);</code> || "h" ||
 
|-
 
|-
−
|<code>subStr ("hello", 1, -1);</code> || "ello" || -1 for length returns the rest of the string
+
|<code>subStr("hello", 1, -1);</code> || "ello" || -1 for length returns the rest of the string
 
|-
 
|-
−
|<code>subStr ("hello", 10, 2);</code> || "" || index is beyond the length of the original string
+
|<code>subStr("hello", 10, 2);</code> || "" || index is beyond the length of the original string
 
|-
 
|-
−
|<code>subStr ("hello", -1, 2);</code> || "he" || index negative is the same as index 0
+
|<code>subStr("hello", -1, 2);</code> || "he" || index negative is the same as index 0
 
|-
 
|-
−
|<code>subStr ("hello", 3, 0);</code> || "" || zero length always returns an empty string
+
|<code>subStr("hello", 3, 0);</code> || "" || zero length always returns an empty string
−
|-
 
−
|<code>length("");</code> || 0 ||
 
−
|-
 
−
|<code>length("&trade;");|| 1 || &trade; is three bytes in [[UTF-8]] but is only one character
 
 
|}
 
|}
 +
 +
[[Category:String Functions]]

Latest revision as of 16:10, 10 October 2016

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

See Also:

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