Mercurial > hg > nginx-site

comparison xml/en/docs/njs/njs_api.xml @ 2186:8e2b3aadc3ce

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added njs String object.
author Yaroslav Zhuravlev <yar@nginx.com>
date Tue, 19 Jun 2018 15:43:46 +0300
parents 97526b8346f4
children 23cfb62121d1
comparison
equal deleted inserted replaced
2185:e90725c6ac6e 2186:8e2b3aadc3ce
20 20
21 </section> 21 </section>
22 22
23 23
24 <section id="core" name="Core"> 24 <section id="core" name="Core">
25
26
27 <section id="string" name="String">
28
29 <para>
30 There are two types of strings:
31 a <literal>Unicode string</literal> (default) and
32 a <literal>byte string</literal>.
33 </para>
34
35 <para>
36 A <literal>Unicode string</literal> corresponds to an ECMAScript string
37 which contains Unicode characters.
38 </para>
39
40 <para>
41 <literal>Byte strings</literal> contain a sequence of bytes.
42 They are used to serialize Unicode strings
43 to external data and deserialize from external sources.
44 For example, the <link id="string_toutf8">toUTF8()</link> method serializes
45 a Unicode string to a byte string using UTF8 encoding:
46 <example>
47 >> '£'.toUTF8().toString('hex')
48 c2a3 /* C2 A3 is the UTF8 representation of 00A3 ('£') code point */
49 </example>
50 The <link id="string_tobytes">toBytes()</link> method serializes
51 a Unicode string with code points up to 255 into a byte string,
52 otherwise, <literal>null</literal> is returned:
53 <example>
54 >> '£'.toBytes().toString('hex')
55 a3 /* a3 is a byte equal to 00A3 ('£') code point */
56 </example>
57 Only byte strings can be converted to different encodings.
58 For example, a string cannot be encoded to <literal>hex</literal> directly:
59 <example>
60 >> 'αβγδ'.toString('base64')
61 TypeError: argument must be a byte string
62 at String.prototype.toString (native)
63 at main (native)
64 </example>
65 To convert a Unicode string to hex,
66 first, it should be converted to a byte string and then to hex:
67 <example>
68 >> 'αβγδ'.toUTF8().toString('base64')
69 zrHOss6zzrQ=
70 </example>
71
72 <list type="tag">
73
74 <tag-name><literal>String.fromCodePoint(<value>codePoint1</value>[, ...[,
75 <value>codePoint2</value>]])</literal></tag-name>
76 <tag-desc>
77 Returns a string from one or more Unicode code points.
78 <example>
79 >> String.fromCodePoint(97, 98, 99, 100)
80 abcd
81 </example>
82 </tag-desc>
83
84 <tag-name><literal>String.prototype.concat(<value>string1</value>[, ...,
85 <value>stringN</value>])</literal></tag-name>
86 <tag-desc>
87 Returns a string that contains the concatenation of specified
88 <literal>strings</literal>.
89 <example>
90 >> "a".concat("b", "c")
91 abc
92 </example>
93 </tag-desc>
94
95 <tag-name><literal>String.prototype.endsWith(<value>searchString</value>[,
96 <value>length</value>])</literal></tag-name>
97 <tag-desc>
98 Returns <literal>true</literal> if a string ends with the characters
99 of a specified string, otherwise <literal>false</literal>.
100 The optional <literal>length</literal> parameter is the the length of string.
101 If omitted, the default value is the length of the string.
102 <example>
103 >> 'abc'.endsWith('abc')
104 true
105 >> 'abca'.endsWith('abc')
106 false
107 </example>
108 </tag-desc>
109
110 <tag-name><literal>String.prototype.fromBytes(<value>start</value>[,
111 <value>end</value>])</literal></tag-name>
112 <tag-desc>
113 (njs specific) Returns a new Unicode string from a byte string
114 where each byte is replaced with a corresponding Unicode code point.
115 </tag-desc>
116
117 <tag-name><literal>String.prototype.fromUTF8(<value>start</value>[,
118 <value>end</value>])</literal></tag-name>
119 <tag-desc>
120 (njs specific) Converts a byte string containing a valid UTF8 string
121 into a Unicode string,
122 otherwise <literal>null</literal> is returned.
123 </tag-desc>
124
125 <tag-name><literal>String.prototype.includes(<value>searchString</value>[,
126 <value>position</value>]))</literal></tag-name>
127 <tag-desc>
128 Returns <literal>true</literal> if a string is found within another string,
129 otherwise <literal>false</literal>.
130 The optional <literal>position</literal> parameter is the position
131 within the string at which to begin search for <literal>searchString</literal>.
132 Default value is 0.
133 <example>
134 >> 'abc'.includes('bc')
135 true
136 </example>
137 </tag-desc>
138
139 <tag-name><literal>String.prototype.indexOf(<value>searchString</value>[,
140 <value>fromIndex</value>])</literal></tag-name>
141 <tag-desc>
142 Returns the position of the first occurrence
143 of the <literal>searchString</literal>
144 The search is started at <literal>fromIndex</literal>.
145 Returns <value>-1</value> if the value is not found.
146 The <literal>fromIndex</literal> is an integer,
147 default value is 0.
148 If <literal>fromIndex</literal> is lower than 0
149 or greater than
150 <link id="string_length">String.prototype.length</link><value></value>,
151 the search starts at index <value>0</value> and
152 <value>String.prototype.length</value>.
153 <example>
154 >> 'abcdef'.indexOf('de', 2)
155 3
156 </example>
157 </tag-desc>
158
159 <tag-name><literal>String.prototype.lastIndexOf(<value>searchString</value>[,
160 <value>fromIndex</value>])</literal></tag-name>
161 <tag-desc>
162 Returns the position of the last occurrence
163 of the <literal>searchString</literal>,
164 searching backwards from <literal>fromIndex</literal>.
165 Returns <value>-1</value> if the value is not found.
166 If <literal>searchString</literal> is empty,
167 then <literal>fromIndex</literal> is returned.
168 <example>
169 >> "nginx".lastIndexOf("gi")
170 1
171 </example>
172 </tag-desc>
173
174 <tag-name id="string_length"><literal>String.prototype.length</literal></tag-name>
175 <tag-desc>
176 Returns the length of the string.
177 <example>
178 >> 'αβγδ'.length
179 4
180 </example>
181 </tag-desc>
182
183 <tag-name><literal>String.prototype.match([<value>regexp</value>])</literal></tag-name>
184 <tag-desc>
185 Matches a string against a <literal>regexp</literal>.
186 <example>
187 >> 'nginx'.match( /ng/i )
188 ng
189 </example>
190 </tag-desc>
191
192 <tag-name><literal>String.prototype.repeat(<value>number</value>)</literal></tag-name>
193 <tag-desc>
194 Returns a string
195 with the specified <literal>number</literal> of copies of the string.
196 <example>
197 >> 'abc'.repeat(3)
198 abcabcabc
199 </example>
200 </tag-desc>
201
202 <tag-name><literal>String.prototype.replace([<value>regexp</value>|<value>string</value>[,
203 <value>string</value>|<value>function</value>]])</literal></tag-name>
204 <tag-desc>
205 Returns a new string with matches of a pattern
206 (<literal>string</literal> or a <literal>regexp</literal>)
207 replaced by a <literal>string</literal> or a <literal>function</literal>.
208 <example>
209 >> 'abcdefgh'.replace('d', 1)
210 abc1efgh
211 </example>
212 </tag-desc>
213
214 <tag-name><literal>String.prototype.search([<value>regexp</value>])</literal></tag-name>
215 <tag-desc>
216 Searches for a string using a <literal>regexp</literal>
217 <example>
218 >> 'abcdefgh'.search('def')
219 3
220 </example>
221 </tag-desc>
222
223 <tag-name><literal>String.prototype.slice(<value>start</value>[,
224 <value>end</value>])</literal></tag-name>
225 <tag-desc>
226 Returns a new string containing a part of an
227 original string between <literal>start</literal>
228 and <literal>end</literal> or
229 from <literal>start</literal> to the end of the string.
230 <example>
231 >> 'abcdefghijklmno'.slice(NaN, 5)
232 abcde
233 </example>
234 </tag-desc>
235
236 <tag-name><literal>String.prototype.startsWith(<value>searchString</value>[,
237 <value>position</value>])</literal></tag-name>
238 <tag-desc>
239 Returns <literal>true</literal> if a string begins with the characters
240 of a specified string, otherwise <literal>false</literal>.
241 The optional <literal>position</literal> parameter is the position
242 in this string at which to begin search for <literal>searchString</literal>.
243 Default value is 0.
244 <example>
245 >> 'abc'.startsWith('abc')
246 true
247 > 'aabc'.startsWith('abc')
248 false
249 </example>
250 </tag-desc>
251
252 <tag-name><literal>String.prototype.substr(<value>start</value>[,
253 <value>length</value>])</literal></tag-name>
254 <tag-desc>
255 Returns the part of the string of the specified <literal>length</literal>
256 from <literal>start</literal>
257 or from <literal>start</literal> to the end of the string.
258 <example>
259 >> 'abcdefghijklmno'.substr(3, 5)
260 defgh
261 </example>
262 </tag-desc>
263
264 <tag-name><literal>String.prototype.substring(<value>start</value>[,
265 <value>end</value>])</literal></tag-name>
266 <tag-desc>
267 Returns the part of the string between
268 <literal>start</literal> and <literal>end</literal> or
269 from <literal>start</literal> to the end of the string.
270 <example>
271 >> 'abcdefghijklmno'.substring(3, 5)
272 de
273 </example>
274 </tag-desc>
275
276 <tag-name id="string_tobytes"><literal>String.prototype.toBytes(start[,
277 end])</literal></tag-name>
278 <tag-desc>
279 (njs specific) Serializes a Unicode string to a byte string.
280 Returns <literal>null</literal> if a character larger than 255 is
281 found in the string.
282 </tag-desc>
283
284 <tag-name><literal>String.prototype.toLowerCase()</literal></tag-name>
285 <tag-desc>
286 Converts a string to lower case.
287 The method supports only simple Unicode folding.
288 <example>
289 >> 'ΑΒΓΔ'.toLowerCase()
290 αβγδ
291 </example>
292 </tag-desc>
293
294 <tag-name><literal>String.prototype.toString([<value>encoding</value>])</literal></tag-name>
295 <tag-desc>
296 <para>
297 If no <literal>encoding</literal> is specified,
298 returns a specified Unicode string or byte string as in ECMAScript.
299 </para>
300
301 <para>
302 (njs specific) If <literal>encoding</literal> is specified,
303 encodes a <link id="string_tobytes">byte string</link> to
304 <literal>hex</literal>,
305 <literal>base64</literal>, or
306 <literal>base64url</literal>.
307 </para>
308 <example>
309 >> 'αβγδ'.toUTF8().toString('base64url')
310 zrHOss6zzrQ
311 </example>
312 </tag-desc>
313
314 <tag-name><literal>String.prototype.toUpperCase()</literal></tag-name>
315 <tag-desc>
316 Converts a string to upper case.
317 The method supports only simple Unicode folding.
318 <example>
319 >> 'αβγδ'.toUpperCase()
320 ΑΒΓΔ
321 </example>
322 </tag-desc>
323
324 <tag-name id="string_toutf8"><literal>String.prototype.toUTF8(<value>start</value>[,
325 <value>end</value>])</literal></tag-name>
326 <tag-desc>
327 (njs specific) Serializes a Unicode string
328 to a byte string using UTF8 encoding.
329 <example>
330 >> 'αβγδ'.toUTF8().length
331 8
332 >> 'αβγδ'.length
333 4
334 </example>
335 </tag-desc>
336
337 <tag-name><literal>String.prototype.trim()</literal></tag-name>
338 <tag-desc>
339 Removes whitespaces from both ends of a string.
340 <example>
341 >> ' abc '.trim()
342 abc
343 </example>
344 </tag-desc>
345
346 <tag-name><literal>String.prototype.split(([<value>string</value>|<value>regexp</value>[,
347 <value>limit</value>]]))</literal></tag-name>
348 <tag-desc>
349 Returns match of a string against a <literal>regexp</literal>.
350 The optional <literal>limit</literal> parameter is an integer that specifies
351 a limit on the number of splits to be found.
352 <example>
353 >> 'abc'.split('')
354 a,b,c
355 </example>
356 </tag-desc>
357
358 <tag-name id="encodeuri"><literal>encodeURI(<value>URI</value>)</literal></tag-name>
359 <tag-desc>
360 encodes a URI by replacing each instance of certain characters by
361 one, two, three, or four escape sequences
362 representing the UTF-8 encoding of the character
363 <example>
364 >> encodeURI('012αβγδ')
365 012%CE%B1%CE%B2%CE%B3%CE%B4
366 </example>
367 </tag-desc>
368
369 <tag-name><literal>encodeURIComponent(<value>encodedURIString</value>)</literal></tag-name>
370 <tag-desc>
371 Encodes a URI by replacing each instance of certain characters
372 by one, two, three, or four escape sequences
373 representing the UTF-8 encoding of the character.
374 <example>
375 >> encodeURIComponent('[@?=')
376 %5B%40%3F%3D
377 </example>
378 </tag-desc>
379
380 <tag-name><literal>decodeURI(<value>encodedURI</value>)</literal></tag-name>
381 <tag-desc>
382 Decodes a previously <link id="encodeuri">encoded</link> URI.
383 <example>
384 >> decodeURI('012%CE%B1%CE%B2%CE%B3%CE%B4')
385 012αβγδ
386 </example>
387 </tag-desc>
388
389 <tag-name><literal>decodeURIComponent(<value>decodedURIString</value>)</literal></tag-name>
390 <tag-desc>
391 Decodes an encoded component of a previously encoded URI.
392 <example>
393 >> decodeURIComponent('%5B%40%3F%3D')
394 [@?=
395 </example>
396 </tag-desc>
397
398 </list>
399 </para>
400
401 </section>
25 402
26 403
27 <section id="core_json" name="JSON"> 404 <section id="core_json" name="JSON">
28 405
29 <para> 406 <para>