ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017...
Transcript of ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017...
![Page 1: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/1.jpg)
Reference number ECMA-123:2009
© Ecma International 2009
ECMA-402 4th Edition / June 2017
ECMAScript® 2017
Internationalization API Specification
![Page 2: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/2.jpg)
COPYRIGHT PROTECTED DOCUMENT
© Ecma International 2017
![Page 3: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/3.jpg)
© 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.
![Page 4: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/4.jpg)
ii © Ecma International 2017
![Page 5: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/5.jpg)
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
![Page 6: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/6.jpg)
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)
![Page 7: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/7.jpg)
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])
![Page 8: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/8.jpg)
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()
![Page 9: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/9.jpg)
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
![Page 10: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/10.jpg)
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
![Page 11: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/11.jpg)
Editor,1stEditionNorbertLindenberg
ContributorsEricAlbrightNebojšaĆirićPeterConstableMarkDavisRichardGillamStevenLoomisMihaiNitaAddisonPhillipsRoozbehPournaderJungshikShinShawnSteeleAllenWirfs-Brock
FeedbackandReviewfromErikArvidssonJohnJ.BartonZbigniewBranieckiMarcosCáceresBrendanEichJohnEmmonsGordonP.HemsleyDavidHermanLukeHobanOliverHuntSureshJayabalanYehudaKatzMarkS.MillerAndrewPaprockiAdamPellerAxelRauschmayerAndreasRossberg
![Page 12: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/12.jpg)
AlexRussellMarkusSchererDmitrySoshnikovYusukeSuzukiJohnTamplinRickWaldronAntonYatsenkoNicholasZakas
ThisStandarddeLinestheapplicationprogramminginterfaceforECMAScriptobjectsthatsupportprogramsthatneedtoadapttothelinguisticandculturalconventionsusedbydifferenthumanlanguagesandcountries.
AconformingimplementationoftheECMAScript2017InternationalizationAPISpeciLicationmustconformtotheECMAScript2017LanguageSpeciLication(ECMA-2628thEdition,orsuccessor),andmustprovideandsupportalltheobjects,properties,functions,andprogramsemanticsdescribedinthisspeciLication.
AconformingimplementationoftheECMAScript2017InternationalizationAPISpeciLicationispermittedtoprovideadditionalobjects,properties,andfunctionsbeyondthosedescribedinthisspeciLication.Inparticular,aconformingimplementationoftheECMAScript2017InternationalizationAPISpeciLicationis
1 Scope
2 Conformance
![Page 13: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/13.jpg)
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
![Page 14: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/14.jpg)
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
![Page 15: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/15.jpg)
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
![Page 16: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/16.jpg)
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
![Page 17: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/17.jpg)
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
![Page 18: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/18.jpg)
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
![Page 19: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/19.jpg)
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
![Page 20: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/20.jpg)
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).
![Page 21: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/21.jpg)
%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
![Page 22: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/22.jpg)
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
![Page 23: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/23.jpg)
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)
![Page 24: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/24.jpg)
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)
![Page 25: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/25.jpg)
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
![Page 26: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/26.jpg)
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
![Page 27: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/27.jpg)
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(...)
![Page 28: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/28.jpg)
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
![Page 29: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/29.jpg)
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
![Page 30: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/30.jpg)
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)
![Page 31: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/31.jpg)
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)
![Page 32: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/32.jpg)
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)
![Page 33: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/33.jpg)
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)
![Page 34: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/34.jpg)
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)
![Page 35: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/35.jpg)
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).
![Page 36: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/36.jpg)
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)
![Page 37: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/37.jpg)
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
![Page 38: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/38.jpg)
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
![Page 39: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/39.jpg)
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)
![Page 40: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/40.jpg)
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)
![Page 41: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/41.jpg)
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)
![Page 42: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/42.jpg)
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)
![Page 43: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/43.jpg)
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.
![Page 44: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/44.jpg)
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
![Page 45: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/45.jpg)
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]])
![Page 46: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/46.jpg)
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])
![Page 47: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/47.jpg)
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
![Page 48: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/48.jpg)
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]
![Page 49: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/49.jpg)
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
![Page 50: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/50.jpg)
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.
![Page 51: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/51.jpg)
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
![Page 52: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/52.jpg)
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
![Page 53: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/53.jpg)
[[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
![Page 54: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/54.jpg)
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)
![Page 55: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/55.jpg)
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
![Page 56: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/56.jpg)
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).
![Page 57: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/57.jpg)
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
![Page 58: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/58.jpg)
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)
![Page 59: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/59.jpg)
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
![Page 60: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/60.jpg)
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
![Page 61: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/61.jpg)
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",
![Page 62: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/62.jpg)
[[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
![Page 63: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/63.jpg)
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
![Page 64: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/64.jpg)
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
![Page 65: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/65.jpg)
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)
![Page 66: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/66.jpg)
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)
![Page 67: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/67.jpg)
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)
![Page 68: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/68.jpg)
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)
![Page 69: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/69.jpg)
?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]])
![Page 70: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/70.jpg)
[[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])
![Page 71: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/71.jpg)
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
![Page 72: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/72.jpg)
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
![Page 73: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/73.jpg)
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
![Page 74: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/74.jpg)
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
![Page 75: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/75.jpg)
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
![Page 76: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/76.jpg)
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
![Page 77: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/77.jpg)
[[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)
![Page 78: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/78.jpg)
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
![Page 79: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/79.jpg)
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)
![Page 80: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/80.jpg)
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)
![Page 81: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/81.jpg)
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)
![Page 82: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/82.jpg)
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)
![Page 83: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/83.jpg)
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
![Page 84: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/84.jpg)
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]]
![Page 85: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/85.jpg)
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
![Page 86: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/86.jpg)
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)
![Page 87: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/87.jpg)
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)
![Page 88: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/88.jpg)
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]])
![Page 89: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/89.jpg)
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
![Page 90: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/90.jpg)
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
![Page 91: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/91.jpg)
"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
![Page 92: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/92.jpg)
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
![Page 93: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/93.jpg)
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
![Page 94: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/94.jpg)
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()
![Page 95: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/95.jpg)
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
![Page 96: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/96.jpg)
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
![Page 97: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/97.jpg)
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]])
![Page 98: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/98.jpg)
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])
![Page 99: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/99.jpg)
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
![Page 100: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/100.jpg)
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]])
![Page 101: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/101.jpg)
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]])
![Page 102: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/102.jpg)
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
![Page 103: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/103.jpg)
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]])
![Page 104: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/104.jpg)
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
![Page 105: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/105.jpg)
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,
![Page 106: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/106.jpg)
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
![Page 107: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/107.jpg)
©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
![Page 108: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/108.jpg)
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)
![Page 109: ECMAScript Internationalization API SpecificationA conforming implementation of the ECMAScript 2017 Internationalization API SpeciLication is permitted to provide additional objects,](https://reader031.fdocuments.net/reader031/viewer/2022013003/5fb70a3756eed77ee10b0e8b/html5/thumbnails/109.jpg)
HOWEVERCAUSEDANDONANYTHEORYOFLIABILITY,WHETHERINCONTRACT,STRICTLIABILITY,ORTORT(INCLUDINGNEGLIGENCEOROTHERWISE)ARISINGINANYWAYOUTOFTHEUSEOFTHISSOFTWARE,EVENIFADVISEDOFTHEPOSSIBILITYOFSUCHDAMAGE.