3.2.1 Constants

A constant is a declaration (matching Const) used to bind a constant value to a name. Constants can appear on interfaces.

const type identifier = value;

The identifier of a constant MUST NOT be the same as the identifier of another interface member defined on the same interface. The identifier also MUST NOT be “length”, “name” or “prototype”.

The type of a constant (matching ConstType) MUST NOT be any type other than a primitive type or a nullable primitive type. If an identifier is used, it MUST reference a typedef whose type is a primitive type or a nullable primitive type.

The ConstValue part of a constant declaration gives the value of the constant, which can be one of the two boolean literal tokens (true and false), the null token, an integer token, a float token, or one of the three special floating point constant values (-Infinity, Infinity and NaN).

The value of the boolean literal tokens true and false are the IDL boolean values true and false.

The value of an integer token is an integer whose value is determined as follows:

1. Let S be the sequence of characters matched by the integer token.
2. Let sign be −1 if S begins with U+002D HYPHEN-MINUS ("-"), and 1 otherwise.
3. Let base be the base of the number based on the characters that follow the optional leading U+002D HYPHEN-MINUS ("-") character:

   U+0030 DIGIT ZERO ("0"), U+0058 LATIN CAPITAL LETTER X ("X")

   U+0030 DIGIT ZERO ("0"), U+0078 LATIN SMALL LETTER X ("x")

   The base is 16.

   U+0030 DIGIT ZERO ("0")

   The base is 8.

   Otherwise

   The base is 10.

4. Let number be the result of interpreting all remaining characters following the optional leading U+002D HYPHEN-MINUS ("-") character and any characters indicating the base as an integer specified in base base.
5. Return sign × number.

The type of an integer token is the same as the type of the constant, dictionary member or optional argument it is being used as the value of. The value of the integer token MUST NOT lie outside the valid range of values for its type, as given in section 3.10 .

The value of a float token is either an IEEE 754 single-precision floating point number or an IEEE 754 double-precision floating point number, depending on the type of the constant, dictionary member or optional argument it is being used as the value for, determined as follows:

1. Let S be the sequence of characters matched by the float token.
2. Let value be the Mathematical Value that would be obtained if S were parsed as an ECMAScript NumericLiteral ( [ ECMA-262] , section 11.8.3).
3. If the float token is being used as the value for a float or unrestricted float, then the value of the float token is the IEEE 754 single-precision floating point number closest to result. Otherwise, the float token is being used as the value for a double or unrestricted double, and the value of the float token is the IEEE 754 double-precision floating point number closest to result. [ IEEE-754]

The value of a constant value specified as Infinity, -Infinity or NaN is either an IEEE 754 single-precision floating point number or an IEEE 754 double-precision floating point number, depending on the type of the constant, dictionary member or optional argument is is being used as the value for:

Type unrestricted float, constant value Infinity

The value is the IEEE 754 single-precision positive infinity value.

Type unrestricted double, constant value Infinity

The value is the IEEE 754 double-precision positive infinity value.

Type unrestricted float, constant value -Infinity

The value is the IEEE 754 single-precision negative infinity value.

Type unrestricted double, constant value -Infinity

The value is the IEEE 754 double-precision negative infinity value.

Type unrestricted float, constant value NaN

The value is the IEEE 754 single-precision NaN value with the bit pattern 0x7fc00000.

Type unrestricted double, constant value NaN

The value is the IEEE 754 double-precision NaN value with the bit pattern 0x7ff8000000000000.

The type of a float token is the same as the type of the constant, dictionary member or optional argument it is being used as the value of. The value of the float token MUST NOT lie outside the valid range of values for its type, as given in section 3.10 . Also, Infinity, -Infinity and NaN MUST NOT be used as the value of a float or double.

The value of the null token is the special null value that is a member of the nullable types. The type of the null token is the same as the type of the constant, dictionary member or optional argument it is being used as the value of.

If VT is the type of the value assigned to a constant, and DT is the type of the constant, dictionary member or optional argument itself, then these types MUST be compatible, which is the case if DT and VT are identical, or DT is a nullable type whose inner type is VT.

Constants are not associated with particular instances of the interface on which they appear. It is language binding specific whether constants are exposed on instances.

interface A {
  const short rambaldi = 47;
};

The following extended attributes are applicable to constants: [Exposed].

interface Util {
  const boolean DEBUG = false;
  const octet LF = 10;
  const unsigned long BIT_MASK = 0x0000fc00;
  const double AVOGADRO = 6.022e23;
};

3.2.2 Attributes

An attribute is an interface member (matching "inherit" ReadOnly AttributeRest, "static" ReadOnly AttributeRest, "stringifier" ReadOnly AttributeRest, or ReadOnly AttributeRest) that is used to declare data fields with a given type and identifier whose value can be retrieved and (in some cases) changed. There are two kinds of attributes:

1. regular attributes, which are those used to declare that objects implementing the interface will have a data field member with the given identifier

   attribute type identifier;

2. static attributes, which are used to declare attributes that are not associated with a particular object implementing the interface

   static attribute type identifier;

If an attribute has no static keyword, then it declares a regular attribute . Otherwise, it declares a static attribute.

The identifier of an attribute MUST NOT be the same as the identifier of another interface member defined on the same interface. The identifier of a static attribute MUST NOT be “prototype”.

The type of the attribute is given by the type (matching Type) that appears after the attribute keyword. If the Type is an identifier or an identifier followed by ?, then the identifier MUST identify an interface, enumeration, callback function or typedef.

The type of the attribute, after resolving typedefs, MUST NOT be a nullable or non-nullable version of any of the following types:

• a sequence type
• a dictionary
• a union type that has a nullable or non-nullable sequence type or dictionary as one of its flattened member types

The attribute is read only if the readonly keyword is used before the attribute keyword. An object that implements the interface on which a read only attribute is defined will not allow assignment to that attribute. It is language binding specific whether assignment is simply disallowed by the language, ignored or an exception is thrown.

readonly attribute type identifier;

A regular attribute that is not read only can be declared to inherit its getter from an ancestor interface. This can be used to make a read only attribute in an ancestor interface be writable on a derived interface. An attribute inherits its getter if its declaration includes inherit in the declaration. The read only attribute from which the attribute inherits its getter is the attribute with the same identifier on the closest ancestor interface of the one on which the inheriting attribute is defined. The attribute whose getter is being inherited MUST be of the same type as the inheriting attribute, and inherit MUST NOT appear on a read only attribute or a static attribute.

interface Ancestor {
  readonly attribute TheType theIdentifier;
};
interface Derived : Ancestor {
  inherit attribute TheType theIdentifier;
};

When the stringifier keyword is used in a regular attribute declaration, it indicates that objects implementing the interface will be stringified to the value of the attribute. See section 3.2.4.2 for details.

stringifier attribute DOMString identifier;

If an implementation attempts to get or set the value of an attribute on a user object (for example, when a callback object has been supplied to the implementation), and that attempt results in an exception being thrown, then, unless otherwise specified, that exception will be propagated to the user code that caused the implementation to access the attribute. Similarly, if a value returned from getting the attribute cannot be converted to an IDL type, then any exception resulting from this will also be propagated to the user code that resulted in the implementation attempting to get the value of the attribute.

The following extended attributes are applicable to regular and static attributes: [Clamp], [EnforceRange], [Exposed], [SameObject], [TreatNullAs].

The following extended attributes are applicable only to regular attributes: [LenientThis], [PutForwards], [Replaceable], [Unforgeable].

interface Animal {
  // A simple attribute that can be set to any string value.
  readonly attribute DOMString name;
  // An attribute whose value can be assigned to.
  attribute unsigned short age;
};
interface Person : Animal {
  // An attribute whose getter behavior is inherited from Animal, and need not be
  // specified in the description of Person.
  inherit attribute DOMString name;
};

3.2.3 Operations

An operation is an interface member (matching "static" OperationRest, "stringifier" OperationRest, "serializer" OperationRest, ReturnType OperationRest or SpecialOperation) that defines a behavior that can be invoked on objects implementing the interface. There are three kinds of operation:

1. regular operations, which are those used to declare that objects implementing the interface will have a method with the given identifier

   return-type identifier(arguments…);

2. special operations, which are used to declare special behavior on objects implementing the interface, such as object indexing and stringification

   special-keywords… return-type identifier(arguments…);
   special-keywords… return-type (arguments…);

3. static operations, which are used to declare operations that are not associated with a particular object implementing the interface

   static return-type identifier(arguments…);

If an operation has an identifier but no static keyword, then it declares a regular operation . If the operation has one or more special keywords used in its declaration (that is, any keyword matching Special, or the stringifier keyword), then it declares a special operation. A single operation can declare both a regular operation and a special operation; see section 3.2.4 for details on special operations.

If an operation has no identifier, then it MUST be declared to be a special operation using one of the special keywords.

The identifier of a regular operation or static operation MUST NOT be the same as the identifier of a constant or attribute defined on the same interface. The identifier of a static operation MUST NOT be “prototype”.

The identifier of a static operation also MUST NOT be the same as the identifier of a regular operation defined on the same interface.

The return type of the operation is given by the type (matching ReturnType) that appears before the operation’s optional identifier. A return type of void indicates that the operation returns no value. If the return type is an identifier followed by ?, then the identifier MUST identify an interface, dictionary, enumeration, callback function or typedef.

An operation’s arguments (matching ArgumentList) are given between the parentheses in the declaration. Each individual argument is specified as a type (matching Type) followed by an identifier (matching ArgumentName).

If the Type of an operation argument is an identifier followed by ?, then the identifier MUST identify an interface, enumeration, callback function or typedef. If the operation argument type is an identifier not followed by ?, then the identifier MUST identify any one of those definitions or a dictionary.

return-type identifier(type identifier, type identifier, …);

The identifier of each argument MUST NOT be the same as the identifier of another argument in the same operation declaration.

Each argument can be preceded by a list of extended attributes (matching ExtendedAttributeList), which can control how a value passed as the argument will be handled in language bindings.

return-type identifier([extended-attributes] type identifier, [extended-attributes] type identifier, …);

interface Dimensions {
  attribute unsigned long width;
  attribute unsigned long height;
};
interface Button {
  // An operation that takes no arguments and returns a boolean.
  boolean isMouseOver();
  // Overloaded operations.
  void setDimensions(Dimensions size);
  void setDimensions(unsigned long width, unsigned long height);
};

An operation is considered to be variadic if the final argument uses the ... token just after the argument type. Declaring an operation to be variadic indicates that the operation can be invoked with any number of arguments after that final argument. Those extra implied formal arguments are of the same type as the final explicit argument in the operation declaration. The final argument can also be omitted when invoking the operation. An argument MUST NOT be declared with the ... token unless it is the final argument in the operation’s argument list.

return-type identifier(type... identifier);
return-type identifier(type identifier, type... identifier);

Extended attributes that take an argument list ([Constructor] and [NamedConstructor], of those defined in this specification) and callback functions are also considered to be variadic when the ... token is used in their argument lists.

interface IntegerSet {
  readonly attribute unsigned long cardinality;
  void union(long... ints);
  void intersection(long... ints);
};

var s = getIntegerSet();  // Obtain an instance of IntegerSet.
s.union();                // Passing no arguments corresponding to 'ints'.
s.union(1, 4, 7);         // Passing three arguments corresponding to 'ints'.

An argument is considered to be an optional argument if it is declared with the optional keyword. The final argument of a variadic operation is also considered to be an optional argument. Declaring an argument to be optional indicates that the argument value can be omitted when the operation is invoked. The final argument in an operation MUST NOT explicitly be declared to be optional if the operation is variadic.

return-type identifier(type identifier, optional type identifier);

Optional arguments can also have a default value specified. If the argument’s identifier is followed by a U+003D EQUALS SIGN ("=") and a value (matching DefaultValue), then that gives the optional argument its default value. The implicitly optional final argument of a variadic operation MUST NOT have a default value specified. The default value is the value to be assumed when the operation is called with the corresponding argument omitted.

return-type identifier(type identifier, optional type identifier = value);

If the type of an argument is a dictionary type or a union type that has a dictionary type as one of its flattened member types, and that dictionary type and its ancestors have no required members, and the argument is either the final argument or is followed only by optional arguments, then the argument MUST be specified as optional. Such arguments are always considered to have a default value of an empty dictionary, unless otherwise specified.

When a boolean literal token (true or false), the null token, an integer token, a float token or one of the three special floating point literal values (Infinity, -Infinity or NaN) is used as the default value, it is interpreted in the same way as for a constant.

Optional argument default values can also be specified using a string token, whose value is a string type determined as follows:

1. Let S be the sequence of Unicode scalar values matched by the string token with its leading and trailing U+0022 QUOTATION MARK ('"') characters removed.
2. Depending on the type of the argument:

   DOMString

   an enumeration type

   The value of the string token is the sequence of 16 bit unsigned integer code units (hereafter referred to just as code units ) corresponding to the UTF-16 encoding of S.

   ByteString

   The value of the string token is the sequence of 8 bit unsigned integer code units corresponding to the UTF-8 encoding of S.

   USVString

   The value of the string token is S.

If the type of the optional argument is an enumeration, then its default value if specified MUST be one of the enumeration’s values.

Optional argument default values can also be specified using the two token value [], which represents an empty sequence value. The type of this value is the same the type of the optional argument it is being used as the default value of. That type MUST be a sequence type or a nullable type.

interface ColorCreator {
  object createColor(double v1, double v2, double v3, optional double alpha);
};

interface ColorCreator {
  object createColor(double v1, double v2, double v3);
  object createColor(double v1, double v2, double v3, double alpha);
};

If an implementation attempts to invoke an operation on a user object (for example, when a callback object has been supplied to the implementation), and that attempt results in an exception being thrown, then, unless otherwise specified, that exception will be propagated to the user code that caused the implementation to invoke the operation. Similarly, if a value returned from invoking the operation cannot be converted to an IDL type, then any exception resulting from this will also be propagated to the user code that resulted in the implementation attempting to invoke the operation.

The following extended attributes are applicable to operations: [Exposed], [NewObject], [TreatNullAs], [Unforgeable].

The following extended attributes are applicable to operation arguments: [Clamp], [EnforceRange], [TreatNullAs].

3.2.4 Special operations

A special operation is a declaration of a certain kind of special behavior on objects implementing the interface on which the special operation declarations appear. Special operations are declared by using one or more special keywords in an operation declaration.

There are six kinds of special operations. The table below indicates for a given kind of special operation what special keyword is used to declare it and what the purpose of the special operation is:

Not all language bindings support all of the six kinds of special object behavior. When special operations are declared using operations with no identifier, then in language bindings that do not support the particular kind of special operations there simply will not be such functionality.

interface Dictionary {
  readonly attribute unsigned long propertyCount;
  getter double (DOMString propertyName);
  setter void (DOMString propertyName, double propertyValue);
};

Defining a special operation with an identifier is equivalent to separating the special operation out into its own declaration without an identifier. This approach is allowed to simplify prose descriptions of an interface’s operations.

interface Dictionary {
  readonly attribute unsigned long propertyCount;
  getter double getProperty(DOMString propertyName);
  setter void setProperty(DOMString propertyName, double propertyValue);
};

interface Dictionary {
  readonly attribute unsigned long propertyCount;
  double getProperty(DOMString propertyName);
  void setProperty(DOMString propertyName, double propertyValue);
  getter double (DOMString propertyName);
  setter void (DOMString propertyName, double propertyValue);
};

A given special keyword MUST NOT appear twice on an operation.

Getters and setters come in two varieties: ones that take a DOMString as a property name, known as named property getters and named property setters , and ones that take an unsigned long as a property index, known as indexed property getters and indexed property setters . There is only one variety of deleter: named property deleters . See section 3.2.4.4 and section 3.2.4.5 for details.

On a given interface, there MUST exist at most one stringifier, at most one serializer, at most one named property deleter, and at most one of each variety of getter and setter. Multiple legacy callers can exist on an interface to specify overloaded calling behavior.

If an interface has a setter of a given variety, then it MUST also have a getter of that variety. If it has a named property deleter, then it MUST also have a named property getter.

Special operations declared using operations MUST NOT be variadic nor have any optional arguments.

Special operations MUST NOT be declared on callback interfaces.

If an object implements more than one interface that defines a given special operation, then it is undefined which (if any) special operation is invoked for that operation.

legacycaller return-type identifier(arguments…);
legacycaller return-type (arguments…);

interface NumberQuadrupler {
  // This operation simply returns four times the given number x.
  legacycaller double compute(double x);
};

var f = getNumberQuadrupler();  // Obtain an instance of NumberQuadrupler.
f.compute(3);                   // This evaluates to 12.
f(3);                           // This also evaluates to 12.

stringifier DOMString identifier();
stringifier DOMString ();

stringifier;

interface A {
  stringifier DOMString ();
};

interface A {
  stringifier;
};

stringifier attribute DOMString identifier;

[Constructor]
interface Student {
  attribute unsigned long id;
  stringifier attribute DOMString name;
};

var s = new Student();
s.id = 12345678;
s.name = '周杰倫';
var greeting = 'Hello, ' + s + '!';  // Now greeting == 'Hello, 周杰倫!'.

[Constructor]
interface Student {
  attribute unsigned long id;
  attribute DOMString? familyName;
  attribute DOMString givenName;
  stringifier DOMString ();
};

var s = new Student();
s.id = 12345679;
s.familyName = 'Smithee';
s.givenName = 'Alan';
var greeting = 'Hi ' + s;  // Now greeting == 'Hi Alan Smithee'.

serializer;

serializer type identifier();

interface Transaction {
  readonly attribute Account from;
  readonly attribute Account to;
  readonly attribute double amount;
  readonly attribute DOMString description;
  readonly attribute unsigned long number;
  serializer;
};
interface Account {
  DOMString name;
  unsigned long number;
};

interface Transaction {
  readonly attribute Account from;
  readonly attribute Account to;
  readonly attribute double amount;
  readonly attribute DOMString description;
  readonly attribute unsigned long number;
  serializer = { from, to, amount, description };
};
interface Account {
  DOMString name;
  unsigned long number;
  serializer = number;
};

// Get an instance of Transaction.
var txn = getTransaction();
// Evaluates to an object like this:
// {
//   from: 1234
//   to: 5678
//   amount: 110.75
//   description: "dinner"
// }
txn.toJSON();
// Evaluates to a string like this:
// '{"from":1234,"to":5678,"amount":110.75,"description":"dinner"}'
JSON.stringify(txn);

getter type identifier(unsigned long identifier);
setter type identifier(unsigned long identifier, type identifier);
getter type (unsigned long identifier);
setter type (unsigned long identifier, type identifier);

interface A {
  getter DOMString toWord(unsigned long index);
};

var a = getA();
a.toWord(0);  // Evalautes to "zero".
a[0];         // Also evaluates to "zero".
a.toWord(5);  // Evaluates to "five".
a[5];         // Evaluates to undefined, since there is no property "5".

interface OrderedMap {
  readonly attribute unsigned long size;
  getter any getByIndex(unsigned long index);
  setter void setByIndex(unsigned long index, any value);
  getter any get(DOMString name);
  setter void set(DOMString name, any value);
};

// Assume map is a platform object implementing the OrderedMap interface.
var map = getOrderedMap();
var x, y;
x = map[0];       // If map.length > 0, then this is equivalent to:
                  //
                  //   x = map.getByIndex(0)
                  //
                  // since a property named "0" will have been placed on map.
                  // Otherwise, x will be set to undefined, since there will be
                  // no property named "0" on map.
map[1] = false;   // This will do the equivalent of:
                  //
                  //   map.setByIndex(1, false)
y = map.apple;    // If there exists a named property named "apple", then this
                  // will be equivalent to:
                  //
                  //   y = map.get('apple')
                  //
                  // since a property named "apple" will have been placed on
                  // map.  Otherwise, y will be set to undefined, since there
                  // will be no property named "apple" on map.
map.berry = 123;  // This will do the equivalent of:
                  //
                  //   map.set('berry', 123)
delete map.cake;  // If a named property named "cake" exists, then the "cake"
                  // property will be deleted, and then the equivalent to the
                  // following will be performed:
                  //
                  //   map.remove("cake")

getter type identifier(DOMString identifier);
setter type identifier(DOMString identifier, type identifier);
deleter type identifier(DOMString identifier);
getter type (DOMString identifier);
setter type (DOMString identifier, type identifier);
deleter type (DOMString identifier);

3.2.5 Static attributes and operations

Static attributes and static operations are ones that are not associated with a particular instance of the interface on which it is declared, and is instead associated with the interface itself. Static attributes and operations are declared by using the static keyword in their declarations.

It is language binding specific whether it is possible to invoke a static operation or get or set a static attribute through a reference to an instance of the interface.

Static attributes and operations MUST NOT be declared on callback interfaces.

interface Point { /* ... */ };
interface Circle {
  attribute double cx;
  attribute double cy;
  attribute double radius;
  static readonly attribute long triangulationCount;
  static Point triangulate(Circle c1, Circle c2, Circle c3);
};

var circles = getCircles();           // an Array of Circle objects
typeof Circle.triangulate;            // Evaluates to "function"
typeof Circle.triangulationCount;     // Evaluates to "number"
Circle.prototype.triangulate;         // Evaluates to undefined
Circle.prototype.triangulationCount;  // Also evaluates to undefined
circles[0].triangulate;               // As does this
circles[0].triangulationCount;        // And this
// Call the static operation
var triangulationPoint = Circle.triangulate(circles[0], circles[1], circles[2]);
// Find out how many triangulations we have done
window.alert(Circle.triangulationCount);

3.2.6 Overloading

If a regular operation or static operation defined on an interface has an identifier that is the same as the identifier of another operation on that interface of the same kind (regular or static), then the operation is said to be overloaded . When the identifier of an overloaded operation is used to invoke one of the operations on an object that implements the interface, the number and types of the arguments passed to the operation determine which of the overloaded operations is actually invoked. If an interface has multiple legacy callers defined on it, then those legacy callers are also said to be overloaded. In the ECMAScript language binding, constructors can be overloaded too. There are some restrictions on the arguments that overloaded operations, legacy callers and constructors can be specified to take, and in order to describe these restrictions, the notion of an effective overload set is used.

Operations and legacy callers MUST NOT be overloaded across interface and partial interface definitions.

interface A {
  void f();
};
partial interface A {
  void f(double x);
  void g();
};
partial interface A {
  void g(DOMString x);
};

An effective overload set represents the allowable invocations for a particular operation, constructor (specified with [Constructor] or [NamedConstructor]), legacy caller or callback function. The algorithm to compute an effective overload set operates on one of the following six types of IDL constructs, and listed with them below are the inputs to the algorithm needed to compute the set.

For regular operations

For static operations

• the interface on which the operations are to be found
• the identifier of the operations
• the number of arguments to be passed

For legacy callers

• the interface on which the legacy callers are to be found
• the number of arguments to be passed

For constructors

• the interface on which the [Constructor] extended attributes are to be found
• the number of arguments to be passed

For named constructors

• the interface on which the [NamedConstructor] extended attributes are to be found
• the identifier of the named constructors
• the number of arguments to be passed

For callback functions

• the callback function
• the number of arguments to be passed

An effective overload set is used, among other things, to determine whether there are ambiguities in the overloaded operations, constructors and callers specified on an interface.

The elements of an effective overload set are tuples of the form < callable, type list, optionality list>. If the effective overload set is for regular operations, static operations or legacy callers, then callable is an operation; if it is for constructors or named constructors, then callable is an extended attribute; and if it is for callback functions, then callable is the callback function itself. In all cases, type list is a list of IDL types, and optionality list is a list of three possible optionality values – “required”, “optional” or “variadic” – indicating whether the argument at a given index was declared as being optional or corresponds to a variadic argument. Each tuple represents an allowable invocation of the operation, constructor, legacy caller or callback function with an argument value list of the given types. Due to the use of optional arguments and variadic operations and constructors, there may be multiple entries in an effective overload set identifying the same operation or constructor.

The algorithm below describes how to compute an effective overload set. The following input variables are used, if they are required:

• the identifier of the operation or named constructor is A
• the argument count is N
• the interface is I
• the callback function is C

Whenever an argument of an extended attribute is mentioned, it is referring to an argument of the extended attribute’s named argument list.

1. Initialize S to ∅.
2. Let F be a set with elements as follows, according to the kind of effective overload set:

   For regular operations

   The elements of F are the regular operations with identifier A defined on interface I.

   For static operations

   The elements of F are the static operations with identifier A defined on interface I.

   For constructors

   The elements of F are the [Constructor] extended attributes on interface I.

   For named constructors

   The elements of F are the [NamedConstructor] extended attributes on interface I whose named argument lists’ identifiers are A.

   For legacy callers

   The elements of F are the legacy callers defined on interface I.

   For callback functions

   The single element of F is the callback function itself, C.

3. Let maxarg be the maximum number of arguments the operations, constructor extended attributes or callback functions in F are declared to take. For variadic operations and constructor extended attributes, the argument on which the ellipsis appears counts as a single argument.

   Note

   So void f(long x, long... y); is considered to be declared to take two arguments.

4. Let m be the maximum of maxarg and N.
5. For each operation, extended attribute or callback function X in F:
   1. Let n be the number of arguments X is declared to take.
   2. Let t_0..n−1 be a list of types, where t_i is the type of X’s argument at index i.
   3. Let o_0..n−1 be a list of optionality values, where o_i is “variadic” if X’s argument at index i is a final, variadic argument, “optional” if the argument is optional, and “required” otherwise.
   4. Add to S the tuple <X, t_0..n−1, o_0..n−1>.
   5. If X is declared to be variadic, then:
      1. Add to S the tuple <X, t_0..n−2, o_0..n−2>.

         Note

         This leaves off the final, variadic argument.

      2. For every integer i, such that n ≤ i ≤ m−1:
         1. Let u_0..i be a list of types, where u_j = t_j (for j < n) and u_j = t_n−1 (for j ≥ n).
         2. Let p_0..i be a list of optionality values, where p_j = o_j (for j < n) and p_j = “variadic” (for j ≥ n).
         3. Add to S the tuple <X, u_0..i, p_0..i>.
   6. Initialize i to n−1.
   7. While i ≥ 0:
      1. If argument i of X is not optional, then break this loop.
      2. Otherwise, add to S the tuple <X, t_0..i−1, o_0..i−1>.
      3. Set i to i−1.
6. The effective overload set is S.

interface A {
  /* f1 */ void f(DOMString a);
  /* f2 */ void f(Node a, DOMString b, double... c);
  /* f3 */ void f();
  /* f4 */ void f(Event a, DOMString b, optional DOMString c, double... d);
};

Two types are distinguishable if at most one of the two includes a nullable type or is a dictionary type, and at least one of the following three conditions is true:

1. The two types (taking their inner types if they are nullable types) appear in the following table and there is a “●” mark in the corresponding entry or there is a letter in the corresponding entry and the designated additional requirement below the table is satisfied:

   	boolean	numeric types	string types	interface	object	callback function	dictionary	sequence<T>	exception types	buffer source types
   boolean		●	●	●	●	●	●	●	●	●
   numeric types			●	●	●	●	●	●	●	●
   string types				●	●	●	●	●	●	●
   interface				(a)		(b)	(b)	●	●	●
   object
   callback function								●	●	●
   dictionary								●	●	●
   sequence<T>									●	●
   exception types										●
   buffer source types

   1. The two identified interfaces are not the same, it is not possible for a single platform object to implement both interfaces, and it is not the case that both are callback interfaces.
   2. The interface type is not a callback interface.
2. One type is a union type or nullable union type, the other is neither a union type nor a nullable union type, and each member type of the first is distinguishable with the second.
3. Both types are either a union type or nullable union type, and each member type of the one is distinguishable with each member type of the other.

If there is more than one entry in an effective overload set that has a given type list length, then for those entries there MUST be an index i such that for each pair of entries the types at index i are distinguishable . The lowest such index is termed the distinguishing argument index for the entries of the effective overload set with the given type list length.

interface B {
  void f(DOMString x);
  void f(double x);
};

In addition, for each index j, where j is less than the distinguishing argument index for a given type list length, the types at index j in all of the entries’ type lists MUST be the same and the booleans in the corresponding list indicating argument optionality MUST be the same.

interface B {
  /* f1 */ void f(DOMString w);
  /* f2 */ void f(long w, double x, Node y, Node z);
  /* f3 */ void f(double w, double x, DOMString y, Node z);
};

3.2.7 Iterable declarations

An interface can be declared to be iterable by using an iterable declaration (matching Iterable) in the body of the interface.

iterable<value-type>;
iterable<key-type, value-type>;

Objects implementing an interface that is declared to be iterable support being iterated over to obtain a sequence of values.

If a single type parameter is given, then the interface has a value iterator and provides values of the specified type. If two type parameters are given, then the interface has a pair iterator and provides value pairs, where the first value is a key and the second is the value associated with the key.

A value iterator MUST only be declared on an interface that supports indexed properties and has an integer-typed attribute named “length”. The value-type of the value iterator MUST be the same as the type returned by the indexed property getter. A value iterator is implicitly defined to iterate over the object’s indexed properties.

A pair iterator MUST NOT be declared on an interface that supports indexed properties. Prose accompanying an interface with a pair iterator MUST define what the list of value pairs to iterate over is.

Interfaces with iterable declarations MUST NOT have any interface members named “entries”, “forEach”, “keys” or “values”, or have any inherited or consequential interfaces that have interface members with these names.

interface SessionManager {
  Session getSessionForUser(DOMString username);
  readonly attribute unsigned long sessionCount;
  iterable<Session>;
};
interface Session {
  readonly attribute DOMString username;
  // ...
};

// Get an instance of SessionManager.
// Assume that it has sessions for two users, "anna" and "brian".
var sm = getSessionManager();
typeof SessionManager.prototype.values;            // Evaluates to "function"
var it = sm.values();                              // values() returns an iterator object
String(it);                                        // Evaluates to "[object SessionManager Iterator]"
typeof it.next;                                    // Evaluates to "function"
// This loop will alert "anna" and then "brian".
for (;;) {
  let result = it.next();
  if (result.done) {
    break;
  }
  let session = result.value;
  window.alert(session.username);
}
// This loop will also alert "anna" and then "brian".
for (let session of sm) {
  window.alert(session.username);
}

An interface MUST NOT have more than one iterable declaration. The inherited and consequential interfaces of an interface with an iterable declaration MUST NOT also have an iterable declaration.

The following extended attributes are applicable to iterable declarations: [Exposed].

3.4.1 Error names

The error names table below lists all the allowed error names for DOMExceptions, a description, and legacy code values.

3.10.1 any

The any type is the union of all other possible non- union types. Its type name is “Any”.

The any type is like a discriminated union type, in that each of its values has a specific non-any type associated with it. For example, one value of the any type is the unsigned long 150, while another is the long 150. These are distinct values.

The particular type of an any value is known as its specific type . (Values of union types also have specific types.)

3.10.2 boolean

The boolean type has two values: true and false.

boolean constant values in IDL are represented with the true and false tokens.

The type name of the boolean type is “Boolean”.

3.10.3 byte

The byte type is a signed integer type that has values in the range [−128, 127].

byte constant values in IDL are represented with integer tokens.

The type name of the byte type is “Byte”.

3.10.4 octet

The octet type is an unsigned integer type that has values in the range [0, 255].

octet constant values in IDL are represented with integer tokens.

The type name of the octet type is “Octet”.

3.10.5 short

The short type is a signed integer type that has values in the range [−32768, 32767].

short constant values in IDL are represented with integer tokens.

The type name of the short type is “Short”.

3.10.6 unsigned short

The unsigned short type is an unsigned integer type that has values in the range [0, 65535].

unsigned short constant values in IDL are represented with integer tokens.

The type name of the unsigned short type is “UnsignedShort”.

3.10.7 long

The long type is a signed integer type that has values in the range [−2147483648, 2147483647].

long constant values in IDL are represented with integer tokens.

The type name of the long type is “Long”.

3.10.8 unsigned long

The unsigned long type is an unsigned integer type that has values in the range [0, 4294967295].

unsigned long constant values in IDL are represented with integer tokens.

The type name of the unsigned long type is “UnsignedLong”.

3.10.9 long long

The long long type is a signed integer type that has values in the range [−9223372036854775808, 9223372036854775807].

long long constant values in IDL are represented with integer tokens.

The type name of the long long type is “LongLong”.

3.10.10 unsigned long long

The unsigned long long type is an unsigned integer type that has values in the range [0, 18446744073709551615].

unsigned long long constant values in IDL are represented with integer tokens.

The type name of the unsigned long long type is “UnsignedLongLong”.

3.10.11 float

The float type is a floating point numeric type that corresponds to the set of finite single-precision 32 bit IEEE 754 floating point numbers. [IEEE-754]

float constant values in IDL are represented with float tokens.

The type name of the float type is “Float”.

3.10.12 unrestricted float

The unrestricted float type is a floating point numeric type that corresponds to the set of all possible single-precision 32 bit IEEE 754 floating point numbers, finite and non-finite. [IEEE-754]

unrestricted float constant values in IDL are represented with float tokens.

The type name of the unrestricted float type is “UnrestrictedFloat”.

3.10.13 double

The double type is a floating point numeric type that corresponds to the set of finite double-precision 64 bit IEEE 754 floating point numbers. [IEEE-754]

double constant values in IDL are represented with float tokens.

The type name of the double type is “Double”.

3.10.14 unrestricted double

The unrestricted double type is a floating point numeric type that corresponds to the set of all possible double-precision 64 bit IEEE 754 floating point numbers, finite and non-finite. [IEEE-754]

unrestricted double constant values in IDL are represented with float tokens.

The type name of the unrestricted double type is “UnrestrictedDouble”.

3.10.15 DOMString

The DOMString type corresponds to the set of all possible sequences of code units. Such sequences are commonly interpreted as UTF-16 encoded strings [RFC2781] although this is not required. While DOMString is defined to be an OMG IDL boxed sequence<unsigned short> valuetype in DOM Level 3 Core ([ DOM3CORE], section 1.2.1), this document defines DOMString to be an intrinsic type so as to avoid special casing that sequence type in various situations where a string is required.

Nothing in this specification requires a DOMString value to be a valid UTF-16 string. For example, a DOMString value might include unmatched surrogate pair characters. However, authors of specifications using Web IDL might want to obtain a sequence of Unicode scalar values given a particular sequence of code units. The following algorithm defines a way to convert a DOMString to a sequence of Unicode scalar values :

1. Let S be the DOMString value.
2. Let n be the length of S.
3. Initialize i to 0.
4. Initialize U to be an empty sequence of Unicode characters.
5. While i < n:
   1. Let c be the code unit in S at index i.
   2. Depending on the value of c:

      c < 0xD800 or c > 0xDFFF

      Append to U the Unicode character with code point c.

      0xDC00 ≤ c ≤ 0xDFFF

      Append to U a U+FFFD REPLACEMENT CHARACTER.

      0xD800 ≤ c ≤ 0xDBFF

      1. If i = n−1, then append to U a U+FFFD REPLACEMENT CHARACTER.
      2. Otherwise, i < n−1:
         1. Let d be the code unit in S at index i+1.
         2. If 0xDC00 ≤ d ≤ 0xDFFF, then:
            1. Let a be c & 0x3FF.
            2. Let b be d & 0x3FF.
            3. Append to U the Unicode character with code point 2¹⁶+2¹⁰a+b.
            4. Set i to i+1.
         3. Otherwise, d < 0xDC00 or d > 0xDFFF. Append to U a U+FFFD REPLACEMENT CHARACTER.

   3. Set i to i+1.
6. Return U.

There is no way to represent a constant DOMString value in IDL, although DOMString dictionary member and operation optional argument default values can be specified using a string literal.

The type name of the DOMString type is “String”.

3.10.16 ByteString

The ByteString type corresponds to the set of all possible sequences of bytes. Such sequences might be interpreted as UTF-8 encoded strings [RFC3629] or strings in some other 8-bit-per-code-unit encoding, although this is not required.

There is no way to represent a constant ByteString value in IDL.

The type name of the ByteString type is “ByteString”.

3.10.17 USVString

The USVString type corresponds to the set of all possible sequences of Unicode scalar values, which are all of the Unicode code points apart from the surrogate code points.

There is no way to represent a constant USVString value in IDL, although USVString dictionary member and operation optional argument default values can be specified using a string literal.

The type name of the USVString type is “USVString”.

3.10.18 object

The object type corresponds to the set of all possible non-null object references.

There is no way to represent a constant object value in IDL.

To denote a type that includes all possible object references plus the null value, use the nullable type object?.

The type name of the object type is “Object”.

3.10.19 Interface types

An identifier that identifies an interface is used to refer to a type that corresponds to the set of all possible non-null references to objects that implement that interface.

For non-callback interfaces, an IDL value of the interface type is represented just by an object reference. For callback interfaces, an IDL value of the interface type is represented by a tuple of an object reference and a callback context . The callback context is a language binding specific value, and is used to store information about the execution context at the time the language binding specific object reference is converted to an IDL value.

There is no way to represent a constant object reference value for a particular interface type in IDL.

To denote a type that includes all possible references to objects implementing the given interface plus the null value, use a nullable type.

The type name of an interface type is the identifier of the interface.

3.10.20 Dictionary types

An identifier that identifies a dictionary is used to refer to a type that corresponds to the set of all dictionaries that adhere to the dictionary definition.

There is no way to represent a constant dictionary value in IDL.

The type name of a dictionary type is the identifier of the dictionary.

3.10.21 Enumeration types

An identifier that identifies an enumeration is used to refer to a type whose values are the set of strings (sequences of code units, as with DOMString) that are the enumeration’s values.

Like DOMString, there is no way to represent a constant enumeration value in IDL, although enumeration-typed dictionary member default values can be specified using a string literal.

The type name of an enumeration type is the identifier of the enumeration.

3.10.22 Callback function types

An identifier that identifies a callback function is used to refer to a type whose values are references to objects that are functions with the given signature.

An IDL value of the callback function type is represented by a tuple of an object reference and a callback context.

There is no way to represent a constant callback function value in IDL.

The type name of a callback function type is the identifier of the callback function.

3.10.23 Nullable types — T?

A nullable type is an IDL type constructed from an existing type (called the inner type ), which just allows the additional value null to be a member of its set of values. Nullable types are represented in IDL by placing a U+003F QUESTION MARK ("?") character after an existing type. The inner type MUST NOT be any, another nullable type, or a union type that itself has includes a nullable type or has a dictionary type as one of its flattened member types.

Nullable type constant values in IDL are represented in the same way that constant values of their inner type would be represented, or with the null token.

The type name of a nullable type is the concatenation of the type name of the inner type T and the string “OrNull”.

interface MyConstants {
  const boolean? ARE_WE_THERE_YET = false;
};

interface Node {
  readonly attribute DOMString? namespaceURI;
  readonly attribute Node? parentNode;
  // ...
};

3.10.24 Sequences — sequence<T>

The sequence<T> type is a parameterized type whose values are (possibly zero-length) sequences of values of type T.

Sequences are always passed by value. In language bindings where a sequence is represented by an object of some kind, passing a sequence to a platform object will not result in a reference to the sequence being kept by that object. Similarly, any sequence returned from a platform object will be a copy and modifications made to it will not be visible to the platform object.

There is no way to represent a constant sequence value in IDL.

Sequences MUST NOT be used as the type of an attribute or constant.

The type name of a sequence type is the concatenation of the type name for T and the string “Sequence”.

3.10.25 Promise types — Promise<T>

A promise type is a parameterized type whose values are references to objects that “is used as a place holder for the eventual results of a deferred (and possibly asynchronous) computation result of an asynchronous operation” [ECMA-262]. See section 25.4 of the ECMAScript specification for details on the semantics of promise objects.

There is no way to represent a promise value in IDL.

The type name of a promise type is the concatenation of the type name for T and the string “Promise”.

3.10.26 Union types

A union type is a type whose set of values is the union of those in two or more other types. Union types (matching UnionType) are written as a series of types separated by the or keyword with a set of surrounding parentheses. The types which comprise the union type are known as the union’s <