Web IDL

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 and exceptions.

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 or another exception member defined on the same exception.

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 below.

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 7.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 below. 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;
};

No extended attributes defined in this specification are applicable to constants.

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

exception Problem {
  const short ERR_UNKNOWN = 0;
  const short ERR_OUT_OF_MEMORY = 1;

  short errorCode;
};

3.2.2. Attributes

An attribute is an interface member (matching "stringifier" Attribute or Attribute) that is used to declare that objects implementing the interface will have a member with the given identifier whose value can be retrieved and (in some cases) changed.

attribute type identifier;

The identifier of an attribute MUST NOT be the same as the identifier of another interface member defined on the same interface.

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 MUST NOT be a sequence type or nullable sequence type, and it MUST NOT be a union type if one of its member types (or one of its member types’s member types, and so on) is a sequence type or nullable sequence type.

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;

An 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.

interface Ancestor {
  readonly attribute TheType theIdentifier;
};

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

When the stringifier keyword is used in an attribute declaration, it indicates that objects implementing the interface will be stringified to the value of the attribute. See section 3.2.4.2 below 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 attributes: [Clamp], [EnforceRange], [LenientThis], [PutForwards], [Replaceable], [TreatNullAs], [TreatUndefinedAs], [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 "stringifier" OperationRest or Operation) 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 below 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 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 or 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 or an identifier followed by ?, then the identifier MUST identify an interface, dictionary, enumeration, callback function or typedef.

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;
};

exception NoPointerDevice { };

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. An argument MUST NOT be declared to be optional unless all subsequent arguments to the operation are also optional. Also, the final argument in an operation MUST NOT 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 an optional argument has a default value, then all following arguments (except for the final argument if the operation is variadic) MUST also have a default value.

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 DOMString or enumeration determined as follows:

1. Let S be the sequence of characters matched by the string token with its leading and trailing U+0022 QUOTATION MARK ('"') characters removed.
2. 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.

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

Web IDL operations do not support being called with omitted optional arguments unless all subsequent optional arguments are also omitted. Bindings for languages that do support function calling in this way will fail such calls in a language binding specific manner.

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

interface ColorCreator {
  object createColor(float v1, float v2, float v3);
  object createColor(float v1, float v2, float v3, float 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: [TreatNullAs], [TreatUndefinedAs].

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

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.

Some language bindings, such as ECMAScript, do not distinguish assignment to an existing indexed or named property and the creation of a new one. Regardless, it is the creator that is invoked when an attempt is made to create a new indexed or named property, and the setter when the property already exists.

interface Dictionary {
  readonly attribute unsigned long propertyCount;

  getter float (DOMString propertyName);
  setter void (DOMString propertyName, float 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 float getProperty(DOMString propertyName);
  setter void setProperty(DOMString propertyName, float propertyValue);
};

interface Dictionary {
  readonly attribute unsigned long propertyCount;

  float getProperty(DOMString propertyName);
  void setProperty(DOMString propertyName, float propertyValue);

  getter float (DOMString propertyName);
  setter void (DOMString propertyName, float propertyValue);
};

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

Getters, setters, creators and deleters come in two varieties: ones that take a DOMString as a property name, known as named property getters, named property setters, named property creators and named property deleters, and ones that take an unsigned long as a property index, known as indexed property getters, indexed property setters, indexed property creators and indexed property deleters. See section 3.2.4.3 and section 3.2.4.4 for details.

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

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 float compute(float 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'.

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

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

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

var a = getA();

a.toWord(0);  // Evalutes 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);
  deleter void removeByIndex(unsigned long index);

  getter any get(DOMString name);
  setter creator void set(DOMString name, any value);
  deleter void remove(DOMString name);
};

// 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;   // If map.length > 1, then this will set the property named
                  // "1" on map to false, and then will do the equivalent of:
                  //
                  //   map.setByIndex(1, false)
                  //
                  // Otherwise, if map.length ≤ 1, then it will set the
                  // property but have no other effect (since an indexed property creator
                  // was not specified).

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;  // Regardless of whether there exists a named property named
                  // "berry", this will set the "berry" property to 123, and
                  // then 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);
creator type identifier(DOMString identifier, type identifier);
deleter type identifier(DOMString identifier);

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

3.2.5. Static operations

A static operation is one that is not called on a particular instance of the interface on which it is declared, and is instead associated with the interface itself. Static operations are declared by using the static keyword in an operation declaration.

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

Static operations MUST NOT be declared on callback interfaces.

interface Point { /* ... */ };

interface Circle {
  attribute float cx;
  attribute float cy;
  attribute float radius;

  static Point triangulate(Circle c1, Circle c2, Circle c3);
};

var circles = getCircles();    // an Array of Circle objects

typeof Circle.triangulate;     // Evaluates to "function"
Circle.prototype.triangulate;  // Evaluates to undefined
circles[0].triangulate;        // Also evaluates to undefined

// Call the static operation
var triangulationPoint = Circle.triangulate(circles[0], circles[1], circles[2]);

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(float 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 pairs of the form <callable, type 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. Each pair 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 the types of the arguments X is defined to take.
   3. Add to S the pair <X, t_0..n−1>.
   4. If n > 0 and X is declared to be variadic, then:
      1. Add to S the pair <X, t_0..n−2>.
      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. Add to S the pair <X, u_0..i>.
   5. For every integer i, such that 0 < i < n:
      1. If argument i of X is optional, then add to S the pair <X, t_0..i−1>.
   6. If n > 0 and the first argument of X is optional, then add to S the pair <X, ()> (where “()” represents the empty list).
6. The effective overload set is S.

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

Two types are distinguishable if at most one of the two is a nullable 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:

   	primitive	DOMString	enumeration	interface	object	callback function	dictionary	sequence<T>	T[]	Date
   primitive				●	●	●	●	●	●	●
   DOMString				●	●	●	●	●	●	●
   enumeration				●	●	●	●	●	●	●
   interface				(a)		(b)	(b)	(b)	(b)	●
   object
   callback function										●
   dictionary								●	●	●
   sequence<T>										●
   T[]										●
   Date

   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(float 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.

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

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 32 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 characters given a particular sequence of code units. The following algorithm defines a way to convert a DOMString to a sequence of Unicode characters:

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 an be specified using a string literal.

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

3.10.16. 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.17. 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.

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.18. 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.19. 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.20. 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.

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.21. 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 or another nullable type or a union type that itself has a nullable type as a member type, as they already allow the null value.

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.22. 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 user agent implemented object will not result in a reference to the sequence being kept by that object. Similarly, any sequence returned from a user agent implemented object will be a copy and modifications made to it will not be visible to the object.

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

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

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

3.10.23. Arrays — T[]

The T[] type is a parameterized type. The values of this type are non-null references to arrays of values of type T. Unlike sequences, arrays are passed by reference. Passing an array to a platform object could result in that array being modified by the object. An array returned from a platform object might also be modified by the object, and any modifications to the array performed by user code might be acted upon by the platform object.

The element type of an array MUST NOT be a sequence or dictionary type.

Arrays can either be fixed length or variable length. Fixed length arrays cannot have their length changed by user code after they have been created, while variable length arrays can. Unless otherwise specified, arrays are fixed length.

Arrays can also be designated as being read only. User code cannot modify the values of read only array elements. If an array is read only, then it is also implicitly fixed length.

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

The type name of an array type is the concatenation of the type name for T and the string “Array”.

3.10.24. 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 member types.

Like the any type, values of union types have a specific type, which is the particular member type that matches the value.

The flattened member types of a union type is a set of types determined as follows:

1. Let T be the union type.
2. Initialize S to ∅.
3. For each member type U of T:
   1. If U is a nullable type, then set U to be the inner type of U.
   2. If U is a union type, then add to S the flattened member types of U.
   3. Otherwise, U is not a union type. Add U to S.
4. Return S.

The number of nullable member types of a union type is an integer determined as follows:

1. Let T be the union type.
2. Initialize n to 0.
3. For each member type U of T:
   1. If U is a nullable type, then:
      1. Set n to n + 1.
      2. Set U to be the inner type of U.
   2. If U is a union type, then:
      1. Let m be the number of nullable member types of U.
      2. Set n to n + m.
4. Return n.

The any type MUST NOT be used as a union member type.

The number of nullable member types of a union type MUST be 0 or 1. A union type includes a nullable type if its number of nullable member types is 1.

Each pair of flattened member types in a union type, T and U, MUST be distinguishable.

Union type constant values in IDL are represented in the same way that constant values of their member types would be represented.

The type name of a union type is formed by taking the type names of each member type, in order, and joining them with the string “Or”.

3.10.25. Date

The Date type is a type that represents an instant in time with millisecond accuracy. The instants in time that this type can represent are the same that can be represented with ECMAScript Date objects ([ECMA-262], section 15.9.1.1) – namely, every millisecond in the 200,000,000 days centered around midnight of 1 January, 1970 UTC, except for any millisecond that is part of an inserted leap second, because they cannot be represented by this type.

An additional value that this type can represent is one that indicates an indeterminate or undefined time, which we write as undefined.

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

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

4.2.1. any

Since the IDL any type is the union of all other IDL types, it can correspond to any ECMAScript value type.

How to convert an ECMAScript value to an IDL any value depends on the type of the ECMAScript value:

The undefined value

The IDL value is an object reference to a special object that represents the ECMAScript undefined value.

The null value

The IDL value is the null object? reference.

A Boolean value

The IDL value is the boolean value that represents the same truth value.

A Number value

The IDL value is that which is obtained by following the rules for converting the Number to an IDL double value, as described in section 4.2.14, below.

A String value

The IDL value is that which is obtained by following the rules for converting the String to an IDL DOMString value, as described in section 4.2.16, below.

An object value

The IDL value is an object value that references the same object.

An IDL any value is converted to an ECMAScript value as follows. If the value is an object reference to a special object that represents an ECMAScript undefined value, then it is converted to the ECMAScript undefined value. Otherwise, the rules for converting the specific type of the IDL any value as described in the remainder of this section are performed.

4.2.2. void

The only place that the void type may appear in IDL is as the return type of an operation. Functions on platform objects that implement an operation whose IDL specifies a void return type MUST return the undefined value.

ECMAScript functions that implement an operation whose IDL specifies a void return type MAY return any value, which will be discarded.

4.2.3. boolean

An ECMAScript value V is converted to an IDL boolean value by running the following algorithm:

1. Let x be the result of computing ToBoolean(V).
2. Return the IDL boolean value that is the one that represents the same truth value as the ECMAScript Boolean value x.

The IDL boolean value true is converted to the ECMAScript true value and the IDL boolean value false is converted to the ECMAScript false value.

4.2.4. byte

An ECMAScript value V is converted to an IDL byte value by running the following algorithm:

1. Initialize x to ToNumber(V).
2. If the conversion to an IDL value is being performed due to any of the following:
   • V is being assigned to an attribute annotated with the [EnforceRange] extended attribute,
   • V is being passed as an operation argument annotated with the [EnforceRange] extended attribute, or
   • V is being used as the value of dictionary member annotated with the [EnforceRange] extended attribute,
   then:
   1. If x is NaN, +∞, or −∞, then throw a TypeError.
   2. Set x to sign(x) * floor(abs(x)).
   3. If x < −2⁷ or x > 2⁷ − 1, then throw a TypeError.
   4. Return the IDL byte value that represents the same numeric value as x.
3. If x is not NaN and the conversion to an IDL value is being performed due to any of the following:
   • V is being assigned to an attribute annotated with the [Clamp] extended attribute,
   • V is being passed as an operation argument annotated with the [Clamp] extended attribute, or
   • V is being used as the value of dictionary member annotated with the [Clamp] extended attribute,
   then:
   1. Round x to the nearest integer, choosing the even integer if it lies halfway between two.
   2. Set x to min(max(x, −2⁷), 2⁷ − 1).
   3. Return the IDL byte value that represents the same numeric value as x.
4. If x is NaN, +0, −0, +∞, or −∞, then return the IDL byte value that represents 0.
5. Set x to sign(x) * floor(abs(x)).
6. Set x to x modulo 2⁸.
7. If x ≥ 2⁷, return the IDL byte value that represents the same numeric value as x − 2⁸. Otherwise, return the IDL byte value that represents the same numeric value as x.

The result of converting an IDL byte value to an ECMAScript value is a Number that represents the same numeric value as the IDL byte value. The Number value will be an integer in the range [−128, 127].

4.2.5. octet

An ECMAScript value V is converted to an IDL octet value by running the following algorithm:

1. Initialize x to ToNumber(V).
2. If the conversion to an IDL value is being performed due to any of the following:
   • V is being assigned to an attribute annotated with the [EnforceRange] extended attribute,
   • V is being passed as an operation argument annotated with the [EnforceRange] extended attribute, or
   • V is being used as the value of dictionary member annotated with the [EnforceRange] extended attribute,
   then:
   1. If x is NaN, +∞, or −∞, then throw a TypeError.
   2. Set x to sign(x) * floor(abs(x)).
   3. If x < 0 or x > 2⁸ − 1, then throw a TypeError.
   4. Return the IDL octet value that represents the same numeric value as x.
3. If x is not NaN and the conversion to an IDL value is being performed due to any of the following:
   • V is being assigned to an attribute annotated with the [Clamp] extended attribute,
   • V is being passed as an operation argument annotated with the [Clamp] extended attribute, or
   • V is being used as the value of dictionary member annotated with the [Clamp] extended attribute,
   then:
   1. Round x to the nearest integer, choosing the even integer if it lies halfway between two.
   2. Set x to min(max(x, 0), 2⁸ − 1).
   3. Return the IDL octet value that represents the same numeric value as x.
4. If x is NaN, +0, −0, +∞, or −∞, then return the IDL octet value that represents 0.
5. Set x to sign(x) * floor(abs(x)).
6. Set x to x modulo 2⁸.
7. Return the IDL octet value that represents the same numeric value as x.

The result of converting an IDL octet value to an ECMAScript value is a Number that represents the same numeric value as the IDL octet value. The Number value will be an integer in the range [0, 255].

4.2.6. short

An ECMAScript value V is converted to an IDL short value by running the following algorithm:

1. Initialize x to ToNumber(V).
2. If the conversion to an IDL value is being performed due to any of the following:
   • V is being assigned to an attribute annotated with the [EnforceRange] extended attribute,
   • V is being passed as an operation argument annotated with the [EnforceRange] extended attribute, or
   • V is being used as the value of dictionary member annotated with the [EnforceRange] extended attribute,
   then:
   1. If x is NaN, +∞, or −∞, then throw a TypeError.
   2. Set x to sign(x) * floor(abs(x)).
   3. If x < −2¹⁵ or x > 2¹⁵ − 1, then throw a TypeError.
   4. Return the IDL short value that represents the same numeric value as x.
3. If x is not NaN and the conversion to an IDL value is being performed due to any of the following:
   • V is being assigned to an attribute annotated with the [Clamp] extended attribute,
   • V is being passed as an operation argument annotated with the [Clamp] extended attribute, or
   • V is being used as the value of dictionary member annotated with the [Clamp] extended attribute,
   then:
   1. Round x to the nearest integer, choosing the even integer if it lies halfway between two.
   2. Set x to min(max(x, −2¹⁵), 2¹⁵ − 1).
   3. Return the IDL short value that represents the same numeric value as x.
4. If x is NaN, +0, −0, +∞, or −∞, then return the IDL short value that represents 0.
5. Set x to sign(x) * floor(abs(x)).
6. Set x to x modulo 2¹⁶.
7. If x ≥ 2¹⁵, return the IDL short value that represents the same numeric value as x − 2¹⁶. Otherwise, return the IDL short value that represents the same numeric value as x.

The result of converting an IDL short value to an ECMAScript value is a Number that represents the same numeric value as the IDL short value. The Number value will be an integer in the range [−32768, 32767].

4.2.7. unsigned short

An ECMAScript value V is converted to an IDL unsigned short value by running the following algorithm:

1. Initialize x to ToNumber(V).
2. If the conversion to an IDL value is being performed due to any of the following:
   • V is being assigned to an attribute annotated with the [EnforceRange] extended attribute,
   • V is being passed as an operation argument annotated with the [EnforceRange] extended attribute, or
   • V is being used as the value of dictionary member annotated with the [EnforceRange] extended attribute,
   then:
   1. If x is NaN, +∞, or −∞, then throw a TypeError.
   2. Set x to sign(x) * floor(abs(x)).
   3. If x < 0 or x > 2¹⁶ − 1, then throw a TypeError.
   4. Return the IDL unsigned short value that represents the same numeric value as x.
3. If x is not NaN and the conversion to an IDL value is being performed due to any of the following:
   • V is being assigned to an attribute annotated with the [Clamp] extended attribute,
   • V is being passed as an operation argument annotated with the [Clamp] extended attribute, or
   • V is being used as the value of dictionary member annotated with the [Clamp] extended attribute,
   then:
   1. Round x to the nearest integer, choosing the even integer if it lies halfway between two.
   2. Set x to min(max(x, 0), 2¹⁶ − 1).
   3. Return the IDL unsigned short value that represents the same numeric value as x.
4. Set x to ToUint16(x).
5. Return the IDL unsigned short value that represents the same numeric value as x.

The result of converting an IDL unsigned short value to an ECMAScript value is a Number that represents the same numeric value as the IDL unsigned short value. The Number value will be an integer in the range [0, 65535].

4.2.8. long

An ECMAScript value V is converted to an IDL long value by running the following algorithm:

1. Initialize x to ToNumber(V).
2. If the conversion to an IDL value is being performed due to any of the following:
   • V is being assigned to an attribute annotated with the [EnforceRange] extended attribute,
   • V is being passed as an operation argument annotated with the [EnforceRange] extended attribute, or
   • V is being used as the value of dictionary member annotated with the [EnforceRange] extended attribute,
   then:
   1. If x is NaN, +∞, or −∞, then throw a TypeError.
   2. Set x to sign(x) * floor(abs(x)).
   3. If x < −2³¹ or x > 2³¹ − 1, then throw a TypeError.
   4. Return the IDL long value that represents the same numeric value as x.
3. If x is not NaN and the conversion to an IDL value is being performed due to any of the following:
   • V is being assigned to an attribute annotated with the [Clamp] extended attribute,
   • V is being passed as an operation argument annotated with the [Clamp] extended attribute, or
   • V is being used as the value of dictionary member annotated with the [Clamp] extended attribute,
   then:
   1. Round x to the nearest integer, choosing the even integer if it lies halfway between two.
   2. Set x to min(max(x, −2³¹), 2³¹ − 1).
   3. Return the IDL long value that represents the same numeric value as x.
4. Set x to ToInt32(x).
5. Return the IDL long value that represents the same numeric value as x.

The result of converting an IDL long value to an ECMAScript value is a Number that represents the same numeric value as the IDL long value. The Number value will be an integer in the range [−2147483648, 2147483647].

4.2.9. unsigned long

An ECMAScript value V is converted to an IDL unsigned long value by running the following algorithm:

1. Initialize x to ToNumber(V).
2. If the conversion to an IDL value is being performed due to any of the following:
   • V is being assigned to an attribute annotated with the [EnforceRange] extended attribute,
   • V is being passed as an operation argument annotated with the [EnforceRange] extended attribute, or
   • V is being used as the value of dictionary member annotated with the [EnforceRange] extended attribute,
   then:
   1. If x is NaN, +∞, or −∞, then throw a TypeError.
   2. Set x to sign(x) * floor(abs(x)).
   3. If x < 0 or x > 2³² − 1, then throw a TypeError.
   4. Return the IDL unsigned long value that represents the same numeric value as x.
3. If x is not NaN and the conversion to an IDL value is being performed due to any of the following:
   • V is being assigned to an attribute annotated with the [Clamp] extended attribute,
   • V is being passed as an operation argument annotated with the [Clamp] extended attribute, or
   • V is being used as the value of dictionary member annotated with the [Clamp] extended attribute,
   then:
   1. Round x to the nearest integer, choosing the even integer if it lies halfway between two.
   2. Set x to min(max(x, 0), 2³² − 1).
   3. Return the IDL unsigned long value that represents the same numeric value as x.
4. Set x to ToUint32(x).
5. Return the IDL unsigned long value that represents the same numeric value as x.

The result of converting an IDL unsigned long value to an ECMAScript value is a Number that represents the same numeric value as the IDL unsigned long value. The Number value will be an integer in the range [0, 4294967295].

4.2.10. long long

An ECMAScript value V is converted to an IDL long long value by running the following algorithm:

1. Initialize x to ToNumber(V).
2. If the conversion to an IDL value is being performed due to any of the following:
   • V is being assigned to an attribute annotated with the [EnforceRange] extended attribute,
   • V is being passed as an operation argument annotated with the [EnforceRange] extended attribute, or
   • V is being used as the value of dictionary member annotated with the [EnforceRange] extended attribute,
   then:
   1. If x is NaN, +∞, or −∞, then throw a TypeError.
   2. Set x to sign(x) * floor(abs(x)).
   3. If x < −(2⁵³ − 1) or x > 2⁵³ − 1, then throw a TypeError.
   4. Return the IDL long long value that represents the same numeric value as x.
3. If x is not NaN and the conversion to an IDL value is being performed due to any of the following:
   • V is being assigned to an attribute annotated with the [Clamp] extended attribute,
   • V is being passed as an operation argument annotated with the [Clamp] extended attribute, or
   • V is being used as the value of dictionary member annotated with the [Clamp] extended attribute,
   then:
   1. Round x to the nearest integer, choosing the even integer if it lies halfway between two.
   2. Set x to min(max(x, −(2⁵³ − 1)), 2⁵³ − 1).
   3. Return the IDL long long value that represents the same numeric value as x.
4. If x is NaN, +0, −0, +∞, or −∞, then return the IDL long long value that represents 0.
5. Set x to sign(x) * floor(abs(x)).
6. Set x to x modulo 2⁶⁴.
7. If x is greater than or equal to 2⁶³, then set x to x − 2⁶⁴.
8. Return the IDL long long value that represents the same numeric value as x.

The result of converting an IDL long long value to an ECMAScript value is a Number value that represents the closest numeric value to the long long, choosing the numeric value with an even significand if there are two equally close values ([ECMA-262], section 8.5). If the long long is in the range (−(2⁵³ − 1), 2⁵³ − 1), then the Number will be able to represent exactly the same value as the long long.

4.2.11. unsigned long long

An ECMAScript value V is converted to an IDL unsigned long long value by running the following algorithm:

1. Initialize x to ToNumber(V).
2. If the conversion to an IDL value is being performed due to any of the following:
   • V is being assigned to an attribute annotated with the [EnforceRange] extended attribute,
   • V is being passed as an operation argument annotated with the [EnforceRange] extended attribute, or
   • V is being used as the value of dictionary member annotated with the [EnforceRange] extended attribute,
   then:
   1. If x is NaN, +∞, or −∞, then throw a TypeError.
   2. Set x to sign(x) * floor(abs(x)).
   3. If x < 0 or x > 2⁵³ − 1, then throw a TypeError.
   4. Return the IDL unsigned long long value that represents the same numeric value as x.
3. If x is not NaN and the conversion to an IDL value is being performed due to any of the following:
   • V is being assigned to an attribute annotated with the [Clamp] extended attribute,
   • V is being passed as an operation argument annotated with the [Clamp] extended attribute, or
   • V is being used as the value of dictionary member annotated with the [Clamp] extended attribute,
   then:
   1. Round x to the nearest integer, choosing the even integer if it lies halfway between two.
   2. Set x to min(max(x, 0), 2⁵³ − 1).
   3. Return the IDL unsigned long long value that represents the same numeric value as x.
4. If x is NaN, +0, −0, +∞, or −∞, then return the IDL unsigned long long value that represents 0.
5. Set x to sign(x) * floor(abs(x)).
6. Set x to x modulo 2⁶⁴.
7. Return the IDL unsigned long long value that represents the same numeric value as x.

The result of converting an IDL unsigned long long value to an ECMAScript value is a Number value that represents the closest numeric value to the unsigned long long, choosing the numeric value with an even significand if there are two equally close values ([ECMA-262], section 8.5). If the unsigned long long is less than or equal to 2⁵³ − 1, then the Number will be able to represent exactly the same value as the unsigned long long.

4.2.12. float

An ECMAScript value V is converted to an IDL float value by running the following algorithm:

1. Let x be ToNumber(V).
2. If x is NaN, +Infinity or −Infinity, then throw a TypeError.
3. Let S be the set of finite IEEE 754 single-precision floating point values except −0, but with two special values added: 2¹²⁸ and −2¹²⁸.
4. Let y be the number in S that is closest to x, selecting the number with an even significand if there are two equally close values ([ECMA-262], section 8.5). (The two special values 2¹²⁸ and −2¹²⁸ are considered to have even significands for this purpose.)
5. If y is 2¹²⁸ or −2¹²⁸, then throw a TypeError.
6. If y is +0 and x is negative, return −0.
7. Return y.

The result of converting an IDL float value to an ECMAScript value is the Number value that represents the same numeric value as the IDL float value.

4.2.13. unrestricted float

An ECMAScript value V is converted to an IDL unrestricted float value by running the following algorithm:

1. Let x be ToNumber(V).
2. If x is NaN, then return the IDL unrestricted float value that represents the IEEE 754 NaN value with the bit pattern 0x7fc00000 [IEEE-754].
3. Let S be the set of finite IEEE 754 single-precision floating point values except −0, but with two special values added: 2¹²⁸ and −2¹²⁸.
4. Let y be the number in S that is closest to x, selecting the number with an even significand if there are two equally close values ([ECMA-262], section 8.5). (The two special values 2¹²⁸ and −2¹²⁸ are considered to have even significands for this purpose.)
5. If y is 2¹²⁸, return +∞.
6. If y is −2¹²⁸, return −∞.
7. If y is +0 and x is negative, return −0.
8. Return y.

The result of converting an IDL unrestricted float value to an ECMAScript value is a Number:

• If the IDL unrestricted float value is a NaN, then the Number value is NaN.
• Otherwise, the Number value is the one that represents the same numeric value as the IDL unrestricted float value.

4.2.14. double

An ECMAScript value V is converted to an IDL double value by running the following algorithm:

1. Let x be ToNumber(V).
2. If x is NaN, +Infinity or −Infinity, then throw a TypeError.
3. Return the IDL double value that has the same numeric value as x.

The result of converting an IDL double value to an ECMAScript value is the Number value that represents the same numeric value as the IDL double value.

4.2.15. unrestricted double

An ECMAScript value V is converted to an IDL unrestricted double value by running the following algorithm:

1. Let x be ToNumber(V).
2. If x is NaN, then return the IDL unrestricted double value that represents the IEEE 754 NaN value with the bit pattern 0x7ff8000000000000 [IEEE-754].
3. Return the IDL unrestricted double value that has the same numeric value as x.

The result of converting an IDL unrestricted double value to an ECMAScript value is a Number:

• If the IDL unrestricted double value is a NaN, then the Number value is NaN.
• Otherwise, the Number value is the one that represents the same numeric value as the IDL unrestricted double value.

4.2.16. DOMString

An ECMAScript value V is converted to an IDL DOMString value by running the following algorithm:

1. If V is null and the conversion to an IDL value is being performed due to any of the following:
   • V is being passed as an operation argument that is annotated with the [TreatNullAs=EmptyString],
   • V is being assigned to an attribute annotated with [TreatNullAs=EmptyString],
   • V is being returned from a user object implementation of an operation annotated with [TreatNullAs=EmptyString], or
   • V is being returned from a user object implementation of an attribute annotated with [TreatNullAs=EmptyString],
   then return the DOMString value that represents the empty string.
2. If V is undefined and the conversion to an IDL value is being performed due to any of the following:
   • V is being passed as an operation argument that is annotated with the [TreatUndefinedAs=EmptyString],
   • V is being assigned to an attribute annotated with [TreatUndefinedAs=EmptyString],
   • V is being returned from a user object implementation of an operation annotated with [TreatUndefinedAs=EmptyString], or
   • V is being returned from a user object implementation of an attribute annotated with [TreatUndefinedAs=EmptyString],
   then return the DOMString value that represents the empty string.
3. Let x be ToString(V).
4. Return the IDL DOMString value that represents the same sequence of code units as the one the ECMAScript String value x represents.

The result of converting an IDL DOMString value to an ECMAScript value is the String value that represents the same sequence of code units that the IDL DOMString represents.

4.2.17. object

IDL object values are represented by ECMAScript Object values.

An ECMAScript value V is converted to an IDL object value by running the following algorithm:

1. If Type(V) is not Object, then throw a TypeError.
2. Return the IDL object value that is a reference to the same object as V.

The result of converting an IDL object value to an ECMAScript value is the Object value that represents a reference to the same object that the IDL object represents.

4.2.18. Interface types

IDL interface type values are represented by ECMAScript Object or Function values.

An ECMAScript value V is converted to an IDL interface type value by running the following algorithm (where I is the interface):

1. If Type(V) is not Object, then throw a TypeError.
2. If V is a platform object that implements I, then return the IDL interface type value that represents a reference to that platform object.
3. If V is a user object that is considered to implement I according to the rules in section 4.7, then return the IDL interface type value that represents a reference to that user object.
4. Throw a TypeError.

The result of converting an IDL interface type value to an ECMAScript value is the Object value that represents a reference to the same object that the IDL interface type value represents.

4.2.19. Dictionary types

IDL dictionary type values are represented by ECMAScript Object values. Properties on the object (or its prototype chain) correspond to dictionary members.

An ECMAScript value V is converted to an IDL dictionary type value by running the following algorithm (where D is the dictionary):

1. If Type(V) is not Object, then throw a TypeError.
2. Let dict be an empty dictionary value of type D; every dictionary member is initially considered to be not present.
3. Let dictionaries be a list consisting of D and all of D’s inherited dictionaries, in order from least to most derived.
4. For each dictionary dictionary in dictionaries, in order:
   1. For each dictionary member member declared on D, in order:
      1. Let key be the identifier of member.
      2. Let present be the result of calling the [[HasProperty]] internal method on V with property name key.
      3. If present is true, then:
         1. Let value be the result of calling the [[Get]] internal method on V with property name key.
         2. Let idlValue be the result of converting value to an IDL value whose type is the type member is declared to be of.
         3. Set the dictionary member on dict with key name key to the value idlValue. This dictionary member is considered to be present.
5. Return dict.

An IDL dictionary value V is converted to an ECMAScript Object value by running the following algorithm (where D is the dictionary):

1. Let O be a new Object value created as if by the expression ({}).
2. Let dictionaries be a list consisting of D and all of D’s inherited dictionaries, in order from least to most derived.
3. For each dictionary dictionary in dictionaries, in order:
   1. For each dictionary member member declared on dictionary, in order:
      1. Let key be the identifier of member.
      2. If the dictionary member named key is present on V, then:
         1. Let idlValue be the value of member on V.
         2. Let value be the result of converting idlValue to an ECMAScript value.
         3. Call the [[DefineOwnProperty]] internal method on O with property name key, descriptor { [[Writable]]: true, [[Enumerable]]: true, [[Configurable]]: true, [[Value]]: value } and Boolean flag false.
4. Return O.

4.2.20. Enumeration types

IDL enumeration types are represented by ECMAScript String values.

An ECMAScript value V is converted to an IDL enumeration type value as follows (where E is the enumeration):

1. Let S be the result of calling ToString(V).
2. If S is not one of E’s enumeration values, then throw a TypeError.
3. Return the enumeration value of type E that is equal to S.

The result of converting an IDL enumeration type value to an ECMAScript value is the String value that represents the same sequence of code units as the enumeration value.

4.2.21. Callback function types

IDL callback function types are represented by ECMAScript Function objects.

An ECMAScript value V is converted to an IDL callback function type value by running the following algorithm:

1. If V is not a Function object, then throw a TypeError.
2. Return the IDL callback function type value that represents a reference to that Function object.

The result of converting an IDL callback function type value to an ECMAScript value is a reference to the same object that the IDL callback function type value represents.

4.2.22. Nullable types — T?

IDL nullable type values are represented by values of either the ECMAScript type corresponding to the inner IDL type, or the ECMAScript null value.

An ECMAScript value V is converted to an IDL nullable type T? value (where T is the inner type) as follows:

1. If V is undefined, the IDL type being converted to is DOMString?, and the conversion to an IDL value is being performed due to any of the following:
   • V is being passed as an operation argument that is annotated with [TreatUndefinedAs],
   • V is being assigned to an attribute annotated with [TreatUndefinedAs],
   • V is being returned from a user object implementation of an operation annotated with [TreatUndefinedAs], or
   • V is being returned from a user object implementation of an attribute annotated with [TreatUndefinedAs],
   and the argument given to [TreatUndefinedAs] is either EmptyString or Null, then:
   1. If the argument given to [TreatUndefinedAs] is EmptyString, then return the DOMString? value that represents the empty string.
   2. Otherwise, the argument given to [TreatUndefinedAs] is Null. Return the null DOMString? value.
2. Otherwise, if the result of calling IsCallable(V) is false, and the conversion to an IDL value is being performed due to V being assigned to an attribute whose type is a nullable callback function that is annotated with [TreatNonCallableAsNull], then return the IDL nullable type T? value null.
3. Otherwise, if V is null or undefined, then return the IDL nullable type T? value null.
4. Otherwise, return the result of converting V to the inner IDL type T.

The result of converting an IDL nullable type value to an ECMAScript value is:

• If the IDL nullable type T? value is null, then the ECMAScript value is null.
• Otherwise, the ECMAScript value is the result of converting the IDL nullable type value to the inner IDL type T.

4.2.23. Sequences — sequence<T>

IDL sequence<T> values are represented by ECMAScript Array values.

An ECMAScript value V is converted to an IDL sequence<T> value as follows:

1. Initialize i to be 0.
2. Depending on the type of V:

   A platform array object

   1. Let length be the length of the platform array object.
   2. Initialize S_0..n−1 to be an IDL sequence with elements of type T, where each element is uninitialized.
   3. While i < n:
      1. Let E be the result of converting the platform array object element at index i to an ECMAScript value.
      2. Set S_i to the result of converting E to an IDL value of type T.
      3. Set i to i + 1.
   4. Return S.

   A native Array object

   A platform object that supports indexed properties

   1. Let A be the result of calling ToObject(V).
   2. Let length be the result of calling [[Get]] on A with property name “length”.
   3. Let n be the result of calling ToUint32(length).
   4. Initialize S_0..n−1 to be an IDL sequence with elements of type T, where each element is uninitialized.
   5. While i < n:
      1. Let P be the result of calling ToString(i).
      2. Let E be the result of calling [[Get]] on A with property name P.
      3. Set S_i to the result of converting E to an IDL value of type T.
      4. Set i to i + 1.
   6. Return S.

   Otherwise

   1. Throw a TypeError.

An IDL sequence value S_0..n−1 of type sequence<T> is converted to an ECMAScript Array object as follows:

1. Let A be a new Array object created as if by the expression [].
2. Initialize i to be 0.
3. While i < n:
   1. Let E be the result of converting S_i to an ECMAScript value.
   2. Let P be the result of calling ToString(i).
   3. Call the [[DefineOwnProperty]] internal method on A with property name P, descriptor { [[Writable]]: true, [[Enumerable]]: true, [[Configurable]]: true, [[Value]]: E } and Boolean flag false.
   4. Set i to i + 1.
4. Return A.

interface Canvas {

  sequence<DOMString> getSupportedImageCodecs();

  void drawPolygon(sequence<float> coordinates);
  sequence<float> getLastDrawnPolygon();

  // ...
};

// Obtain an instance of Canvas.  Assume that getSupportedImageCodecs()
// returns a sequence with two DOMString values: "image/png" and "image/svg+xml".
var canvas = getCanvas();

// An Array object of length 2.
var supportedImageCodecs = canvas.getSupportedImageCodecs();

// Evaluates to "image/png".
supportedImageCodecs[0];

// Each time canvas.getSupportedImageCodecs() is called, it returns a
// new Array object.  Thus modifying the returned Array will not
// affect the value returned from a subsequent call to the function.
supportedImageCodecs[0] = "image/jpeg";

// Evaluates to "image/png".
canvas.getSupportedImageCodecs()[0];

// This evaluates to false, since a new Array object is returned each call.
canvas.getSupportedImageCodecs() == canvas.getSupportedImageCodecs();


// An Array of Numbers...
var a = [0, 0, 100, 0, 50, 62.5];

// ...can be passed to a platform object expecting a sequence<float>.
canvas.drawPolygon(a);

// Each element will be converted to a float by first calling ToNumber().
// So the following call is equivalent to the previous one, except that
// "hi" will be alerted before drawPolygon() returns.
a = [false, '',
     { valueOf: function() { alert('hi'); return 100; } }, 0,
     '50', new Number(62.5)];
canvas.drawPolygon(s);

// Modifying an Array that was passed to drawPolygon() is guaranteed not to
// have an effect on the Canvas, since the Array is effectively passed by value.
a[4] = 20;
var b = canvas.getLastDrawnPolygon();
alert(b[4]);    // This would alert "50".

4.2.24. Arrays — T[]

IDL array values are represented by references to objects known as platform array objects, with particular characteristics that allow them to behave similarly to native Array objects. All platform array objects are platform objects, and thus each is associated with a particular global environment.

The value of the internal [[Prototype]] property of a platform array object MUST be the Array prototype object ([ECMA-262], section 15.4.4) from its associated global environment.

The class string of a platform array object MUST be the type name of the array type.

Platform array objects appear to have a “length” property and a property for each element of the array. The values and behaviors of these properties are implemented by the internal [[GetOwnProperty]], [[DefineOwnProperty]] and [[Delete]] methods, which are also defined below.

Platform array objects cannot be fixed; if Object.freeze, Object.seal or Object.preventExtensions is called on one, the function MUST throw a TypeError.

An ECMAScript value V is converted to an IDL array value of type T[] as follows:

• If V is a platform array object whose element type is T, then return the array that the platform array object represents.
• Let values be the result of converting V to a sequence with element type T.
• Let n be the length of values.
• Return a new fixed length array of length n whose element values are the same as those in values.

An IDL array value V of type T[] is converted to an ECMAScript value as follows:

• If V is already represented by a platform array object, then the ECMAScript value is that platform array object.
• Otherwise, the ECMAScript value is a newly created platform array object that represents V.

[Constructor]
interface LotteryResults {
  readonly attribute unsigned short[] numbers;
};

var results = new LotteryResults();  // results is a new platform object
                                     // implementing the LotteryResults interface.

var a = [4, 8, 15, 16, 23, 42];      // Numbers will be assigned into the array.
for (var i = 0; i < 6; i++) {
  results.numbers[i] = a[i];
}

results.numbers = a;                 // This has no effect, since numbers is
                                     // read only.

a[0] = 5;                            // Change the array.
results.numbers[0];                  // Evaluates to 4, since results.numbers is
                                     // not a reference to 'a'.

results.numbers[0] = 5;              // Modifies the array stored in the platform
                                     // object.
results.numbers[0];                  // Now evaluates to 5.

results.numbers[0] = 6.25;           // Assigns 6 to the first element of the array
                                     // since that is how 6.5 is converted to an
                                     // unsigned short.

results.numbers.length = 7;          // Has no effect, since numbers is
                                     // fixed length.
results.numbers[6];                  // Evaluates to undefined.

results.numbers.slice(0, 2);         // Evaluates to an Array [6, 8].

results.numbers.push(108);           // Has no effect, since the definition of
                                     // push() relies on calling [[Put]] on a
                                     // non-existent array index property
                                     // and on "length", both of which will
                                     // be silently ignored.

delete results.numbers[3];           // Has no effect and evaluates to false,
                                     // since the array index properties are
                                     // non-configurable.

[Constructor]
interface LotteryResults {
  attribute unsigned short[] numbers;
};

var results = new LotteryResults();

results.numbers.length;       // Evaluates to 6.

var a = [1, 3, 5];

results.numbers = a;          // Assigns a fixed length IDL array of length 3 to
                              // the numbers attribute.

results.numbers;              // This now evaluates to a platform array object
                              // that represents the fixed length IDL array,
                              // not the Array object assigned in the previous
                              // statement.

results.numbers == a;         // Evaluates to false.

results.numbers.length;       // Evaluates to 3.
                            
results.numbers.push(7);      // Silently ignored in non-strict mode.
results.numbers.length;       // So this still evaluates to 3.

4.2.25. Union types

IDL union type values are represented by ECMAScript values that correspond to the union’s member types.

To convert an ECMAScript value V to an IDL union type value is done as follows:

1. If the union type includes a nullable type and V is null or undefined, then return the IDL value null.
2. Let types be the flattened member types of the union type.
3. If V is a platform object, but not a platform array object, then:
   1. If types includes an interface type that V implements, then return the IDL value that is a reference to the object V.
   2. If types includes object, then return the IDL value that is a reference to the object V.
4. If V is a platform array object, a native Array object, or a platform object that supports indexed properties, then:
   1. If types includes an array type, then return the result of converting V to that type.
   2. If types includes a sequence type, then return the result of converting V to that type.
   3. If types includes object, then return the IDL value that is a reference to the object V.
5. If V is a Date object, then:
   1. If types includes Date, then return the result of converting V to Date.
   2. If types includes object, then return the IDL value that is a reference to the object V.
6. If V is any other type of object, then:
   1. If types includes a callback interface type, then return the result of converting V to that interface type.
   2. If types includes a callback function type, then return the result of converting V to that callback function type.
   3. If types includes a dictionary type, then return the result of converting V to that dictionary type.
   4. If types includes object, then return the IDL value that is a reference to the object V.
7. If types includes DOMString or an enumeration type, then return the result of converting V to that type.
8. If types includes a primitive type, then return the result of converting V to that primitive type.
9. Throw a TypeError.

An IDL union type value is converted to an ECMAScript value as follows. If the value is an object reference to a special object that represents an ECMAScript undefined value, then it is converted to the ECMAScript undefined value. Otherwise, the rules for converting the specific type of the IDL union type value as described in this section (4.2).

4.2.26. Date

IDL Date values are represented by ECMAScript Date objects.

An ECMAScript value V is converted to an IDL Date value by running the following algorithm:

1. If V is not an ECMAScript Date object, then throw a TypeError.
2. If the time value of V is NaN, then return the undefined IDL Date value.
3. Return the IDL Date value that represents the same time value as V.

An IDL Date value V is converted to an ECMAScript value by running the following the algorithm:

1. If V is the undefined Date value, then return a newly constructed ECMAScript Date object whose time value is NaN.
2. Otherwise, return a newly constructed ECMAScript Date object that represents the same millisecond as V.

Platform objects returning an ECMAScript Date object from attributes, operations or exception field do not hold on to a reference to the Date object. A script that modifies a Date object so retrieved cannot affect the platform object it was retrieved from.

4.3.1. [ArrayClass]

If the [ArrayClass] extended attribute appears on an interface that is not defined to inherit from another, it indicates that the internal [[Prototype]] property of its interface prototype object will be the Array prototype object rather than the Object prototype object. This allows Array methods to be used more easily with objects implementing the interface.

The [ArrayClass] extended attribute MUST take no arguments. It MUST NOT be used on an interface that has any inherited interfaces.

See section 4.4.3 for the specific requirements that the use of [ArrayClass] entails.

[ArrayClass]
interface ItemList {
  attribute unsigned long length;
  getter object getItem(unsigned long index);
  creator setter object setItem(unsigned long index, object item);
  deleter void removeItem(unsigned long index);
};

[ArrayClass]
interface ImmutableItemList {
  readonly attribute unsigned long length;
  getter object getItem(unsigned long index);
};

var list = getItemList();  // Obtain an instance of ItemList.

list.concat();             // Clone the ItemList into an Array.
list.pop();                // Remove an item from the ItemList.
list.unshift({ });         // Insert an item at index 0.

4.3.2. [Clamp]

If the [Clamp] extended attribute appears on an operation argument, writable attribute or dictionary member whose type is one of the integer types, it indicates that when an ECMAScript Number is converted to the IDL type, out of range values will be clamped to the range of valid values, rather than using the operators that use a modulo operation (ToInt32, ToUint32, etc.).

The [Clamp] extended attribute MUST take no arguments.

The [Clamp] extended attribute MUST NOT appear on a read only attribute, or an attribute, operation argument or dictionary member that is not of an integer type. It also MUST NOT be used in conjunction with the [EnforceRange] extended attribute.

See the rules for converting ECMAScript values to the various IDL integer types in section 4.2 for the specific requirements that the use of [Clamp] entails.

interface GraphicsContext {
  void setColor(octet red, octet green, octet blue);
  void setColorClamped([Clamp] octet red, [Clamp] octet green, [Clamp] octet blue);
};

// Get an instance of GraphicsContext.
var context = getGraphicsContext();

// Calling the non-[Clamp] version uses ToUint8 to coerce the Numbers to octets.
// This is equivalent to calling setColor(255, 255, 1).
context.setColor(-1, 255, 257);

// Call setColorClamped with some out of range values.
// This is equivalent to calling setColorClamped(0, 255, 255).
context.setColorClamped(-1, 255, 257);

4.3.3. [Constructor]

If the [Constructor] extended attribute appears on an interface, it indicates that the interface object for this interface will have an [[Construct]] internal method, allowing objects implementing the interface to be constructed. Multiple [Constructor] extended attributes may appear on a given interface.

The [Constructor] extended attribute MUST either take no arguments or take an argument list. The bare form, [Constructor], has the same meaning as using an empty argument list, [Constructor()]. For each [Constructor] extended attribute on the interface, there will be a way to construct an object that implements the interface by passing the specified arguments.

If the [Constructor] extended attribute is specified on an interface, then the [NoInterfaceObject] extended attribute MUST NOT also be specified on that interface.

The [Constructor] extended attribute MUST NOT be used on a callback interface.

See section 4.4.1.1 below for details on how a constructor is to be implemented.

interface NodeList {
  Node item(unsigned long index);
  readonly attribute unsigned long length;
};

[Constructor,
 Constructor(float radius)]
interface Circle {
  attribute float r;
  attribute float cx;
  attribute float cy;
  readonly attribute float circumference;
};

var x = new Circle();      // The uses the zero-argument constructor to create a
                           // reference to a platform object that implements the
                           // Circle interface.

var y = new Circle(1.25);  // This also creates a Circle object, this time using
                           // the one-argument constructor.

var z = new NodeList();    // This would throw a TypeError, since no
                           // [Constructor] is declared.

4.3.4. [EnforceRange]

If the [EnforceRange] extended attribute appears on an operation argument, writable attribute or dictionary member whose type is one of the integer types, it indicates that when an ECMAScript Number is converted to the IDL type, out of range values will cause an exception to be thrown, rather than converted to being a valid value using the operators that use a modulo operation (ToInt32, ToUint32, etc.). The Number will be rounded towards zero before being checked against its range.

The [EnforceRange] extended attribute MUST take no arguments.

The [EnforceRange] extended attribute MUST NOT appear on a read only attribute, or an attribute, operation argument or dictionary member that is not of an integer type. It also MUST NOT be used in conjunction with the [Clamp] extended attribute.

See the rules for converting ECMAScript values to the various IDL integer types in section 4.2 for the specific requirements that the use of [EnforceRange] entails.

interface GraphicsContext {
  void setColor(octet red, octet green, octet blue);
  void setColorEnforcedRange([EnforceRange] octet red, [EnforceRange] octet green, [EnforceRange] octet blue);
};

// Get an instance of GraphicsContext.
var context = getGraphicsContext();

// Calling the non-[EnforceRange] version uses ToUint8 to coerce the Numbers to octets.
// This is equivalent to calling setColor(255, 255, 1).
context.setColor(-1, 255, 257);

// When setColorEnforcedRange is called, Numbers are rounded towards zero.
// This is equivalent to calling setColor(0, 255, 255).
context.setColorEnforcedRange(-0.9, 255, 255.2);

// The following will cause a TypeError to be thrown, since even after
// rounding the first and third argument values are out of range.
context.setColorEnforcedRange(-1, 255, 256);

4.3.5. [ImplicitThis]

If the [ImplicitThis] extended attribute appears on an interface, it indicates that when a Function corresponding to one of the interface’s operations is invoked with the null or undefined value as the this value, that the ECMAScript global object will be used as the this value instead. This is regardless of whether the calling code is in strict mode.

The [ImplicitThis] extended attribute MUST take no arguments.

See section 4.4.7 for the specific requirements that the use of [ImplicitThis] entails.

[ImplicitThis]
interface Window {
  ...
  attribute DOMString name;
  void alert(DOMString message);
};

"use strict";

window.alert("hello");      // Calling alert with an explicit window object works.
alert("hello");             // This also works, even though we are in strict mode.
alert.call(null, "hello");  // As does passing null explicitly as the this value.

// This does not apply to getters for attributes on the interface, though.
// The following will throw a TypeError.
Object.getOwnPropertyDescriptor(Window.prototype, "name").get.call(null);

4.3.6. [LenientThis]

If the [LenientThis] extended attribute appears on an attribute, it indicates that invocations of the attribute’s getter or setter with a this value that is not an object that implements the interface on which the attribute appears will be ignored.

The [LenientThis] extended attribute MUST take no arguments.

See the Attributes section below for how [LenientThis] is to be implemented.

interface Example {
  [LenientThis] attribute DOMString x;
  attribute DOMString y;
};

var example = getExample();  // Get an instance of Example.
var obj = { };

// Fine.
example.x;

// Ignored, since the this value is not an Example object and [LenientThis] is used.
Object.getOwnPropertyDescriptor(Example.prototype, "x").get.call(obj);

// Also ignored, since Example.prototype is not an Example object and [LenientThis] is used.
Example.prototype.x;

// Throws a TypeError, since Example.prototype is not an Example object.
Example.prototype.y;

4.3.7. [NamedConstructor]

If the [NamedConstructor] extended attribute appears on an interface, it indicates that the ECMAScript global object will have a property with the specified name whose value is a constructor function that can create objects that implement the interface. Multiple [NamedConstructor] extended attributes may appear on a given interface.

The [NamedConstructor] extended attribute MUST either take an identifier or take a named argument list. The first form, [NamedConstructor=identifier], has the same meaning as using an empty argument list, [NamedConstructor=identifier()]. For each [NamedConstructor] extended attribute on the interface, there will be a way to construct an object that implements the interface by passing the specified arguments to the constructor function that is the value of the aforementioned property.

The identifier used for the named constructor MUST NOT be the same as that used by an [NamedConstructor] extended attribute on another interface, MUST NOT be the same as an identifier of an interface (or exception) that has an interface object (or exception interface object), and MUST NOT be one of the reserved identifiers.

The [Constructor] extended attribute MUST NOT be used on a callback interface.

See section 4.4.2 below for details on how named constructors are to be implemented.

[NamedConstructor=Audio,
 NamedConstructor=Audio(DOMString src)]
interface HTMLAudioElement : HTMLMediaElement {
  // ...
};

typeof Audio;                   // Evaluates to 'function'.

var a1 = new Audio();           // Creates a new object that implements
                                // HTMLAudioElement, using the zero-argument
                                // constructor.

var a2 = new Audio('a.flac');   // Creates an HTMLAudioElement using the
                                // one-argument constructor.

4.3.8. [NoInterfaceObject]

If the [NoInterfaceObject] extended attribute appears on an interface, it indicates that an interface object will not exist for the interface in the ECMAScript binding. Similarly, if it appears on an exception it indicates that an exception interface object will not exist for the exception in the ECMAScript binding.

The [NoInterfaceObject] extended attribute MUST take no arguments.

If the [NoInterfaceObject] extended attribute is specified on an interface, then the [Constructor] extended attribute MUST NOT also be specified on that interface. A [NamedConstructor] extended attribute is fine, however.

The [NoInterfaceObject] extended attribute MUST NOT be specified on an interface that has any static operations defined on it.

The [NoInterfaceObject] extended attribute MUST NOT be specified on a callback interface, as interface objects never exist for callback interfaces.

See section 4.2.18 and section 4.9 for the specific requirements that the use of [NoInterfaceObject] entails.

interface Storage {
  void addEntry(unsigned long key, any value);
};

[NoInterfaceObject]
interface Query {
  any lookupEntry(unsigned long key);
};

typeof Storage;                        // evaluates to "object"

// Add some tracing alert() call to Storage.addEntry.
var fn = Storage.prototype.addEntry;
Storage.prototype.addEntry = function(key, value) {
  alert('Calling addEntry()');
  return fn.call(this, key, value);
};

typeof Query;                          // evaluates to "undefined"
var fn = Query.prototype.lookupEntry;  // exception, Query isn’t defined

4.3.9. [OverrideBuiltins]

If the [OverrideBuiltins] extended attribute appears on an interface, it indicates that for a platform object implementing the interface, properties corresponding to all of the object’s supported property names will appear to be on the object, regardless of what other properties exist on the object or its prototype chain. This means that named properties will always shadow any properties that would otherwise appear on the object. This is in contrast to the usual behavior, which is for named properties to be exposed only if there is no property with the same name on the object itself or somewhere on its prototype chain.

The [OverrideBuiltins] extended attribute MUST take no arguments and MUST NOT appear on an interface that does not define a named property getter or that also is declared with the [NamedPropertiesObject] extended attribute. If the extended attribute is specified on a partial interface definition, then that partial interface definition MUST be the part of the interface definition that defines the named property getter.

See section 4.6.1 and section 4.6.3 for the specific requirements that the use of [OverrideBuiltins] entails.

interface StringMap {
  readonly attribute unsigned long length;
  getter DOMString lookup(DOMString key);
};

[OverrideBuiltins]
interface StringMap2 {
  readonly attribute unsigned long length;
  getter DOMString lookup(DOMString key);
};

// Obtain an instance of StringMap.  Assume that it has "abc", "length" and
// "toString" as supported property names.
var map1 = getStringMap();  

// This invokes the named property getter.
map1.abc;

// This fetches the "length" property on the object that corresponds to the
// length attribute.
map1.length;

// This fetches the "toString" property from the object's prototype chain.
map1.toString;


// Obtain an instance of StringMap2.  Assume that it also has "abc", "length"
// and "toString" as supported property names.
var map2 = getStringMap2();  

// This invokes the named property getter.
map2.abc;

// This also invokes the named property getter, despite the fact that the "length"
// property on the object corresponds to the length attribute.
map2.length;

// This too invokes the named property getter, despite the fact that "toString" is
// a property in map2's prototype chain.
map2.toString;

4.3.10. [PutForwards]

If the [PutForwards] extended attribute appears on a read only attribute declaration whose type is an interface type, it indicates that assigning to the attribute will have specific behavior. Namely, the assignment is “forwarded” to the attribute (specified by the extended attribute argument) on the object that is currently referenced by the attribute being assigned to.

The [PutForwards] extended attribute MUST take an identifier. Assuming that:

• A is the attribute on which the [PutForwards] extended attribute appears,
• I is the interface on which A is declared,
• J is the interface type that A is declared to be of, and
• N is the identifier argument of the extended attribute,

then there MUST be another attribute B declared on J whose identifier is N. Assignment of a value to the attribute A on an object implementing I will result in that value being assigned to attribute B of the object that A references, instead.

Note that [PutForwards]-annotated attributes can be chained. That is, an attribute with the [PutForwards] extended attribute can refer to an attribute that itself has that extended attribute. There MUST NOT exist a cycle in a chain of forwarded assignments. A cycle exists if, when following the chain of forwarded assignments, a particular attribute on an interface is encountered more than once.

An attribute with the [PutForwards] extended attribute MUST NOT also be declared with the [Replaceable] extended attribute.

The [PutForwards] extended attribute MUST NOT be used on an attribute declared on a callback interface.

See the Attributes section below for how [PutForwards] is to be implemented.