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

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.

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

Date.prototype.toLocaleString

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

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

toLocaleString

method

is used.

This function returns a String value. The contents of the String are

implementation-defined

, but are intended to

represent the Date in the current time zone in a convenient, human-readable form that corresponds to the conventions
of the

host environment

's current locale.

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

Date.prototype.toLocaleTimeString

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

ECMAScript implementation does not include the ECMA-402 API the following specification of the

toLocaleTimeString

method is used.

This function returns a String value. The contents of the String are

implementation-defined

, but are intended to

represent the “time” portion of the Date in the current time zone in a convenient, human-readable form that
corresponds to the conventions of the

host environment

's current locale.

The following steps are performed:

1. Let

be ?

thisTimeValue

(

this

value).

2. Return

ToDateString

(

NOTE 1

For any Date object

such that

d.[[DateValue]]

is evenly divisible by 1000, the result of

Date.parse(d.toString())

d.valueOf()

. See

21.4.3.2

21.4.4.39 Date.prototype.toLocaleString ( [

reserved1

[ ,

reserved2

] ] )

21.4.4.40 Date.prototype.toLocaleTimeString ( [

reserved1

[ ,

reserved2

] ] )

21.4.4.41 Date.prototype.toString ( )

549

NOTE 2

The abstract operation TimeString takes argument

. It performs the following steps when called:

) is Number.

is not

NaN

3. Let

hour

be the String representation of

HourFromTime

(

), formatted as a two-digit decimal number, padded

to the left with the code unit 0x0030 (DIGIT ZERO) if necessary.

4. Let

minute

be the String representation of

MinFromTime

(

), formatted as a two-digit decimal number, padded

to the left with the code unit 0x0030 (DIGIT ZERO) if necessary.

5. Let

second

be the String representation of

SecFromTime

(

), formatted as a two-digit decimal number, padded

to the left with the code unit 0x0030 (DIGIT ZERO) if necessary.

6. Return the

string-concatenation

hour

":"

minute

":"

second

, the code unit 0x0020 (SPACE), and

"GMT"

The abstract operation DateString takes argument

. It performs the following steps when called:

) is Number.

is not

NaN

3. Let

weekday

be the Name of the entry in

Table 52

with the Number

WeekDay

(

4. Let

month

be the Name of the entry in

Table 53

with the Number

MonthFromTime

(

5. Let

day

be the String representation of

DateFromTime

(

), formatted as a two-digit decimal number, padded to

the left with the code unit 0x0030 (DIGIT ZERO) if necessary.

6. Let

YearFromTime

(

7. If

≥

𝔽

, let

yearSign

be the empty String; otherwise, let

yearSign

"-"

8. Let

year

be the String representation of

abs

(

)), formatted as a decimal number.

9. Let

paddedYear

be !

StringPad

(

year

𝔽

"0"

start

10. Return the

string-concatenation

weekday

, the code unit 0x0020 (SPACE),

month

, the code unit 0x0020

(SPACE),

day

, the code unit 0x0020 (SPACE),

yearSign

, and

paddedYear

Table 52: Names of days of the week

Number Name

𝔽

"Sun"

𝔽

"Mon"

𝔽

"Tue"

𝔽

"Wed"

𝔽

"Thu"

𝔽

"Fri"

𝔽

"Sat"

The

toString

function is not generic; it throws a

TypeError

exception if its

this

value is not a

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

21.4.4.41.1 TimeString (

)

21.4.4.41.2 DateString (

)

550

Table 53: Names of months of the year

Number Name

𝔽

"Jan"

𝔽

"Feb"

𝔽

"Mar"

𝔽

"Apr"

𝔽

"May"

𝔽

"Jun"

𝔽

"Jul"

𝔽

"Aug"

𝔽

"Sep"

𝔽

"Oct"

𝔽

"Nov"

𝔽

"Dec"

The abstract operation TimeZoneString takes argument

. It performs the following steps when called:

) is Number.

is not

NaN

3. Let

offset

LocalTZA

(

true

4. If

offset

≥

𝔽

, then

a. Let

offsetSign

"+"

b. Let

absOffset

offset

5. Else,

a. Let

offsetSign

"-"

b. Let

absOffset

be -

offset

6. Let

offsetMin

be the String representation of

MinFromTime

(

absOffset

), formatted as a two-digit decimal number,

padded to the left with the code unit 0x0030 (DIGIT ZERO) if necessary.

7. Let

offsetHour

be the String representation of

HourFromTime

(

absOffset

), formatted as a two-digit decimal

number, padded to the left with the code unit 0x0030 (DIGIT ZERO) if necessary.

8. Let

tzName

be an

implementation-defined

string that is either the empty String or the

string-concatenation

the code unit 0x0020 (SPACE), the code unit 0x0028 (LEFT PARENTHESIS), an

implementation-defined

timezone name, and the code unit 0x0029 (RIGHT PARENTHESIS).

9. Return the

string-concatenation

offsetSign

offsetHour

offsetMin

, and

tzName

21.4.4.41.3 TimeZoneString (

)

21.4.4.41.4 ToDateString (

)

551

The abstract operation ToDateString takes argument

. It performs the following steps when called:

Assert

Type

(

) is Number.

2. If

NaN

, return

"Invalid Date"

3. Let

4. Return the

), the code unit 0x0020 (SPACE),

), and

The following steps are performed:

1. Let

this Date object

2. Let

be ?

thisTimeValue

(

3. If

NaN

, return

"Invalid Date"

4. Let

5. Return the

(

) and

method returns a String value representing the instance in time corresponding to

this time

value

. The format of the String is based upon "HTTP-date" from RFC 7231, generalized to support the full range of

times supported by ECMAScript Date objects. It performs the following steps when called:

1. Let

this Date object

2. Let

be ?

thisTimeValue

(

3. If

NaN

, return

"Invalid Date"

4. Let

weekday

be the Name of the entry in

Table 52

with the Number

WeekDay

(

5. Let

month

be the Name of the entry in

Table 53

with the Number

MonthFromTime

(

6. Let

day

be the String representation of

DateFromTime

(

), formatted as a two-digit decimal number, padded to

the left with the code unit 0x0030 (DIGIT ZERO) if necessary.

7. Let

YearFromTime

(

8. If

≥

𝔽

, let

yearSign

be the empty String; otherwise, let

yearSign

"-"

9. Let

year

be the String representation of

abs

(

)), formatted as a decimal number.

10. Let

paddedYear

be !

StringPad

(

year

𝔽

"0"

start

11. Return the

string-concatenation

weekday

","

, the code unit 0x0020 (SPACE),

day

, the code unit 0x0020

(SPACE),

month

, the code unit 0x0020 (SPACE),

yearSign

paddedYear

, the code unit 0x0020 (SPACE), and

TimeString

(

The following steps are performed:

1. Return ?

thisTimeValue

(

this

value).

This function is called by ECMAScript language operators to convert a Date object to a primitive value. The allowed
values for

hint

are

"default"

"number"

, and

"string"

. Date objects, are unique among built-in ECMAScript object in

21.4.4.42 Date.prototype.toTimeString ( )

21.4.4.43 Date.prototype.toUTCString ( )

21.4.4.44 Date.prototype.valueOf ( )

21.4.4.45 Date.prototype [ @@toPrimitive ] (

hint

)

552

that they treat

"default"

as being equivalent to

"string"

, All other built-in ECMAScript objects treat

"default"

as being

equivalent to

"number"

When the

@@toPrimitive

method is called with argument

hint

, the following steps are taken:

1. Let

be the

this

value.

2. If

Type

(

) is not Object, throw a

TypeError

exception.

3. If

hint

"string"

"default"

, then

a. Let

tryFirst

string

4. Else if

hint

"number"

, then

a. Let

tryFirst

number

5. Else, throw a

TypeError

exception.

6. Return ?

OrdinaryToPrimitive

(

tryFirst

The value of the

"name"

property of this function is

"[Symbol.toPrimitive]"

This property has the attributes { [[Writable]]:

false

, [[Enumerable]]:

false

, [[Configurable]]:

true

Date instances are ordinary objects that inherit properties from the

Date prototype object

. Date instances also have a

[[DateValue]] internal slot. The [[DateValue]] internal slot is the

time value

represented by

this Date object

The String

constructor

%String%

is the initial value of the

"String"

property of the

global object

creates and initializes a new String object when called as a

constructor

performs a type conversion when called as a function rather than as a

constructor

is designed to be subclassable. It may be used as the value of an

extends

clause of a class definition. Subclass

constructors that intend to inherit the specified String behaviour must include a

super

call to the String

constructor

to create and initialize the subclass instance with a [[StringData]] internal slot.

When

String

is called with argument

value

, the following steps are taken:

1. If

value

is not present, let

be the empty String.

2. Else,

a. If NewTarget is

undefined

and

Type

(

value

) is Symbol, return

SymbolDescriptiveString

(

value

21.4.5 Properties of Date Instances

22 Text Processing

22.1 String Objects

22.1.1 The String Constructor

22.1.1.1 String (

value

)

553

b. Let

be ?

ToString

(

value

3. If NewTarget is

undefined

, return

4. Return !

StringCreate

(

, ?

GetPrototypeFromConstructor

(NewTarget,

"%String.prototype%"

)).

The String

constructor

has a [[Prototype]] internal slot whose value is

%Function.prototype%

has the following properties:

The

String.fromCharCode

function may be called with any number of arguments which form the rest

parameter

codeUnits

. The following steps are taken:

1. Let

length

be the number of elements in

codeUnits

2. Let

elements

be a new empty

List

3. For each element

next

codeUnits

, do

a. Let

nextCU

ToUint16

(

next

)).

b. Append

nextCU

to the end of

elements

4. Return the String value whose code units are the elements in the

List

elements

. If

codeUnits

is empty, the empty

String is returned.

The

"length"

property of the

fromCharCode

function is

𝔽

The

String.fromCodePoint

function may be called with any number of arguments which form the rest

parameter

codePoints

. The following steps are taken:

1. Let

result

be the empty String.

2. For each element

next

codePoints

, do

a. Let

nextCP

be ?

ToNumber

(

next

b. If !

IsIntegralNumber

(

nextCP

) is

false

, throw a

RangeError

exception.

nextCP

) > 0x10FFFF, throw a

RangeError

exception.

d. Set

result

to the

string-concatenation

result

and !

UTF16EncodeCodePoint

(

nextCP

)).

Assert

: If

codePoints

is empty, then

result

is the empty String.

4. Return

result

The

"length"

property of the

fromCodePoint

function is

𝔽

The initial value of

String.prototype

is the

String prototype object

This property has the attributes { [[Writable]]:

false

, [[Enumerable]]:

false

, [[Configurable]]:

false

22.1.2 Properties of the String Constructor

22.1.2.1 String.fromCharCode ( ...

codeUnits

)

22.1.2.2 String.fromCodePoint ( ...

codePoints

)

22.1.2.3 String.prototype

22.1.2.4 String.raw (

template

, ...

substitutions

)

554

The

String.raw

function may be called with a variable number of arguments. The first argument is

template

and

the remainder of the arguments form the

List

substitutions

. The following steps are taken:

1. Let

numberOfSubstitutions

be the number of elements in

substitutions

2. Let

cooked

be ?

ToObject

(

template

3. Let

raw

be ?

ToObject

Get

(

cooked

"raw"

)).

4. Let

literalSegments

be ?

LengthOfArrayLike

(

raw

5. If

literalSegments

≤

0, return the empty String.

6. Let

stringElements

be a new empty

List

7. Let

nextIndex

be 0.

8. Repeat,

a. Let

nextKey

be !

ToString

(

nextIndex

)).

b. Let

nextSeg

raw

nextKey

)).

c. Append the code unit elements of

nextSeg

to the end of

stringElements

d. If

nextIndex

+ 1 =

literalSegments

, then

i. Return the String value whose code units are the elements in the

List

stringElements

. If

stringElements

has no elements, the empty String is returned.

e. If

nextIndex

numberOfSubstitutions

, let

next

substitutions

[

nextIndex

f. Else, let

next

be the empty String.

g. Let

nextSub

be ?

ToString

(

next

h. Append the code unit elements of

nextSub

to the end of

stringElements

i. Set

nextIndex

+ 1.

NOTE

The

String prototype object

%String.prototype%

is a

String exotic object

and has the internal methods specified for such objects.

has a [[StringData]] internal slot whose value is the empty String.
has a

"length"

property whose initial value is

𝔽

and whose attributes are { [[Writable]]:

false

, [[Enumerable]]:

false

, [[Configurable]]:

false

has a [[Prototype]] internal slot whose value is

%Object.prototype%

Unless explicitly stated otherwise, the methods of the String prototype object defined below are not generic and the

this

value passed to them must be either a String value or an object that has a [[StringData]] internal slot that has been

initialized to a String value.

The abstract operation

thisStringValue

takes argument

value

. It performs the following steps when called:

1. If

Type

(

value

) is String, return

value

2. If

Type

(

value

) is Object and

value

has a [[StringData]] internal slot, then

a. Let

value

.[[StringData]].

Assert

Type

(

) is String.

The

raw

function is intended for use as a tag function of a Tagged Template (

13.3.11

). When

called as such, the first argument will be a well formed template object and the rest parameter
will contain the substitution values.

22.1.3 Properties of the String Prototype Object

555

c. Return

3. Throw a

TypeError

exception.

NOTE 1

When the

charAt

method is called with one argument

pos

, the following steps are taken:

1. Let

be ?

RequireObjectCoercible

(

this

value).

2. Let

be ?

ToString

(

3. Let

position

be ?

ToIntegerOrInfinity

(

pos

4. Let

size

be the length of

5. If

position

< 0 or

position

≥

size

, return the empty String.

6. Return the String value of length 1, containing one code unit from

, namely the code unit at index

position

NOTE 2

NOTE 1

When the

charCodeAt

method is called with one argument

pos

, the following steps are taken:

1. Let

be ?

RequireObjectCoercible

(

this

value).

2. Let

be ?

ToString

(

3. Let

position

be ?

ToIntegerOrInfinity

(

pos

4. Let

size

be the length of

5. If

position

< 0 or

position

≥

size

, return

NaN

6. Return the

Number value

for the numeric value of the code unit at index

position

within the String

NOTE 2

Returns a single element String containing the code unit at index

pos

within the String value

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

pos

is an

integral Number

, then the result of

x.charAt(pos)

is equivalent to the result of

x.substring(pos, pos + 1)

The

charAt

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.

Returns a Number (a non-negative

integral Number

less than 2

) that is the numeric value of the

code unit 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

NaN

The

charCodeAt

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.1 String.prototype.charAt (

pos

)

22.1.3.2 String.prototype.charCodeAt (

pos

)

22.1.3.3 String.prototype.codePointAt (

pos

)

556

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