Reference number ECMA-123:2009

© Ecma International 2009

ECMA-402 4th Edition / June 2017

ECMAScript® 2017

Internationalization API Specification

COPYRIGHT PROTECTED DOCUMENT

© Ecma International 2017

© Ecma International 2017 i

Copyright notice

Copyright © 2017 Ecma International Ecma International Rue du Rhone 114 CH-1204 Geneva Tel: +41 22 849 6000 Fax: +41 22 849 6001 Web: http://www.ecma-international.org This document and possible translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to Ecma International, except as needed for the purpose of developing any document or deliverable produced by Ecma International (in which case the rules applied to copyrights must be followed) or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by Ecma International or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and ECMA INTERNATIONAL DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE." Software License All Software contained in this document ("Software)" is protected by copyright and is being made available under the "BSD License", included below. This Software may be subject to third party rights (rights from parties other than Ecma International), including patent rights, and no licenses under such third party rights are granted under this license even if the third party concerned is a member of Ecma International. SEE THE ECMA CODE OF CONDUCT IN PATENT MATTERS AVAILABLE AT http://www.ecma-international.org/memento/codeofconduct.htm FOR INFORMATION REGARDING THE LICENSING OF PATENT CLAIMS THAT ARE REQUIRED TO IMPLEMENT ECMA INTERNATIONAL STANDARDS*. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the authors nor Ecma International may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE ECMA INTERNATIONAL "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ECMA INTERNATIONAL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

ii © Ecma International 2017

Introduction1Scope2Conformance3NormativeReferences4Overview4.1Internationalization,Localization,andGlobalization4.2APIOverview4.3ImplementationDependencies

5NotationalConventions5.1Well-KnownIntrinsicObjects

6IdentiLicationofLocales,Currencies,andTimeZones6.1CaseSensitivityandCaseMapping6.2LanguageTags6.2.1UnicodeLocaleExtensionSequences6.2.2IsStructurallyValidLanguageTag(locale)6.2.3CanonicalizeLanguageTag(locale)6.2.4DefaultLocale()

6.3CurrencyCodes6.3.1IsWellFormedCurrencyCode(currency)

6.4TimeZoneNames

ECMAScript®2017InternationalizationAPISpeci9ication

TableofContents

6.4.1IsValidTimeZoneName(timeZone)6.4.2CanonicalizeTimeZoneName6.4.3DefaultTimeZone()

7RequirementsforStandardBuilt-inECMAScriptObjects8TheIntlObject8.1ConstructorPropertiesoftheIntlObject8.1.1Intl.Collator(...)8.1.2Intl.NumberFormat(...)8.1.3Intl.DateTimeFormat(...)

8.2FunctionPropertiesoftheIntlObject8.2.1Intl.getCanonicalLocales(locales)

9LocaleandParameterNegotiation9.1InternalslotsofServiceConstructors9.2AbstractOperations9.2.1CanonicalizeLocaleList(locales)9.2.2BestAvailableLocale(availableLocales,locale)9.2.3LookupMatcher(availableLocales,requestedLocales)9.2.4BestFitMatcher(availableLocales,requestedLocales)9.2.5UnicodeExtensionSubtags(extension)9.2.6ResolveLocale(availableLocales,requestedLocales,options,relevantExtensionKeys,localeData)9.2.7LookupSupportedLocales(availableLocales,requestedLocales)9.2.8BestFitSupportedLocales(availableLocales,requestedLocales)9.2.9SupportedLocales(availableLocales,requestedLocales,options)9.2.10GetOption(options,property,type,values,fallback)9.2.11GetNumberOption(options,property,minimum,maximum,fallback)

10CollatorObjects10.1TheIntl.CollatorConstructor10.1.1InitializeCollator(collator,locales,options)

10.1.2Intl.Collator([locales[,options]])10.2PropertiesoftheIntl.CollatorConstructor10.2.1Intl.Collator.prototype10.2.2Intl.Collator.supportedLocalesOf(locales[,options])10.2.3InternalSlots

10.3PropertiesoftheIntl.CollatorPrototypeObject10.3.1Intl.Collator.prototype.constructor10.3.2Intl.Collator.prototype[@@toStringTag]10.3.3getIntl.Collator.prototype.compare10.3.4CollatorCompareFunctions10.3.5Intl.Collator.prototype.resolvedOptions()

10.4PropertiesofIntl.CollatorInstances11NumberFormatObjects11.1AbstractOperationsForNumberFormatObjects11.1.1SetNumberFormatDigitOptions(intlObj,options,mnfdDefault)11.1.2InitializeNumberFormat(numberFormat,locales,options)11.1.3CurrencyDigits(currency)11.1.4NumberFormatFunctions11.1.5FormatNumberToString(numberFormat,x)11.1.6PartitionNumberPattern(numberFormat,x)11.1.7FormatNumber(numberFormat,x)11.1.8FormatNumberToParts(numberFormat,x)11.1.9ToRawPrecision(x,minPrecision,maxPrecision)11.1.10ToRawFixed(x,minInteger,minFraction,maxFraction)11.1.11UnwrapNumberFormat(nf)

11.2TheIntl.NumberFormatConstructor11.2.1Intl.NumberFormat([locales[,options]])

11.3PropertiesoftheIntl.NumberFormatConstructor11.3.1Intl.NumberFormat.prototype11.3.2Intl.NumberFormat.supportedLocalesOf(locales[,options])

11.3.3Internalslots11.4PropertiesoftheIntl.NumberFormatPrototypeObject11.4.1Intl.NumberFormat.prototype.constructor11.4.2Intl.NumberFormat.prototype[@@toStringTag]11.4.3getIntl.NumberFormat.prototype.format11.4.4Intl.NumberFormat.prototype.resolvedOptions()

11.5PropertiesofIntl.NumberFormatInstances12DateTimeFormatObjects12.1AbstractOperationsForDateTimeFormatObjects12.1.1InitializeDateTimeFormat(dateTimeFormat,locales,options)12.1.2ToDateTimeOptions(options,required,defaults)12.1.3BasicFormatMatcher(options,formats)12.1.4BestFitFormatMatcher(options,formats)12.1.5DateTimeFormatFunctions12.1.6PartitionDateTimePattern(dateTimeFormat,x)12.1.7FormatDateTime(dateTimeFormat,x)12.1.8FormatDateTimeToParts(dateTimeFormat,x)12.1.9ToLocalTime(date,calendar,timeZone)12.1.10UnwrapDateTimeFormat(dtf)

13TheIntl.DateTimeFormatConstructor13.1Intl.DateTimeFormat([locales[,options]])

14PropertiesoftheIntl.DateTimeFormatConstructor14.1Intl.DateTimeFormat.prototype14.2Intl.DateTimeFormat.supportedLocalesOf(locales[,options])14.3Internalslots

15PropertiesoftheIntl.DateTimeFormatPrototypeObject15.1Intl.DateTimeFormat.prototype.constructor15.2Intl.DateTimeFormat.prototype[@@toStringTag]15.3getIntl.DateTimeFormat.prototype.format15.4Intl.DateTimeFormat.prototype.formatToParts([date])15.5Intl.DateTimeFormat.prototype.resolvedOptions()

16PropertiesofIntl.DateTimeFormatInstances17LocaleSensitiveFunctionsoftheECMAScriptLanguageSpeciLication17.1PropertiesoftheStringPrototypeObject17.1.1String.prototype.localeCompare(that[,locales[,options]])17.1.2String.prototype.toLocaleLowerCase([locales])17.1.3String.prototype.toLocaleUpperCase([locales])

17.2PropertiesoftheNumberPrototypeObject17.2.1Number.prototype.toLocaleString([locales[,options]])

17.3PropertiesoftheDatePrototypeObject17.3.1Date.prototype.toLocaleString([locales[,options]])17.3.2Date.prototype.toLocaleDateString([locales[,options]])17.3.3Date.prototype.toLocaleTimeString([locales[,options]])

17.4PropertiesoftheArrayPrototypeObject17.4.1Array.prototype.toLocaleString([locales[,options]])

AImplementationDependentBehaviourBAdditionsandChangesThatIntroduceIncompatibilitieswithPriorEditionsCCopyright&SoftwareLicense

ThisspeciLication'ssourcecanbefoundathttps://github.com/tc39/ecma402.

TheECMAScript2017InternationalizationAPISpeciLication(ECMA-4024thEdition),provideskeylanguagesensitivefunctionalityasacomplementtotheECMAScript2017LanguageSpeciLication(ECMA-

Introduction

2628thEditionorsuccessor).Itsfunctionalityhasbeenselectedfromthatofwell-establishedinternationalizationAPIssuchasthoseoftheInternationalizationComponentsforUnicode(ICU)library,ofthe.NETframework,oroftheJavaplatform.

The1stEditionAPIwasdevelopedbyanad-hocgroupestablishedbyEcmaTC39inSeptember2010basedonaproposalbyNebojšaĆirićandJungshikShin.

Internationalizationofsoftwareisnevercomplete.WeexpectsigniLicantenhancementsinfutureeditionsofthisspeciLication.

Editor,4rdEditionCaridyPatiño

ContributorsZibiBranieckiDanielEhrenberg

Editor,3rdEditionCaridyPatiño

ContributorsRickWaldronAndréBargullEricFerraiuoloStevenR.LoomisZibiBraniecki

Editor,2ndEditionRickWaldron

ContributorsNorbertLindenbergAllenWirfs-BrockAndréBargullStevenR.Loomis

Editor,1stEditionNorbertLindenberg

ContributorsEricAlbrightNebojšaĆirićPeterConstableMarkDavisRichardGillamStevenLoomisMihaiNitaAddisonPhillipsRoozbehPournaderJungshikShinShawnSteeleAllenWirfs-Brock

FeedbackandReviewfromErikArvidssonJohnJ.BartonZbigniewBranieckiMarcosCáceresBrendanEichJohnEmmonsGordonP.HemsleyDavidHermanLukeHobanOliverHuntSureshJayabalanYehudaKatzMarkS.MillerAndrewPaprockiAdamPellerAxelRauschmayerAndreasRossberg

AlexRussellMarkusSchererDmitrySoshnikovYusukeSuzukiJohnTamplinRickWaldronAntonYatsenkoNicholasZakas

ThisStandarddeLinestheapplicationprogramminginterfaceforECMAScriptobjectsthatsupportprogramsthatneedtoadapttothelinguisticandculturalconventionsusedbydifferenthumanlanguagesandcountries.

AconformingimplementationoftheECMAScript2017InternationalizationAPISpeciLicationmustconformtotheECMAScript2017LanguageSpeciLication(ECMA-2628thEdition,orsuccessor),andmustprovideandsupportalltheobjects,properties,functions,andprogramsemanticsdescribedinthisspeciLication.

AconformingimplementationoftheECMAScript2017InternationalizationAPISpeciLicationispermittedtoprovideadditionalobjects,properties,andfunctionsbeyondthosedescribedinthisspeciLication.Inparticular,aconformingimplementationoftheECMAScript2017InternationalizationAPISpeciLicationis

1 Scope

2 Conformance

permittedtoprovidepropertiesnotdescribedinthisspeciLication,andvaluesforthoseproperties,forobjectsthataredescribedinthisspeciLication.AconformingimplementationisnotpermittedtoaddoptionalargumentstothefunctionsdeLinedinthisspeciLication.

Aconformingimplementationispermittedtoacceptadditionalvalues,andthenhaveimplementation-deLinedbehaviourinsteadofthrowingaRangeError,forthefollowingpropertiesofoptionsarguments:

TheoptionspropertylocaleMatcherinallconstructorsandsupportedLocalesOfmethods.TheoptionspropertiesusageandsensitivityintheCollatorconstructor.TheoptionspropertiesstyleandcurrencyDisplayintheNumberFormatconstructor.TheoptionspropertiesminimumIntegerDigits,minimumFractionDigits,maximumFractionDigits,minimumSigniLicantDigits,andmaximumSigniLicantDigitsintheNumberFormatconstructor,providedthattheadditionalvaluesareinterpretedasintegervalueshigherthanthespeciLiedlimits.TheoptionspropertieslistedinTable4intheDateTimeFormatconstructor.TheoptionspropertyformatMatcherintheDateTimeFormatconstructor.

Thefollowingreferenceddocumentsarerequiredfortheapplicationofthisdocument.Fordatedreferences,onlytheeditioncitedapplies.Forundatedreferences,thelatesteditionofthereferenced

3 NormativeReferences

document(includinganyamendments)applies.

ECMAScript2017LanguageSpeciLication(ECMA-2628thEdition,orsuccessor).http://www.ecma-international.org/publications/standards/Ecma-262.htm

NOTE Throughoutthisdocument,thephrase"ES2017,x"(wherexisasequenceofnumbersseparatedbyperiods)maybeusedasshorthandfor"ECMAScript2017LanguageSpeciLication(ECMA-2628thEdition,subclausex)".

ISO/IEC10646:2014:InformationTechnology–UniversalMultiple-OctetCodedCharacterSet(UCS)plusAmendment1:2015andAmendment2,plusadditionalamendmentsandcorrigenda,orsuccessor

http://www.iso.org/iso/catalogue_detail.htm?csnumber=63182http://www.iso.org/iso/catalogue_detail.htm?csnumber=65047http://www.iso.org/iso/catalogue_detail.htm?csnumber=66791

ISO4217:2015,Codesfortherepresentationofcurrenciesandfunds,orsuccessorIETFBCP47:

RFC5646,TagsforIdentifyingLanguages,orsuccessorRFC4647,MatchingofLanguageTags,orsuccessor

IETFRFC6067,BCP47ExtensionU,orsuccessorIANATimeZoneDatabaseTheUnicodeStandardUnicodeTechnicalStandard35,UnicodeLocaleDataMarkupLanguage

Thissectioncontainsanon-normativeoverviewoftheECMAScript2017InternationalizationAPISpeciLication.

Internationalizationofsoftwaremeansdesigningitsuchthatitsupportsorcanbeeasilyadaptedtosupporttheneedsofusersspeakingdifferentlanguagesandhavingdifferentculturalexpectations,andenablesworldwidecommunicationbetweenthem.LocalizationthenistheactualadaptationtoaspeciLiclanguageandculture.Globalizationofsoftwareiscommonlyunderstoodtobethecombinationofinternationalizationandlocalization.Globalizationstartsatthelowestlevelbyusingatextrepresentationthatsupportsalllanguagesintheworld,andusingstandardidentiLierstoidentifylanguages,countries,timezones,andotherrelevantparameters.Itcontinueswithusingauserinterfacelanguageanddatapresentationthattheuserunderstands,andLinallyoftenrequiresproduct-speciLicadaptationstotheuser’slanguage,culture,andenvironment.

TheECMAScript2017LanguageSpeciLicationlaysthefoundationbyusingUnicodefortextrepresentationandbyprovidingafewlanguage-sensitivefunctions,butgivesapplicationslittlecontroloverthebehaviourofthesefunctions.TheECMAScript2017InternationalizationAPISpeciLicationbuildsonthisbyprovidingasetofcustomizablelanguage-sensitivefunctionality.TheAPIisusefulevenforapplicationsthatthemselvesarenotinternationalized,asevenapplicationstargetingonlyonelanguageandoneregionneedtoproperlysupportthatonelanguageandregion.However,theAPIalsoenablesapplicationsthatsupportmultiplelanguagesand

4 Overview

4.1 Internationalization,Localization,andGlobalization

regions,evenconcurrently,asmaybeneededinserverenvironments.

TheECMAScript2017InternationalizationAPISpeciLicationisdesignedtocomplementtheECMAScript2017LanguageSpeciLicationbyprovidingkeylanguage-sensitivefunctionality.TheAPIcanbeaddedtoanimplementationoftheECMAScript2017LanguageSpeciLication(ECMA-2628thEdition,orsuccessor).

TheECMAScript2017InternationalizationAPISpeciLicationprovidesseveralkeypiecesoflanguage-sensitivefunctionalitythatarerequiredinmostapplications:Stringcomparison(collation),numberformatting,dateandtimeformatting,andcaseconversion.WhiletheECMAScript2017LanguageSpeciLicationprovidesfunctionsforthisbasicfunctionality(onArray.prototype:toLocaleString;onString.prototype:localeCompare,toLocaleLowerCase,toLocaleUpperCase;onNumber.prototype:toLocaleString;onDate.prototype:toLocaleString,toLocaleDateString,andtoLocaleTimeString),itleavestheactualbehaviourofthesefunctionslargelyuptoimplementationstodeLine.TheECMAScript2017InternationalizationAPISpeciLicationprovidesadditionalfunctionality,controloverthelanguageandoverdetailsofthebehaviourtobeused,andamorecompletespeciLicationofrequiredfunctionality.

ApplicationscanusetheAPIintwoways:

1. Directly,byusingtheconstructorsIntl.Collator,Intl.NumberFormat,orIntl.DateTimeFormattoconstructanobject,specifyingalistofpreferredlanguagesandoptionstoconLigurethebehaviouroftheresultingobject.Theobjectthen

4.2 APIOverview

providesamainfunction(compareorformat),whichcanbecalledrepeatedly.ItalsoprovidesaresolvedOptionsfunction,whichtheapplicationcanusetoLindouttheexactconLigurationoftheobject.

2. Indirectly,byusingthefunctionsoftheECMAScript2017LanguageSpeciLicationmentionedabove.ThecollationandformattingfunctionsarerespeciLiedinthisspeciLicationtoacceptthesameargumentsastheCollator,NumberFormat,andDateTimeFormatconstructorsandproducethesameresultsastheircompareorformatmethods.ThecaseconversionfunctionsarerespeciLiedtoacceptalistofpreferredlanguages.

TheIntlobjectisusedtopackageallfunctionalitydeLinedintheECMAScript2017InternationalizationAPISpeciLicationtoavoidnamecollisions.

Duetothenatureofinternationalization,theAPIspeciLicationhastoleaveseveraldetailsimplementationdependent:

Thesetoflocalesthatanimplementationsupportswithadequatelocalizations:Linguistsestimatethenumberofhumanlanguagestoaround6000,andthemorewidelyspokenoneshavevariationsbasedonregionsorotherparameters.Evenlargelocaledatacollections,suchastheCommonLocaleDataRepository,coveronlyasubsetofthislargeset.Implementationstargetingresource-constraineddevicesmayhavetofurtherreducethesubset.Theexactformoflocalizationssuchasformatpatterns:Inmanycaseslocale-dependentconventionsarenotstandardized,sodifferentformsmayexistsidebyside,ortheyvaryovertime.Differentinternationalizationlibrariesmayhaveimplemented

4.3 ImplementationDependencies

differentforms,withoutanyofthembeingactuallywrong.InordertoallowthisAPItobeimplementedontopofexistinglibraries,suchvariationshavetobepermitted.SubsetsofUnicode:Someoperations,suchascollation,operateonstringsthatcanincludecharactersfromtheentireUnicodecharacterset.However,boththeUnicodestandardandtheECMAScriptstandardallowimplementationstolimittheirfunctionalitytosubsetsoftheUnicodecharacterset.Inaddition,localeconventionstypicallydon’tspecifythedesiredbehaviourfortheentireUnicodecharacterset,butonlyforthosecharactersthatarerelevantforthelocale.WhiletheUnicodeCollationAlgorithmcombinesadefaultcollationorderfortheentireUnicodecharactersetwiththeabilitytotailorforlocalconventions,subsetsandtailoringsstillresultindifferencesinbehaviour.

ThisstandardusesasubsetofthenotationalconventionsoftheECMAScript2017LanguageSpeciLication(ECMA-2628thEdition),asES2017:

ObjectInternalMethodsandInternalSlots,asdescribedinES2017,6.1.7.2.Algorithmconventions,includingtheuseofabstractoperations,asdescribedinES2017,7.1,7.2,7.3.InternalSlots,asdescribedinES2017,9.1.TheListandRecordSpeciLicationType,asdescribedinES2017,6.2.1.

NOTE AsdescribedintheECMAScriptLanguageSpeciLication,algorithmsareusedtopreciselyspecify

5 NotationalConventions

therequiredsemanticsofECMAScriptconstructs,butarenotintendedtoimplytheuseofanyspeciLicimplementationtechnique.InternalslotsareusedtodeLinethesemanticsofobjectvalues,butarenotpartoftheAPI.TheyaredeLinedpurelyforexpositorypurposes.AnimplementationoftheAPImustbehaveasifitproducedandoperateduponinternalslotsinthemannerdescribedhere.

AsanextensiontotheRecordSpeciLicationType,thenotation"[[<name>]]"denotesaLieldwhosenameisgivenbythevariablename,whichmusthaveaStringvalue.Forexample,ifavariableshasthevalue"a",then[[<s>]]denotestheLield[[<a>]].

ForECMAScriptobjects,thisstandardmayusevariable-namedinternalslots:Thenotation"[[<name>]]"denotesaninternalslotwhosenameisgivenbythevariablename,whichmusthaveaStringvalue.Forexample,ifavariableshasthevalue"a",then[[<s>]]denotesthe[[<a>]]internalslot.

ThisspeciLicationusesblocksdemarcatedas NORMATIVEOPTIONALtodenotethesenseofAnnexBinECMA262.Thatis,normativeoptionalsectionsarerequiredwhentheECMAScripthostisawebbrowser.ThecontentofthesectionisnormativebutoptionaliftheECMAScripthostisnotawebbrowser.

ThefollowingtableextendstheWell-KnownIntrinsicObjectstabledeLinedinES2017,6.1.7.4.

Table1:Well-knownIntrinsicObjects(Extensions)

IntrinsicName GlobalName ECMAScriptLanguage

5.1 Well-KnownIntrinsicObjects

Association

%Date_now% Date.now Theinitialvalueofthenowdatapropertyoftheintrinsic(ES2017,

%Intl% Intl TheIntl

%Collator% Intl.Collator TheIntl.Collatorconstructor(

%CollatorPrototype% Intl.Collator.prototype Theinitialvalueoftheprototype

propertyoftheintrinsic%Collator%

%NumberFormat% Intl.NumberFormat TheIntl.NumberFormat

constructor(

%NumberFormatPrototype% Intl.NumberFormat.prototype Theinitialvalueoftheprototype

propertyoftheintrinsic%NumberFormat%(11.3.1).

%DateTimeFormat% Intl.DateTimeFormat TheIntl.DateTimeFormat

constructor(

%DateTimeFormatPrototype% Intl.DateTimeFormat.prototype Theinitialvalueoftheprototype

propertyoftheintrinsic%DateTimeFormat%(14.1).

%StringProto_includes% String.prototype.includes Theinitialvalueoftheincludes

propertyoftheintrinsic%StringPrototype%(ES2017,

%StringProto_indexOf% String.prototype.indexOf TheinitialvalueoftheindexOf

oftheintrinsic%StringPrototype%(ES2017,

%ArrayProto_indexOf% Array.prototype.indexOf TheinitialvalueoftheindexOf

oftheintrinsic%ArrayPrototype%(ES2017,

ThisclausedescribestheStringvaluesusedintheECMAScript2017InternationalizationAPISpeciLicationtoidentifylocales,currencies,andtimezones.

TheStringvaluesusedtoidentifylocales,currencies,andtimezonesareinterpretedinacase-insensitivemanner,treatingtheUnicode

6 Identi9icationofLocales,Currencies,andTimeZones

6.1 CaseSensitivityandCaseMapping

BasicLatincharacters"A"to"Z"(U+0041toU+005A)asequivalenttothecorrespondingBasicLatincharacters"a"to"z"(U+0061toU+007A).Noothercasefoldingequivalencesareapplied.Whenmappingtouppercase,amappingshallbeusedthatmapscharactersintherange"a"to"z"(U+0061toU+007A)tothecorrespondingcharactersintherange"A"to"Z"(U+0041toU+005A)andmapsnoothercharacterstothelatterrange.

EXAMPLES"ß"(U+00DF)mustnotmatchorbemappedto"SS"(U+0053,U+0053)."ı"(U+0131)mustnotmatchorbemappedto"I"(U+0049).

TheECMAScript2017InternationalizationAPISpeciLicationidentiLieslocalesusinglanguagetagsasdeLinedbyIETFBCP47(RFCs5646and4647ortheirsuccessors),whichmayincludeextensionssuchasthoseregisteredthroughRFC6067.TheircanonicalformisspeciLiedinRFC5646section4.5oritssuccessor.

BCP47languagetagsthatmeetthosevaliditycriteriaofRFC5646section2.2.9thatcanbeveriLiedwithoutreferencetotheIANALanguageSubtagRegistryareconsideredstructurallyvalid.AllstructurallyvalidlanguagetagsarevalidforusewiththeAPIsdeLinedbythisstandard.However,thesetoflocalesandthuslanguagetagsthatanimplementationsupportswithadequatelocalizationsisimplementationdependent.TheconstructorsCollator,NumberFormat,andDateTimeFormatmapthelanguagetagsusedinrequeststolocalessupportedbytheirrespectiveimplementations.

6.2 LanguageTags

6.2.1 UnicodeLocaleExtensionSequences

Thisstandardusestheterm"Unicodelocaleextensionsequence"foranysubstringofalanguagetagthatisnotpartofaprivateusesubtagsequence,startswithaseparator"-"andthesingleton"u",andincludesthemaximumsequenceoffollowingnon-singletonsubtagsandtheirpreceding"-"separators.

TheIsStructurallyValidLanguageTagabstractoperationveriLiesthatthelocaleargument(whichmustbeaStringvalue)

representsawell-formedBCP47languagetagasspeciLiedinRFC5646section2.1,orsuccessor,doesnotincludeduplicatevariantsubtags,anddoesnotincludeduplicatesingletonsubtags.

TheabstractoperationreturnstrueiflocalecanbegeneratedfromtheABNFgrammarinsection2.1oftheRFC,startingwithLanguage-Tag,anddoesnotcontainduplicatevariantorsingletonsubtags(otherthanasaprivateusesubtag).Itreturnsfalseotherwise.TerminalvaluecharactersinthegrammarareinterpretedastheUnicodeequivalentsoftheASCIIoctetvaluesgiven.

TheCanonicalizeLanguageTagabstractoperationreturnsthecanonicalandcase-regularizedformofthelocaleargument(whichmustbeaStringvaluethatisastructurallyvalidBCP47languagetagasveriLiedbytheIsStructurallyValidLanguageTagabstractoperation).IttakesthestepsspeciLiedinRFC5646section4.5,orsuccessor,tobringthelanguagetagintocanonicalform,andtoregularizethecaseofthesubtags,butdoesnottakethestepstobringalanguagetaginto"extlangform"andtoreordervariantsubtags.

6.2.2 IsStructurallyValidLanguageTag(locale)

6.2.3 CanonicalizeLanguageTag(locale)

ThespeciLicationsforextensionstoBCP47languagetags,suchasRFC6067,mayincludecanonicalizationrulesfortheextensionsubtagsequencestheydeLinethatgobeyondthecanonicalizationrulesofRFC5646section4.5.Implementationsareallowed,butnotrequired,toapplytheseadditionalrules.

TheDefaultLocaleabstractoperationreturnsaStringvaluerepresentingthestructurallyvalid(6.2.2)andcanonicalized(6.2.3)BCP47languagetagforthehostenvironment’scurrentlocale.

TheECMAScript2017InternationalizationAPISpeciLicationidentiLiescurrenciesusing3-lettercurrencycodesasdeLinedbyISO4217.Theircanonicalformisuppercase.

Allwell-formed3-letterISO4217currencycodesareallowed.However,thesetofcombinationsofcurrencycodeandlanguagetagforwhichlocalizedcurrencysymbolsareavailableisimplementationdependent.Wherealocalizedcurrencysymbolisnotavailable,theISO4217currencycodeisusedforformatting.

TheIsWellFormedCurrencyCodeabstractoperationveriLiesthatthecurrencyargument(whichmustbeaStringvalue)representsawell-formed3-letterISOcurrencycode.Thefollowingstepsaretaken:

1. Letnormalizedbetheresultofmappingcurrencytouppercaseasdescribedin6.1.

6.2.4 DefaultLocale()

6.3 CurrencyCodes

6.3.1 IsWellFormedCurrencyCode(currency)

2. Ifthestringlengthofnormalizedisnot3,returnfalse.3. Ifnormalizedcontainsanycharacterthatisnotintherange"A"to"Z"(U+0041toU+005A),returnfalse.

4. Returntrue.

TheECMAScript2017InternationalizationAPISpeciLicationidentiLiestimezonesusingtheZoneandLinknamesoftheIANATimeZoneDatabase.TheircanonicalformisthecorrespondingZonenameinthecasingusedintheIANATimeZoneDatabase.

AllregisteredZoneandLinknamesareallowed.Implementationsmustrecognizeallsuchnames,andusebestavailablecurrentandhistoricalinformationabouttheiroffsetsfromUTCandtheirdaylightsavingtimerulesincalculations.However,thesetofcombinationsoftimezonenameandlanguagetagforwhichlocalizedtimezonenamesareavailableisimplementationdependent.

TheIsValidTimeZoneNameabstractoperationveriLiesthatthetimeZoneargument(whichmustbeaStringvalue)representsavalidZoneorLinknameoftheIANATimeZoneDatabase.

TheabstractoperationreturnstrueiftimeZone,convertedtouppercaseasdescribedin6.1,isequaltooneoftheZoneorLinknamesoftheIANATimeZoneDatabase,convertedtouppercaseasdescribedin6.1.Itreturnsfalseotherwise.

6.4 TimeZoneNames

6.4.1 IsValidTimeZoneName(timeZone)

6.4.2 CanonicalizeTimeZoneName

TheCanonicalizeTimeZoneNameabstractoperationreturnsthecanonicalandcase-regularizedformofthetimeZoneargument(whichmustbeaStringvaluethatisavalidtimezonenameasveriLiedbytheIsValidTimeZoneNameabstractoperation).Thefollowingstepsaretaken:

1. LetianaTimeZonebetheZoneorLinknameoftheIANATimeZoneDatabasesuchthattimeZone,convertedtouppercaseasdescribedin6.1,isequaltoianaTimeZone,convertedtouppercaseasdescribedin6.1.

2. IfianaTimeZoneisaLinkname,letianaTimeZonebethecorrespondingZonenameasspeciLiedinthe"backward"LileoftheIANATimeZoneDatabase.

3. IfianaTimeZoneis"Etc/UTC"or"Etc/GMT",return"UTC".4. ReturnianaTimeZone.

TheIntl.DateTimeFormatconstructorallowsthistimezonename;ifthetimezoneisnotspeciLied,thehostenvironment’scurrenttimezoneisused.ImplementationsshallsupportUTCandthehostenvironment’scurrenttimezone(ifdifferentfromUTC)informatting.

TheDefaultTimeZoneabstractoperationreturnsaStringvaluerepresentingthevalid(6.4.1)andcanonicalized(6.4.2)timezonenameforthehostenvironment’scurrenttimezone.

6.4.3 DefaultTimeZone()

7 RequirementsforStandardBuilt-inECMAScriptObjects

UnlessspeciLiedotherwiseinthisdocument,theobjects,functions,andconstructorsdescribedinthisstandardaresubjecttothegenericrequirementsandrestrictionsspeciLiedforstandardbuilt-inECMAScriptobjectsintheECMAScript2017LanguageSpeciLication,8thedition,clause17,orsuccessor.

TheIntlobjectisthe%Intl%intrinsicobjectandtheinitialvalueoftheIntlpropertyoftheglobalobject.TheIntlobjectisasingleordinaryobject.

Thevalueofthe[[Prototype]]internalslotoftheIntlobjectistheintrinsicobject%ObjectPrototype%.

TheIntlobjectisnotafunctionobject.Itdoesnothavea[[Construct]]internalmethod;itisnotpossibletousetheIntlobjectasaconstructorwiththenewoperator.TheIntlobjectdoesnothavea[[Call]]internalmethod;itisnotpossibletoinvoketheIntlobjectasafunction.

TheIntlobjecthasaninternalslot,[[FallbackSymbol]],whichisanew%Symbol%inthecurrentrealm.

See10.

8 TheIntlObject

8.1 ConstructorPropertiesoftheIntlObject

8.1.1 Intl.Collator(...)

See11.

See12.

WhenthegetCanonicalLocalesmethodiscalledwithargumentlocales,thefollowingstepsaretaken:

1. Letllbe?CanonicalizeLocaleList(locales).2. ReturnCreateArrayFromList(ll).

Theconstructorsfortheobjectsprovidinglocalesensitiveservices,Collator,NumberFormat,andDateTimeFormat,useacommonpatterntonegotiatetherequestsrepresentedbythelocalesandoptionsargumentsagainsttheactualcapabilitiesoftheirimplementations.Thecommonbehaviourisdescribedhereintermsofinternalslotsdescribingthecapabilitiesandofabstractoperationsusingtheseinternalslots.

8.1.2 Intl.NumberFormat(...)

8.1.3 Intl.DateTimeFormat(...)

8.2 FunctionPropertiesoftheIntlObject

8.2.1 Intl.getCanonicalLocales(locales)

9 LocaleandParameterNegotiation

TheconstructorsIntl.Collator,Intl.NumberFormat,andIntl.DateTimeFormathavethefollowinginternalslots:

[[AvailableLocales]]isaListthatcontainsstructurallyvalid(6.2.2)andcanonicalized(6.2.3)BCP47languagetagsidentifyingthelocalesforwhichtheimplementationprovidesthefunctionalityoftheconstructedobjects.LanguagetagsonthelistmustnothaveaUnicodelocaleextensionsequence.ThelistmustincludethevaluereturnedbytheDefaultLocaleabstractoperation(6.2.4),andmustnotincludeduplicates.Implementationsmustincludein[[AvailableLocales]]localesthatcanserveasfallbacksinthealgorithmusedtoresolvelocales(see9.2.6).Forexample,implementationsthatprovidea"de-DE"localemustincludea"de"localethatcanserveasafallbackforrequestssuchas"de-AT"and"de-CH".Forlocalesthatincurrentusagewouldincludeascriptsubtag(suchasChineselocales),old-stylelanguagetagswithoutscriptsubtagsmustbeincludedsuchthat,forexample,requestsfor"zh-TW"and"zh-HK"leadtooutputintraditionalChineseratherthanthedefaultsimpliLiedChinese.Theorderingofthelocaleswithin[[AvailableLocales]]isirrelevant.[[RelevantExtensionKeys]]isaListofkeysofthelanguagetagextensionsdeLinedinUnicodeTechnicalStandard35thatarerelevantforthefunctionalityoftheconstructedobjects.[[SortLocaleData]]and[[SearchLocaleData]](forIntl.Collator)and[[LocaleData]](forIntl.NumberFormatandIntl.DateTimeFormat)areobjectsthathavepropertiesforeachlocalecontainedin[[AvailableLocales]].Thevalueofeachofthesepropertiesmustbeanobjectthathaspropertiesforeachkeycontainedin[[RelevantExtensionKeys]].Thevalueofeachofthesepropertiesmustbeanon-emptyarrayofthosevaluesdeLinedinUnicodeTechnicalStandard35forthegivenkeythat

9.1 InternalslotsofServiceConstructors

aresupportedbytheimplementationforthegivenlocale,withtheLirstelementprovidingthedefaultvalue.

EXAMPLEAnimplementationofDateTimeFormatmightincludethelanguagetag"th"inits[[AvailableLocales]]internalslot,andmust(accordingto14.3)includethekey"ca"inits[[RelevantExtensionKeys]]internalslot.ForThai,the"buddhist"calendarisusuallythedefault,butanimplementationmightalsosupportthecalendars"gregory","chinese",and"islamicc"forthelocale"th".The[[LocaleData]]internalslotwouldthereforeatleastinclude{"th":{ca:["buddhist","gregory","chinese","islamicc"]}}.

WherethefollowingabstractoperationstakeanavailableLocalesargument,itmustbean[[AvailableLocales]]ListasspeciLiedin9.1.

TheabstractoperationCanonicalizeLocaleListtakesthefollowingsteps:

1. Iflocalesisunde9ined,thena. ReturnanewemptyList.

2. LetseenbeanewemptyList.3. IfType(locales)isString,then

a. LetObeCreateArrayFromList(«locales»).4. Else,

a. LetObe?ToObject(locales).5. Letlenbe?ToLength(?Get(O,"length")).6. Letkbe0.7. Repeat,whilek<len

a. LetPkbeToString(k).

9.2 AbstractOperations

9.2.1 CanonicalizeLocaleList(locales)

b. LetkPresentbe?HasProperty(O,Pk).c. IfkPresentistrue,then

i. LetkValuebe?Get(O,Pk).ii. IfType(kValue)isnotStringorObject,throwaTypeErrorexception.

iii. Lettagbe?ToString(kValue).iv. IfIsStructurallyValidLanguageTag(tag)isfalse,

throwaRangeErrorexception.v. LetcanonicalizedTagbeCanonicalizeLanguageTag(tag).

vi. IfcanonicalizedTagisnotanelementofseen,appendcanonicalizedTagasthelastelementofseen.

d. Increasekby1.8. Returnseen.

NOTE1 Non-normativesummary:TheabstractoperationinterpretsthelocalesargumentasanarrayandcopiesitselementsintoaList,validatingtheelementsasstructurallyvalidlanguagetagsandcanonicalizingthem,andomittingduplicates.

NOTE2 RequiringkValuetobeaStringorObjectmeansthattheNumbervalueNaNwillnotbeinterpretedasthelanguagetag"nan",whichstandsforMinNanChinese.

TheBestAvailableLocaleabstractoperationcomparestheprovidedargumentlocale,whichmustbeaStringvaluewithastructurallyvalidandcanonicalizedBCP47languagetag,againstthelocalesinavailableLocalesandreturnseitherthelongestnon-emptypreLixoflocalethatisanelementofavailableLocales,orunde9inedifthereisnosuchelement.ItusesthefallbackmechanismofRFC4647,section

9.2.2 BestAvailableLocale(availableLocales,locale)

3.4.Thefollowingstepsaretaken:

1. Letcandidatebelocale.2. Repeat

a. IfavailableLocalescontainsanelementequaltocandidate,returncandidate.

b. Letposbethecharacterindexofthelastoccurrenceof"-"(U+002D)withincandidate.Ifthatcharacterdoesnotoccur,returnunde9ined.

c. Ifpos≥2andthecharacter"-"occursatindexpos-2ofcandidate,decreaseposby2.

d. Letcandidatebethesubstringofcandidatefromposition0,inclusive,topositionpos,exclusive.

TheLookupMatcherabstractoperationcomparesrequestedLocales,whichmustbeaListasreturnedbyCanonicalizeLocaleList,againstthelocalesinavailableLocalesanddeterminesthebestavailablelanguagetomeettherequest.Thefollowingstepsaretaken:

1. Letkbe0.2. LetrLocalesbeCreateArrayFromList(requestedLocales).3. Letlenbe!ToLength(!Get(rLocales,"length")).4. LetavailableLocalebeunde9ined.5. Repeatwhilek<lenandavailableLocaleisunde9ined:

a. Letlocalebe!Get(rLocales,!ToString(k)).b. LetnoExtensionsLocalebetheStringvaluethatislocalewithallUnicodelocaleextensionsequencesremoved.

c. LetavailableLocalebeBestAvailableLocale(availableLocales,noExtensionsLocale).

d. Increasekby1.6. LetresultbeanewRecord.

9.2.3 LookupMatcher(availableLocales,requestedLocales)

7. IfavailableLocaleisnotunde9ined,thena. Setresult.[[locale]]toavailableLocale.b. IflocaleandnoExtensionsLocalearenotthesameStringvalue,theni. LetextensionbetheStringvalueconsistingoftheLirstsubstringoflocalethatisaUnicodelocaleextensionsequence.

ii. Setresult.[[extension]]toextension.8. Else,

a. LetdefLocalebeDefaultLocale().b. Setresult.[[locale]]todefLocale.

9. Returnresult.

NOTE ThealgorithmisbasedontheLookupalgorithmdescribedinRFC4647section3.4,butoptionsspeciLiedthroughUnicodelocaleextensionsequencesareignoredinthelookup.Informationaboutsuchsubsequencesisreturnedseparately.Theabstractoperationreturnsarecordwitha[[locale]]Lield,whosevalueisthelanguagetagoftheselectedlocale,whichmustbeanelementofavailableLocales.IfthelanguagetagoftherequestlocalethatledtotheselectedlocalecontainedaUnicodelocaleextensionsequence,thenthereturnedrecordalsocontainsan[[extension]]LieldwhosevalueistheLirstUnicodelocaleextensionsequencewithintherequestlocalelanguagetag.

TheBestFitMatcherabstractoperationcomparesrequestedLocales,whichmustbeaListasreturnedbyCanonicalizeLocaleList,againstthelocalesinavailableLocalesanddeterminesthebestavailable

9.2.4 BestFitMatcher(availableLocales,requestedLocales)

languagetomeettherequest.Thealgorithmisimplementationdependent,butshouldproduceresultsthatatypicaluseroftherequestedlocaleswouldperceiveasatleastasgoodasthoseproducedbytheLookupMatcherabstractoperation.OptionsspeciLiedthroughUnicodelocaleextensionsequencesmustbeignoredbythealgorithm.Informationaboutsuchsubsequencesisreturnedseparately.Theabstractoperationreturnsarecordwitha[[locale]]Lield,whosevalueisthelanguagetagoftheselectedlocale,whichmustbeanelementofavailableLocales.IfthelanguagetagoftherequestlocalethatledtotheselectedlocalecontainedaUnicodelocaleextensionsequence,thenthereturnedrecordalsocontainsan[[extension]]LieldwhosevalueistheLirstUnicodelocaleextensionsequencewithintherequestlocalelanguagetag.

TheabstractoperationUnicodeExtensionSubtagssplitsextension,whichmustbeaUnicodelocaleextensionsequence,intoitssubtags.Thefollowingstepsaretaken:

1. Letsizebethenumberofelementsinextension.2. Ifsize=0,then

a. Return«».3. LetextensionSubtagsbe«».4. Letattributebetrue.5. Letqbe3.6. Letpbeq.7. Lettbeq.8. Repeat,whileq<size

a. LetcbethecodeunitvalueoftheelementatindexqintheStringextension.

b. Ifcis0x002D(HYPHEN-MINUS),theni. Ifq-p=2,then

9.2.5 UnicodeExtensionSubtags(extension)

1. Ifp-t>1,thena. LettypebeaStringvalueequaltothesubstringofextensionconsistingofthecodeunitsatindicest(inclusive)throughp-1(exclusive).

b. AppendtypeasthelastelementofextensionSubtags.

2. LetkeybeaStringvalueequaltothesubstringofextensionconsistingofthecodeunitsatindicesp(inclusive)throughq(exclusive).

3. AppendkeyasthelastelementofextensionSubtags.

4. Lettbeq+1.5. Letattributebefalse.

ii. Elseifattributeistrue,then1. LetattrbeaStringvalueequaltothesubstringofextensionconsistingofthecodeunitsatindicesp(inclusive)throughq(exclusive).

2. AppendattrasthelastelementofextensionSubtags.

3. Lettbeq+1.iii. Letpbeq+1.

c. Letqbeq+1.9. Ifsize-p=2,then

a. Ifp-t>1,theni. LettypebeaStringvalueequaltothesubstringofextensionconsistingofthecodeunitsatindicest(inclusive)throughp-1(exclusive).

ii. AppendtypeasthelastelementofextensionSubtags.b. Lettbep.

10. LettailbeaStringvalueequaltothesubstringofextensionconsistingofthecodeunitsatindicest(inclusive)throughsize(exclusive).

11. AppendtailasthelastelementofextensionSubtags.12. ReturnextensionSubtags.

TheResolveLocaleabstractoperationcomparesaBCP47languageprioritylistrequestedLocalesagainstthelocalesinavailableLocalesanddeterminesthebestavailablelanguagetomeettherequest.availableLocales,requestedLocales,andrelevantExtensionKeysmustbeprovidedasListvalues,optionsasaRecord.

Thefollowingstepsaretaken:

1. Letmatcherbeoptions.[[localeMatcher]].2. Ifmatcheris"lookup",then

a. LetrbeLookupMatcher(availableLocales,requestedLocales).

3. Else,a. LetrbeBestFitMatcher(availableLocales,requestedLocales).

4. LetfoundLocaleber.[[locale]].5. Ifrhasan[[extension]]Lield,then

a. Letextensionber.[[extension]].b. LetextensionSubtagsbeCreateArrayFromList(UnicodeExtensionSubtags(extension)).

c. LetextensionSubtagsLengthbeGet(extensionSubtags,"length").

6. LetresultbeanewRecord.7. Setresult.[[dataLocale]]tofoundLocale.8. LetsupportedExtensionbe"-u".9. Letkbe0.10. LetrExtensionKeysbe

9.2.6 ResolveLocale(availableLocales,requestedLocales,options,relevantExtensionKeys,localeData)

CreateArrayFromList(relevantExtensionKeys).11. Letlenbe!ToLength(!Get(rExtensionKeys,"length")).12. Repeatwhilek<len

a. Letkeybe!Get(rExtensionKeys,!ToString(k)).b. LetfoundLocaleDatabe?Get(localeData,foundLocale).c. LetkeyLocaleDatabe?ToObject(Get(foundLocaleData,key)).

d. Letvaluebe?ToString(Get(keyLocaleData,"0")).e. LetsupportedExtensionAdditionbe"".f. IfextensionSubtagsisnotunde9ined,then

i. LetkeyPosbeCall(%ArrayProto_indexOf%,extensionSubtags,«key»).

ii. IfkeyPos≠-1,then1. IfkeyPos+1<extensionSubtagsLengthandthe

lengthpropertyoftheresultofGet(extensionSubtags,ToString(keyPos+1))isgreaterthan2,thena. LetrequestedValuebeGet(extensionSubtags,ToString(keyPos+1)).

b. IftheresultofCall(%StringProto_includes%,keyLocaleData,«requestedValue»)istrue,theni. LetvalueberequestedValue.ii. LetsupportedExtensionAdditionbetheconcatenationof"-",key,"-",andvalue.

2. ElseiftheresultofCall(%StringProto_includes%,keyLocaleData,«"true"»)istrue,thena. Letvaluebe"true".

g. IfoptionshasaLield[[<key>]],then

i. LetoptionsValuebe?ToString(options.[[<key>]]).ii. IftheresultofCall(%StringProto_includes%,keyLocaleData,«optionsValue»)istrue,then1. IfoptionsValueisnotequaltovalue,then

a. LetvaluebeoptionsValue.b. LetsupportedExtensionAdditionbe"".

h. Setresult.[[<key>]]tovalue.i. AppendsupportedExtensionAdditiontosupportedExtension.

j. Increasekby1.13. IfthenumberofelementsinsupportedExtensionisgreaterthan

2,thena. LetprivateIndexbeCall(%StringProto_indexOf%,foundLocale,«"-x-"»).

b. IfprivateIndex=-1,theni. LetfoundLocalebetheconcatenationoffoundLocaleandsupportedExtension.

c. Else,i. LetpreExtensionbethesubstringoffoundLocalefromposition0,inclusive,topositionprivateIndex,exclusive.

ii. LetpostExtensionbethesubstringoffoundLocalefrompositionprivateIndextotheendofthestring.

iii. LetfoundLocalebetheconcatenationofpreExtension,supportedExtension,andpostExtension.

d. Assert:IsStructurallyValidLanguageTag(foundLocale)istrue.

e. LetfoundLocalebeCanonicalizeLanguageTag(foundLocale).

14. Setresult.[[locale]]tofoundLocale.15. Returnresult.

NOTE Non-normativesummary:Twoalgorithmsareavailabletomatchthelocales:theLookupalgorithm

describedinRFC4647section3.4,andanimplementationdependentbest-Litalgorithm.Independentofthelocalematchingalgorithm,optionsspeciLiedthroughUnicodelocaleextensionsequencesarenegotiatedseparately,takingthecaller’srelevantextensionkeysandlocaledataaswellasclient-providedoptionsintoconsideration.Theabstractoperationreturnsarecordwitha[[locale]]Lieldwhosevalueisthelanguagetagoftheselectedlocale,andLieldsforeachkeyinrelevantExtensionKeysprovidingtheselectedvalueforthatkey.

TheLookupSupportedLocalesabstractoperationreturnsthesubsetoftheprovidedBCP47languageprioritylistrequestedLocalesforwhichavailableLocaleshasamatchinglocalewhenusingtheBCP47Lookupalgorithm.LocalesappearinthesameorderinthereturnedlistasinrequestedLocales.Thefollowingstepsaretaken:

1. LetrLocalesbeCreateArrayFromList(requestedLocales).2. Letlenbe!ToLength(!Get(rLocales,"length")).3. LetsubsetbeanewemptyList.4. Letkbe0.5. Repeatwhilek<len

a. Letlocalebe!Get(rLocales,!ToString(k)).b. LetnoExtensionsLocalebetheStringvaluethatislocalewithallUnicodelocaleextensionsequencesremoved.

c. LetavailableLocalebeBestAvailableLocale(availableLocales,noExtensionsLocale).

d. IfavailableLocaleisnotunde9ined,appendlocaletotheendofsubset.

e. Incrementkby1.

9.2.7 LookupSupportedLocales(availableLocales,requestedLocales)

6. Returnsubset.

TheBestFitSupportedLocalesabstractoperationreturnsthesubsetoftheprovidedBCP47languageprioritylistrequestedLocalesforwhichavailableLocaleshasamatchinglocalewhenusingtheBestFitMatcheralgorithm.LocalesappearinthesameorderinthereturnedlistasinrequestedLocales.Thestepstakenareimplementationdependent.

TheSupportedLocalesabstractoperationreturnsthesubsetoftheprovidedBCP47languageprioritylistrequestedLocalesforwhichavailableLocaleshasamatchinglocale.Twoalgorithmsareavailabletomatchthelocales:theLookupalgorithmdescribedinRFC4647section3.4,andanimplementationdependentbest-Litalgorithm.LocalesappearinthesameorderinthereturnedlistasinrequestedLocales.Thefollowingstepsaretaken:

1. Ifoptionsisnotunde9ined,thena. Letmatcherbe?GetOption(options,"localeMatcher","string",«"lookup","best9it"»,"best9it").

2. Else,letmatcherbe"best9it".3. Ifmatcheris"best9it",

a. LetsupportedLocalesbeBestFitSupportedLocales(availableLocales,requestedLocales).

4. Else,a. LetsupportedLocalesbeLookupSupportedLocales(availableLocales,

9.2.8 BestFitSupportedLocales(availableLocales,requestedLocales)

9.2.9 SupportedLocales(availableLocales,requestedLocales,options)

requestedLocales).5. LetsubsetbeCreateArrayFromList(supportedLocales).6. Letkeysbesubset.[[OwnPropertyKeys]]().7. RepeatforeachelementPofkeysinListorder,

a. LetdescbePropertyDescriptor{[[ConLigurable]]:false,[[Writable]]:false}.

b. Perform!DeLinePropertyOrThrow(subset,P,desc).8. Returnsubset.

TheabstractoperationGetOptionextractsthevalueofthepropertynamedpropertyfromtheprovidedoptionsobject,convertsittotherequiredtype,checkswhetheritisoneofaListofallowedvalues,andLillsinafallbackvalueifnecessary.

1. Letoptsbe?ToObject(options).2. Letvaluebe?Get(opts,property).3. Ifvalueisnotunde9ined,then

a. Assert:typeis"boolean"or"string".b. Iftypeis"boolean",then

i. LetvaluebeToBoolean(value).c. Iftypeis"string",then

i. Letvaluebe?ToString(value).d. Ifvaluesisnotunde9ined,then

i. Ifvaluesdoesnotcontainanelementequaltovalue,throwaRangeErrorexception.

e. Returnvalue.4. Else,returnfallback.

9.2.10 GetOption(options,property,type,values,fallback)

9.2.11 GetNumberOption(options,property,minimum,maximum,fallback)

TheabstractoperationGetNumberOptionextractsthevalueofthepropertynamedpropertyfromtheprovidedoptionsobject,convertsittoaNumbervalue,checkswhetheritisintheallowedrange,andLillsinafallbackvalueifnecessary.

1. Letoptsbe?ToObject(options).2. Letvaluebe?Get(opts,property).3. Ifvalueisnotunde9ined,then

a. Letvaluebe?ToNumber(value).b. IfvalueisNaNorlessthanminimumorgreaterthanmaximum,throwaRangeErrorexception.

c. ReturnLloor(value).4. Else,returnfallback.

TheIntl.Collatorconstructoristhe%Collator%intrinsicobjectandastandardbuilt-inpropertyoftheIntlobject.BehaviourcommontoallserviceconstructorpropertiesoftheIntlobjectisspeciLiedin9.1.

TheabstractoperationInitializeCollatoracceptstheargumentscollator(whichmustbeanobject),locales,andoptions.ItinitializescollatorasaCollatorobject.

Severalstepsinthealgorithmusevaluesfromthefollowingtable,whichassociatesUnicodelocaleextensionkeys,internalslots,

10 CollatorObjects

10.1 TheIntl.CollatorConstructor

10.1.1 InitializeCollator(collator,locales,options)

propertynames,types,andallowablevalues:

Table2:Collatoroptionssettablethroughextensionkeys,internalslotsandoptionsproperties

Key InternalSlot

Property Type Values

kn [[Numeric]] "numeric" "boolean"

kf [[CaseFirst]] "caseFirst" "string" "upper","lower","false"

Thefollowingstepsaretaken:

1. Ifcollator.[[InitializedIntlObject]]istrue,throwaTypeErrorexception.

2. Setcollator.[[InitializedIntlObject]]totrue.3. LetrequestedLocalesbe?CanonicalizeLocaleList(locales).4. Ifoptionsisunde9ined,then

a. LetoptionsbeObjectCreate(%ObjectPrototype%).5. Else,

a. Letoptionsbe?ToObject(options).6. Letube?GetOption(options,"usage","string",«"sort","search"»,"sort").

7. Setcollator.[[Usage]]tou.8. Ifuis"sort",then

a. LetlocaleDatabe%Collator%.[[SortLocaleData]].9. Else,

a. LetlocaleDatabe%Collator%.[[SearchLocaleData]].10. LetoptbeanewRecord.11. Letmatcherbe?GetOption(options,"localeMatcher","string",

«"lookup","best9it"»,"best9it").12. Setopt.[[localeMatcher]]tomatcher.

13. ForeachrowinTable2,excepttheheaderrow,do:a. LetkeybethenamegivenintheKeycolumnoftherow.b. LetpropbethenamegiveninthePropertycolumnoftherow.

c. LettypebethestringgivenintheTypecolumnoftherow.d. LetlistbeaListcontainingtheStringsgivenintheValuescolumnoftherow,orunde9inedifnostringsaregiven.

e. Letvaluebe?GetOption(options,prop,type,list,unde9ined).

f. IfthestringgivenintheTypecolumnoftherowis"boolean"andvalueisnotunde9ined,theni. Letvaluebe!ToString(value).

g. Setopt.[[<key>]]tovalue.14. LetrelevantExtensionKeysbe%Collator%.

[[RelevantExtensionKeys]].15. LetrbeResolveLocale(%Collator%.[[AvailableLocales]],

requestedLocales,opt,relevantExtensionKeys,localeData).16. Setcollator.[[Locale]]tor.[[locale]].17. Letkbe0.18. LetrExtensionKeysbe

CreateArrayFromList(relevantExtensionKeys).19. Letlenbe!ToLength(!Get(rExtensionKeys,"length")).20. Repeatwhilek<len:

a. Letkeybe!Get(rExtensionKeys,!ToString(k)).b. Ifkeyis"co",then

i. Letvalueber.[[co]].ii. Ifvalueisnull,letvaluebe"default".iii. Setcollator.[[Collation]]tovalue.

c. ElseusetherowofTable2thatcontainskeyintheKeycolumn:i. Letvalueber.[[<key>]].ii. IfthenamegivenintheTypecolumnoftherowis"boolean",letvaluebetheresultofcomparingvalue

with"true".iii. Setcollator'sinternalslotwhosenameistheInternal

Slotcolumnoftherowtovalue.d. Increasekby1.

21. Letsbe?GetOption(options,"sensitivity","string",«"base","accent","case","variant"»,unde9ined).

22. Ifsisunde9ined,thena. Ifuis"sort",then

i. Letsbe"variant".b. Else,

i. LetdataLocaleber.[[dataLocale]].ii. LetdataLocaleDatabeGet(localeData,dataLocale).iii. LetsbeGet(dataLocaleData,"sensitivity").

23. Setcollator.[[Sensitivity]]tos.24. Letipbe?GetOption(options,"ignorePunctuation",

"boolean",unde9ined,false).25. Setcollator.[[IgnorePunctuation]]toip.26. Setcollator.[[BoundCompare]]tounde9ined.27. Setcollator.[[InitializedCollator]]totrue.28. Returncollator.

WhentheIntl.Collatorfunctioniscalledwithoptionalargumentslocalesandoptions,thefollowingstepsaretaken:

1. IfNewTargetisunde9ined,letnewTargetbetheactivefunctionobject,elseletnewTargetbeNewTarget.

2. LetinternalSlotsListbe«[[InitializedIntlObject]],[[InitializedCollator]],[[Locale]],[[Usage]],[[Sensitivity]],[[IgnorePunctuation]],[[Collation]],[[BoundCompare]]».

3. If%Collator%.[[RelevantExtensionKeys]]contains"kn",thena. Append[[Numeric]]asthelastelementof

10.1.2 Intl.Collator([locales[,options]])

internalSlotsList.4. If%Collator%.[[RelevantExtensionKeys]]contains"kf",then

a. Append[[CaseFirst]]asthelastelementofinternalSlotsList.

5. Letcollatorbe?OrdinaryCreateFromConstructor(newTarget,"%CollatorPrototype%",internalSlotsList).

6. Return?InitializeCollator(collator,locales,options).

TheIntl.Collatorconstructorhasthefollowingproperties:

ThevalueofIntl.Collator.prototypeis%CollatorPrototype%.

Thispropertyhastheattributes{[[Writable]]:false,[[Enumerable]]:false,[[ConLigurable]]:false}.

WhenthesupportedLocalesOfmethodiscalled,thefollowingstepsaretaken:

1. LetrequestedLocalesbe?CanonicalizeLocaleList(locales).2. Return?SupportedLocales(%Collator%.[[AvailableLocales]],requestedLocales,options).

ThevalueofthelengthpropertyofthesupportedLocalesOfmethodis1.

10.2 PropertiesoftheIntl.CollatorConstructor

10.2.1 Intl.Collator.prototype

10.2.2 Intl.Collator.supportedLocalesOf(locales[,options])

Thevalueofthe[[AvailableLocales]]internalslotisimplementationdeLinedwithintheconstraintsdescribedin9.1.Thevalueofthe[[RelevantExtensionKeys]]internalslotisaListthatmustincludetheelement"co",mayincludeanyoralloftheelements"kn"and"kf",andmustnotincludeanyotherelements.

NOTE UnicodeTechnicalStandard35describestenlocaleextensionkeysthatarerelevanttocollation:"co"forcollatorusageandspecializations,"ka"foralternatehandling,"kb"forbackwardsecondlevelweight,"kc"forcaselevel,"kn"fornumeric,"kh"forhiraganaquaternary,"kk"fornormalization,"kf"forcaseLirst,"kr"forreordering,"ks"forcollationstrength,and"vt"forvariabletop.Collator,however,requiresthattheusageisspeciLiedthroughtheusagepropertyoftheoptionsobject,alternatehandlingthroughtheignorePunctuationpropertyoftheoptionsobject,andcaselevelandthestrengththroughthesensitivitypropertyoftheoptionsobject.The"co"keyinthelanguagetagissupportedonlyforcollatorspecializations,andthekeys"kb","kh","kk","kr",and"vt"arenotallowedinthisversionoftheInternationalizationAPI.Supportfortheremainingkeysisimplementationdependent.

Thevaluesofthe[[SortLocaleData]]and[[SearchLocaleData]]internalslotsareimplementationdeLinedwithintheconstraintsdescribedin9.1andthefollowingadditionalconstraints:

TheLirstelementof[[SortLocaleData]][locale].coand[[SearchLocaleData]][locale].comustbenullforalllocalevalues.Thevalues"standard"and"search"mustnotbeusedas

10.2.3 InternalSlots

elementsinany[[SortLocaleData]][locale].coand[[SearchLocaleData]][locale].coarray.[[SearchLocaleData]][locale]musthaveasensitivitypropertywithaStringvalueequalto"base","accent","case",or"variant"foralllocalevalues.

TheIntl.Collatorprototypeobjectistheintrinsicobject%CollatorPrototype%.TheIntl.CollatorprototypeobjectisitselfanIntl.CollatorinstanceasspeciLiedin10.4,whoseinternalslotsaresetasifithadbeenconstructedbytheexpressionConstruct(%Collator%,«»,%Object%).

Inthefollowingdescriptionsoffunctionsthatarepropertiesor[[Get]]attributesofpropertiesof%CollatorPrototype%,thephrase"thisCollatorobject"referstotheobjectthatisthethisvaluefortheinvocationofthefunction;aTypeErrorexceptionisthrownifthethisvalueisnotanobjectoranobjectthatdoesnothavean[[InitializedCollator]]internalslotwithvaluetrue.

TheinitialvalueofIntl.Collator.prototype.constructoristheintrinsicobject%Collator%.

Theinitialvalueofthe@@toStringTagpropertyisthestringvalue"Object".

10.3 PropertiesoftheIntl.CollatorPrototypeObject

10.3.1 Intl.Collator.prototype.constructor

10.3.2 Intl.Collator.prototype[@@toStringTag]

Thispropertyhastheattributes{[[Writable]]:false,[[Enumerable]]:false,[[ConLigurable]]:true}.

ThisnamedaccessorpropertyreturnsafunctionthatcomparestwostringsaccordingtothesortorderofthisCollatorobject.

Thevalueofthe[[Get]]attributeisafunctionthattakesthefollowingsteps:

1. Letcollatorbethisvalue.2. IfType(collator)isnotObject,throwaTypeErrorexception.3. Ifcollatordoesnothavean[[InitializedCollator]]internalslot,throwaTypeErrorexception.

4. Ifcollator.[[BoundCompare]]isunde9ined,thena. LetFbeanewbuilt-infunctionobjectasdeLinedin10.3.4.b. LetbcbeBoundFunctionCreate(F,collator,«»).c. Perform!DeLinePropertyOrThrow(bc,"length",PropertyDescriptor{[[Value]]:2,[[Writable]]:false,[[Enumerable]]:false,[[ConLigurable]]:true}).

d. Setcollator.[[BoundCompare]]tobc.5. Returncollator.[[BoundCompare]].

NOTE Thefunctionreturnedby[[Get]]isboundtothisCollatorobjectsothatitcanbepasseddirectlytoArray.prototype.sortorotherfunctions.

Thevalueofthe[[Set]]attributeisunde9ined.

ACollatorcomparefunctionisananonymousbuilt-infunction.

10.3.3 getIntl.Collator.prototype.compare

10.3.4 CollatorCompareFunctions

WhenaCollatorcomparefunctioniscalledwithargumentsxandy,thefollowingstepsaretaken:

1. Letcollatorbethethisvalue.2. Assert:Type(collator)isObjectandcollator.[[InitializedCollator]]istrue.

3. Ifxisnotprovided,letxbeunde9ined.4. Ifyisnotprovided,letybeunde9ined.5. LetXbe?ToString(x).6. LetYbe?ToString(y).7. ReturnCompareStrings(collator,X,Y).

WhentheCompareStringsabstractoperationiscalledwithargumentscollator(whichmustbeanobjectinitializedasaCollator),xandy(whichmustbeStringvalues),itreturnsaNumberotherthanNaNthatrepresentstheresultofalocale-sensitiveStringcomparisonofxwithy.ThetwoStringsarecomparedinanimplementation-deLinedfashion.TheresultisintendedtoorderStringvaluesinthesortorderspeciLiedbytheeffectivelocaleandcollationoptionscomputedduringconstructionofcollator,andwillbenegative,zero,orpositive,dependingonwhetherxcomesbeforeyinthesortorder,theStringsareequalunderthesortorder,orxcomesafteryinthesortorder,respectively.StringvaluesmustbeinterpretedasUTF-16codeunitsequences,andasurrogatepair(acodeunitintherange0xD800to0xDBFFfollowedbyacodeunitintherange0xDC00to0xDFFF)withinastringmustbeinterpretedasthecorrespondingcodepoint.

Thesensitivityofcollatorisinterpretedasfollows:

base:Onlystringsthatdifferinbaseletterscompareasunequal.Examples:a≠b,a=á,a=A.accent:Onlystringsthatdifferinbaselettersoraccentsandotherdiacriticmarkscompareasunequal.Examples:a≠b,a≠á,a=A.

case:Onlystringsthatdifferinbaselettersorcasecompareasunequal.Examples:a≠b,a=á,a≠A.variant:Stringsthatdifferinbaseletters,accentsandotherdiacriticmarks,orcasecompareasunequal.Otherdifferencesmayalsobetakenintoconsideration.Examples:a≠b,a≠á,a≠A.

NOTE1 Insomelanguages,certainletterswithdiacriticmarksareconsideredbaseletters.Forexample,inSwedish,“ö”isabaseletterthat’sdifferentfrom“o”.

Ifthecollatorissettoignorepunctuation,thenstringsthatdifferonlyinpunctuationcompareasequal.

Fortheinterpretationofoptionssettablethroughextensionkeys,seeUnicodeTechnicalStandard35.

TheCompareStringsabstractoperationwithanygivencollatorargument,ifconsideredasafunctionoftheremainingtwoargumentsxandy,mustbeaconsistentcomparisonfunction(asdeLinedinES2017,22.1.3.25)onthesetofallStrings.

Theactualreturnvaluesareimplementation-deLinedtopermitimplementerstoencodeadditionalinformationinthevalue.Themethodisrequiredtoreturn0whencomparingStringsthatareconsideredcanonicallyequivalentbytheUnicodestandard.

NOTE2 ItisrecommendedthattheCompareStringsabstractoperationbeimplementedfollowingUnicodeTechnicalStandard10,UnicodeCollationAlgorithm(availableathttp://unicode.org/reports/tr10/),usingtailoringsfortheeffectivelocaleandcollationoptionsofcollator.ItisrecommendedthatimplementationsusethetailoringsprovidedbytheCommonLocaleDataRepository(availableat

http://cldr.unicode.org/).

NOTE3 ApplicationsshouldnotassumethatthebehaviouroftheCompareStringsabstractoperationforCollatorinstanceswiththesameresolvedoptionswillremainthesamefordifferentversionsofthesameimplementation.

Thisfunctionprovidesaccesstothelocaleandcollationoptionscomputedduringinitializationoftheobject.

ThefunctionreturnsanewobjectwhosepropertiesandattributesaresetasifconstructedbyanobjectliteralassigningtoeachofthefollowingpropertiesthevalueofthecorrespondinginternalslotofthisCollatorobject(see10.4):locale,usage,sensitivity,ignorePunctuation,collation,aswellasthosepropertiesshowninTable2whosekeysareincludedinthe%Collator%.[[RelevantExtensionKeys]]internalslotofthestandardbuilt-inobjectthatistheinitialvalueofIntl.Collator.

Intl.Collatorinstancesareordinaryobjectsthatinheritpropertiesfrom%CollatorPrototype%.

Intl.CollatorinstancesandotherobjectsthathavebeensuccessfullyinitializedasaCollatorhave[[InitializedIntlObject]]and[[InitializedCollator]]internalslotswhosevaluesaretrue.

ObjectsthathavebeensuccessfullyinitializedasaCollatoralsohaveseveralinternalslotsthatarecomputedbytheconstructor:

10.3.5 Intl.Collator.prototype.resolvedOptions()

10.4 PropertiesofIntl.CollatorInstances

[[Locale]]isaStringvaluewiththelanguagetagofthelocalewhoselocalizationisusedforcollation.[[Usage]]isoneoftheStringvalues"sort"or"search",identifyingthecollatorusage.[[Sensitivity]]isoneoftheStringvalues"base","accent","case",or"variant",identifyingthecollator’ssensitivity.[[IgnorePunctuation]]isaBooleanvalue,specifyingwhetherpunctuationshouldbeignoredincomparisons.[[Collation]]isaStringvaluewiththe"type"giveninUnicodeTechnicalStandard35forthecollation,exceptthatthevalues"standard"and"search"arenotallowed,whilethevalue"default"isallowed.

ObjectsthathavebeensuccessfullyinitializedasaCollatoralsohavethefollowinginternalslotsifthekeycorrespondingtothenameoftheinternalslotinTable2isincludedinthe[[RelevantExtensionKeys]]internalslotofIntl.Collator:

[[Numeric]]isaBooleanvalue,specifyingwhethernumericsortingisused.[[CaseFirst]]isaStringvalue;allowedvaluesarespeciLiedinTable2.

Finally,objectsthathavebeensuccessfullyinitializedasaCollatorhavea[[BoundCompare]]internalslotthatcachesthefunctionreturnedbythecompareaccessor(10.3.3).

11 NumberFormatObjects

11.1 AbstractOperationsForNumberFormatObjects

TheabstractoperationSetNumberFormatDigitOptionsappliesdigitoptionsusedfornumberformattingontotheintlobject.

1. Assert:Type(intlObj)isObjectandintlObj.[[InitializedIntlObject]]istrue.

2. Assert:Type(options)isObject.3. Assert:type(mnfdDefault)isNumber.4. Letmnidbe?GetNumberOption(options,"minimumIntegerDigits,",1,21,1).

5. Letmnfdbe?GetNumberOption(options,"minimumFractionDigits",0,20,mnfdDefault).

6. Letmxfdbe?GetNumberOption(options,"maximumFractionDigits",mnfd,20).

7. Letmnsdbe?Get(options,"minimumSigni9icantDigits").8. Letmxsdbe?Get(options,"maximumSigni9icantDigits").9. SetintlObj.[[MinimumIntegerDigits]]tomnid.10. SetintlObj.[[MinimumFractionDigits]]tomnfd.11. SetintlObj.[[MaximumFractionDigits]]tomxfd.12. Ifmnsdisnotunde9inedormxsdisnotunde9ined,then

a. Letmnsdbe?GetNumberOption(options,"minimumSigni9icantDigits",1,21,1).

b. Letmxsdbe?GetNumberOption(options,"maximumSigni9icantDigits",mnsd,21,21).

c. SetintlObj.[[MinimumSigniLicantDigits]]tomnsd.d. SetintlObj.[[MaximumSigniLicantDigits]]tomxsd.

TheabstractoperationInitializeNumberFormatacceptstheargumentsnumberFormat(whichmustbeanobject),locales,and

11.1.1 SetNumberFormatDigitOptions(intlObj,options,mnfdDefault)

11.1.2 InitializeNumberFormat(numberFormat,locales,options)

options.ItinitializesnumberFormatasaNumberFormatobject.

Thefollowingstepsaretaken:

1. IfnumberFormat.[[InitializedIntlObject]]istrue,throwaTypeErrorexception.

2. SetnumberFormat.[[InitializedIntlObject]]totrue.3. LetrequestedLocalesbe?CanonicalizeLocaleList(locales).4. Ifoptionsisunde9ined,then

a. LetoptionsbeObjectCreate(%ObjectPrototype%).5. Else,

a. Letoptionsbe?ToObject(options).6. LetoptbeanewRecord.7. Letmatcherbe?GetOption(options,"localeMatcher","string",«"lookup","best9it"»,"best9it").

8. Setopt.[[localeMatcher]]tomatcher.9. LetlocaleDatabe%NumberFormat%.[[LocaleData]].10. LetrbeResolveLocale(%NumberFormat%.[[AvailableLocales]],

requestedLocales,opt,%NumberFormat%.[[RelevantExtensionKeys]],localeData).

11. SetnumberFormat.[[Locale]]tor.[[locale]].12. SetnumberFormat.[[NumberingSystem]]tor.[[nu]].13. LetdataLocaleber.[[dataLocale]].14. Letstylebe?GetOption(options,"style","string",«"decimal",

"percent","currency"»,"decimal").15. SetnumberFormat.[[Style]]tostyle.16. Letcbe?GetOption(options,"currency","string",unde9ined,

unde9ined).17. Ifcisnotunde9ined,then

a. IftheresultofIsWellFormedCurrencyCode(c)isfalse,throwaRangeErrorexception.

18. Ifstyleis"currency"andcisunde9ined,throwaTypeErrorexception.

19. Ifstyleis"currency",then

a. LetcbetheresultofconvertingctouppercaseasspeciLiedin6.1.

b. SetnumberFormat.[[Currency]]toc.c. LetcDigitsbeCurrencyDigits(c).

20. Letcdbe?GetOption(options,"currencyDisplay","string",«"code","symbol","name"»,"symbol").

21. Ifstyleis"currency",setnumberFormat.[[CurrencyDisplay]]tocd.

22. Ifstyleis"currency",thena. LetmnfdDefaultbecDigits.

23. Else,a. LetmnfdDefaultbe0.

24. Perform?SetNumberFormatDigitOptions(numberFormat,options,mnfdDefault).

25. IfnumberFormat.[[MaximumFractionDigits]]isunde9ined,thena. Ifstyleis"currency",then

i. SetnumberFormat.[[MaximumFractionDigits]]tomax(numberFormat.[[MinimumFractionDigits]],cDigits).

b. Elseifstyleis"percent",theni. SetnumberFormat.[[MaximumFractionDigits]]tomax(numberFormat.[[MinimumFractionDigits]],0).

c. Else,i. SetnumberFormat.[[MaximumFractionDigits]]tomax(numberFromat.[[MinimumFractionDigits]],3).

26. Letgbe?GetOption(options,"useGrouping","boolean",unde9ined,true).

27. SetnumberFormat.[[UseGrouping]]tog.28. LetdataLocaleDatabeGet(localeData,dataLocale).29. LetpatternsbeGet(dataLocaleData,"patterns").30. Assert:patternsisanobject(see11.3.3).31. LetstylePatternsbeGet(patterns,s).

32. SetnumberFormat.[[PositivePattern]]toGet(stylePatterns,"positivePattern").

33. SetnumberFormat.[[NegativePattern]]toGet(stylePatterns,"negativePattern").

34. SetnumberFormat.[[BoundFormat]]tounde9ined.35. SetnumberFormat.[[InitializedNumberFormat]]totrue.36. ReturnnumberFormat.

WhentheabstractoperationCurrencyDigitsiscalledwithanargumentcurrency(whichmustbeanuppercaseStringvalue),thefollowingstepsaretaken:

1. IftheISO4217currencyandfundscodelistcontainscurrencyasanalphabeticcode,returntheminorunitvaluecorrespondingtothecurrencyfromthelist;otherwise,return2.

ANumberformatfunctionisananonymousbuilt-infunction.

WhenaNumberformatfunctioniscalledwithoptionalargumentvalue,thefollowingstepsaretaken:

1. Letnfbethethisvalue.2. Assert:Type(nf)isObjectandnf.[[InitializedNumberFormat]]istrue.

3. Ifvalueisnotprovided,letvaluebeunde9ined.4. Letxbe?ToNumber(value).5. ReturnFormatNumber(nf,x).

ThelengthpropertyofaNumberformatfunctionis1.

11.1.3 CurrencyDigits(currency)

11.1.4 NumberFormatFunctions

TheFormatNumberToStringabstractoperationiscalledwithargumentsnumberFormat(whichmustbeanobjectwithLieldsminimumSigniLicantDigits,maximumSigniLicantDigits,minimumIntegerDigits,minimumFractionDigitsandmaximumFractionDigits),andx(whichmustbeaNumbervalue),andreturnsxasastringvaluewithdigitsformattedaccordingtothe5formattingparameters.

1. Assert:numberFormat.[[InitializedIntlObject]]istrue.2. IfthenumberFormat.[[MinimumSigniLicantDigits]]andnumberFormat.[[MaximumSigniLicantDigits]]arepresent,thena. LetresultbeToRawPrecision(x,numberFormat.[[MinimumSigniLicantDigits]],numberFormat.[[MaximumSigniLicantDigits]]).

3. Else,a. LetresultbeToRawFixed(x,numberFormat.[[MinimumIntegerDigits]],numberFormat.[[MinimumFractionDigits]],numberFormat.[[MaximumFractionDigits]]).

4. Returnresult.

ThePartitionNumberPatternabstractoperationiscalledwithargumentsnumberFormat(whichmustbeanobjectinitializedasaNumberFormat)andx(whichmustbeaNumbervalue),interpretsxasanumericvalue,andcreatesthecorrespondingpartsaccordingtotheeffectivelocaleandtheformattingoptionsofnumberFormat.Thefollowingstepsaretaken:

11.1.5 FormatNumberToString(numberFormat,x)

11.1.6 PartitionNumberPattern(numberFormat,x)

1. IfxisnotNaNandx<0,then:a. Letxbe-x.b. LetpatternbenumberFormat.[[NegativePattern]].

2. Else,a. LetpatternbenumberFormat.[[PositivePattern]].

3. LetresultbeanewemptyList.4. LetbeginIndexbeCall(%StringProto_indexOf%,pattern,"{",0).5. LetendIndexbe0.6. LetnextIndexbe0.7. Letlengthbethenumberofcodeunitsinpattern.8. RepeatwhilebeginIndexisanintegerindexintopattern:

a. SetendIndextoCall(%StringProto_indexOf%,pattern,"}",beginIndex)

b. Assert:endIndexisgreaterthanthanbeginIndex.c. IfbeginIndexisgreaterthannextIndex,then:

i. LetliteralbeasubstringofpatternfrompositionnextIndex,inclusive,topositionbeginIndex,exclusive.

ii. AppendanewRecord{[[Type]]:"literal",[[Value]]:literal}asthelastelementofresult.

d. LetpbethesubstringofpatternfrompositionbeginIndex,exclusive,topositionendIndex,exclusive.

e. Ifpisequal"number",then:i. IfxisNaN,

1. LetnbeanILDStringvalueindicatingtheNaNvalue.

2. AppendanewRecord{[[Type]]:"nan",[[Value]]:n}asthelastelementofresult.

ii. ElseifisFinite(x)isfalse,1. LetnbeanILDStringvalueindicatinginLinity.2. AppendanewRecord{[[Type]]:"in9inity",[[Value]]:n}asthelastelementofresult.

iii. Else,1. IfnumberFormat.[[Style]]is"percent",letxbe

100×x.2. LetnbeFormatNumberToString(numberFormat,x).

3. IfthenumberFormat.[[NumberingSystem]]matchesoneofthevaluesinthe"NumberingSystem"columnofTable3below,thena. Letdigitsbeanarraywhose10StringvaluedelementsaretheUTF-16stringrepresentationsofthe10digitsspeciLiedinthe"Digits"columnofthematchingrowinTable3.

b. Replaceeachdigitinnwiththevalueofdigits[digit].

4. Elseuseanimplementationdependentalgorithmtomapntotheappropriaterepresentationofninthegivennumberingsystem.

5. LetdecimalSepIndexbeCall(%StringProto_indexOf%,n,".",0).

6. IfdecimalSepIndex>0,then:a. Letintegerbethesubstringofnfromposition0,inclusive,topositiondecimalSepIndex,exclusive.

b. LetfractionbethesubstringofnfrompositiondecimalSepIndex,exclusive,totheendofn.

7. Else:a. Letintegerben.b. Letfractionbeunde9ined.

8. IfthenumberFormat.[[UseGrouping]]istrue,a. LetgroupSepSymbolbetheILNDStringrepresentingthegroupingseparator.

b. LetgroupsbeaListwhoseelementsare,in

lefttorightorder,thesubstringsdeLinedbyILNDsetoflocationswithintheinteger.

c. Assert:ThenumberofelementsingroupsListisgreaterthan0.

d. Repeat,whilegroupsListisnotempty:i. RemovetheLirstelementfromgroupsandletintegerGroupbethevalueofthatelement.

ii. AppendanewRecord{[[Type]]:"integer",[[Value]]:integerGroup}asthelastelementofresult.

iii. IfgroupsListisnotempty,then:i. AppendanewRecord{[[Type]]:"group",[[Value]]:groupSepSymbol}asthelastelementofresult.

9. Else,a. AppendanewRecord{[[Type]]:"integer",[[Value]]:integer}asthelastelementofresult.

10. Iffractionisnotunde9ined,then:a. LetdecimalSepSymbolbetheILNDStringrepresentingthedecimalseparator.

b. AppendanewRecord{[[Type]]:"decimal",[[Value]]:decimalSepSymbol}asthelastelementofresult.

c. AppendanewRecord{[[Type]]:"fraction",[[Value]]:fraction}asthelastelementofresult.

f. Elseifpisequal"plusSign",then:i. LetplusSignSymbolbetheILNDStringrepresentingtheplussign.

ii. AppendanewRecord{[[Type]]:"plusSign",

[[Value]]:plusSignSymbol}asthelastelementofresult.

g. Elseifpisequal"minusSign",then:i. LetminusSignSymbolbetheILNDStringrepresentingtheminussign.

ii. AppendanewRecord{[[Type]]:"minusSign",[[Value]]:minusSignSymbol}asthelastelementofresult.

h. Elseifpisequal"percentSign"andnumberFormat.[[Style]]is"percent",then:i. LetpercentSignSymbolbetheILNDStringrepresentingthepercentsign.

ii. AppendanewRecord{[[Type]]:"percentSign",[[Value]]:percentSignSymbol}asthelastelementofresult.

i. Elseifpisequal"currency"andnumberFormat.[[Style]]is"currency",then:i. LetcurrencybenumberFormat.[[Currency]].ii. Assert:numberFormat.[[CurrencyDisplay]]is"code","symbol"or"name".

iii. IfnumberFormat.[[CurrencyDisplay]]is"code",then1. Letcdbecurrency.

iv. ElseifnumberFormat.[[CurrencyDisplay]]is"symbol",then1. LetcdbeanILDstringrepresentingcurrencyinshortform.Iftheimplementationdoesnothavesucharepresentationofcurrency,usecurrencyitself.

v. ElseifnumberFormat.[[CurrencyDisplay]]is"name",then1. LetcdbeanILDstringrepresentingcurrencyinlongform.Iftheimplementationdoesnothavesucharepresentationofcurrency,thenuse

currencyitself.vi. AppendanewRecord{[[Type]]:"currency",

[[Value]]:cd}asthelastelementofresult.j. Else,

i. LetliteralbethesubstringofpatternfrompositionbeginIndex,inclusive,topositionendIndex,inclusive.

ii. AppendanewRecord{[[Type]]:"literal",[[Value]]:literal}asthelastelementofresult.

k. SetnextIndextoendIndex+1.l. SetbeginIndextoCall(%StringProto_indexOf%,pattern,"{",nextIndex)

9. IfnextIndexislessthanlength,then:a. LetliteralbethesubstringofpatternfrompositionnextIndex,inclusive,topositionlength,exclusive.

b. AppendanewRecord{[[Type]]:"literal",[[Value]]:literal}asthelastelementofresult.

10. Returnresult.

Table3:Numberingsystemswithsimpledigitmappings

NumberingSystem

Digits

arab U+0660toU+0669

arabext U+06F0toU+06F9

bali U+1B50toU+1B59

beng U+09E6toU+09EF

deva U+0966toU+096F

fullwide U+FF10toU+FF19

gujr U+0AE6toU+0AEF

guru U+0A66toU+0A6F

hanidec U+3007,U+4E00,U+4E8C,U+4E09,U+56DB,U+4E94,U+516D,U+4E03,U+516B,U+4E5D

khmr U+17E0toU+17E9

knda U+0CE6toU+0CEF

laoo U+0ED0toU+0ED9

latn U+0030toU+0039

limb U+1946toU+194F

mlym U+0D66toU+0D6F

mong U+1810toU+1819

mymr U+1040toU+1049

orya U+0B66toU+0B6F

tamldec U+0BE6toU+0BEF

telu U+0C66toU+0C6F

thai U+0E50toU+0E59

tibt U+0F20toU+0F29

NOTE1 ThecomputationsrelyonStringvaluesandlocationswithinnumericstringsthataredependentupontheimplementationandtheeffectivelocaleofnumberFormat(“ILD")orupontheimplementation,theeffectivelocale,andthenumberingsystemofnumberFormat(“ILND").TheILDandILNDStringsmentioned,otherthanthoseforcurrencynames,mustnotcontainanycharactersintheGeneralCategory“Number,decimaldigit"asspeciLiedbytheUnicode

Standard.

NOTE2 ItisrecommendedthatimplementationsusethelocaleprovidedbytheCommonLocaleDataRepository(availableathttp://cldr.unicode.org/).

TheFormatNumberabstractoperationiscalledwithargumentsnumberFormat(whichmustbeanobjectinitializedasaNumberFormat)andx(whichmustbeaNumbervalue),andperformsthefollowingsteps:

1. Letpartsbe?PartitionNumberPattern(numberFormat,x).2. LetresultbetheemptyString.3. Foreachpartinparts,do:

a. SetresulttoaStringvalueproducedbyconcatenatingresultandpart.[[Value]].

4. Returnresult.

TheFormatNumberToPartsabstractoperationiscalledwithargumentsnumberFormat(whichmustbeanobjectinitializedasaNumberFormat)andx(whichmustbeaNumbervalue),andperformsthefollowingsteps:

1. Letpartsbe?PartitionNumberPattern(numberFormat,x).2. LetresultbeArrayCreate(0).3. Letnbe0.4. Foreachpartinparts,do:

a. LetObeObjectCreate(%ObjectPrototype%).b. Perform?CreateDataPropertyOrThrow(O,"type",part.[[Type]]).

11.1.7 FormatNumber(numberFormat,x)

11.1.8 FormatNumberToParts(numberFormat,x)

c. Perform?CreateDataPropertyOrThrow(O,"value",part.[[Value]]).

d. Perform?CreateDataPropertyOrThrow(result,?ToString(n),O).

e. Incrementnby1.5. Returnresult.

WhentheToRawPrecisionabstractoperationiscalledwithargumentsx(whichmustbeaLinitenon-negativenumber),minPrecision,andmaxPrecision(bothmustbeintegersbetween1and21),thefollowingstepsaretaken:

1. LetpbemaxPrecision.2. Ifx=0,then

a. LetmbetheStringconsistingofpoccurrencesofthecharacter"0".

b. Letebe0.3. Else,

a. Leteandnbeintegerssuchthat10p–1≤n<10pandforwhichtheexactmathematicalvalueofn×10e–p+1–xisasclosetozeroaspossible.Iftherearetwosuchsetsofeandn,picktheeandnforwhichn×10e–p+1islarger.

b. LetmbetheStringconsistingofthedigitsofthedecimalrepresentationofn(inorder,withnoleadingzeroes).

4. Ife≥p,thena. Returntheconcatenationofmande-p+1occurrencesofthecharacter"0".

5. Ife=p-1,thena. Returnm.

6. Ife≥0,then

11.1.9 ToRawPrecision(x,minPrecision,maxPrecision)

a. LetmbetheconcatenationoftheLirste+1charactersofm,thecharacter".",andtheremainingp–(e+1)charactersofm.

7. Ife<0,thena. LetmbetheconcatenationoftheString"0.",–(e+1)occurrencesofthecharacter"0",andthestringm.

8. Ifmcontainsthecharacter".",andmaxPrecision>minPrecision,thena. LetcutbemaxPrecision–minPrecision.b. Repeatwhilecut>0andthelastcharacterofmis"0":

i. Removethelastcharacterfromm.ii. Decreasecutby1.

c. Ifthelastcharacterofmis".",theni. Removethelastcharacterfromm.

9. Returnm.

WhentheToRawFixedabstractoperationiscalledwithargumentsx(whichmustbeaLinitenon-negativenumber),minInteger(whichmustbeanintegerbetween1and21),minFraction,andmaxFraction(whichmustbeintegersbetween0and20),thefollowingstepsaretaken:

1. LetfbemaxFraction.2. Letnbeanintegerforwhichtheexactmathematicalvalueofn÷10f–xisasclosetozeroaspossible.Iftherearetwosuchn,pickthelargern.

3. Ifn=0,letmbetheString"0".Otherwise,letmbetheStringconsistingofthedigitsofthedecimalrepresentationofn(inorder,withnoleadingzeroes).

4. Iff≠0,thena. Letkbethenumberofcharactersinm.

11.1.10 ToRawFixed(x,minInteger,minFraction,maxFraction)

b. Ifk≤f,theni. LetzbetheStringconsistingoff+1–koccurrencesofthecharacter"0".

ii. LetmbetheconcatenationofStringszandm.iii. Letkbef+1.

c. LetabetheLirstk–fcharactersofm,andletbbetheremainingfcharactersofm.

d. LetmbetheconcatenationofthethreeStringsa,".",andb.

e. Letintbethenumberofcharactersina.5. Else,letintbethenumberofcharactersinm.6. LetcutbemaxFraction–minFraction.7. Repeatwhilecut>0andthelastcharacterofmis"0":

a. Removethelastcharacterfromm.b. Decreasecutby1.

8. Ifthelastcharacterofmis".",thena. Removethelastcharacterfromm.

9. Ifint<minInteger,thena. LetzbetheStringconsistingofminInteger–intoccurrencesofthecharacter"0".

b. LetmbetheconcatenationofStringszandm.10. Returnm.

TheUnwrapNumberFormatabstractoperationgetstheunderlyingNumberFormatoperationforvariousmethodswhichimplementECMA-402v1semanticsforsupportinginitializingexistingIntlobjects.

NORMATIVEOPTIONAL

1. IfType(nf)isObjectandnfdoesnothavean[[InitializedNumberFormat]]internalslotand

11.1.11 UnwrapNumberFormat(nf)

?InstanceofOperator(nf,%NumberFormat%)isequaltrue,thena. LetnfbeGet(nf,Intl.[[FallbackSymbol]]).

2. IfType(nf)isnotObjectornfdoesnothavean[[InitializedNumberFormat]]internalslot,thena. ThrowaTypeErrorexception.

3. Returnnf.

TheNumberFormatconstructoristhe%NumberFormat%intrinsicobjectandastandardbuilt-inpropertyoftheIntlobject.BehaviourcommontoallserviceconstructorpropertiesoftheIntlobjectisspeciLiedin9.1.

WhentheIntl.NumberFormatfunctioniscalledwithoptionalargumentslocalesandoptions,thefollowingstepsaretaken:

1. IfNewTargetisunde9ined,letnewTargetbetheactivefunctionobject,elseletnewTargetbeNewTarget.

2. LetnumberFormatbe?OrdinaryCreateFromConstructor(newTarget,"%NumberFormatPrototype%",«[[InitializedIntlObject]],[[InitializedNumberFormat]],[[Locale]],[[NumberingSystem]],[[Style]],[[Currency]],[[CurrencyDisplay]],[[MinimumIntegerDigits]],[[MinimumFractionDigits]],[[MaximumFractionDigits]],[[MinimumSigniLicantDigits]],[[MaximumSigniLicantDigits]],[[UseGrouping]],

11.2 TheIntl.NumberFormatConstructor

11.2.1 Intl.NumberFormat([locales[,options]])

[[PositivePattern]],[[NegativePattern]],[[BoundFormat]]»).3. Perform?InitializeNumberFormat(numberFormat,locales,options).

NORMATIVEOPTIONAL

4. Letthisbethethisvalue.5. IfNewTargetisunde9inedand?InstanceofOperator(this,%NumberFormat%),thena. Perform?DeLineOwnPropertyOrThrow(this,Intl.[[FallbackSymbol]],{[[Value]]:numberFormat,[[Writable]]:false,[[Enumerable]]:false,[[ConLigurable]]:false}).

b. Returnthis.

6. ReturnnumberFormat.

TheIntl.NumberFormatconstructorhasthefollowingproperties:

ThevalueofIntl.NumberFormat.prototypeis%NumberFormatPrototype%.

Thispropertyhastheattributes{[[Writable]]:false,[[Enumerable]]:false,[[ConLigurable]]:false}.

11.3 PropertiesoftheIntl.NumberFormatConstructor

11.3.1 Intl.NumberFormat.prototype

11.3.2 Intl.NumberFormat.supportedLocalesOf(locales[,options])

WhenthesupportedLocalesOfmethodiscalledwithargumentslocalesandoptions,thefollowingstepsaretaken:

1. LetavailableLocalesbe%NumberFormat%.[[AvailableLocales]].

2. LetrequestedLocalesbe?CanonicalizeLocaleList(locales).3. Return?SupportedLocales(availableLocales,requestedLocales,options).

ThevalueofthelengthpropertyofthesupportedLocalesOfmethodis1.

Thevalueofthe[[AvailableLocales]]internalslotisimplementationdeLinedwithintheconstraintsdescribedin9.1.

Thevalueofthe[[RelevantExtensionKeys]]internalslotis«"nu"».

NOTE1 UnicodeTechnicalStandard35describestwolocaleextensionkeysthatarerelevanttonumberformatting,"nu"fornumberingsystemand"cu"forcurrency.Intl.NumberFormat,however,requiresthatthecurrencyofacurrencyformatisspeciLiedthroughthecurrencypropertyintheoptionsobjects.

Thevalueofthe[[LocaleData]]internalslotisimplementationdeLinedwithintheconstraintsdescribedin9.1andthefollowingadditionalconstraints:

Thearraythatisthevalueofthe"nu"propertyofanylocalepropertyof[[LocaleData]]mustnotincludethevalues"native","traditio",or"Linance".[[LocaleData]][locale]musthaveapatternspropertyforalllocalevalues.Thevalueofthispropertymustbeanobject,

11.3.3 Internalslots

whichmusthavepropertieswiththenamesofthethreenumberformatstyles:"decimal","percent",and"currency".EachofthesepropertiesinturnmustbeanobjectwiththepropertiespositivePatternandnegativePattern.Thevalueofthesepropertiesmustbestringvaluesthatmustcontainthesubstring"{number}"andmaycontainthesubstrings"{plusSign}",and"{minusSign}";thevalueswithinthepercentpropertymustalsocontainthesubstring"{percentSign}";thevalueswithinthecurrencypropertymustalsocontainthesubstring"{currency}".ThepatternstringsmustnotcontainanycharactersintheGeneralCategory“Number,decimaldigit"asspeciLiedbytheUnicodeStandard.

NOTE2 ItisrecommendedthatimplementationsusethelocaledataprovidedbytheCommonLocaleDataRepository(availableathttp://cldr.unicode.org/).

TheIntl.NumberFormatprototypeobjectistheintrinsicobject%NumberFormatPrototype%.TheIntl.NumberFormatprototypeobjectisitselfanIntl.NumberFormatinstanceasspeciLiedin11.5,whoseinternalslotsaresetasifithadbeenconstructedbytheexpressionConstruct(%NumberFormat%,«»,%Object%).

Inthefollowingdescriptionsoffunctionsthatarepropertiesor[[Get]]attributesofpropertiesof%NumberFormatPrototype%,thephrase"thisNumberFormatobject"referstotheobjectthatisthethisvaluefortheinvocationofthefunction;aTypeErrorexceptionisthrownifthethisvalueisnotanobjectoranobjectthatdoesnothavean[[InitializedNumberFormat]]internalslotwithvaluetrue.

11.4 PropertiesoftheIntl.NumberFormatPrototypeObject

TheinitialvalueofIntl.NumberFormat.prototype.constructoristheintrinsicobject%NumberFormat%.

Theinitialvalueofthe@@toStringTagpropertyisthestringvalue"Object".

Thispropertyhastheattributes{[[Writable]]:false,[[Enumerable]]:false,[[ConLigurable]]:true}.

Intl.NumberFormat.prototype.formatisanaccessorpropertywhosesetaccessorfunctionisunde9ined.Itsgetaccessorfunctionperformsthefollowingsteps:

1. Letnfbethisvalue.2. IfType(nf)isnotObject,throwaTypeErrorexception.3. Letnfbe?UnwrapNumberFormat(nf);4. Ifnf.[[BoundFormat]]isunde9ined,then

a. LetFbeanewbuilt-infunctionobjectasdeLinedinNumberFormatFunctions(11.1.4).

b. LetbfbeBoundFunctionCreate(F,nf,«»).c. Perform!DeLinePropertyOrThrow(bf,"length",PropertyDescriptor{[[Value]]:1,[[Writable]]:false,[[Enumerable]]:false,[[ConLigurable]]:true}).

d. Setnf.[[BoundFormat]]tobf.5. Returnnf.[[BoundFormat]].

11.4.1 Intl.NumberFormat.prototype.constructor

11.4.2 Intl.NumberFormat.prototype[@@toStringTag]

11.4.3 getIntl.NumberFormat.prototype.format

Thisfunctionprovidesaccesstothelocaleandformattingoptionscomputedduringinitializationoftheobject.ThisfunctioninitiallyinvokestheinternalalgorithmUnwrapNumberFormattogetthe%NumberFormat%objectonwhichtooperate.

ThefunctionreturnsanewobjectwhosepropertiesandattributesaresetasifconstructedbyanobjectliteralassigningtoeachofthefollowingpropertiesthevalueofthecorrespondinginternalslotofthisNumberFormatobject(see11.5):locale,numberingSystem,style,currency,currencyDisplay,minimumIntegerDigits,minimumFractionDigits,maximumFractionDigits,minimumSigniLicantDigits,maximumSigniLicantDigits,anduseGrouping.Propertieswhosecorrespondinginternalslotshavethevalueunde9inedarenotassigned.

Intl.NumberFormatinstancesinheritpropertiesfrom%NumberFormatPrototype%.

Intl.NumberFormatinstancesandotherobjectsthathavebeensuccessfullyinitializedasaNumberFormathave[[InitializedIntlObject]]and[[InitializedNumberFormat]]internalslotswhosevaluesaretrue.

ObjectsthathavebeensuccessfullyinitializedasaNumberFormatobjectalsohaveseveralinternalslotsthatarecomputedbytheconstructor:

[[Locale]]isaStringvaluewiththelanguagetagofthelocale

11.4.4 Intl.NumberFormat.prototype.resolvedOptions()

11.5 PropertiesofIntl.NumberFormatInstances

whoselocalizationisusedforformatting.[[NumberingSystem]]isaStringvaluewiththe“type”giveninUnicodeTechnicalStandard35forthenumberingsystemusedforformatting.[[Style]]isoneoftheStringvalues"decimal","currency",or"percent",identifyingthenumberformatstyleused.[[Currency]]isaStringvaluewiththecurrencycodeidentifyingthecurrencytobeusedifformattingwiththe"currency"style.Itisonlyusedwhen[[Style]]hasthevalue"currency".[[CurrencyDisplay]]isoneoftheStringvalues"code","symbol",or"name",specifyingwhethertodisplaythecurrencyasanISO4217alphabeticcurrencycode,alocalizedcurrencysymbol,oralocalizedcurrencynameifformattingwiththe"currency"style.Itisonlyusedwhen[[Style]]hasthevalue"currency".[[MinimumIntegerDigits]]isanon-negativeintegerNumbervalueindicatingtheminimumintegerdigitstobeused.Numberswillbepaddedwithleadingzeroesifnecessary.[[MinimumFractionDigits]]and[[MaximumFractionDigits]]arenon-negativeintegerNumbervaluesindicatingtheminimumandmaximumfractiondigitstobeused.Numberswillberoundedorpaddedwithtrailingzeroesifnecessary.[[MinimumSigniLicantDigits]]and[[MaximumSigniLicantDigits]]arepositiveintegerNumbervaluesindicatingtheminimumandmaximumfractiondigitstobeshown.Eithernoneorbothofthesepropertiesarepresent;iftheyare,theyoverrideminimumandmaximumintegerandfractiondigits–theformatteruseshowevermanyintegerandfractiondigitsarerequiredtodisplaythespeciLiednumberofsigniLicantdigits.[[UseGrouping]]isaBooleanvalueindicatingwhetheragroupingseparatorshouldbeused.[[PositivePattern]]and[[NegativePattern]]areStringvaluesas

describedin11.3.3.

Finally,objectsthathavebeensuccessfullyinitializedasaNumberFormathavea[[BoundFormat]]internalslotthatcachesthefunctionreturnedbytheformataccessor(11.4.3).

SeveralDateTimeFormatalgorithmsusevaluesfromthefollowingtable,whichprovidesinternalslots,propertynamesandallowablevaluesforthecomponentsofdateandtimeformats:

Table4:Componentsofdateandtimeformats

InternalSlot Property Values

[[Weekday]] "weekday" "narrow","short","long"

[[Era]] "era" "narrow","short","long"

[[Year]] "year" "2-digit","numeric"

[[Month]] "month" "2-digit","numeric","narrow","short","long"

[[Day]] "day" "2-digit","numeric"

[[Hour]] "hour" "2-digit","numeric"

[[Minute]] "minute" "2-digit","numeric"

[[Second]] "second" "2-digit","numeric"

12 DateTimeFormatObjects

12.1 AbstractOperationsForDateTimeFormatObjects

[[TimeZoneName]] "timeZoneName" "short","long"

TheabstractoperationInitializeDateTimeFormatacceptstheargumentsdateTimeFormat(whichmustbeanobject),locales,andoptions.ItinitializesdateTimeFormatasaDateTimeFormatobject.Thisabstractoperationfunctionsasfollows:

1. IfdateTimeFormat.[[InitializedIntlObject]]istrue,throwaTypeErrorexception.

2. SetdateTimeFormat.[[InitializedIntlObject]]totrue.3. LetrequestedLocalesbe?CanonicalizeLocaleList(locales).4. Letoptionsbe?ToDateTimeOptions(options,"any","date").5. LetoptbeanewRecord.6. Letmatcherbe?GetOption(options,"localeMatcher","string",«"lookup","best9it"»,"best9it").

7. Setopt.[[localeMatcher]]tomatcher.8. LetlocaleDatabe%DateTimeFormat%.[[LocaleData]].9. LetrbeResolveLocale(%DateTimeFormat%.[[AvailableLocales]],requestedLocales,opt,%DateTimeFormat%.[[RelevantExtensionKeys]],localeData).

10. SetdateTimeFormat.[[Locale]]tor.[[locale]].11. SetdateTimeFormat.[[Calendar]]tor.[[ca]].12. SetdateTimeFormat.[[NumberingSystem]]tor.[[nu]].13. LetdataLocaleber.[[dataLocale]].14. Lettzbe?Get(options,"timeZone").15. Iftzisnotunde9ined,then

a. Lettzbe?ToString(tz).b. IftheresultofIsValidTimeZoneName(tz)isfalse,then

i. ThrowaRangeErrorexception.c. LettzbeCanonicalizeTimeZoneName(tz).

12.1.1 InitializeDateTimeFormat(dateTimeFormat,locales,options)

16. Else,a. LettzbeDefaultTimeZone().

17. SetdateTimeFormat.[[TimeZone]]totz.18. LetoptbeanewRecord.19. ForeachrowofTable4,excepttheheaderrow,do:

a. LetpropbethenamegiveninthePropertycolumnoftherow.

b. Letvaluebe?GetOption(options,prop,"string",«thestringsgivenintheValuescolumnoftherow»,unde9ined).

c. Setopt.[[<prop>]]tovalue.20. LetdataLocaleDatabeGet(localeData,dataLocale).21. LetformatsbeGet(dataLocaleData,"formats").22. Letmatcherbe?GetOption(options,"formatMatcher",

"string",«"basic","best9it"»,"best9it").23. Ifmatcheris"basic",then

a. LetbestFormatbeBasicFormatMatcher(opt,formats).24. Else,

a. LetbestFormatbeBestFitFormatMatcher(opt,formats).25. ForeachrowinTable4,excepttheheaderrow,do

a. LetpropbethenamegiveninthePropertycolumnoftherow.

b. LetpbeGet(bestFormat,prop).c. Ifpnotunde9ined,then

i. SetdateTimeFormat'sinternalslotwhosenameistheInternalSlotcolumnoftherowtop.

26. Lethr12be?GetOption(options,"hour12","boolean",unde9ined,unde9ined).

27. IfdateTimeFormathasaninternalslot[[Hour]],thena. Ifhr12isunde9ined,then

i. Lethr12beGet(dataLocaleData,"hour12").b. SetdateTimeFormat.[[Hour12]]tohr12.c. Ifhr12istrue,then

i. LethourNo0beGet(dataLocaleData,"hourNo0").ii. SetdateTimeFormat.[[HourNo0]]tohourNo0.iii. LetpatternbeGet(bestFormat,"pattern12").

d. Else,i. LetpatternbeGet(bestFormat,"pattern").

28. Else,a. LetpatternbeGet(bestFormat,"pattern").

29. SetdateTimeFormat.[[Pattern]]topattern.30. SetdateTimeFormat.[[BoundFormat]]tounde9ined.31. SetdateTimeFormat.[[InitializedDateTimeFormat]]totrue.32. ReturndateTimeFormat.

WhentheToDateTimeOptionsabstractoperationiscalledwithargumentsoptions,required,anddefaults,thefollowingstepsaretaken:

1. Ifoptionsisunde9ined,letoptionsbenull;otherwiseletoptionsbe?ToObject(options).

2. LetoptionsbeObjectCreate(options).3. LetneedDefaultsbetrue.4. Ifrequiredis"date"or"any",

a. Foreachofthepropertynames"weekday","year","month","day":i. Letpropbethepropertyname.ii. Letvaluebe?Get(options,prop).iii. Ifvalueisnotunde9ined,letneedDefaultsbefalse.

5. Ifrequiredis"time"or"any",a. Foreachofthepropertynames"hour","minute","second":i. Letpropbethepropertyname.ii. Letvaluebe?Get(options,prop).

12.1.2 ToDateTimeOptions(options,required,defaults)

iii. Ifvalueisnotunde9ined,letneedDefaultsbefalse.6. IfneedDefaultsistrueanddefaultsiseither"date"or"all",thena. Foreachofthepropertynames"year","month","day":

i. Perform?CreateDataPropertyOrThrow(options,prop,"numeric").

7. IfneedDefaultsistrueanddefaultsiseither"time"or"all",thena. Foreachofthepropertynames"hour","minute","second":i. Perform?CreateDataPropertyOrThrow(options,prop,"numeric").

8. Returnoptions.

WhentheBasicFormatMatcherabstractoperationiscalledwithtwoargumentsoptionsandformats,thefollowingstepsaretaken:

1. LetremovalPenaltybe120.2. LetadditionPenaltybe20.3. LetlongLessPenaltybe8.4. LetlongMorePenaltybe6.5. LetshortLessPenaltybe6.6. LetshortMorePenaltybe3.7. LetbestScorebe-In9inity.8. LetbestFormatbeunde9ined.9. Letkbe0.10. Assert:formatsisanArrayobject.11. LetlenbeGet(formats,"length").12. Repeatwhilek<len:

a. LetformatbeGet(formats,ToString(k)).b. Letscorebe0.

12.1.3 BasicFormatMatcher(options,formats)

c. ForeachpropertyshowninTable4:i. LetoptionsPropbeoptions.[[<property>]].ii. LetformatPropbeGet(format,property).iii. IfoptionsPropisunde9inedandformatPropisnot

unde9ined,thendecreasescorebyadditionPenalty.iv. ElseifoptionsPropisnotunde9inedandformatProp

isunde9ined,thendecreasescorebyremovalPenalty.v. ElseifoptionsProp≠formatProp,

1. Letvaluesbethearray["2-digit","numeric","narrow","short","long"].

2. LetoptionsPropIndexbetheindexofoptionsPropwithinvalues.

3. LetformatPropIndexbetheindexofformatPropwithinvalues.

4. Letdeltabemax(min(formatPropIndex-optionsPropIndex,2),-2).

5. Ifdelta=2,decreasescorebylongMorePenalty.6. Elseifdelta=1,decreasescorebyshortMorePenalty.

7. Elseifdelta=-1,decreasescorebyshortLessPenalty.

8. Elseifdelta=-2,decreasescorebylongLessPenalty.

d. Ifscore>bestScore,i. LetbestScorebescore.ii. LetbestFormatbeformat.

e. Increasekby1.13. ReturnbestFormat.

WhentheBestFitFormatMatcherabstractoperationiscalledwithtwoargumentsoptionsandformats,itperformsimplementation

12.1.4 BestFitFormatMatcher(options,formats)

dependentsteps,whichshouldreturnasetofcomponentrepresentationsthatatypicaluseroftheselectedlocalewouldperceiveasatleastasgoodastheonereturnedbyBasicFormatMatcher.

ADateTimeformatfunctionisananonymousbuilt-infunction.

WhenaDateTimeformatfunctioniscalledwithoptionalargumentdate,thefollowingstepsaretaken:

1. Letdtfbethethisvalue.2. Assert:Type(dtf)isObjectanddtf.[[InitializedDateTimeFormat]]istrue.

3. Ifdateisnotprovidedorisunde9ined,thena. LetxbeCall(%Date_now%,unde9ined).

4. Else,a. Letxbe?ToNumber(date).

5. ReturnFormatDateTime(dtf,x).

NOTE Thefunctionreturnedby[[Get]]isboundtothisDateTimeFormatobjectsothatitcanbepasseddirectlytoArray.prototype.maporotherfunctions.

ThelengthpropertyofaDateTimeformatfunctionis1.

ThePartitionDateTimePatternabstractoperationiscalledwithargumentsdateTimeFormat(whichmustbeanobjectinitializedasaDateTimeFormat)andx(whichmustbeaNumbervalue),interpretsxasatimevalueasspeciLiedinES2015,20.3.1.1,andcreatesthe

12.1.5 DateTimeFormatFunctions

12.1.6 PartitionDateTimePattern(dateTimeFormat,x)

correspondingpartsaccordingtotheeffectivelocaleandtheformattingoptionsofdateTimeFormat.Thefollowingstepsaretaken:

1. IfxisnotaLiniteNumber,throwaRangeErrorexception.2. LetlocalebedateTimeFormat.[[Locale]].3. LetnfLocalebeCreateArrayFromList(«locale»).4. LetnfOptionsbeObjectCreate(%ObjectPrototype%).5. Perform!CreateDataPropertyOrThrow(nfOptions,

"useGrouping",false).6. Letnfbe?Construct(%NumberFormat%,«nfLocale,nfOptions»).

7. Letnf2OptionsbeObjectCreate(%ObjectPrototype%).8. Perform!CreateDataPropertyOrThrow(nf2Options,

"minimumIntegerDigits",2).9. Perform!CreateDataPropertyOrThrow(nf2Options,

"useGrouping",false).10. Letnf2be?Construct(%NumberFormat%,«nfLocale,

nf2Options»).11. LettmbeToLocalTime(x,dateTimeFormat.[[Calendar]],

dateTimeFormat.[[TimeZone]]).12. LetpatternbedateTimeFormat.[[Pattern]].13. LetresultbeanewemptyList.14. LetbeginIndexbeCall(%StringProto_indexOf%,pattern,"{",0).15. LetendIndexbe0.16. LetnextIndexbe0.17. Letlengthbethenumberofcodeunitsinpattern.18. RepeatwhilebeginIndexisanintegerindexintopattern:

a. SetendIndextoCall(%StringProto_indexOf%,pattern,"}",beginIndex)

b. IfendIndex=-1,thrownewErrorexception.c. IfbeginIndexisgreaterthannextIndex,then:

i. Letliteralbeasubstringofpatternfromposition

nextIndex,inclusive,topositionbeginIndex,exclusive.ii. Addnewpartrecord{[[Type]]:"literal",[[Value]]:literal}asanewelementofthelistresult.

d. LetpbethesubstringofpatternfrompositionbeginIndex,exclusive,topositionendIndex,exclusive.

e. IfpmatchesaPropertycolumnoftherowinTable4,then:i. LetfbethevalueofdateTimeFormat'sinternalslotwhosenameistheInternalSlotcolumnofthematchingrow.

ii. Letvbethevalueoftm'sLieldwhosenameistheInternalSlotcolumnofthematchingrow.

iii. Ifpis"year"andv≤0,letvbe1-v.iv. Ifpis"month",increasevby1.v. Ifpis"hour"anddateTimeFormat.[[Hour12]]istrue,then1. Letvbevmodulo12.2. Ifvis0anddateTimeFormat.[[HourNo0]]istrue,letvbe12.

vi. Iffis"numeric",then1. LetfvbeFormatNumber(nf,v).

vii. Elseiffis"2-digit",then1. LetfvbeFormatNumber(nf2,v).2. Ifthelengthpropertyoffvisgreaterthan2,letfvbethesubstringoffvcontainingthelasttwocharacters.

viii. Elseiffis"narrow","short",or"long",thenletfvbeaStringvaluerepresentingfinthedesiredform;theStringvaluedependsupontheimplementationandtheeffectivelocaleandcalendarofdateTimeFormat.Ifpis"month",thentheStringvaluemayalsodependonwhetherdateTimeFormathasa[[Day]]internalslot.Ifpis"timeZoneName",thentheStringvaluemayalsodependonthevalueofthe[[inDST]]

Lieldoftm.Ifpis"era",thentheStringvaluemayalsodependonwhetherdateTimeFormathasa[[Era]]internalslotandiftheimplementationdoesnothavealocalizedrepresentationoff,thenusefitself.

ix. Addnewpartrecord{[[Type]]:p,[[Value]]:fv}asanewelementofthelistresult.

f. Elseifpisequal"ampm",then:i. Letvbetm.[[hour]].ii. Ifvisgreaterthan11,then:

1. LetfvbeanimplementationandlocaledependentStringvaluerepresenting"postmeridiem";

iii. Else,1. LetfvbeanimplementationandlocaledependentStringvaluerepresenting"antemeridiem".

iv. Addnewpartrecord{[[Type]]:"dayPeriod",[[Value]]:fv}asanewelementofthelistresult.

v. LetliteralbethesubstringofpatternfrompositionbeginIndex,inclusive,topositionendIndex,inclusive.

vi. Addnewpartrecord{[[Type]]:"literal",[[Value]]:literal}asanewelementofthelistresult.

g. SetnextIndextoendIndex+1.h. SetbeginIndextoCall(%StringProto_indexOf%,pattern,"}",nextIndex)

19. IfnextIndexislessthanlength,then:a. LetliteralbethesubstringofpatternfrompositionnextIndex,exclusive,topositionlength,exclusive.

b. Addnewpartrecord{[[Type]]:"literal",[[Value]]:literal}asanewelementofthelistresult.

20. Returnresult.

NOTE1 Itisrecommendedthatimplementationsusethe

localeandcalendardependentstringsprovidedbytheCommonLocaleDataRepository(availableathttp://cldr.unicode.org/),anduseCLDR"abbreviated"stringsforDateTimeFormat"short"strings,andCLDR"wide"stringsforDateTimeFormat"long"strings.

NOTE2 ItisrecommendedthatimplementationsusethetimezoneinformationoftheIANATimeZoneDatabase.

TheFormatDateTimeabstractoperationiscalledwithargumentsdateTimeFormat(whichmustbeanobjectinitializedasaDateTimeFormat)andx(whichmustbeaNumbervalue),andperformsthefollowingsteps:

1. Letpartsbe?PartitionDateTimePattern(dateTimeFormat,x).2. LetresultbetheemptyString.3. Foreachpartinparts,do:

a. SetresulttoaStringvalueproducedbyconcatenatingresultandpart.[[Value]].

4. Returnresult.

TheFormatDateTimeToPartsabstractoperationiscalledwithargumentsdateTimeFormat(whichmustbeanobjectinitializedasaDateTimeFormat)andx(whichmustbeaNumbervalue),andperformsthefollowingsteps:

1. Letpartsbe?PartitionDateTimePattern(dateTimeFormat,x).2. LetresultbeArrayCreate(0).3. Letnbe0.

12.1.7 FormatDateTime(dateTimeFormat,x)

12.1.8 FormatDateTimeToParts(dateTimeFormat,x)

4. Foreachpartinparts,do:a. LetObeObjectCreate(%ObjectPrototype%).b. Perform?CreateDataPropertyOrThrow(O,"type",part.[[Type]]).

c. Perform?CreateDataPropertyOrThrow(O,"value",part.[[Value]]).

d. Perform?CreateDataProperty(result,?ToString(n),O).e. Incrementnby1.

5. Returnresult.

WhentheToLocalTimeabstractoperationiscalledwithargumentsdate,calendar,andtimeZone,thefollowingstepsaretaken:

1. ApplycalendricalcalculationsondateforthegivencalendarandtimeZonetoproduceweekday,era,year,month,day,hour,minute,second,andinDSTvalues.ThecalculationsshouldusebestavailableinformationaboutthespeciLiedcalendarandtimeZone,includingcurrentandhistoricalinformationabouttimezoneoffsetsfromUTCanddaylightsavingtimerules.Ifthecalendaris"gregory",thenthecalculationsmustmatchthealgorithmsspeciLiedinES2017,20.3.1.

2. ReturnaRecordwithLields[[weekday]],[[era]],[[year]],[[month]],[[day]],[[hour]],[[minute]],[[second]],and[[inDST]],eachwiththecorrespondingcalculatedvalue.

NOTE ItisrecommendedthatimplementationsusethetimezoneinformationoftheIANATimeZoneDatabase.

TheUnwrapDateTimeFormatabstractoperationgetstheunderlyingDateTimeFormatoperationforvariousmethodswhichimplement

12.1.9 ToLocalTime(date,calendar,timeZone)

12.1.10 UnwrapDateTimeFormat(dtf)

ECMA-402v1semanticsforsupportinginitializingexistingIntlobjects.

NORMATIVEOPTIONAL

2. IfType(dtf)isObjectanddtfdoesnothavean[[initializedDateTimeFormat]]internalslotand?InstanceofOperator(dtf,%DateTimeFormat%)istrue,then

3. Ifdtfdoesnothavean[[InitializedDateTimeFormat]]internalslotand?InstanceofOperator(dtf,%DateTimeFormat%)isequaltrue,thena. LetdtfbeGet(dtf,Intl.[[FallbackSymbol]]).

2. IfType(dtf)isnotObjectordtfdoesnothavean[[initializedDateTimeFormat]]internalslot,thena. ThrowaTypeErrorexception.

3. Returndtf.

TheIntl.DateTimeFormatconstructoristhe%DateTimeFormat%intrinsicobjectandastandardbuilt-inpropertyoftheIntlobject.BehaviourcommontoallserviceconstructorpropertiesoftheIntlobjectisspeciLiedin9.1.

WhentheIntl.DateTimeFormatfunctioniscalledwithoptional

13 TheIntl.DateTimeFormatConstructor

13.1 Intl.DateTimeFormat([locales[,options]])

argumentslocalesandoptions,thefollowingstepsaretaken:

1. IfNewTargetisunde9ined,letnewTargetbetheactivefunctionobject,elseletnewTargetbeNewTarget.

2. LetdateTimeFormatbe?OrdinaryCreateFromConstructor(newTarget,"%DateTimeFormatPrototype%",«[[InitializedIntlObject]],[[InitializedDateTimeFormat]],[[Locale]],[[Calendar]],[[NumberingSystem]],[[TimeZone]],[[Weekday]],[[Era]],[[Year]],[[Month]],[[Day]],[[Hour]],[[Minute]],[[Second]],[[TimeZoneName]],[[Hour12]],[[HourNo0]],[[Pattern]],[[BoundFormat]]»).

3. Perform?InitializeDateTimeFormat(dateTimeFormat,locales,options).

NORMATIVEOPTIONAL

4. Letthisbethethisvalue.5. IfNewTargetisunde9inedand?InstanceofOperator(this,%DateTimeFormat%),thena. Perform?DeLineOwnPropertyOrThrow(this,Intl.[[FallbackSymbol]],{[[Value]]:dateTimeFormat,[[Writable]]:false,[[Enumerable]]:false,[[ConLigurable]]:false}).

b. Returnthis.

6. ReturndateTimeFormat.

14 PropertiesoftheIntl.DateTimeFormatConstructor

TheIntl.DateTimeFormatconstructorhasthefollowingproperties:

ThevalueofIntl.DateTimeFormat.prototypeis%DateTimeFormatPrototype%.

Thispropertyhastheattributes{[[Writable]]:false,[[Enumerable]]:false,[[ConLigurable]]:false}.

WhenthesupportedLocalesOfmethodiscalledwithargumentslocalesandoptions,thefollowingstepsaretaken:

1. LetavailableLocalesbe%DateTimeFormat%.[[AvailableLocales]].

2. LetrequestedLocalesbe?CanonicalizeLocaleList(locales).3. Return?SupportedLocales(availableLocales,requestedLocales,options).

ThevalueofthelengthpropertyofthesupportedLocalesOfmethodis1.

Thevalueofthe[[AvailableLocales]]internalslotisimplementationdeLinedwithintheconstraintsdescribedin9.1.

Thevalueofthe[[RelevantExtensionKeys]]internalslotis«"ca",

14.1 Intl.DateTimeFormat.prototype

14.2 Intl.DateTimeFormat.supportedLocalesOf(locales[,options])

14.3 Internalslots

"nu"».

NOTE1 UnicodeTechnicalStandard35describesthreelocaleextensionkeysthatarerelevanttodateandtimeformatting,"ca"forcalendar,"tz"fortimezone,andimplicitly"nu"forthenumberingsystemofthenumberformatusedfornumberswithinthedateformat.DateTimeFormat,however,requiresthatthetimezoneisspeciLiedthroughthetimeZonepropertyintheoptionsobjects.

Thevalueofthe[[LocaleData]]internalslotisimplementationdeLinedwithintheconstraintsdescribedin9.1andthefollowingadditionalconstraints:

Thearraythatisthevalueofthe"nu"propertyofanylocalepropertyof[[LocaleData]]mustnotincludethevalues"native","traditio",or"Linance".[[LocaleData]][locale]musthavehour12andhourNo0propertieswithBooleanvaluesforalllocalevalues.[[LocaleData]][locale]musthaveaformatspropertyforalllocalevalues.Thevalueofthispropertymustbeanarrayofobjects,eachofwhichhasasubsetofthepropertiesshowninTable4,whereeachpropertymusthaveoneofthevaluesspeciLiedforthepropertyinTable4.Multipleobjectsinanarraymayusethesamesubsetofthepropertiesaslongastheyhavedifferentvaluesfortheproperties.Thefollowingsubsetsmustbeavailableforeachlocale:

weekday,year,month,day,hour,minute,secondweekday,year,month,dayyear,month,dayyear,monthmonth,dayhour,minute,second

hour,minuteEachoftheobjectsmustalsohaveapatternproperty,whosevalueisaStringvaluethatcontainsforeachofthedateandtimeformatcomponentpropertiesoftheobjectasubstringstartingwith"{",followedbythenameoftheproperty,followedby"}".Iftheobjecthasanhourproperty,itmustalsohaveapattern12property,whosevalueisaStringvaluethat,inadditiontothesubstringsofthepatternproperty,containsasubstring"{ampm}".

EXAMPLEAnimplementationmightincludethefollowingobjectaspartofitsEnglishlocaledata:{hour:"numeric",minute:"2-digit",second:"2-digit",pattern:"{hour}:{minute}:{second}",pattern12:"{hour}:{minute}:{second}{ampm}"}.

NOTE2 ItisrecommendedthatimplementationsusethelocaledataprovidedbytheCommonLocaleDataRepository(availableathttp://cldr.unicode.org/).

TheIntl.DateTimeFormatprototypeobjectistheintrinsicobject%DateTimeFormatPrototype%.TheIntl.DateTimeFormatprototypeobjectisitselfan%DateTimeFormat%instance,whoseinternalslotsaresetasifithadbeenconstructedbytheexpressionConstruct(%DateTimeFormat%,«»,%Object%).

Inthefollowingdescriptionsoffunctionsthatarepropertiesor[[Get]]attributesofpropertiesoftheIntl.DateTimeFormatprototype

15 PropertiesoftheIntl.DateTimeFormatPrototypeObject

object,thephrase"thisDateTimeFormatobject"referstotheobjectthatisthethisvaluefortheinvocationofthefunction;aTypeErrorexceptionisthrownifthethisvalueisnotanobjectoranobjectthatdoesnothavean[[InitializedDateTimeFormat]]internalslotwithvaluetrue.

TheinitialvalueofIntl.DateTimeFormat.prototype.constructoristheintrinsicobject%DateTimeFormat%.

Theinitialvalueofthe@@toStringTagpropertyisthestringvalue"Object".

Thispropertyhastheattributes{[[Writable]]:false,[[Enumerable]]:false,[[ConLigurable]]:true}.

Intl.DateTimeFormat.prototype.formatisanaccessorpropertywhosesetaccessorfunctionisunde9ined.Itsgetaccessorfunctionperformsthefollowingsteps:

1. Letdtfbethisvalue.2. IfType(dtf)isnotObject,throwaTypeErrorexception.

15.1 Intl.DateTimeFormat.prototype.constructor

15.2 Intl.DateTimeFormat.prototype[@@toStringTag]

15.3 getIntl.DateTimeFormat.prototype.format

3. Letdtfbe?UnwrapDateTimeFormat(dtf).4. Ifdtf.[[BoundFormat]]isunde9ined,then

a. LetFbeanewbuilt-infunctionobjectasdeLinedinDateTimeFormatFunctions(12.1.5).

b. LetbfbeBoundFunctionCreate(F,dft,«»).c. Perform!DeLinePropertyOrThrow(bf,"length",PropertyDescriptor{[[Value]]:1,[[Writable]]:false,[[Enumerable]]:false,[[ConLigurable]]:true}).

d. Setdtf.[[BoundFormat]]tobf.5. Returndtf.[[BoundFormat]].

WhentheformatToPartsmethodiscalledwithanoptionalargumentdate,thefollowingstepsaretaken:

1. Letdtfbethisvalue.2. IfType(dtf)isnotObject,throwaTypeErrorexception.3. Ifdtfdoesnothavean[[InitializedDateTimeFormat]]internalslot,throwaTypeErrorexception.

4. Ifdateisnotprovidedorisunde9ined,thena. Letxbe%Date_now%().

5. Else,a. Letxbe?ToNumber(date).

6. Return?FormatDateTimeToParts(dtf,x).

Thisfunctionprovidesaccesstothelocaleandformattingoptions

15.4 Intl.DateTimeFormat.prototype.formatToParts([date])

15.5 Intl.DateTimeFormat.prototype.resolvedOptions()

computedduringinitializationoftheobject.ThisfunctioninitiallyinvokestheinternalalgorithmUnwrapDateTimeFormattogetthe%DateTimeFormat%objectonwhichtooperate.

ThefunctionreturnsanewobjectwhosepropertiesandattributesaresetasifconstructedbyanobjectliteralassigningtoeachofthefollowingpropertiesthevalueofthecorrespondinginternalslotofthisDateTimeFormatobject(see16):locale,calendar,numberingSystem,timeZone,hour12,weekday,era,year,month,day,hour,minute,second,andtimeZoneName.Propertieswhosecorrespondinginternalslotshavethevalueunde9inedarenotassigned.

NOTE InthisversionoftheECMAScript2017InternationalizationAPI,thetimeZonepropertywillbethenameofthedefaulttimezoneifnotimeZonepropertywasprovidedintheoptionsobjectprovidedtotheIntl.DateTimeFormatconstructor.TheLirsteditionleftthetimeZonepropertyunde9inedinthiscase.

Intl.DateTimeFormatinstancesinheritpropertiesfrom%DateTimeFormatPrototype%.

Intl.DateTimeFormatinstancesandotherobjectsthathavebeensuccessfullyinitializedasaDateTimeFormatobjecthave[[InitializedIntlObject]]and[[InitializedDateTimeFormat]]internalslotswhosevaluesaretrue.

16 PropertiesofIntl.DateTimeFormatInstances

ObjectsthathavebeensuccessfullyinitializedasaDateTimeFormatalsohaveseveralinternalslotsthatarecomputedbytheconstructor:

[[Locale]]isaStringvaluewiththelanguagetagofthelocalewhoselocalizationisusedforformatting.[[Calendar]]isaStringvaluewiththe"type"giveninUnicodeTechnicalStandard35forthecalendarusedforformatting.[[NumberingSystem]]isaStringvaluewiththe"type"giveninUnicodeTechnicalStandard35forthenumberingsystemusedforformatting.[[TimeZone]]isaStringvaluewiththeIANAtimezonenameofthetimezoneusedforformatting.[[Weekday]],[[Era]],[[Year]],[[Month]],[[Day]],[[Hour]],[[Minute]],[[Second]],[[TimeZoneName]]areeacheitherunde9ined,indicatingthatthecomponentisnotusedforformatting,oroneoftheStringvaluesgiveninTable4,indicatinghowthecomponentshouldbepresentedintheformattedoutput.[[Hour12]]isaBooleanvalueindicatingwhether12-hourformat(true)or24-hourformat(false)shouldbeused.Itisonlyusedwhen[[Hour]]isnotunde9ined.[[HourNo0]]isaBooleanvalueindicatingwhetherhoursfrom1to12(true)orfrom0to11(false)shouldbeused.Itisonlyusedwhen[[Hour12]]hasthevaluetrue.[[Pattern]]isaStringvalueasdescribedin14.3.

Finally,objectsthathavebeensuccessfullyinitializedasaDateTimeFormathavea[[BoundFormat]]internalslotthatcachesthefunctionreturnedbytheformataccessor(15.3).

17 LocaleSensitiveFunctionsoftheECMAScriptLanguage

TheECMAScriptLanguageSpeciLication,edition6orsuccessor,describesseverallocalesensitivefunctions.AnECMAScriptimplementationthatimplementsthisInternationalizationAPISpeciLicationshallimplementthesefunctionsasdescribedhere.

NOTE TheCollator,NumberFormat,orDateTimeFormatobjectscreatedinthealgorithmsinthisclauseareonlyusedwithinthesealgorithms.TheyareneverdirectlyaccessedbyECMAScriptcodeandneednotactuallyexistwithinanimplementation.

ThisdeLinitionsupersedesthedeLinitionprovidedinES2017,21.1.3.10.

WhenthelocaleComparemethodiscalledwithargumentthatandoptionalargumentslocales,andoptions,thefollowingstepsaretaken:

1. LetObeRequireObjectCoercible(thisvalue).2. LetSbe?ToString(O).3. LetthatValuebe?ToString(that).4. Letcollatorbe?Construct(%Collator%,«locales,options»).5. ReturnCompareStrings(collator,S,thatValue).

ThevalueofthelengthpropertyofthelocaleComparemethodis

Speci9ication

17.1 PropertiesoftheStringPrototypeObject

17.1.1 String.prototype.localeCompare(that[,locales[,options]])

1.

NOTE1 ThelocaleComparemethoditselfisnotdirectlysuitableasanargumenttoArray.prototype.sortbecausethelatterrequiresafunctionoftwoarguments.

NOTE2 ThelocaleComparefunctionisintentionallygeneric;itdoesnotrequirethatitsthisvaluebeaStringobject.Therefore,itcanbetransferredtootherkindsofobjectsforuseasamethod.

ThisdeLinitionsupersedesthedeLinitionprovidedinES2017,21.1.3.22.

Thisfunctioninterpretsastringvalueasasequenceofcodepoints,asdescribedinES2017,6.1.4.Thefollowingstepsaretaken:

1. LetObeRequireObjectCoercible(thisvalue).2. LetSbe?ToString(O).3. LetrequestedLocalesbe?CanonicalizeLocaleList(locales).4. LetlenbethenumberofelementsinrequestedLocales.5. Iflen>0,then

a. LetrequestedLocalebetheLirstelementofrequestedLocales.

6. Else,a. LetrequestedLocalebeDefaultLocale().

7. LetnoExtensionsLocalebetheStringvaluethatisrequestedLocalewithallUnicodelocaleextensionsequences(6.2.1)removed.

8. LetavailableLocalesbeaListwiththelanguagetagsofthe

17.1.2 String.prototype.toLocaleLowerCase([locales])

languagesforwhichtheUnicodecharacterdatabasecontainslanguagesensitivecasemappings.

9. LetlocalebeBestAvailableLocale(availableLocales,noExtensionsLocale).

10. Iflocaleisunde9ined,letlocalebe"und".11. LetcpListbeaListcontaininginorderthecodepointsofSas

deLinedinES2017,6.1.4,startingattheLirstelementofS.12. ForeachcodepointcincpList,iftheUnicodeCharacter

Databaseprovidesalowercaseequivalentofcthatiseitherlanguageinsensitiveorforthelanguagelocale,replacecincpListwiththat/thoseequivalentcodepoint(s).

13. LetcuListbeanewemptyList.14. ForeachcodepointcincpList,inorder,appendtocuListthe

elementsoftheUTF-16Encoding(deLinedinES2017,6.1.4)ofc.

15. LetLbeaStringwhoseelementsare,inorder,theelementsofcuList.

16. ReturnL.

TheresultmustbederivedaccordingtothecasemappingsintheUnicodecharacterdatabase(thisexplicitlyincludesnotonlytheUnicodeData.txtLile,butalsotheSpecialCasings.txtLilethataccompaniesit).

NOTE1 AsofUnicode5.1,theavailableLocaleslistcontainstheelements"az","lt",and"tr".

NOTE2 Thecasemappingofsomecodepointsmayproducemultiplecodepoints.InthiscasetheresultStringmaynotbethesamelengthasthesourceString.BecausebothtoLocaleUpperCaseandtoLocaleLowerCasehavecontext-sensitivebehaviour,thefunctionsarenotsymmetrical.Inotherwords,s.toLocaleUpperCase().toLocaleLowerCase()isnot

necessarilyequaltos.toLocaleLowerCase().

NOTE3 ThetoLocaleLowerCasefunctionisintentionallygeneric;itdoesnotrequirethatitsthisvaluebeaStringobject.Therefore,itcanbetransferredtootherkindsofobjectsforuseasamethod.

ThisdeLinitionsupersedesthedeLinitionprovidedinES2017,21.1.3.23.

Thisfunctioninterpretsastringvalueasasequenceofcodepoints,asdescribedinES2017,6.1.4.ThisfunctionbehavesinexactlythesamewayasString.prototype.toLocaleLowerCase,exceptthatcharactersaremappedtotheiruppercaseequivalentsasspeciLiedintheUnicodecharacterdatabase.

NOTE ThetoLocaleUpperCasefunctionisintentionallygeneric;itdoesnotrequirethatitsthisvaluebeaStringobject.Therefore,itcanbetransferredtootherkindsofobjectsforuseasamethod.

ThefollowingdeLinition(s)refertotheabstractoperationthisNumberValueasdeLinedinES2017,20.1.3.

17.1.3 String.prototype.toLocaleUpperCase([locales])

17.2 PropertiesoftheNumberPrototypeObject

17.2.1 Number.prototype.toLocaleString([locales[,options]])

ThisdeLinitionsupersedesthedeLinitionprovidedinES2017,20.1.3.4.

WhenthetoLocaleStringmethodiscalledwithoptionalargumentslocalesandoptions,thefollowingstepsaretaken:

1. Letxbe?thisNumberValue(thisvalue).2. LetnumberFormatbe?Construct(%NumberFormat%,«locales,options»).

3. ReturnFormatNumber(numberFormat,x).

ThefollowingdeLinition(s)refertotheabstractoperationthisTimeValueasdeLinedinES2017,20.3.4.

ThisdeLinitionsupersedesthedeLinitionprovidedinES2017,20.3.4.39.

WhenthetoLocaleStringmethodiscalledwithoptionalargumentslocalesandoptions,thefollowingstepsaretaken:

1. Letxbe?thisTimeValue(thisvalue).2. IfxisNaN,return"InvalidDate".3. Letoptionsbe?ToDateTimeOptions(options,"any","all").4. LetdateFormatbe?Construct(%DateTimeFormat%,«locales,options»).

5. ReturnFormatDateTime(dateFormat,x).

17.3 PropertiesoftheDatePrototypeObject

17.3.1 Date.prototype.toLocaleString([locales[,options]])

ThisdeLinitionsupersedesthedeLinitionprovidedinES2017,20.3.4.38.

WhenthetoLocaleDateStringmethodiscalledwithoptionalargumentslocalesandoptions,thefollowingstepsaretaken:

1. Letxbe?thisTimeValue(thisvalue).2. IfxisNaN,return"InvalidDate".3. Letoptionsbe?ToDateTimeOptions(options,"date","date").4. LetdateFormatbe?Construct(%DateTimeFormat%,«locales,options»).

5. ReturnFormatDateTime(dateFormat,x).

ThisdeLinitionsupersedesthedeLinitionprovidedinES2017,20.3.4.40.

WhenthetoLocaleTimeStringmethodiscalledwithoptionalargumentslocalesandoptions,thefollowingstepsaretaken:

1. Letxbe?thisTimeValue(thisvalue).2. IfxisNaN,return"InvalidDate".3. Letoptionsbe?ToDateTimeOptions(options,"time","time").4. LettimeFormatbe?Construct(%DateTimeFormat%,«locales,options»).

5. ReturnFormatDateTime(timeFormat,x).

17.3.2 Date.prototype.toLocaleDateString([locales[,options]])

17.3.3 Date.prototype.toLocaleTimeString([locales[,options]])

17.4 PropertiesoftheArrayPrototypeObject

ThisdeLinitionsupersedesthedeLinitionprovidedinES2017,22.1.3.27.

WhenthetoLocaleStringmethodiscalledwithoptionalargumentslocalesandoptions,thefollowingstepsaretaken:

1. LetAbe?ToObject(thisvalue).2. Letlenbe?ToLength(?Get(A,"length")).3. LetseparatorbetheStringvalueforthelist-separatorStringappropriateforthehostenvironment’scurrentlocale(thisisderivedinanimplementation-deLinedway).

4. Ifleniszero,returntheemptyString.5. LetUirstElementbe?Get(A,"0").6. IfUirstElementisunde9inedornull,then

a. LetRbetheemptyString.7. Else,

a. LetRbe?ToString(?Invoke(UirstElement,"toLocaleString",«locales,options»)).

8. Letkbe1.9. Repeat,whilek<len

a. LetSbeaStringvalueproducedbyconcatenatingRandseparator.

b. LetnextElementbe?Get(A,ToString(k)).c. IfnextElementisunde9inedornull,then

i. LetRbetheemptyString.d. Else,

i. LetRbe?ToString(?Invoke(nextElement,"toLocaleString",«locales,options»)).

e. LetRbeaStringvalueproducedbyconcatenatingSandR.f. Increasekby1.

10. ReturnR.

NOTE1 TheelementsofthearrayareconvertedtoStrings

17.4.1 Array.prototype.toLocaleString([locales[,options]])

NOTE1 TheelementsofthearrayareconvertedtoStringsusingtheirtoLocaleStringmethods,andtheseStringsarethenconcatenated,separatedbyoccurrencesofaseparatorStringthathasbeenderivedinanimplementationdeLinedlocale-speciLicway.TheresultofcallingthisfunctionisintendedtobeanalogoustotheresultoftoString,exceptthattheresultofthisfunctionisintendedtobelocale-speciLic.

NOTE2 ThetoLocaleStringfunctionisintentionallygeneric;itdoesnotrequirethatitsthisvaluebeanArrayobject.Thereforeitcanbetransferredtootherkindsofobjectsforuseasamethod.

ThefollowingaspectsoftheECMAScript2017InternationalizationAPISpeciLicationareimplementationdependent:

Inallfunctionality:Additionalvaluesforsomepropertiesofoptionsarguments(2)CanonicalizationofextensionsubtagsequencesbeyondtherulesofRFC5646(6.2.3)Thedefaultlocale(6.2.4)Thedefaulttimezone(6.4.3)Thesetofavailablelocalesforeachconstructor(9.1)TheBestFitMatcheralgorithm(9.2.4)TheBestFitSupportedLocalesalgorithm(9.2.8)

InCollator:SupportfortheUnicodeextensionskeyskn,kfandthe

A ImplementationDependentBehaviour

paralleloptionspropertiesnumeric,caseFirst(10.1.1)Thesetofsupported"co"keyvalues(collations)perlocalebeyondadefaultcollation(10.2.3)Thesetofsupported"kn"keyvalues(numericcollation)perlocale(10.2.3)Thesetofsupported"kf"keyvalues(caseorder)perlocale(10.2.3)Thedefaultsearchsensitivityperlocale(10.2.3)Thesortorderforeachsupportedlocaleandoptionscombination(10.3.4)

InNumberFormat:Thesetofsupported"nu"keyvalues(numberingsystems)perlocale(11.3.3)Thepatternsusedforformattingpositiveandnegativevaluesasdecimal,percent,orcurrencyvaluesperlocale(11.1.7)LocalizedrepresentationsofNaNandIn9inity(11.1.7)TheimplementationofnumberingsystemsnotlistedinTable3(11.1.7)Localizeddecimalandgroupingseparators(11.1.7)Localizeddigitgroupingschemata(11.1.7)Localizedcurrencysymbolsandnames(11.1.7)

InDateTimeFormat:TheBestFitFormatMatcheralgorithm(12.1.1)Thesetofsupported"ca"keyvalues(calendars)perlocale(14.3)Thesetofsupported"nu"keyvalues(numberingsystems)perlocale(14.3)Thedefaulthour12andhourNo0settingsperlocale(14.3)Thesetofsupporteddate-timeformatsperlocalebeyondacoreset,includingtherepresentationsusedforeachcomponentandtheassociatedpatterns(14.3)Localizedweekdaynames,eranames,monthnames,

am/pmindicators,andtimezonenames(12.1.7)Thecalendriccalculationsusedforcalendarsotherthan"gregory",andadjustmentsforlocaltimezonesanddaylightsavingtime(12.1.7)

10.1,11.2,13InECMA-402,1stEdition,constructorscouldbeusedtocreateIntlobjectsfromarbitraryobjects.Thisisnolongerpossiblein2ndEdition.15.3InECMA-402,1stEdition,thelengthpropertyofthefunctionobjectFwassetto0.In2ndEdition,lengthissetto1.

EcmaInternational

RueduRhone114

CH-1204Geneva

Tel:+41228496000

Fax:+41228496001

Web:http://www.ecma-international.org

B AdditionsandChangesThatIntroduceIncompatibilitieswithPriorEditions

C Copyright&SoftwareLicense

©2017EcmaInternational

Thisdraftdocumentmaybecopiedandfurnishedtoothers,andderivativeworksthatcommentonorotherwiseexplainitorassistinitsimplementationmaybeprepared,copied,published,anddistributed,inwholeorinpart,withoutrestrictionofanykind,providedthattheabovecopyrightnoticeandthissectionareincludedonallsuchcopiesandderivativeworks.However,thisdocumentitselfmaynotbemodiLiedinanyway,includingbyremovingthecopyrightnoticeorreferencestoEcmaInternational,exceptasneededforthepurposeofdevelopinganydocumentordeliverableproducedbyEcmaInternational.

ThisdisclaimerisvalidonlypriortoLinalversionofthisdocument.AfterapprovalallrightsonthestandardarereservedbyEcmaInternational.

ThelimitedpermissionsaregrantedthroughthestandardizationphaseandwillnotberevokedbyEcmaInternationaloritssuccessorsorassignsduringthistime.

Thisdocumentandtheinformationcontainedhereinisprovidedonan"ASIS"basisandECMAINTERNATIONALDISCLAIMSALLWARRANTIES,EXPRESSORIMPLIED,INCLUDINGBUTNOTLIMITEDTOANYWARRANTYTHATTHEUSEOFTHEINFORMATIONHEREINWILLNOTINFRINGEANYOWNERSHIPRIGHTSORANYIMPLIEDWARRANTIESOFMERCHANTABILITYORFITNESSFORAPARTICULARPURPOSE.

AllSoftwarecontainedinthisdocument("Software")isprotectedby

CopyrightNotice

SoftwareLicense

copyrightandisbeingmadeavailableunderthe"BSDLicense",includedbelow.ThisSoftwaremaybesubjecttothirdpartyrights(rightsfrompartiesotherthanEcmaInternational),includingpatentrights,andnolicensesundersuchthirdpartyrightsaregrantedunderthislicenseevenifthethirdpartyconcernedisamemberofEcmaInternational.SEETHEECMACODEOFCONDUCTINPATENTMATTERSAVAILABLEAThttp://www.ecma-international.org/memento/codeofconduct.htmFORINFORMATIONREGARDINGTHELICENSINGOFPATENTCLAIMSTHATAREREQUIREDTOIMPLEMENTECMAINTERNATIONALSTANDARDS.

Redistributionanduseinsourceandbinaryforms,withorwithoutmodiLication,arepermittedprovidedthatthefollowingconditionsaremet:

1. Redistributionsofsourcecodemustretaintheabovecopyrightnotice,thislistofconditionsandthefollowingdisclaimer.

2. Redistributionsinbinaryformmustreproducetheabovecopyrightnotice,thislistofconditionsandthefollowingdisclaimerinthedocumentationand/orothermaterialsprovidedwiththedistribution.

3. NeitherthenameoftheauthorsnorEcmaInternationalmaybeusedtoendorseorpromoteproductsderivedfromthissoftwarewithoutspeciLicpriorwrittenpermission.

THISSOFTWAREISPROVIDEDBYTHEECMAINTERNATIONAL"ASIS"ANDANYEXPRESSORIMPLIEDWARRANTIES,INCLUDING,BUTNOTLIMITEDTO,THEIMPLIEDWARRANTIESOFMERCHANTABILITYANDFITNESSFORAPARTICULARPURPOSEAREDISCLAIMED.INNOEVENTSHALLECMAINTERNATIONALBELIABLEFORANYDIRECT,INDIRECT,INCIDENTAL,SPECIAL,EXEMPLARY,ORCONSEQUENTIALDAMAGES(INCLUDING,BUTNOTLIMITEDTO,PROCUREMENTOFSUBSTITUTEGOODSORSERVICES;LOSSOFUSE,DATA,ORPROFITS;ORBUSINESSINTERRUPTION)

HOWEVERCAUSEDANDONANYTHEORYOFLIABILITY,WHETHERINCONTRACT,STRICTLIABILITY,ORTORT(INCLUDINGNEGLIGENCEOROTHERWISE)ARISINGINANYWAYOUTOFTHEUSEOFTHISSOFTWARE,EVENIFADVISEDOFTHEPOSSIBILITYOFSUCHDAMAGE.