View
22
Download
0
Category
Preview:
Citation preview
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.
Recommended