Web IDL

3.3.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 ConstExpr part of a constant declaration (or dictionary member declaration) gives the value of the constant (or the default value of the dictionary member), which can be one of the two boolean literal tokens (true and false), the null token, an integer token, a float token or a string token.

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, parsed in a manner common to many programming languages, as follows:

1. Let S be the string value of 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 CAPTIAL LETTER X ("X")

   U+0030 DIGIT ZERO ("0"), U+0058 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 or dictionary member 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.9 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 or dictionary member it is being used as the value for, determined as follows:

1. Let S be the string value of 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, 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, and the value of the float token is the IEEE 754 double-precision floating point number closest to result. [IEEE-754]

It is not possible to specify an infinite or Not-a-Number float constant or dictionary member default value.

The type of a float token is the same as the type of the constant or dictionary member 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.9 below.

The value of a string token is a DOMString, determined as follows:

1. Let S be the string value of 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 corresponding to the UTF-16 encoding of S.

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 or dictionary member 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 or dictionary member 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.

No extended attributes 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 Error {
  const short ERR_UNKNOWN = 0;
  const short ERR_OUT_OF_MEMORY = 1;

  short errorCode;
};

3.3.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 an attribute 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 AttributeType) that appears after the attribute keyword. This allows for any type except sequence types. If the AttributeType is a scoped name, then it MUST resolve to an interface or typedef.

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 inherits getter after the attribute’s identifier. 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 inherits getter MUST NOT appear on a read only attribute.

interface Ancestor {
  readonly attribute TheType theIdentifier;
};

interface Derived : Ancestor {
  attribute TheType theIdentifier inherits getter;
};

The GetRaises and SetRaises clauses are used to declare the possible exceptions that can be thrown when retrieving the value of and assigning a value to the attribute, respectively. Each scoped name in the GetRaises and SetRaises clauses MUST resolve to an exception.

attribute type identifier getraises(scoped-name, …);
attribute type identifier setraises(scoped-name, …);
attribute type identifier getraises(scoped-name, …) setraises(scoped-name, …);
attribute type identifier inherits getter setraises(scoped-name, …);

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.3.4.2 below for details.

stringifier attribute DOMString identifier;

If an implementation attempts to get or set the value of an attribute on an object implemented by user code (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], [PutForwards], [Replaceable], [TreatNullAs], [TreatUndefinedAs], [Unforgeable].

exception InvalidName {
  DOMString reason;
};

exception NoSuchPet { };

interface Animal {

  // A simple attribute that can be set to any string value.
  readonly attribute DOMString name;
};

interface Person : Animal {

  // An attribute whose value cannot be assigned to.
  readonly attribute unsigned short age;

  // An attribute that can raise an exception if it is set to an invalid value.
  // Its getter behavior is inherited from Animal, and need not be specified
  // in the description of Person.
  attribute DOMString name inherits getter setraises (InvalidName);

  // An attribute whose value cannot be assigned to, and which can raise an
  // exception in some circumstances.
  readonly attribute DOMString petName getraises (NoSuchPet);
};

3.3.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.3.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 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 a scoped name, then it MUST resolve to an interface, dictionary 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 (given by an identifier token). If the Type is a scoped name, then it MUST resolve to an interface, dictionary or typedef.

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

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] in type identifier, [extended-attributes] in type identifier, …);

The in keyword used in the declaration of each argument is optional. No other types of arguments (such as out or in-out arguments) can be specified with Web IDL.

interface Dimensions {
  attribute unsigned long width;
  attribute unsigned long height;
};

exception NoPointerDevice { };

interface Button {

  // An operation that takes no arguments, returns a boolean, and could possibly
  // raise an exception.
  boolean isMouseOver() raises (NoPointerDevice);

  // Overloaded operations.
  void setDimensions(in Dimensions size);
  void setDimensions(in unsigned long width, in unsigned long height);
};

An operation is considered to be a variadic operation 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(in type... identifier);
return-type identifier(in type identifier, in type... identifier);

interface IntegerSet {
  readonly attribute unsigned long cardinality;

  void union(in long... ints);
  void intersection(in 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 an the argument value can be omitted when the operation is invoked. An argument MUST NOT be declared to be optional unless any subsequent arguments to the operation are also optional.

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

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

interface ColorCreator {

  object createColor(in float v1, in float v2, in float v3);
  object createColor(in float v1, in float v2, in float v3, in float alpha);
};

A raises clause (matching Raises) is used to declare the possible exceptions that can be thrown when invoking the operation. Each scoped name in the Raises clause MUST resolve to an exception.

return-type identifier(arguments…) raises(scoped-name, …);

If an implementation attempts to invoke an operation on an object implemented by user code (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 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: [AllowAny], [Clamp], [TreatNullAs], [TreatUndefinedAs].

3.3.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 keywords in an operation declaration.

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

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

interface Dictionary {
  readonly attribute unsigned long propertyCount;

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

Special operations can be declared using an operation that has an identifier and the omittable keyword to indicate that in language bindings that do not support that kind of special operation, the regular operation is to be available on the object for use instead. Such operations are known as omittable.

interface Dictionary {
  readonly attribute unsigned long propertyCount;

  omittable getter float getProperty(in DOMString propertyName);
  omittable setter void setProperty(in DOMString propertyName, in float propertyValue);
};

public interface Dictionary {

  long getPropertyCount();
  float getProperty(String propertyName);
  void setProperty(String propertyName, float propertyValue);
}

var dictionary = getDictionary();  // Get an instance of Dictionary.

dictionary.getProperty;            // Actually invokes the property getter with property name "getProperty".
dictionary.x = 1;                  // Invokes the property setter with property name "x" and value 1.

Defining a special operation without using the omittable keyword on an operation but giving the operation an identifier is equivalent to separating the special operation out into its own declaration without an identifier. This approach is admitted to simplify prose descriptions of an interface’s operations.

interface Dictionary {
  readonly attribute unsigned long propertyCount;

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

interface Dictionary {
  readonly attribute unsigned long propertyCount;

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

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

The omittable keyword MUST NOT appear on an operation that has no identifier.

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 name getters, name setters, name creators and name deleters, and ones that take an unsigned long as a property index, known as index getters, index setters, index creators and index deleters. See section 3.3.4.3 and section 3.3.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 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.

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.

caller return-type identifier(arguments…);
caller return-type (arguments…);
omittable caller return-type identifier(arguments…);

interface NumberQuadrupler {
  // This operation simply returns four times the given number x.
  caller float compute(in 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 ();
omittable stringifier DOMString identifier();

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(in unsigned long identifier);
setter type identifier(in unsigned long identifier, in type identifier);
creator type identifier(in unsigned long identifier, in type identifier);
deleter type identifier(in unsigned long identifier);

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

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

interface OrderedMap {
  readonly attribute unsigned long size;

  getter any getByIndex(in unsigned long index);
  setter void setByIndex(in unsigned long index, in any value);
  deleter void removeByIndex(in unsigned long index);

  getter any get(in DOMString name);
  setter creator void set(in DOMString name, in any value);
  deleter void remove(in 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 index 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(in DOMString identifier);
setter type identifier(in DOMString identifier, in type identifier);
creator type identifier(in DOMString identifier, in type identifier);
deleter type identifier(in DOMString identifier);

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

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

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

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

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

  static Point triangulate(in Circle c1, in Circle c2, in 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]);

Circle[] circles = getCircles();  // an array of Circle objects

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

3.3.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 callers defined on it, then those 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, callers and constructors can be specified to take, and in order to describe these restrictions, the notion of an effective overload set is used.

An effective overload set for a given identifier, argument count, interface and target language binding represents the allowable invocations in that language binding of operations or constructors (specified with [Constructor] and [NamedConstructor]) that have the specified identifier on that interface. The set is used to determine whether there are ambiguities in the overloaded operations or constructors specified on the interface. The effective overload set is stated to be “for regular operations”, “for static operations”, “for constructors” or “for callers”, to distinguish between these four uses. Effective overload sets for callers do not use an identifier; only an argument count, interface and target language binding are needed.

The elements of an effective overload set are triples of the form <f, types, any>. If the effective overload set is for regular operations, static operations or callers, then f is an operation, and if it is for constructors, then f is an extended attribute. In either case, types is a list of IDL types and any is a list of boolean values. Each triple represents an allowable invocation of the operation, constructor or caller with an argument value list of the given types. any specifies whether a particular argument has been annotated with the [AllowAny] extended attribute. 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 effective overload set for identifier A, argument count N, interface I and a given target language binding is derived as follows. 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 [NamedConstructor] extended attributes on interface I whose named argument lists’ identifiers are A. If A is the same as the identifier of interface I, then F also includes the [Constructor] extended attributes on I.

   For callers

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

3. If the effective overload set is for regular operations, then:
   1. If the target language binding supports object indexing, then remove from F any operation that is declared to be an omittable getter, setter, creator or deleter.
   2. If the target language binding supports object calling, then remove from F any operation that is declared to be an omittable caller.
   3. If the target language binding supports object stringification, then remove from F any operation that is declared to be an omittable stringifier.
4. Let maxarg be the maximum number of arguments the operations or constructor extended attributes in F are declared to take.
5. Let m be the maximum of maxarg and N.
6. For each operation or extended attribute 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. Let a_0..n−1 be boolean values indicating whether each argument X is defined to take is declared with the [AllowAny] extended attribute.
   4. Add to S the triple <X, t_0..n−1, a_0..n−1>.
   5. If n > 0 and X is declared to be variadic, then:
      1. Add to S the triple <X, t_0..n−2, a_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. Let b_0..i be a list of booleans, where b_j = a_j (for j < n) and b_j = a_n−1 (for j ≥ n).
         3. Add to S the triple <X, u_0..i, b_0..i>.
   6. For every integer i, such that 0 < i < n:
      1. If argument i of X is optional, then add to S the triple <X, t_0..i−1, a_0..i−1>.
   7. If n > 0 and the first argument of X is optional, then add to S the triple <X, (), ()> (where “()” represents the empty list).
7. The effective overload set for identifier A and interface X is S.

For each pair of entries in an effective overload set at least one of the following MUST be true:

• the type list lengths of the two entries are different, or
• there is an index i such that the types in the two type lists at index i are distinguishable.

Two types are distinguishable if there is a “●” mark in the corresponding entry in the following table:

• [1] Two interface types are distinguishable only if two different interfaces are identified.

interface A {
  // ...
};

interface B {
  // ...
};

interface C {
  void f(in A? x);
  void f(in B? x);
};

interface A {
  /* f1 */ void f(in DOMString a);
  /* f2 */ void f([AllowAny] in DOMString a, in DOMString b, in float... c);
  /* f3 */ void f();
  /* f4 */ void f(in long a, in DOMString b, in optional DOMString c, in float... d);
};

3.9.1. any

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

3.9.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.9.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.9.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.9.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.9.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.9.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.9.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.9.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.9.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.9.11. float

The float type is a floating point numeric type that corresponds to the set of possible 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.9.12. double

The double type is a floating point numeric type that corresponds to the set of possible 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.9.13. DOMString

The DOMString type corresponds to the set of all possible sequences of 16 bit unsigned integer code units (to be interpreted as UTF-16 encoded strings [RFC2781]). 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. Authors of specifications using Web IDL might want to obtain a sequence of Unicode characters given a particular sequence of 16 bit unsigned integer code units, however. 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.

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

3.9.14. object

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

There is no way to represent an object constant 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.9.15. Interface types

A scoped name that resolves to 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 value for interface types 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.9.16. Dictionary types

A scoped name that resolves to 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 value for dictionary types in IDL.

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

3.9.17. 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, 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.9.18. 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 sequence constant 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.9.19. Arrays — T[]

The T[] type is a parameterized type whose values are non-null references to (possibly zero-length) 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 an array constant value in IDL.

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

3.9.20. 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 seconds, which cannot be represented with 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 Date constant value in IDL.

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

3.10.1. [Callback]

If the [Callback] extended attribute appears on an interface, it indicates that user objects can implement the interface. As described in section 3.8 above, user objects will only be considered to implement a given interface if the interface is annotated with [Callback]. User objects implementing an interface are most often used to provide callback methods to a platform object, hence the name of this extended attribute.

The [Callback] extended attribute MUST either take no argument or take an identifier. The identifier, if present, is used only by the ECMAScript language binding, to control exactly which kinds of objects can be considered to implement a [Callback]-annotated interface. See section 4.3.2 below for details.

The [Callback] extended attribute MUST NOT be used on an interface that does not meet the criteria for an interface that can implemented by user objects, as described in section 3.8 above.

interface Node {
  readonly attribute DOMString nodeName;
  readonly attribute Node? parentNode;
  Node appendChild(in Node newChild);
  void addEventListener(in DOMString type, in EventListener listener);
};

[Callback]
interface EventListener {
  void handleEvent(in Event event);
};

var node = getNode();  // Obtain an instance of Node.

var listener = {
  handleEvent: function(event) {
    ...
  }
};
node.addEventListener("click", listener);

var node = getNode();  // Obtain an instance of Node.

var newNode = {
  nodeName: "span",
  parentNode: null,
  appendChild: function(newchild) {
    ...
  },
  addEventListener: function(type, listener) {
    ...
  }
};
node.appendChild(newNode);  // This will throw a TypeError exception.

3.10.2. [Prefix]

If the [Prefix] extended attribute appears on a module, it affects the name of the language binding specific namespacing construct the module will correspond to. See the definition of a module’s prefixed name for details.

The [Prefix] extended attribute MUST take a scoped name.

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.13, 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.14, 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 value 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

IDL boolean values are represented by ECMAScript Boolean values.

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 is the one that represents the same truth value as the ECMAScript Boolean value x.

The result of converting an IDL boolean value to an ECMAScript value is a Boolean that represents the same truth value as the IDL boolean value.

4.2.4. byte

IDL byte values are represented by integer ECMAScript Number values in the range [−128, 127].

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

1. Initialize x to ToNumber(V).
2. 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 set x to min(max(x, −2⁷), 2⁷ − 1).
3. If x is NaN, +0, −0, +∞, or −∞, then return the IDL octet value that represents 0.
4. Set x to sign(x) * floor(abs(x)).
5. Set x to x modulo 2⁸.
6. 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.

4.2.5. octet

IDL octet values are represented by integer ECMAScript Number values in the range [0, 255].

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

1. Initialize x to ToNumber(V).
2. 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 set x to min(max(x, 0), 2⁸ − 1).
3. If x is NaN, +0, −0, +∞, or −∞, then return the IDL octet value that represents 0.
4. Set x to sign(x) * floor(abs(x)).
5. Set x to x modulo 2⁸.
6. 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.

4.2.6. short

IDL short values are represented by integer ECMAScript Number values in the range [−32768, 32767].

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

1. Initialize x to ToNumber(V).
2. 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 set x to min(max(x, −2¹⁵), 2¹⁵ − 1).
3. If x is NaN, +0, −0, +∞, or −∞, then return the IDL short value that represents 0.
4. Set x to sign(x) * floor(abs(x)).
5. Set x to x modulo 2¹⁶.
6. 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.

4.2.7. unsigned short

IDL unsigned short values are represented by integer ECMAScript Number values in the range [0, 65535].

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 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 set x to min(max(x, 0), 2¹⁶ − 1).
3. Set x to ToUint16(x).
4. 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.

4.2.8. long

IDL long values are represented by integer ECMAScript Number values in the range [−2147483648, 2147483647].

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

1. Initialize x to ToNumber(V).
2. 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 set x to min(max(x, −2³¹), 2³¹ − 1).
3. Set x to ToInt32(x).
4. 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.

4.2.9. unsigned long

IDL unsigned long values are represented by integer ECMAScript Number values in the range [0, 4294967295].

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 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 set x to min(max(x, 0), 2³² − 1).
3. Set x to ToUint32(x).
4. 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.

4.2.10. long long

IDL long long values are represented by ECMAScript Number values.

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 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 set x to min(max(x, −2⁶³), 2⁶³ − 1).
3. If x is NaN, +0, −0, +∞, or −∞, then return the IDL long long value that represents 0.
4. Set x to sign(x) * floor(abs(x)).
5. Set x to x modulo 2⁶⁴.
6. If x is greater than or equal to 2⁶³, return the IDL long long value that represents the same numeric value as x − 2⁶⁴. Otherwise, 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. 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

IDL unsigned long long values are represented by ECMAScript Number values.

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 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 set x to min(max(x, 0), 2⁶⁴ − 1).
3. If x is NaN, +0, −0, +∞, or −∞, then return the IDL unsigned long long value that represents 0.
4. Set x to sign(x) * floor(abs(x)).
5. Set x to x modulo 2⁶⁴.
6. 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 to 2⁵³ − 1, then the Number will be able to represent exactly the same value as the unsigned long long.

4.2.12. float

IDL float values are represented by ECMAScript Number values.

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, then return the IDL 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 float value to an ECMAScript value is a Number:

• If the IDL 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 float value.

4.2.13. double

IDL double values are represented by ECMAScript Number values.

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, then return the IDL float value that represents the IEEE 754 NaN value with the bit pattern 0x7ff8000000000000 [IEEE-754].
3. Let S be the set of finite IEEE 754 double-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 double value to an ECMAScript value is a Number:

• If the IDL 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 double value.

4.2.14. DOMString

IDL DOMString values are represented by ECMAScript String values.

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 characters 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 16 bit code units that the IDL DOMString represents.

4.2.15. 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. Let x be the result of calling ToObject(V).
2. Return the IDL object value that is a reference to the same object as x.

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.16. Interface types

IDL interface type values are represented by ECMAScript Object values.

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

1. Let x be the result of calling ToObject(V).
2. If x is a platform object that implements I, then return the IDL interface type value that represents a reference to that platform object.
3. If x is a user object that is considered to implement I according to the rules in section 4.8, 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.17. 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. Let dict be an empty dictionary value of type D; every dictionary member is initially considered to be not present.
2. Let object be the result of calling ToObject(V).
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 object with property name key.
      3. If present is true, then:
         1. Let value be the result of calling the [[Get]] internal method on object 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 [[Put]] internal method on O with arguments key, value and false.
4. Return O.

4.2.18. 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 and the IDL type being converted to is DOMString?, then:
   1. If 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],
      • 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],
      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 V is null or undefined, then return the IDL nullable type T? value null.
3. 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 IDL nullable type value is the result of converting the ECMAScript value to the inner IDL type T.

4.2.19. 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. If V is null or undefined, then return a sequence of length zero.
2. Let A be the result of calling ToObject(V).
3. Let length be the result of calling [[Get]] on A with property name length.
4. Let n be the result of calling ToUint32(length).
5. Initialize S_0..n−1 to be an IDL sequence with elements of type T, where each element is uninitialized.
6. Initialize i to be 0.
7. 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.
8. Return S.

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 [[Put]] on A with property name P and value E.
   4. Set i to i + 1.
4. Return A.

interface Canvas {

  sequence<DOMString> getSupportedImageCodecs();

  void drawPolygon(in sequence<float> coordinates);

  // ...
};

// 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.
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.
canvas.drawPolygon
  ([false, '',
    { valueOf: function() { alert('hi'); return 100 } }, 0,
    '50', new Number(62.5)]);

// 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[0] = 20;

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

The value of the internal [[Prototype]] property of an platform array object MUST be the Array prototype object ([ECMA-262], section 15.4.4).

The value of the internal [[Class]] property of an 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 defy being 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:

• Let O be the result of calling ToObject(V).
• If O is an platform array object, then the IDL array value is the array value that the platform array object represents.
• Otherwise, the IDL array value is determined as follows:
  1. Initialize n to be the result of calling [[Get]] on V with property name “length”.
  2. Set n to ToUint32(n).
  3. Initialize E_0..n to be a list of IDL values.
  4. Initialize i to be 0.
  5. While i < n:
     1. Let x be the result of calling [[Get]] on V with property name ToString(i).
     2. Set E_i to be the result of converting x to an IDL value of type T.
     3. Set i to i + 1.
  6. The IDL array value is a fixed length array of length n whose values are E_0..n.

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

• If V is already represented by an 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 can 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 [4, 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 an platform array object
                              // that represents the fixed length IDL array,
                              // not the Array object assigned in the previous
                              // statement.

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

4.2.21. 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. Let D be the result of calling ToObject(V).
2. If D is not an ECMAScript Date object, then throw a TypeError.
3. If the time value of D is NaN, then return the undefined IDL Date value.
4. Return the IDL Date value that represents the same millisecond as D.

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. Script that modifies a Date object so returned cannot affect the platform object it was returned from.

4.3.1. [AllowAny]

If the [AllowAny] extended attribute appears on an operation argument, it indicates that any ECMAScript value will be accepted as that argument’s value. Normally, as part of the overload resolution algorithm, a non-DOMString value will disqualify a given overloaded operation that is declared to take a DOMString for a given argument. When the [AllowAny] extended attribute is present on the argument, that disqualification is not performed.

The [AllowAny] extended attribute MUST take no argument.

interface A {
  void f();
  void f(in A a);
  void f(in DOMString s);
};

interface B {
  void g();
  void g(in B b);
  void g([AllowAny] in DOMString s);
};

var a = getA();  // Obtain an instance of A.
var b = getB();  // Obtain an instance of B.

a.f(1.23);       // Throws a TypeError.
b.g(1.23);       // Equivalent to b.g("1.23").
b.g(a);          // Equivalent to calling b.g with ToString(a).

4.3.2. [Callback]

As described in section 3.10.1 above, the [Callback] extended attribute is used to indicate that an interface can be implemented by a user object. In the ECMAScript language binding, the identifier argument of [Callback], or the lack of one, is used to control which kinds of ECMAScript objects can be used as user object implementations of the interface, as follows:

• If the extended attribute was specified as [Callback] (with no identifier argument) or as [Callback=PropertyOnly], then any native ECMAScript object is considered to be a user object implementation of the interface.
• Otherwise, if it was specified as [Callback=FunctionOnly], then only Function objects are considered to be user object implementations of the interface.

[Callback=FunctionOnly] MUST NOT be specified on an interface that is not a single operation interface, which is an interface that:

• is not declared to inherit from another interface,
• has no consequential interfaces,
• has no attributes, and
• has one or more regular operations that all have the same identifier, and no others.

Section 4.8 below details how native ECMAScript objects are used as user objects implementing an interface and exactly how [Callback] influences this.

[Callback]
interface Listener {
  void eventOccurred();
};

interface Thing {
  void addListener(in Listener listener);
};

// Obtain an instance of Thing.
var t = getThing();

// The function is the implementation of the eventOccurred operation on the
// Listener interface.  If Listener had been declared with
// [Callback=PropertyOnly] this addListener() call would still succeed, but
// a TypeError would be thrown when the user agent attempts to invoke the
// callback.
t.addListener(function() { });

// This also works, but it is the function with /* 1 */ in it that is the
// implementation of eventOccurred.
var x = function() { /* 1 */ };
x.eventOccurred = function() { /* 2 */ };
t.addListener(x);

// This works too, and the value of the eventOccurred property is the
// implementation of the operation.  If Listener had been declared with
// [Callback=FunctionOnly] however, this would have thrown a TypeError.
t.addListener({ eventOccurred: function() { } });

4.3.3. [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 (ToInt16, ToInt32, ToUint32, etc.).

The [Clamp] extended attribute MUST take no argument.

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.

interface GraphicsContext {
  void setColor(in octet red, in octet green, in octet blue);
  void setColorClamped([Clamp] in octet red, [Clamp] in octet green, [Clamp] in 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.4. [CopyInheritedPrototype]

If the [CopyInheritedPrototype] extended attribute appears on an interface, it indicates that the interface prototype object for this interface will have a copy of all of the properties that correspond to the constants, attributes and operations from the interface it inherits from. The prototype chain of objects that implement the [CopyInheritedPrototype]-annotated interface will not include the inherited interface’s interface prototype object.

The [CopyInheritedPrototype] extended attribute MUST take no argument. It MUST NOT appear on an interface that is not defined to inherit from another interface, or one that is defined to inherit from another interface which itself has an interface with the [CopyInheritedPrototype] extended attribute in its inheritance chain. The extended attribute also MUST NOT appear on an interface if any of its interface members have the same identifier as an interface member on the inherited interface.

4.3.5. [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 argument 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.

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

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

[Constructor,
 Constructor(in 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.6. [NamedConstructor]

If the [NamedConstructor] extended attribute appears on an interface, it indicates that the relevant namespace object for the interface (often, 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, and it MUST NOT be the same as an identifier of an interface (or exception) that has an interface object (or exception interface object).

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

[NamedConstructor=Audio,
 NamedConstructor=Audio(in 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.7. [NamespaceObject]

If the [NamespaceObject] extended attribute appears on a module, it indicates that the hierarchy of that module and its descendant modules will be reflected as namespace objects. Interface objects and exception interface objects for interfaces and exceptions defined in a module annotated with [NamespaceObject] (or in a descendant of such a module) will be placed on a namespace object instead of the ECMAScript global object.

The [NamespaceObject] extended attribute MUST take no argument.

The [NamespaceObject] extended attribute MUST NOT be specified on a module if is specified on one of its ancestor modules.

[NamespaceObject]
module acme {
  
  exception DeviceException { };

  module pim {

    [Constructor]
    interface Contact { };

    [Constructor,
     NamedConstructor=RecurringEvent(in long freq)]
    interface CalendarEvent { };
  };
};

acme;                             // A namespace object.
acme.pim;                         // Another namespace object.

acme.DeviceException;             // An exception interface object.
acme.pim.Contact;                 // An interface object.

new acme.pim.Contact();           // Creates an object implementing acme::pim::Contact.
new acme.pim.RecurringEvent(10);  // Creates an object implementing acme::pim::CalendarEvent.

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

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

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

[NoInterfaceObject]
interface Query {
  any lookupEntry(in 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 will appear to be own the object corresponding to all of the object’s supported property names, 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 constrast 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 argument and MUST NOT appear on an interface that does not define a name getter or that also is declared with the [ReplaceableNamedProperties] extended attribute.

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

[OverrideBuiltins]
interface StringMap2 {
  readonly attribute unsigned long length;
  getter DOMString lookup(in 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 name 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 name getter.
map2.abc;

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

// This too invokes the name 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.

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

interface Name {
  attribute DOMString full;
  attribute DOMString family;
  attribute DOMString given;
};

interface Person {
  [PutForwards=full] readonly attribute Name name;
  attribute unsigned short age;
};

var p = getPerson();           // Obtain an instance of Person.

p.name = 'John Citizen';       // This statement...
p.name.full = 'John Citizen';  // ...has the same behavior as this one.

4.3.11. [Replaceable]

If the [Replaceable] extended attribute appears on a read only attribute, it indicates that setting the corresponding property on the platform object will result in that property being reconfigured to one that is unrelated to the attribute, and which has the value being assigned.

The [Replaceable] extended attribute MUST take no argument.

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

interface Counter {
  [Replaceable] readonly attribute unsigned long value;
  void increment();
};

var counter = getCounter();  // Obtain an instance of Counter.
counter.value;               // Evaluates to 0.

counter.increment();
counter.increment();
counter.value;               // Evaluates to 2.

counter.value = 'a';         // Replaces the property with one that is unrelated
                             // to Counter::value.

counter.increment();
counter.value;               // Evaluates to 'a'.

4.3.12. [ReplaceableNamedProperties]

If the [ReplaceableNamedProperties] extended attribute appears on an interface, then for objects that support named properties but which do not have a name setter, attempting to set a property that corresponds to a named property will result in an own property being defined on the object, rather than in the assignment failing, which is the normal behavior.

The [ReplaceableNamedProperties] extended attribute MUST take no argument.

The [ReplaceableNamedProperties] extended attribute MUST NOT be declared on an interface that does not define a name getter, that does define a name setter or that also is declared with the [OverrideBuiltins] extended attribute.

[ReplaceableNamedProperties]
interface Window {
  getter any (in DOMString name);
  // ...
};

<!DOCTYPE html>
<title>Replaceable named properties on Window</title>
<iframe name=abc></iframe>
<script>
window.abc;    // Evaluates to the iframe's Window object.
abc = 1;       // Replaces the named property.
window.abc;    // Evaluates to 1.
</script>

4.3.13. [TreatNullAs]

If the [TreatNullAs] extended attribute appears on an attribute or operation argument whose type is DOMString, it indicates that a null value assigned to the attribute or passed as the operation argument will be handled differently from its default handling. Instead of being stringified to "null", which is the default, it will be converted to the empty string "".

If [TreatNullAs] is specified on an operation itself, then it indicates that a user object implementing the interface will have the return value of the function that implements the operation handled in the same way as for operation arguments and attributes, as above.

The [TreatNullAs] extended attribute MUST take the identifier EmptyString.

The [TreatNullAs] extended attribute MUST NOT be specified on an operation argument, attribute or operation return value whose type is not DOMString.

interface Dog {
  attribute DOMString name;
  attribute DOMString owner;

  boolean isMemberOfBreed([TreatNullAs=EmptyString] in DOMString breedName);
};

var d = getDog();         // Assume d is a platform object implementing the Dog
                          // interface.

d.name = null;            // This assigns the string "null" to the .name
                          // property.

d.isMemberOfBreed(null);  // This passes the string "" to the isMemberOfBreed
                          // function.

4.3.14. [TreatUndefinedAs]

If the [TreatUndefinedAs] extended attribute appears on an attribute or operation argument whose type is DOMString or DOMString?, it indicates that an undefined value assigned to the corresponding property or passed as an argument to the corresponding function will be handled differently from its default handling, which is to stringify to "undefined":

• If the argument to [TreatUndefinedAs] is EmptyString, then the value assigned to the attribute or passed as the operation argument will be the empty string, "".
• Otherwise, if the argument to [TreatUndefinedAs] is Null, then the value assigned to the attribute or passed as the operation argument will be the null value.

If [TreatUndefinedAs] is specified on an operation itself, then it indicates that a user object implementing the interface will have the return value of the function that implements the operation handled in the same way as for operation arguments and attributes, as above.

The [TreatUndefinedAs] extended attribute MUST take an identifier: either EmptyString or Null.

[TreatUndefinedAs=Null] MUST NOT be specified on operation argument, attribute or operation return value whose type is not DOMString?, and [TreatUndefinedAs=EmptyString] MUST NOT be specified on operation argument, attribute or operation return value whose type is neither DOMString nor DOMString?.

interface Cat {
  attribute DOMString name;
  attribute DOMString owner;

  boolean isMemberOfBreed([TreatUndefinedAs=EmptyString] in DOMString breedName);
};

var c = getCat();              // Obtain an instance of Cat.

c.name = undefined;            // This assigns the string "undefined" to the
                               // .name property.

c.isMemberOfBreed(undefined);  // This passes the string "" to the
                               // isMemberOfBreed function.

4.3.15. [Unforgeable]

If the [Unforgeable] extended attribute appears on a read only attribute, it indicates that the attribute will be reflected as an ECMAScript property in a way that means its behavior cannot be modified and that performing a property lookup on the object will always result in the attribute’s property value being returned. In particular, the property will be non-configurable and will exist as an own property on the object itself rather than on its prototype.

The [Unforgeable] extended attribute MUST take no argument.

The [Unforgeable] extended attribute MUST NOT appear on anything other than a read only attribute. It also MUST NOT appear on an attribute on interface A if there exists another interface B that defines any interface member with the same identifier, and which either has A as an inherited interface or which is a consequential interface of A.

interface System {
  [Unforgeable] readonly attribute DOMString username;
  readonly attribute Date loginTime; 
};

var system = getSystem();                      // Get an instance of System.

system.hasOwnProperty("username");             // Evaluates to true.
system.hasOwnProperty("loginTime");            // Evaluates to false.
System.prototype.hasOwnProperty("username");   // Evaluates to false.
System.prototype.hasOwnProperty("loginTime");  // Evaluates to true.

try {
  // This call would fail, since the property is non-configurable.
  Object.defineProperty(system, "username", { value: "administrator" });
} catch (e) { }

// This defineProperty call would succeed, because System.prototype.loginTime
// is configurable.
var forgedLoginTime = new Date(new Date() - 3600000);
Object.defineProperty(System.prototype, "loginTime", { value: forgedLoginTime });

system.loginTime;  // So this now evaluates to forgedLoginTime.

4.5.1. Interface object

There exists an interface object for every interface not declared with the [NoInterfaceObject] extended attribute. Interface objects are always function objects.

The [[Class]] property of the interface object MUST be the identifier of the interface.

The interface object also has properties that correspond to the constants and static operations defined on that interface, as described in sections 4.5.4 and 4.5.6 below.

The interface object MUST also have a property named prototype with attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false } whose value is an object called the interface prototype object. This object has properties that correspond to the attributes and operations defined on the interface, and is described in more detail in section 4.5.3 below.

4.5.2. Named constructors

A named constructor that exists due to one or more [NamedConstructor] extended attributes with a given identifier is a function object. It MUST have a [[Call]] internal property, which allows construction of objects that implement the interface on which the [NamedConstructor] extended attributes appear. It behaves as follows, assuming arg_0..n−1 is the list of argument values passed to the constructor, id is the identifier of the constructor specified in the extended attribute named argument list, and I is the interface on which the [NamedConstructor] extended attribute appears:

1. Initialize S to the effective overload set for constructors with identifier id on interface I and with argument count n (for the ECMAScript language binding).
2. Set S to the result of passing S and arg_0..n−1 to the overload resolution algorithm.
3. If S is empty, throw a TypeError.
4. If S contains more than one entry, then the constructor call is ambiguous. Remove all but one entry from S according to rules specified in the description of interface I, or arbitrarily if no such rules exist.
5. Let x be the extended attribute that represents the constructor, and t_0..m−1 be the type list, of the single entry in S.
6. Let idlarg_0..m−1 be a list of IDL values, where idlarg_i is the result of converting arg_i to an IDL value. These conversions MUST be done in order from arg₀ to arg_m−1.
7. Let R be the result of performing the actions listed in the description of the constructor represented by x with idlarg_0..m−1 as the argument values.
8. Return the result of converting R to an ECMAScript interface type value I.

If the internal [[Call]] method of the named constructor returns normally, then it MUST return an object that implements interface I.

A named constructor MUST have a property named “length” with attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false } whose value is a Number determined as follows:

1. Initialize S to the effective overload set for constructors with identifier id on interface I and with argument count 0 (for the ECMAScript language binding).
2. Return the maximum argument list length of the constructors in the entries of S.

4.5.3. Interface prototype object

There MUST exist an interface prototype object for every interface defined, regardless of whether the interface was declared with the [NoInterfaceObject] extended attribute. The interface prototype object for a particular interface has properties that correspond to the attributes and operations defined on that interface. These properties are described in more detail in sections 4.5.5 and 4.5.6 below.

As with the interface object, the interface prototype object also has properties that correspond to the constants defined on that interface, described in section 4.5.4 below.

If the [NoInterfaceObject] extended attribute was not specified on the interface, then the interface prototype object MUST also have a property named “constructor” with attributes { [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: true } whose value is a reference to the interface object for the interface.

The interface prototype object for a given interface A MUST have an internal [[Prototype]] property whose value is as follows:

1. If A is not declared to inherit from another interface, then the value of the internal [[Prototype]] property of A is the Object prototype object ([ECMA-262], section 15.2.4).
2. Otherwise, if A is declared with the [CopyInheritedPrototype] extended attribute, then value of the internal [[Prototype]] property of A is the same as the value of the internal [[Prototype]] property of the interface prototype object of the interface A inherits from.
3. Otherwise, A does inherit from another interface and is not declared with the [CopyInheritedPrototype] extended attribute. The value of the internal [[Prototype]] property of A is the interface prototype object for the inherited interface.

Any properties corresponding to constants, attributes or operations that are required to exist on an interface A’s interface prototype object MUST also exist, with the same characteristics, on the interface prototype object of interfaces that inherit from A and are declared with the [CopyInheritedPrototype] extended attribute.

4.5.4. Constants

For each constant defined on an interface A, there MUST be a corresponding property on the interface object, if it exists, if the identifier of the constant is not “prototype”. The property has the following characteristics:

• The name of the property is the identifier of the constant.
• The value of the property is that which is obtained by converting the constant’s IDL value to an ECMAScript value.
• The property has attributes { [[Writable]]: false, [[Enumerable]]: true, [[Configurable]]: false }.

In addition, a property with the same characteristics MUST exist on the interface prototype object, unless:

• the identifier of the constant is “constructor”; or
• the identifier of the constant is “toString” and the interface has a stringifier.

4.5.5. Attributes

For each attribute defined on the interface, there MUST be a corresponding property either on the interface prototype object or on every object that implements the interface, unless:

• the identifier of the attribute is “constructor”; or
• the identifier of the attribute is “toString” and the interface has a stringifier.

The characteristics of these properties are as follows:

• If the attribute was declared with the [Unforgeable] extended attribute, then the property exists on every object that implements the interface. Otherwise, it exists on the interface’s interface prototype object.
• The name of the property is the identifier of the attribute.
• The property has attributes { [[Get]]: G, [[Set]]: S, [[Enumerable]]: true, [[Configurable]]: configurable }, where:
  • configurable is false if the attribute was declared with the [Unforgeable] extended attribute and true otherwise;
  • G is the attribute getter, defined below; and
  • S is the attribute setter, also defined below.
• The attribute getter is a Function object whose behavior when invoked is as follows:
  1. Let O be the result of calling ToObject on the this value.
  2. If O is not a platform object that implements the interface on which the attribute was declared, then throw a TypeError.
  3. Let idlValue be the result of performing the actions listed in the description of the attribute that occur when getting (or those listed in the description of the inherited attribute, if this attribute is declared to inherit its getter), with O as the object.
  4. Let V be the result of converting the idlValue to an ECMAScript value.
  5. Return V.
  The value of the Function object’s length property is the Number value 0.
• The attribute setter is undefined if the attribute is declared readonly and has neither a [PutForwards] nor a [Replaceable] extended attribute declared on it. Otherwise, it is a Function object whose behavior when invoked is as follows:
  1. Let O be the result of calling ToObject on the this value.
  2. If O is not a platform object that implements the interface on which the attribute was declared, then throw a TypeError.
  3. Let V be the value of the first argument passed to the Function, or undefined is no arguments were passed.
  4. If the attribute is declared with a [PutForwards] extended attribute, then:
     1. Let Q be the result of calling the [[Get]] method on O using the identifier of the attribute as the property name.
     2. If Q is not an object, then throw a TypeError.
     3. Let A be the attribute identified by the [PutForwards] extended attribute.
     4. Call the [[Put]] method on Q using the identifier of A as the property name and V as the value.
     5. Return.
  5. If the attribute is declared with a [Replaceable] extended attribute, then:
     1. Let O be the result of calling ToObject on the this value.
     2. If O is not an instance of the interface on which the attribute was declared, then throw a TypeError.
     3. Let P be the identifier of the attribute.
     4. Call the [[DefineOwnProperty]] method of O passing property name P, Property Descriptor { [[Value]]: V, [[Writable]]: true, [[Enumerable]]: true, [[Configurable]]: true }, and false.
     5. Return undefined.
  6. Let idlValue be the result of converting V to an IDL value.
  7. Perform the actions listed in the description of the attribute that occur when setting, with O as the object and idlValue as the value.
  8. Return undefined.
  The value of the Function object’s length property is the Number value 1.

Note that attempting to assign to a property corresponding to a read only attribute results in different behavior depending on whether the script doing so is in strict mode. When in strict mode, such an assignment will result in a TypeError being thrown. When not in strict mode, the assignment attempt will be ignored.

4.5.6. Operations

For each unique identifier of a non-omittable operation defined on the interface, there MUST be a corresponding property on the interface prototype object (if it is a regular operation) or the interface object (if it is a static operation), unless:

• the effective overload set for that identifier and operation and with an argument count of 0 (for the ECMAScript language binding) has no entries; or
• the operation is a regular operation and its identifier is “constructor”; or
• the operation is a regular operation, its identifier is “toString” and the interface has a stringifier; or
• the operation is a static operation and its identifier is “toString”; or
• the operation is a static operation and its identifier is “prototype”.

The characteristics of such a corresponding property are as follows:

• The name of the property is the identifier.
• The property has attributes { [[Writable]]: true, [[Enumerable]]: true, [[Configurable]]: true }.
• The value of the property is a Function object whose behavior is as follows, assuming id is the identifier, arg_0..n−1 is the list of argument values passed to the function and I is the interface:
  1. Let O be the result of calling ToObject on the this value.
  2. If O is not a platform object that implements interface I, throw a TypeError.
  3. Initialize S to the effective overload set for regular operations (if the operation is a regular operation) or for static operations (if the operation is a static operation) with identifier id on interface I and with argument count n (for the ECMAScript language binding).
  4. Set S to the result of passing S and arg_0..n−1 to the overload resolution algorithm.
  5. If S is empty, throw a TypeError.
  6. If S contains more than one entry, then the operation call is ambiguous. Remove all but one entry from S according to rules specified in the description of interface I, or arbitrarily if no such rules exist.
  7. Let op be the operation and t_0..m−1 be the type list of the single entry in S.
  8. Let idlarg_0..m−1 be a list of IDL values, where idlarg_i is the result of converting arg_i to an IDL value. These conversions MUST be done in order from arg₀ to arg_m−1.
  9. Let R be the result of performing the actions listed in the description of operation op with idlarg_0..m−1 as the argument values.
  10. Return the result of converting R to an ECMAScript value of the type op is declared to return.
• The value of the Function object’s length property is a Number determined as follows:
  1. Let S be the effective overload set for regular operations (if the operation is a regular operation) or for static operations (if the operation is a static operation) with identifier id on interface I and with argument count 0 (for the ECMAScript language binding).
  2. Return the maximum argument list length of the functions in the entries of S.

In addition, if the interface has a stringifier, then a property MUST exist on the interface prototype object whose name is toString, with attributes { [[Writable]]: true, [[Enumerable]]: true, [[Configurable]]: true } and whose value is a Function object. If stringifier was specified on an attribute A, then the function, when invoked, MUST behave as follows:

1. Let O be the result of calling ToObject on the this value.
2. If O is not an object that implements the interface on which A was declared, then throw a TypeError.
3. Let V be the result of invoking the [[Get]] method of O with P as the argument.
4. Return ToString(V).

If stringifier was specified on an operation with an identifier P, then the function, when invoked, MUST behave as follows:

1. Let O be the result of calling ToObject on the this value.
2. Let F be the result of invoking the [[Get]] method of object O with P as the argument.
3. If F is not callable, throw a TypeError.
4. Let V be the result of invoking the [[Call]] method of F, using O as the this value and passing no arguments.
5. Return ToString(V).

If stringifier was specified on an operation with no identifier, then the behavior of the function is the stringification behavior of the interface, as described in the prose for the interface.

4.7.1. Indexed and named properties

If a platform object implements an interface that supports indexed or named properties, the object will appear to have additional properties that correspond to the object’s indexed and named properties. These properties are not “real” own properties on the object, but are made to look like they are by being exposed by the [[GetOwnProperty]] internal method.

It is permissible for an object to implement multiple interfaces that support indexed properties. However, if so, and there are conflicting definitions as to the object’s supported property indices, or if one of the interfaces is a supplemental interface for the platform object, then it is undefined what additional properties the object will appear to have, or what its exact behavior will be with regard to its indexed properties. The same applies for named properties.

The index getter that is defined on the derived-most interface that the platform object implements is the one that defines the behavior when indexing the object with an array index. Similarly for index setters, deleters and creators. This way, the definitions of these special operations from ancestor interfaces can be overridden.

Platform objects implementing an interface that support indexed or named properties defy being fixed; if Object.freeze, Object.seal or Object.preventExtensions is called on one, these the function MUST throw a TypeError.

The name of each property that appears to exist due to an object supporting indexed properties is an array index property name, which is a property name P for which the following algorithm returns true:

1. Let i be ToUint32(P).
2. Let s be ToString(i).
3. If s ≠ P or i = 2³² − 1, then return false.
4. Return true.

Specifications can state that certain named properties are resolved before prototype properties. This means that such named properties will be resolved after real own properties on the object (as with all non-[OverrideBuiltins] named properties), but before properties from the prototype chain. Specifications SHOULD NOT declare any named properties to be resolved before prototype properties unless this is required to specify the behavior of legacy APIs.

The named property visibility algorithm is used to determine if a given named property is exposed on an object. Some named properties are not exposed on an object depending on whether the [OverrideBuiltins] extended attribute was used. The algorithm operates as follows, with property name P and object O:

1. If O implements an interface with an [Unforgeable]-annotated attribute whose identifier is P, then return false.
2. If P is not a supported property name of O, then return false.
3. If O implements an interface that has the [OverrideBuiltins] extended attribute, then return true.
4. If O has an own property named P, then return false.
5. If P is to be resolved before prototype properties, then return true.
6. Let prototype be the value of the internal [[Prototype]] property of O.
7. If prototype is null, then return true.
8. If the result of calling the [[HasProperty]] internal method on prototype with property name P is true, then return false.
9. Return true.

Support for getters is handled by the platform object [[GetOwnProperty]] method defined in section 4.7.2, for creators and setters by the platform object [[DefineOwnProperty]] method defined in section 4.7.3, and for deleters by the platform object [[Delete]] method defined in section 4.7.4.

4.7.2. Platform object [[GetOwnProperty]] method

The internal [[GetOwnProperty]] method of every platform object O that implements an interface which supports indexed or named properties MUST behave as follows when called with property name P:

1. If O supports indexed properties and P is an array index property name, then:
   1. Let index be the result of calling ToUint32(P).
   2. If index is a supported property index, then:
      1. Let operation be the operation used to declare the index getter.
      2. Let value be an uninitialized variable.
      3. If operation was defined without an identifier, then set value to the result of performing the steps listed in the interface description to determine the value of an indexed property with index as the index.
      4. Otherwise, operation was defined with an identifier. Set value to the result of performing the steps listed in the description of operation with index as the only argument value.
      5. Let desc be a newly created property descriptor ([ECMA-262], section 8.10) with no fields.
      6. Set desc.[[Value]] to the result of converting value to an ECMAScript value.
      7. If O implements an interface with an index setter, then set desc.[[Writable]] to true, otherwise set it to false.
      8. Set desc.[[Enumerable]] and desc.[[Configurable]] to true.
      9. Return desc.
2. If O supports named properties, then:
   1. If the result of running the named property visibility algorithm with property name P and object O is true, then:
      1. Let operation be the operation used to declare the name getter.
      2. Let value be an uninitialized variable.
      3. If operation was defined without an identifier, then set value to the result of performing the steps listed in the interface description to determine the value of a named property with P as the name.
      4. Otherwise, operation was defined with an identifier. Set value to the result of performing the steps listed in the description of operation with P as the only argument value.
      5. Let desc be a newly created property descriptor ([ECMA-262], section 8.10) with no fields.
      6. Set desc.[[Value]] to the result of converting value to an ECMAScript value.
      7. If O implements an interface with an name setter and O does not implement an interface with the [ReplaceableNamedProperties] extended attribute, then set desc.[[Writable]] to true, otherwise set it to false.
      8. Set desc.[[Enumerable]] and desc.[[Configurable]] to true.
      9. Return desc.
3. Return the result of calling the default [[GetOwnProperty]] internal method ([ECMA-262], section 8.12.1) on O passing P as the argument.

4.7.3. Platform object [[DefineOwnProperty]] method

The internal [[DefineOwnProperty]] method of every platform object O that implements an interface which supports indexed or named properties MUST behave as follows when called with property name P, property descriptor Desc and boolean flag Throw. The term “Reject” is used in the same sense as that defined in ECMA-262, namely, to mean “If Throw is true, then throw a TypeError exception, otherwise return false”.

1. Set Desc.[[Configurable]] to true.
2. If O supports indexed properties and P is an array index property name, then:
   1. If the result of calling IsDataDescriptor(Desc) is false, then Reject.
   2. Let index be the result of calling ToUint32(P).
   3. Let creating be true if index is not a supported property index, and false otherwise.
   4. If creating is true and O does not implement an interface with an index creator, then Reject.
   5. If creating is false and O does not implement an interface with an index setter, then Reject.
   6. Let operation be the operation used to declare the index creator if creating is true, or the index setter if creating is false.
   7. Let T be the type of the second argument of operation.
   8. Let value be the result of converting Desc.[[Value]] to an IDL value of type T.
   9. If operation was defined without an identifier, then:
      1. If creating is true, then perform the steps listed in the interface description to set the value of a new indexed property with index as the index and value as the value.
      2. Otherwise, creating is false. Perform the steps listed in the interface description to set the value of an existing indexed property with index as the index and value as the value.
   10. Otherwise, operation was defined with an identifier. Perform the steps listed in the description of operation with index and value as the two argument values.
   11. Return true.
3. If O supports named properties and P is not the identifier of an [Unforgeable]-annotated attribute on an interface that O implements, then:
   1. Let creating be true if P is not a supported property name, and false otherwise.
   2. If creating is false and O implements an interface with the [ReplaceableNamedProperties] extended attribute, then:
      1. If the result of calling IsAccessorDescriptor(Desc) is true, then:
         1. Create an own accessor property named P on O whose [[Get]], [[Set]], [[Enumerable]] and [[Configurable]] attribute values are described by Desc. If the value of an attribute field of Desc is absent, the attribute of the newly created property is set to its default value ([ECMA-262], section 8.6.1).
      2. Otherwise:
         1. Create an own data property named P on O whose [[Value]], [[Writable]], [[Enumerable]] and [[Configurable]] attribute values are described by Desc. If the value of an attribute field of Desc is absent, the attribute of the newly created property is set to its default value ([ECMA-262], section 8.6.1).
      3. Return true.
   3. Otherwise, if O implements an interface with the [OverrideBuiltins] extended attribute or O does not have an own property named P, then:
      1. If creating is false and O does not implement an interface with a name setter, then Reject.
      2. If creating is false or O implements an interface with a name creator, then:
         1. If the result of calling IsDataDescriptor(Desc) is false, then Reject.
         2. Let operation be the operation used to declare the name creator if creating is true, or the name setter if creating is false.
         3. Let T be the type of the second argument of operation.
         4. Let value be the result of converting Desc.[[Value]] to an IDL value of type T.
         5. If operation was defined without an identifier, then:
            1. If creating is true, then perform the steps listed in the interface description to set the value of a new named property with P as the name and value as the value.
            2. Otherwise, creating is false. Perform the steps listed in the interface description to set the value of an existing named property with P as the name and value as the value.
         6. Otherwise, operation was defined with an identifier. Perform the steps listed in the description of operation with index and value as the two argument values.
         7. Return true.
4. Call the default [[DefineOwnProperty]] internal method ([ECMA-262], section 8.12.9) on O passing P, Desc, and Throw as arguments.

4.7.4. Platform object [[Delete]] method

The internal [[Delete]] method of every platform object O that implements an interface which supports indexed or named properties MUST behave as follows when called with property name P and boolean flag Throw. The term “Reject” is used as defined in 4.7.3 above.

1. If O supports indexed properties and P is an array index property name, then:
   1. Let index be the result of calling ToUint32(P).
   2. If index is not a supported property index, then return true.
   3. If O does not implement an interface with an index deleter, then Reject.
   4. Let operation be the operation used to declare the index deleter.
   5. If operation was defined without an identifier, then:
      1. Perform the steps listed in the interface description to delete an existing indexed property with index as the index.
      2. If the steps indicated that the deletion failed, then Reject.
   6. Otherwise, operation was defined with an identifier:
      1. Perform the steps listed in description of operation with index as the only argument value.
      2. If operation was declared with a return type of boolean and the steps returned false, then Reject.
   7. Return true.
2. If O supports named properties and the result of calling the named property visibility algorithm with property name P and object O is true, then:
   1. If O does not to implement an interface with an name deleter, then Reject.
   2. Let operation be the operation used to declare the name deleter.
   3. If operation was defined without an identifier, then:
      1. Perform the steps listed in the interface description to delete an existing named property with P as the name.
      2. If the steps indicated that the deletion failed, then Reject.
   4. Otherwise, operation was defined with an identifier:
      1. Perform the steps listed in description of operation with P as the only argument value.
      2. If operation was declared with a return type of boolean and the steps returned false, then Reject.
   5. Return true.
3. If O has an own property with name P, then:
   1. If the property is not configurable, then Reject.
   2. Otherwise, remove the property from O.
4. Return true.