Skip to content

Commit

Permalink
Editorial: Better phrasing for sorting Lists of Strings (#3299)
Browse files Browse the repository at this point in the history
There are a few places where Lists of Strings are sorted with the awkward
phrasing "ordered as if an Array of the same values had been sorted using
%Array.prototype.sort% using *undefined* as _comparefn_." Change the
wording of this, and add a definition in the section about List
specification types.  I find this clearer about the intention (the
current language leaves it implicit that the sorting is by code unit),
and more concise.

This phrasing is used in several places in ECMA-402 as well, so this change will bring additional benefit there.
  • Loading branch information
ptomato authored and ljharb committed Apr 25, 2024
1 parent 5d8f62d commit ed82ebb
Showing 1 changed file with 4 additions and 4 deletions.
8 changes: 4 additions & 4 deletions spec.html
Original file line number Diff line number Diff line change
Expand Up @@ -4012,6 +4012,7 @@ <h1>The List and Record Specification Types</h1>
<p>When an algorithm iterates over the elements of a List without specifying an order, the order used is the order of the elements in the List.</p>
<p>For notational convenience within this specification, a literal syntax can be used to express a new List value. For example, « 1, 2 » defines a List value that has two elements each of which is initialized to a specific value. A new empty List can be expressed as « ».</p>
<p>In this specification, the phrase "the <dfn id="list-concatenation">list-concatenation</dfn> of _A_, _B_, ..." (where each argument is a possibly empty List) denotes a new List value whose elements are the concatenation of the elements (in order) of each of the arguments (in order).</p>
<p>As applied to a List of Strings, the phrase "sorted according to <dfn id="lexicographic-code-unit-order">lexicographic code unit order</dfn>" means sorting by the numeric value of each code unit up to the length of the shorter string, and sorting the shorter string before the longer string if all are equal, as described in the abstract operation IsLessThan.</p>
<p>The <dfn variants="Records">Record</dfn> type is used to describe data aggregations within the algorithms of this specification. A Record type value consists of one or more named fields. The value of each field is an ECMAScript language value or specification value. Field names are always enclosed in double brackets, for example [[Value]].</p>
<p>For notational convenience within this specification, an object literal-like syntax can be used to express a Record value. For example, { [[Field1]]: 42, [[Field2]]: *false*, [[Field3]]: ~empty~ } defines a Record value that has three fields, each of which is initialized to a specific value. Field name order is not significant. Any fields that are not explicitly listed are considered to be absent.</p>
<p>In specification text and algorithms, dot notation may be used to refer to a specific field of a Record value. For example, if R is the record shown in the previous paragraph then R.[[Field2]] is shorthand for “the field of R named [[Field2]]”.</p>
Expand Down Expand Up @@ -14980,7 +14981,7 @@ <h1>Module Namespace Exotic Objects</h1>
a List of Strings
</td>
<td>
A List whose elements are the String values of the exported names exposed as own properties of this object. The list is ordered as if an Array of those String values had been sorted using %Array.prototype.sort% using *undefined* as _comparefn_.
A List whose elements are the String values of the exported names exposed as own properties of this object. The list is sorted according to lexicographic code unit order.
</td>
</tr>
</table>
Expand Down Expand Up @@ -15193,7 +15194,7 @@ <h1>
1. Let _M_ be MakeBasicObject(_internalSlotsList_).
1. Set _M_'s essential internal methods to the definitions specified in <emu-xref href="#sec-module-namespace-exotic-objects"></emu-xref>.
1. Set _M_.[[Module]] to _module_.
1. [declared="comparefn"] Let _sortedExports_ be a List whose elements are the elements of _exports_ ordered as if an Array of the same values had been sorted using %Array.prototype.sort% using *undefined* as _comparefn_.
1. Let _sortedExports_ be a List whose elements are the elements of _exports_, sorted according to lexicographic code unit order.
1. Set _M_.[[Exports]] to _sortedExports_.
1. Create own properties of _M_ corresponding to the definitions in <emu-xref href="#sec-module-namespace-objects"></emu-xref>.
1. Set _module_.[[Namespace]] to _M_.
Expand Down Expand Up @@ -32729,8 +32730,7 @@ <h1>AvailableNamedTimeZoneIdentifiers ( ): a List of Time Zone Identifier Record
<emu-alg>
1. If the implementation does not include local political rules for any time zones, then
1. Return « the Time Zone Identifier Record { [[Identifier]]: *"UTC"*, [[PrimaryIdentifier]]: *"UTC"* } ».
1. Let _identifiers_ be the List of unique available named time zone identifiers.
1. [declared="comparefn"] Sort _identifiers_ into the same order as if an Array of the same values had been sorted using %Array.prototype.sort% with *undefined* as _comparefn_.
1. Let _identifiers_ be the List of unique available named time zone identifiers, sorted according to lexicographic code unit order.
1. Let _result_ be a new empty List.
1. For each element _identifier_ of _identifiers_, do
1. Let _primary_ be _identifier_.
Expand Down

0 comments on commit ed82ebb

Please sign in to comment.