ECMA-262 (12th Edition) ECMAScript 2021 Language Specification - page 51

this

value).

2. Let

3. Let

position

be ?

(

pos

4. Let

size

be the length of

5. If

position

< 0 or

position

≥

size

, return

undefined

6. Let

CodePointAt

position

7. Return

.[[CodePoint]]).

NOTE 2

NOTE 1

When the

concat

method is called with zero or more arguments, the following steps are taken:

1. Let

be ?

this

value).

2. Let

3. Let

4. For each element

next

args

, do

a. Let

nextString

next

b. Set

to the

and

nextString

5. Return

The

"length"

property of the

concat

method is

𝔽

NOTE 2

The initial value of

String.prototype.constructor

%String%

Returns a non-negative

integral Number

less than or equal to

0x10FFFF

𝔽

that is the code point

value of the UTF-16 encoded code point (

) starting at the string element at index

pos

within

the String resulting from converting this object to a String. If there is no element at that index, the
result is

undefined

. If a valid UTF-16

surrogate pair

does not begin at

pos

, the result is the code

unit at

pos

The

codePointAt

function is intentionally generic; it does not require that its

this

value be a

String object. Therefore it can be transferred to other kinds of objects for use as a method.

When the

concat

method is called it returns the String value consisting of the code units of the

this

value (converted to a String) followed by the code units of each of the arguments converted

to a String. The result is a String value, not a String object.

The

concat

function is intentionally generic; it does not require that its

this

value be a String

object. Therefore it can be transferred to other kinds of objects for use as a method.

22.1.3.4 String.prototype.concat ( ...

args

)

22.1.3.5 String.prototype.constructor

22.1.3.6 String.prototype.endsWith (

searchString

[ ,

endPosition

] )

557

The following steps are taken:

1. Let

be ?

this

value).

2. Let

3. Let

isRegExp

be ?

searchString

4. If

isRegExp

true

, throw a

TypeError

exception.

5. Let

searchStr

be ?

(

searchString

6. Let

len

be the length of

7. If

endPosition

undefined

, let

pos

len

; else let

pos

be ?

endPosition

8. Let

end

be the result of

pos

between 0 and

len

9. Let

searchLength

be the length of

searchStr

10. If

searchLength

= 0, return

true

11. Let

start

end

searchLength

12. If

start

< 0, return

false

13. Let

substring

be the

from

start

end

14. Return !

SameValueNonNumeric

substring

searchStr

NOTE 1

NOTE 2

NOTE 3

The

includes

method takes two arguments,

searchString

and

position

, and performs the following steps:

1. Let

be ?

this

value).

2. Let

3. Let

isRegExp

be ?

searchString

4. If

isRegExp

true

, throw a

TypeError

exception.

5. Let

searchStr

be ?

(

searchString

6. Let

pos

be ?

position

: If

position

undefined

, then

pos

is 0.

8. Let

len

be the length of

9. Let

start

be the result of

pos

between 0 and

len

10. Let

index

be !

(

searchStr

start

11. If

index

is not -1, return

true

12. Return

false

Returns

true

if the sequence of code units of

searchString

converted to a String is the same as the

corresponding code units of this object (converted to a String) starting at

endPosition

length(this). Otherwise returns

false

Throwing an exception if the first argument is a RegExp is specified in order to allow future
editions to define extensions that allow such argument values.

The

endsWith

function is intentionally generic; it does not require that its

this

value be a String

object. Therefore, it can be transferred to other kinds of objects for use as a method.

22.1.3.7 String.prototype.includes (

searchString

[ ,

position

] )

558

NOTE 1

NOTE 2

NOTE 3

NOTE 1

The

indexOf

method takes two arguments,

searchString

and

position

, and performs the following steps:

1. Let

be ?

this

value).

2. Let

3. Let

searchStr

be ?

(

searchString

4. Let

pos

be ?

position

: If

position

undefined

, then

pos

is 0.

6. Let

len

be the length of

7. Let

start

be the result of

pos

between 0 and

len

8. Return

searchStr

start

)).

NOTE 2

NOTE 1

The

lastIndexOf

method takes two arguments,

searchString

and

position

, and performs the following steps:

1. Let

be ?

this

value).

2. Let

3. Let

searchStr

be ?

(

searchString

4. Let

numPos

be ?

ToNumber

position

: If

position

undefined

, then

numPos

NaN

searchString

appears as a substring of the result of converting this object to a String, at one or

more indices that are greater than or equal to

position

, return

true

; otherwise, returns

false

. If

position

undefined

, 0 is assumed, so as to search all of the String.

Throwing an exception if the first argument is a RegExp is specified in order to allow future
editions to define extensions that allow such argument values.

The

includes

function is intentionally generic; it does not require that its

this

value be a String

object. Therefore, it can be transferred to other kinds of objects for use as a method.

searchString

appears as a substring of the result of converting this object to a String, at one or

more indices that are greater than or equal to

position

, then the smallest such index is returned;

otherwise,

-1

𝔽

is returned. If

position

undefined

𝔽

is assumed, so as to search all of the String.

The

indexOf

function is intentionally generic; it does not require that its

this

value be a String

object. Therefore, it can be transferred to other kinds of objects for use as a method.

searchString

appears as a substring of the result of converting this object to a String at one or

more indices that are smaller than or equal to

position

, then the greatest such index is returned;

otherwise,

-1

𝔽

is returned. If

position

undefined

, the length of the String value is assumed, so as

to search all of the String.

22.1.3.8 String.prototype.indexOf (

searchString

[ ,

position

] )

22.1.3.9 String.prototype.lastIndexOf (

searchString

[ ,

position

] )

559

6. If

numPos

NaN

, let

pos

be +

∞

; otherwise, let

pos

be !

(

numPos

7. Let

len

be the length of

8. Let

start

be the result of

pos

between 0 and

len

9. Let

searchLen

be the length of

searchStr

10. Let

be the largest possible non-negative

not larger than

start

such that

searchLen

≤

len

, and for all

non-negative integers

such that

searchLen

, the code unit at index

within

is the same as the code unit

at index

within

searchStr

; but if there is no such

default locale, and will be

, let

be -1.

11. Return

NOTE 2

An ECMAScript implementation that includes the ECMA-402 Internationalization API must implement the

localeCompare

method as specified in the ECMA-402 specification. If an ECMAScript implementation does not

include the ECMA-402 API the following specification of the

localeCompare

method is used.

When the

localeCompare

method is called with argument

that

, it returns a Number other than

NaN

that

represents the result of a locale-sensitive String comparison of the

this

value (converted to a String) with

that

(converted to a String). The two Strings are

and

That

. The two Strings are compared in an

implementation-defined

fashion. The result is intended to order String values in the sort order specified by a

host

negative, zero, or positive, depending on whether

comes before

That

in the sort order, the Strings are equal, or

comes after

That

in the sort order, respectively.

Before performing the comparisons, the following steps are performed to prepare the Strings:

1. Let

be ?

this

value).

2. Let

3. Let

That

comparison function (as defined in

that

The meaning of the optional second and third parameters to this method are defined in the ECMA-402 specification;
implementations that do not include ECMA-402 support must not assign any other interpretation to those parameter
positions.

The

localeCompare

method, if considered as a function of two arguments

this

and

that

, is a consistent

23.1.3.27

) on the set of all Strings.

The actual return values are

implementation-defined

to permit implementers to encode additional information in the

value, but the function is required to define a total ordering on all Strings. This function must treat Strings that are
canonically equivalent according to the Unicode standard as identical and must return

when comparing Strings that

are considered canonically equivalent.

NOTE 1

The

lastIndexOf

function is intentionally generic; it does not require that its

this

value be a

String object. Therefore, it can be transferred to other kinds of objects for use as a method.

The

localeCompare

method itself is not directly suitable as an argument to

Array.prototype.sort

because the latter requires a function of two arguments.

22.1.3.10 String.prototype.localeCompare (

that

[ ,

reserved1

[ ,

reserved2

] ] )

560

NOTE 2

NOTE 3

When the

match

method is called with argument

regexp

, the following steps are taken:

1. Let

be ?

this

value).

2. If

regexp

is neither

undefined

nor

null

, then

a. Let

matcher

(

regexp

@@match

b. If

matcher

is not

undefined

, then

(

matcher

regexp

, «

»).

3. Let

4. Let

be ?

RegExpCreate

regexp

undefined

5. Return ?

Invoke

(

@@match

, «

»).

NOTE

Performs a regular expression match of the String representing the

this

value against

regexp

and returns an iterator.

Each iteration result's value is an Array object containing the results of the match, or

null

if the String did not match.

When the

matchAll

method is called, the following steps are taken:

1. Let

be ?

this

value).

2. If

regexp

is neither

undefined

nor

null

, then

a. Let

isRegExp

be ?

regexp

b. If

isRegExp

true

, then

i. Let

flags

be ?

Get

(

regexp

"flags"

ii. Perform ?

(

flags

iii. If ?

flags

) does not contain

"g"

, throw a

TypeError

exception.

c. Let

matcher

(

regexp

@@matchAll

This function is intended to rely on whatever language-sensitive comparison functionality is
available to the ECMAScript environment from the

, and to compare according

to the rules of the

https://unicode.org/reports/tr15/

's current locale. However, regardless of the

host

provided

comparison capabilities, this function must treat Strings that are canonically equivalent according
to the Unicode standard as identical. It is recommended that this function should not honour
Unicode compatibility equivalences or decompositions. For a definition and discussion of
canonical equivalence see the Unicode Standard, chapters 2 and 3, as well as Unicode Standard
Annex #15, Unicode Normalization Forms (

) and Unicode

Technical Note #5, Canonical Equivalence in Applications
(

https://www.unicode.org/notes/tn5/

). Also see Unicode Technical Standard #10, Unicode

Collation Algorithm (

https://unicode.org/reports/tr10/

The

localeCompare

function is intentionally generic; it does not require that its

this

value be

a String object. Therefore, it can be transferred to other kinds of objects for use as a method.

The

match

function is intentionally generic; it does not require that its

this

value be a String

object. Therefore, it can be transferred to other kinds of objects for use as a method.

22.1.3.11 String.prototype.match (

regexp

)

22.1.3.12 String.prototype.matchAll (

regexp

)

561

d. If

matcher

is not

undefined

, then

(

matcher

regexp

, «

»).

3. Let

4. Let

be ?

RegExpCreate

regexp

"g"

5. Return ?

Invoke

(

@@matchAll

, «

»).

NOTE 1

NOTE 2

When the

normalize

method is called with one argument

form

, the following steps are taken:

1. Let

be ?

this

value).

2. Let

3. If

form

undefined

, let

"NFC"

4. Else, let

be ?

https://unicode.org/reports/tr15/

(

form

5. If

is not one of

"NFC"

"NFD"

"NFKC"

, or

"NFKD"

, throw a

RangeError

exception.

6. Let

be the String value that is the result of normalizing

into the normalization form named by

as specified

7. Return

NOTE

When the

padEnd

method is called, the following steps are taken:

1. Let

be ?

this

value).

2. Return ?

StringPad

maxLength

fillString

end

When the

padStart

method is called, the following steps are taken:

1. Let

be ?

this

value).

2. Return ?

StringPad

maxLength

fillString

start

The abstract operation StringPad takes arguments

maxLength

fillString

, and

placement

. It performs the following

steps when called:

The

matchAll

function is intentionally generic, it does not require that its

this

value be a String

object. Therefore, it can be transferred to other kinds of objects for use as a method.

Similarly to

String.prototype.split

String.prototype.matchAll

is designed

to typically act without mutating its inputs.

The

normalize

function is intentionally generic; it does not require that its

this

value be a

String object. Therefore it can be transferred to other kinds of objects for use as a method.

22.1.3.13 String.prototype.normalize ( [

form

] )

22.1.3.14 String.prototype.padEnd (

maxLength

[ ,

fillString

] )

22.1.3.15 String.prototype.padStart (

maxLength

[ ,

fillString

] )

22.1.3.15.1 StringPad (

maxLength

fillString

placement

)

562

placement

start

end

2. Let

3. Let

intMaxLength

ToLength

maxLength

)).

4. Let

stringLength

be the length of

5. If

intMaxLength

≤

stringLength

, return

6. If

fillString

undefined

, let

filler

be the String value consisting solely of the code unit 0x0020 (SPACE).

7. Else, let

filler

be ?

(

fillString

8. If

filler

is the empty String, return

9. Let

fillLen

intMaxLength

stringLength

10. Let

truncatedStringFiller

be the String value consisting of repeated concatenations of

filler

truncated to length

fillLen

11. If

placement

start

, return the

truncatedStringFiller

and

12. Else, return the

and

truncatedStringFiller

NOTE 1

NOTE 2

The following steps are taken:

1. Let

be ?

this

value).

2. Let

3. Let

count

4. If

< 0 or

is +

∞

, throw a

RangeError

exception.

5. If

is 0, return the empty String.

6. Return the String value that is made from

copies of

appended together.

NOTE 1

NOTE 2

When the

replace

method is called with arguments

searchValue

and

replaceValue

, the following steps are taken:

1. Let

be ?

this

value).

2. If

searchValue

is neither

undefined

nor

null

, then

a. Let

replacer

(

searchValue

@@replace

b. If

replacer

is not

undefined

, then

(

replacer

searchValue

, «

replaceValue

»).

The argument

maxLength

will be clamped such that it can be no smaller than the length of

The argument

fillString

defaults to

" "

(the String value consisting of the code unit 0x0020

SPACE).

This method creates the String value consisting of the code units of the

this

value (converted to

String) repeated

count

times.

The

repeat

function is intentionally generic; it does not require that its

this

value be a String

object. Therefore, it can be transferred to other kinds of objects for use as a method.

22.1.3.16 String.prototype.repeat (

count

)

22.1.3.17 String.prototype.replace (

searchValue

replaceValue

)

563

3. Let

string

be ?

(

4. Let

searchString

searchValue

5. Let

functionalReplace

IsCallable

replaceValue

6. If

functionalReplace

false

, then

a. Set

replaceValue

to ?

replaceValue

7. Let

searchLength

be the length of

searchString

8. Let

position

string

searchString

, 0).

9. If

position

is -1, return

string

10. Let

preserved

be the

string

from 0 to

position

11. If

functionalReplace

true

, then

a. Let

replacement

(

replaceValue

undefined

, «

searchString

(

position

string

»)).

12. Else,

replaceValue

) is String.

b. Let

captures

be a new empty

List

c. Let

replacement

be !

GetSubstitution

(

searchString

string

position

captures

undefined

replaceValue

13. Return the

preserved

replacement

, and the

string

from

position

searchLength

NOTE

The abstract operation GetSubstitution takes arguments

matched

str

position

(a non-negative

captures

namedCaptures

, and

replacement

. It performs the following steps when called:

matched

) is String.

2. Let

matchLength

be the number of code units in

matched

str

) is String.

4. Let

stringLength

be the number of code units in

str

position

≤

stringLength

captures

replacement

) is String.

8. Let

tailPos

position

matchLength

9. Let

be the number of elements in

captures

10. Let

result

be the String value derived from

replacement

by copying code unit elements from

replacement

result

while performing replacements as specified in

Table 54

. These

replacements are done left-to-right, and, once

such a replacement is performed, the new replacement text is not subject to further replacements.

11. Return

result

The

replace

function is intentionally generic; it does not require that its

this

value be a String

object. Therefore, it can be transferred to other kinds of objects for use as a method.

22.1.3.17.1 GetSubstitution (

matched

str

position

captures

namedCaptures

replacement

)

564

Table 54: Replacement Text Symbol Substitutions

Code

units

Unicode Characters

Replacement text

0x0024,
0x0024

0x0024,
0x0026

matched

0x0024,
0x0060

The replacement is the

str

from 0 to

position

0x0024,
0x0027

tailPos

≥

stringLength

, the replacement is the empty String. Otherwise the

replacement is the

str

from

tailPos

0x0024,
N
Where
0x0031

≤

0x0039

where

is one of

1 2 3 4 5

6 7 8 9

and

is not

followed by a decimal
digit

The

element of

captures

, where

is a single digit in the range 1 to 9. If

≤

and the

element of

captures

undefined

, use the empty String instead.

, no replacement is done.

0x0024,
N, N
Where
0x0030

≤

0x0039

$nn

where

is one of

0 1 2 3 4

5 6 7 8 9

The

element of

captures

, where

is a two-digit decimal number in the

range 01 to 99. If

≤

and the

element of

captures

undefined

, use the

empty String instead. If

is 00 or

, no replacement is done.

0x0024,
0x003C

1. If

namedCaptures

undefined

, the replacement text is the String

"$<"

2. Else,

namedCaptures

) is Object.

b. Scan until the next

U+003E (GREATER-THAN SIGN).

c. If none is found, the replacement text is the String

"$<"

d. Else,

i. Let

groupName

be the enclosed substring.

ii. Let

capture

be ?

Get

(

namedCaptures

groupName

iii. If

capture

undefined

, replace the text through

with

the empty String.

iv. Otherwise, replace the text through

with

(

capture

0x0024

in any context that does

not match any of the
above.

565

When the

replaceAll

method is called with arguments

searchValue

and

replaceValue

, the following steps are taken:

1. Let

be ?

this

value).

2. If

searchValue

is neither

undefined

nor

null

, then

a. Let

isRegExp

be ?

searchValue

b. If

isRegExp

true

, then

i. Let

flags

be ?

Get

(

searchValue

"flags"

ii. Perform ?

(

flags

iii. If ?

flags

) does not contain

"g"

, throw a

TypeError

exception.

c. Let

replacer

(

searchValue

@@replace

d. If

replacer

is not

undefined

, then

(

replacer

searchValue

, «

replaceValue

»).

3. Let

string

be ?

(

4. Let

searchString

searchValue

5. Let

functionalReplace

IsCallable

replaceValue

6. If

functionalReplace

false

, then

a. Set

replaceValue

to ?

replaceValue

7. Let

searchLength

be the length of

searchString

8. Let

advanceBy

(1,

searchLength

9. Let

matchPositions

be a new empty

List

10. Let

position

string

searchString

, 0).

11. Repeat, while

position

is not -1,

a. Append

position

to the end of

matchPositions

b. Set

position

to !

(

string

searchString

position

advanceBy

12. Let

endOfLastMatch

be 0.

13. Let

result

be the empty String.

14. For each element

matchPositions

, do

a. Let

preserved

be the

string

from

endOfLastMatch

b. If

functionalReplace

true

, then

i. Let

replacement

(

replaceValue

undefined

, «

searchString

(

string

»)).

c. Else,

replaceValue

) is String.

ii. Let

captures

be a new empty

List

iii. Let

replacement

be !

GetSubstitution

(

searchString

string

captures

undefined

replaceValue

d. Set

result

to the

result

preserved

, and

replacement

e. Set

endOfLastMatch

searchLength

15. If

endOfLastMatch

< the length of

string

, then

a. Set

result

to the

result

and the

string

from

endOfLastMatch

16. Return

result

When the

method is called with argument

regexp

, the following steps are taken:

1. Let

be ?

this

value).

2. If

regexp

is neither

undefined

nor

null

, then

a. Let

searcher

be ?

regexp

@@search

22.1.3.18 String.prototype.replaceAll (

searchValue

replaceValue

)

22.1.3.19 String.prototype.search (

regexp

)

566

b. If

searcher

is not

undefined

, then

(

searcher

regexp

, «

»).

3. Let

string

be ?

(

4. Let

be ?

RegExpCreate

regexp

undefined

5. Return ?

Invoke

(

@@search

, «

string

»).

NOTE

The

slice

method takes two arguments,

start

and

end

, and returns a substring of the result of converting this object

to a String, starting from index

start

and running to, but not including, index

end

(or through the end of the String if

end

undefined

). If

start

is negative, it is treated as

sourceLength

start

where

sourceLength

is the length of the String.

end

is negative, it is treated as

sourceLength

end

where

sourceLength

is the length of the String. The result is a String

value, not a String object. The following steps are taken:

1. Let

be ?

this

value).

2. Let

3. Let

len

be the length of

4. Let

intStart

be ?

(

start

5. If

intStart

is -

∞

, let

from

be 0.

6. Else if

intStart

< 0, let

from

len

intStart

, 0).

7. Else, let

from

min

(

intStart

len

8. If

end

undefined

, let

intEnd

len

; else let

intEnd

end

9. If

intEnd

is -

∞

, let

be 0.

10. Else if

intEnd

< 0, let

(

len

intEnd

, 0).

11. Else, let

min

(

intEnd

len

12. If

from

≥

, return the empty String.

13. Return the

length or it may be an object, such as a RegExp, that has a

from

from

NOTE

Returns an Array object into which substrings of the result of converting this object to a String have been stored. The
substrings are determined by searching from left to right for occurrences of

separator

; these occurrences are not part of

any String in the returned array, but serve to divide up the String value. The value of

separator

may be a String of any

@@split

method.

When the

split

method is called, the following steps are taken:

1. Let

be ?

this

value).

2. If

separator

is neither

undefined

nor

null

, then

a. Let

splitter

be ?

separator

@@split

b. If

splitter

is not

undefined

, then

The

function is intentionally generic; it does not require that its

this

value be a String

object. Therefore, it can be transferred to other kinds of objects for use as a method.

The

slice

function is intentionally generic; it does not require that its

this

value be a String

object. Therefore it can be transferred to other kinds of objects for use as a method.

22.1.3.20 String.prototype.slice (

start

end

)

22.1.3.21 String.prototype.split (

separator

limit

)

567

(

splitter

separator

, «

limit

»).

3. Let

4. Let

(0).

5. Let

lengthA

be 0.

6. If

limit

undefined

, let

lim

be 2

- 1; else let

lim

ToUint32

limit

)).

7. Let

(

separator

8. If

lim

= 0, return

9. If

separator

undefined

, then

a. Perform !

(

"0"

b. Return

10. Let

be the length of

11. If

= 0, then

a. If

is not the empty String, then

i. Perform !

(

"0"

b. Return

12. Let

be 0.

13. Let

14. Repeat, while

≠

a. Let

SplitMatch

(

b. If

not-matched

, set

+ 1.

c. Else,

is a non-negative

≤

ii. If

, set

+ 1.

iii. Else,

1. Let

be the

from

2. Perform !

(

, !

(

lengthA

)),

3. Set

lengthA

+ 1.

4. If

lengthA

lim

, return

5. Set

6. Set

15. Let

be the

from

16. Perform !

(

, !

(

lengthA

)),

17. Return

NOTE 1

The value of

separator

may be an empty String. In this case,

separator

does not match the empty

substring at the beginning or end of the input String, nor does it match the empty substring at
the end of the previous separator match. If

separator

is the empty String, the String is split up into

individual code unit elements; the length of the result array equals the length of the String, and
each substring contains one code unit.

If the

this

value is (or converts to) the empty String, the result depends on whether

separator

can

match the empty String. If it can, the result array contains no elements. Otherwise, the result
array contains one element, which is the empty String.

separator

undefined

, then the result array contains just one String, which is the

this

value

(converted to a String). If

limit

is not

undefined

, then the output array is truncated so that it

contains no more than

limit

elements.

568

NOTE 2

The abstract operation SplitMatch takes arguments

(a String),

(a non-negative

), and

(a String). It returns

either

not-matched

or the end index of a match. It performs the following steps when called:

1. Let

be the number of code units in

2. Let

be the number of code units in

3. If

, return

not-matched

4. If there exists an

between 0 (inclusive) and

(exclusive) such that the code unit at index

within

is different from the code unit at index

within

, return

not-matched

5. Return

The following steps are taken:

1. Let

be ?

this

value).

2. Let

3. Let

isRegExp

be ?

searchString

4. If

isRegExp

true

, throw a

TypeError

exception.

5. Let

searchStr

be ?

(

searchString

6. Let

len

be the length of

7. If

position

undefined

, let

pos

be 0; else let

pos

be ?

(

position

8. Let

start

be the result of

pos

between 0 and

len

9. Let

searchLength

be the length of

searchStr

10. If

searchLength

= 0, return

true

11. Let

end

start

searchLength

12. If

end

len

, return

false

13. Let

substring

be the

from

start

end

14. Return !

SameValueNonNumeric

substring

searchStr

NOTE 1

NOTE 2

NOTE 3

The

split

function is intentionally generic; it does not require that its

this

value be a String

object. Therefore, it can be transferred to other kinds of objects for use as a method.

This method returns

true

if the sequence of code units of

searchString

converted to a String is the

same as the corresponding code units of this object (converted to a String) starting at index

position

. Otherwise returns

false

Throwing an exception if the first argument is a RegExp is specified in order to allow future
editions to define extensions that allow such argument values.

The

startsWith

function is intentionally generic; it does not require that its

this

value be a

String object. Therefore, it can be transferred to other kinds of objects for use as a method.

22.1.3.21.1 SplitMatch (

)

22.1.3.22 String.prototype.startsWith (

searchString

[ ,

position

] )

22.1.3.23 String.prototype.substring (

start

end

)

569

The

substring

method takes two arguments,

start

and

end

, and returns a substring of the result of converting this

object to a String, starting from index

start

and running to, but not including, index

end

of the String (or through the

end of the String if

end

undefined

). The result is a String value, not a String object.

If either argument is

NaN

or negative, it is replaced with zero; if either argument is larger than the length of the

String, it is replaced with the length of the String.

start

is larger than

end

, they are swapped.

The following steps are taken:

1. Let

be ?

this

value).

2. Let

3. Let

len

be the length of

4. Let

intStart

be ?

(

start

5. If

end

undefined

, let

intEnd

len

; else let

intEnd

end

6. Let

finalStart

be the result of

intStart

between 0 and

len

7. Let

finalEnd

be the result of

intEnd

between 0 and

len

8. Let

from

min

(

finalStart

finalEnd

9. Let

finalStart

finalEnd

10. Return the

from

from

NOTE

An ECMAScript implementation that includes the ECMA-402 Internationalization API must implement the

toLocaleLowerCase

method as specified in the ECMA-402 specification. If an ECMAScript implementation does

not include the ECMA-402 API the following specification of the

toLocaleLowerCase

method is used.

This function interprets a String value as a sequence of UTF-16 encoded code points, as described in

This function works exactly the same as

toLowerCase

except that its result is intended to yield the correct result

for the

's current locale, rather than a locale-independent result. There will only be a difference in the

few cases (such as Turkish) where the rules for that language conflict with the regular Unicode case mappings.

The meaning of the optional parameters to this method are defined in the ECMA-402 specification; implementations
that do not include ECMA-402 support must not use those parameter positions for anything else.

NOTE

An ECMAScript implementation that includes the ECMA-402 Internationalization API must implement the

toLocaleUpperCase

method as specified in the ECMA-402 specification. If an ECMAScript implementation does

The

substring

function is intentionally generic; it does not require that its

this

value be a

String object. Therefore, it can be transferred to other kinds of objects for use as a method.

The

toLocaleLowerCase

function is intentionally generic; it does not require that its

this

value be a String object. Therefore, it can be transferred to other kinds of objects for use as a
method.

22.1.3.24 String.prototype.toLocaleLowerCase ( [

reserved1

[ ,

reserved2

] ] )

22.1.3.25 String.prototype.toLocaleUpperCase ( [

reserved1

[ ,

reserved2

] ] )

570

not include the ECMA-402 API the following specification of the

toLocaleUpperCase

method is used.

This function interprets a String value as a sequence of UTF-16 encoded code points, as described in

This function works exactly the same as

toUpperCase

except that its result is intended to yield the correct result

for the

's current locale, rather than a locale-independent result. There will only be a difference in the

few cases (such as Turkish) where the rules for that language conflict with the regular Unicode case mappings.

NOTE

This function interprets a String value as a sequence of UTF-16 encoded code points, as described in

. The

following steps are taken:

1. Let

be ?

this

value).

2. Let

3. Let

sText

StringToCodePoints

(

4. Let

lowerText

be the result of toLowercase(

sText

), according to the Unicode Default Case Conversion algorithm.

5. Let

be !

CodePointsToString

lowerText

6. Return

The result must be derived according to the locale-insensitive case mappings in the Unicode Character Database (this
explicitly includes not only the UnicodeData.txt file, but also all locale-insensitive mappings in the SpecialCasings.txt
file that accompanies it).

NOTE 1

NOTE 2

When the

toString

method is called, the following steps are taken:

1. Return ?

thisStringValue

(

this

value).

The

toLocaleUpperCase

function is intentionally generic; it does not require that its

this

value be a String object. Therefore, it can be transferred to other kinds of objects for use as a
method.

The case mapping of some code points may produce multiple code points. In this case the result
String may not be the same length as the source String. Because both

toUpperCase

and

toLowerCase

have context-sensitive behaviour, the functions are not symmetrical. In other

words,

s.toUpperCase().toLowerCase()

is not necessarily equal to

s.toLowerCase()

The

toLowerCase

function is intentionally generic; it does not require that its

this

value be a

String object. Therefore, it can be transferred to other kinds of objects for use as a method.

22.1.3.26 String.prototype.toLowerCase ( )

22.1.3.27 String.prototype.toString ( )

571

NOTE

This function interprets a String value as a sequence of UTF-16 encoded code points, as described in

This function behaves in exactly the same way as

String.prototype.toLowerCase

, except that the String is

mapped using the toUppercase algorithm of the Unicode Default Case Conversion.

NOTE

This function interprets a String value as a sequence of UTF-16 encoded code points, as described in

The following steps are taken:

1. Let

be the

this

value.

2. Return ?

TrimString

encoded code points, as described in

start+end

NOTE

The abstract operation TrimString takes arguments

string

and

where

. It interprets

string

as a sequence of UTF-16

. It performs the following steps when called:

1. Let

str

(

string

2. Let

str

3. If

where

start

, let

be the String value that is a copy of

with leading white space removed.

4. Else if

where

end

, let

be the String value that is a copy of

with trailing white space removed.

5. Else,

. When determining whether a Unicode

where

start+end

b. Let

be the String value that is a copy of

with both leading and trailing white space removed.

6. Return

The definition of white space is the union of

WhiteSpace

and

LineTerminator

code point is in Unicode general category “Space_Separator” (“Zs”), code unit sequences are interpreted as UTF-16
encoded code point sequences as specified in

This function interprets a String value as a sequence of UTF-16 encoded code points, as described in