Clear up WebIDL/ECMAScript confusion in key defintion. Bug 20582.
authorJoshua bell <jsbell@google.com>
Fri, 01 Mar 2013 10:41:15 -0800
changeset 400f74a5b0a703c
parent 399 dffdbbe300ab
child 401 b6d2f7b5a5a0
Clear up WebIDL/ECMAScript confusion in key defintion. Bug 20582.
Overview.html
Speclet_020_IDB_API_Constructs.html
     1.1 --- a/Overview.html	Fri Mar 01 10:06:24 2013 -0800
     1.2 +++ b/Overview.html	Fri Mar 01 10:41:15 2013 -0800
     1.3 @@ -426,28 +426,48 @@
     1.4            <p>
     1.5              In order to efficiently retrieve <a>record</a>s stored in an indexed database,
     1.6              each <a>record</a> is organized according to its <dfn>key</dfn>. A value is said to be a <dfn>valid key</dfn>
     1.7 -            if it is one of the following types:
     1.8 -            <code>Array</code> JavaScript objects [[!ECMA-262]], <code>DOMString</code> [[!WEBIDL]],
     1.9 -            <code>Date</code> [[!ECMA-262]] or <code>float</code> [[!WEBIDL]].
    1.10 -            However <code>Array</code>s are only <a>valid key</a>s if every item in the array is defined and is
    1.11 -            a <a>valid key</a> (i.e. sparse arrays can not be <a>valid key</a>s) and if the <code>Array</code> doesn't directly or
    1.12 +            if it is one of the following JavaScript [[!ECMA-262]] types:
    1.13 +            <code>Number</code> primitive value,
    1.14 +            <code>String</code> primitive value,
    1.15 +            <code>Date</code> object, or
    1.16 +            <code>Array</code> object.
    1.17 +
    1.18 +            An <code>Array</code> is only a <a title="valid key">valid keys</a> if every item in the array is defined and is
    1.19 +            a <a>valid key</a> (i.e. sparse arrays can not be <a title="valid key">valid keys</a>) and if the <code>Array</code> doesn't directly or
    1.20              indirectly contain itself.
    1.21 -            Any non-numeric properties are ignored, and thus does not affect whether the <code>Array</code> is a <a>valid key</a>.
    1.22 -            Additionally, if the value is of type <code>float</code>, it is only a <a>valid key</a> if it is not <code>NaN</code>,
    1.23 -            and if the value is of type <code>Date</code> it is only a <a>valid key</a> if its <code>[<span>[</span>PrimitiveValue]]</code>
    1.24 +
    1.25 +            Any non-numeric properties on an <code>Array</code> are ignored, and thus do not affect whether the <code>Array</code> is a <a>valid key</a>.
    1.26 +
    1.27 +            If the value is of type <code>Number</code>, it is only a <a>valid key</a> if it is not <code>NaN</code>.
    1.28 +
    1.29 +            If the value is of type <code>Date</code> it is only a <a>valid key</a> if its <code>[<span>[</span>PrimitiveValue]]</code>
    1.30              internal property, as defined by [[!ECMA-262]], is not <code>NaN</code>.
    1.31 -            <a>Conforming user agents</a> MUST support all <a>valid key</a>s as keys.
    1.32 +
    1.33 +            <a>Conforming user agents</a> MUST support all <a title="valid key">valid keys</a> as keys.
    1.34            </p>
    1.35            <p class="note">
    1.36 -            Infinite <code>float</code> values are <a>valid key</a>s. As are empty <code>Array</code>s.
    1.37 +            Infinite <code>Number</code> values are <a title="valid key">valid keys</a>. As are empty <code>Array</code>s.
    1.38            </p>
    1.39 +
    1.40            <p>
    1.41 -            For purposes of comparison, all <code>Array</code>s are greater than all <code>DOMString</code>,
    1.42 -            <code>Date</code> and <code>float</code> values; all <code>DOMString</code> values are greater than all
    1.43 -            <code>Date</code> and <code>float</code> values; and all <code>Date</code> values are greater than all
    1.44 -            <code>float</code> values. Values of type <code>float</code> are compared to other <code>float</code> values
    1.45 +              Operations that accept <a title="key">keys</a> MUST perform as if  each <a>key</a> parameter
    1.46 +              value, in order, is copied by the by the <a>structured clone algorithm</a> [[!HTML5]] and
    1.47 +              the copy is instead used as input to the operation, before proceding with rest of the operation.
    1.48 +          </p>
    1.49 +          <p class="note">
    1.50 +              This implicit copying step ensures that side effects, as might be implemented
    1.51 +              by JavaScript [[!ECMA-262]] getters, setters and type conversions functions such as
    1.52 +              <code>toString()</code> and <code>valueOf()</code>, and that objects used as keys do not
    1.53 +              change in value after the operation begins.
    1.54 +          </p>
    1.55 +
    1.56 +          <p>
    1.57 +            For purposes of comparison, all <code>Array</code>s are greater than all <code>String</code>,
    1.58 +            <code>Date</code> and <code>Number</code> values; all <code>String</code> values are greater than all
    1.59 +            <code>Date</code> and <code>Number</code> values; and all <code>Date</code> values are greater than all
    1.60 +            <code>Number</code> values. Values of type <code>Number</code> are compared to other <code>Number</code> values
    1.61              numerically. Values of type <code>Date</code> are compared to other <code>Date</code> values chronologically.
    1.62 -            Values of type <code>DOMString</code> are compared to other values of type <code>DOMString</code>
    1.63 +            Values of type <code>String</code> are compared to other values of type <code>String</code>
    1.64              by using the algorithm defined by step 4 of <cite>section 11.8.5, The Abstract Relational Comparison Algorithm</cite>,
    1.65              of the ECMAScript Language Specification [[!ECMA-262]].
    1.66              Values of type <code>Array</code> are compared to other values of type <code>Array</code> as follows:
    1.67 @@ -484,7 +504,7 @@
    1.68              </li>
    1.69            </ol>
    1.70            <p class="note">
    1.71 -            Note that <code>Array</code>s that contain other <code>Array</code>s are allowed as <a>valid key</a>s.
    1.72 +            Note that <code>Array</code>s that contain other <code>Array</code>s are allowed as <a title="valid key">valid keys</a>.
    1.73              In this case the algorithm above runs recursively when comparing the individual values in the arrays.
    1.74            </p>
    1.75            <p class="note">
    1.76 @@ -497,7 +517,7 @@
    1.77              the above comparisons.
    1.78            </p>
    1.79            <p>
    1.80 -            The following examples illustrate the different behaviors when trying to use in-line <a>key</a>s and <a>key generator</a>s
    1.81 +            The following examples illustrate the different behaviors when trying to use in-line <a title="key">keys</a> and <a>key generator</a>s
    1.82              to save an object to an <a>object store</a>.
    1.83            </p>
    1.84            <aside class="example">
    1.85 @@ -575,9 +595,9 @@
    1.86            <h4>Values</h4>
    1.87            <p>
    1.88              Each record is associated with a <dfn>value</dfn>. <a>Conforming user agents</a> MUST support
    1.89 -            any value supported by the <a>structured clone algorithm</a>
    1.90 -            [[!HTML5]]. This includes simple types such as <code>DOMString</code>
    1.91 -            and <code>Date</code> as well as <code>Object</code> and <code>Array</code>
    1.92 +            any JavaScript [[!ECMA-262]] value supported by the <a>structured clone algorithm</a>
    1.93 +            [[!HTML5]]. This includes simple types such as <code>String</code> primitive values
    1.94 +            and <code>Date</code> objects as well as <code>Object</code> and <code>Array</code>
    1.95              instances.
    1.96            </p>
    1.97          </section>
    1.98 @@ -591,7 +611,7 @@
    1.99            <ul>
   1.100              <li>An empty <code>DOMString</code>.</li>
   1.101              <li>An <dfn>identifier</dfn>, which is a <code>DOMString</code> matching
   1.102 -                the <code>IdentifierName</code> production from the JavaScript language grammar. [[!ECMA-262]].</li>
   1.103 +                the <code>IdentifierName</code> production from the ECMAScript Language Specification [[!ECMA-262]].</li>
   1.104              <li>A <code>DOMString</code> consisting of two or more <a title="identifier">identifiers</a> separated by
   1.105              periods (ASCII character code 46).</li>
   1.106              <li>A non-empty <code>Array</code> containing only <code>DOMString</code>s conforming to
     2.1 --- a/Speclet_020_IDB_API_Constructs.html	Fri Mar 01 10:06:24 2013 -0800
     2.2 +++ b/Speclet_020_IDB_API_Constructs.html	Fri Mar 01 10:41:15 2013 -0800
     2.3 @@ -204,28 +204,48 @@
     2.4            <p>
     2.5              In order to efficiently retrieve <a>record</a>s stored in an indexed database,
     2.6              each <a>record</a> is organized according to its <dfn>key</dfn>. A value is said to be a <dfn>valid key</dfn>
     2.7 -            if it is one of the following types:
     2.8 -            <code>Array</code> JavaScript objects [[!ECMA-262]], <code>DOMString</code> [[!WEBIDL]],
     2.9 -            <code>Date</code> [[!ECMA-262]] or <code>float</code> [[!WEBIDL]].
    2.10 -            However <code>Array</code>s are only <a>valid key</a>s if every item in the array is defined and is
    2.11 -            a <a>valid key</a> (i.e. sparse arrays can not be <a>valid key</a>s) and if the <code>Array</code> doesn't directly or
    2.12 +            if it is one of the following JavaScript [[!ECMA-262]] types:
    2.13 +            <code>Number</code> primitive value,
    2.14 +            <code>String</code> primitive value,
    2.15 +            <code>Date</code> object, or
    2.16 +            <code>Array</code> object.
    2.17 +
    2.18 +            An <code>Array</code> is only a <a title="valid key">valid keys</a> if every item in the array is defined and is
    2.19 +            a <a>valid key</a> (i.e. sparse arrays can not be <a title="valid key">valid keys</a>) and if the <code>Array</code> doesn't directly or
    2.20              indirectly contain itself.
    2.21 -            Any non-numeric properties are ignored, and thus does not affect whether the <code>Array</code> is a <a>valid key</a>.
    2.22 -            Additionally, if the value is of type <code>float</code>, it is only a <a>valid key</a> if it is not <code>NaN</code>,
    2.23 -            and if the value is of type <code>Date</code> it is only a <a>valid key</a> if its <code>[<span>[</span>PrimitiveValue]]</code>
    2.24 +
    2.25 +            Any non-numeric properties on an <code>Array</code> are ignored, and thus do not affect whether the <code>Array</code> is a <a>valid key</a>.
    2.26 +
    2.27 +            If the value is of type <code>Number</code>, it is only a <a>valid key</a> if it is not <code>NaN</code>.
    2.28 +
    2.29 +            If the value is of type <code>Date</code> it is only a <a>valid key</a> if its <code>[<span>[</span>PrimitiveValue]]</code>
    2.30              internal property, as defined by [[!ECMA-262]], is not <code>NaN</code>.
    2.31 -            <a>Conforming user agents</a> MUST support all <a>valid key</a>s as keys.
    2.32 +
    2.33 +            <a>Conforming user agents</a> MUST support all <a title="valid key">valid keys</a> as keys.
    2.34            </p>
    2.35            <p class="note">
    2.36 -            Infinite <code>float</code> values are <a>valid key</a>s. As are empty <code>Array</code>s.
    2.37 +            Infinite <code>Number</code> values are <a title="valid key">valid keys</a>. As are empty <code>Array</code>s.
    2.38            </p>
    2.39 +
    2.40            <p>
    2.41 -            For purposes of comparison, all <code>Array</code>s are greater than all <code>DOMString</code>,
    2.42 -            <code>Date</code> and <code>float</code> values; all <code>DOMString</code> values are greater than all
    2.43 -            <code>Date</code> and <code>float</code> values; and all <code>Date</code> values are greater than all
    2.44 -            <code>float</code> values. Values of type <code>float</code> are compared to other <code>float</code> values
    2.45 +              Operations that accept <a title="key">keys</a> MUST perform as if  each <a>key</a> parameter
    2.46 +              value, in order, is copied by the by the <a>structured clone algorithm</a> [[!HTML5]] and
    2.47 +              the copy is instead used as input to the operation, before proceding with rest of the operation.
    2.48 +          </p>
    2.49 +          <p class="note">
    2.50 +              This implicit copying step ensures that side effects, as might be implemented
    2.51 +              by JavaScript [[!ECMA-262]] getters, setters and type conversions functions such as
    2.52 +              <code>toString()</code> and <code>valueOf()</code>, and that objects used as keys do not
    2.53 +              change in value after the operation begins.
    2.54 +          </p>
    2.55 +
    2.56 +          <p>
    2.57 +            For purposes of comparison, all <code>Array</code>s are greater than all <code>String</code>,
    2.58 +            <code>Date</code> and <code>Number</code> values; all <code>String</code> values are greater than all
    2.59 +            <code>Date</code> and <code>Number</code> values; and all <code>Date</code> values are greater than all
    2.60 +            <code>Number</code> values. Values of type <code>Number</code> are compared to other <code>Number</code> values
    2.61              numerically. Values of type <code>Date</code> are compared to other <code>Date</code> values chronologically.
    2.62 -            Values of type <code>DOMString</code> are compared to other values of type <code>DOMString</code>
    2.63 +            Values of type <code>String</code> are compared to other values of type <code>String</code>
    2.64              by using the algorithm defined by step 4 of <cite>section 11.8.5, The Abstract Relational Comparison Algorithm</cite>,
    2.65              of the ECMAScript Language Specification [[!ECMA-262]].
    2.66              Values of type <code>Array</code> are compared to other values of type <code>Array</code> as follows:
    2.67 @@ -262,7 +282,7 @@
    2.68              </li>
    2.69            </ol>
    2.70            <p class="note">
    2.71 -            Note that <code>Array</code>s that contain other <code>Array</code>s are allowed as <a>valid key</a>s.
    2.72 +            Note that <code>Array</code>s that contain other <code>Array</code>s are allowed as <a title="valid key">valid keys</a>.
    2.73              In this case the algorithm above runs recursively when comparing the individual values in the arrays.
    2.74            </p>
    2.75            <p class="note">
    2.76 @@ -275,7 +295,7 @@
    2.77              the above comparisons.
    2.78            </p>
    2.79            <p>
    2.80 -            The following examples illustrate the different behaviors when trying to use in-line <a>key</a>s and <a>key generator</a>s
    2.81 +            The following examples illustrate the different behaviors when trying to use in-line <a title="key">keys</a> and <a>key generator</a>s
    2.82              to save an object to an <a>object store</a>.
    2.83            </p>
    2.84            <aside class="example">
    2.85 @@ -353,9 +373,9 @@
    2.86            <h4>Values</h4>
    2.87            <p>
    2.88              Each record is associated with a <dfn>value</dfn>. <a>Conforming user agents</a> MUST support
    2.89 -            any value supported by the <a>structured clone algorithm</a>
    2.90 -            [[!HTML5]]. This includes simple types such as <code>DOMString</code>
    2.91 -            and <code>Date</code> as well as <code>Object</code> and <code>Array</code>
    2.92 +            any JavaScript [[!ECMA-262]] value supported by the <a>structured clone algorithm</a>
    2.93 +            [[!HTML5]]. This includes simple types such as <code>String</code> primitive values
    2.94 +            and <code>Date</code> objects as well as <code>Object</code> and <code>Array</code>
    2.95              instances.
    2.96            </p>
    2.97          </section>
    2.98 @@ -369,7 +389,7 @@
    2.99            <ul>
   2.100              <li>An empty <code>DOMString</code>.</li>
   2.101              <li>An <dfn>identifier</dfn>, which is a <code>DOMString</code> matching
   2.102 -                the <code>IdentifierName</code> production from the JavaScript language grammar. [[!ECMA-262]].</li>
   2.103 +                the <code>IdentifierName</code> production from the ECMAScript Language Specification [[!ECMA-262]].</li>
   2.104              <li>A <code>DOMString</code> consisting of two or more <a title="identifier">identifiers</a> separated by
   2.105              periods (ASCII character code 46).</li>
   2.106              <li>A non-empty <code>Array</code> containing only <code>DOMString</code>s conforming to