ECMAScript 4 Netscape Proposal Libraries Machine Types

Tuesday, March 4, 2003

Purpose

Machine types are low-level numeric types for use in ECMAScript 4 programs. These types provide Java-style integer operations that are useful for communicating between ECMAScript 4 and other programming languages. These types are not intended to replace Number and Integer for general-purpose scripting.

Contents

The following low-level numeric types are available:

The above type names are not reserved words.

8, 16, and 32-bit Integers

The first six types sbyte, byte, short, ushort, int, and uint are all proper subtypes of Integer, which is itself a subtype of Number. A particular number is a member of multiple types. For example, 3.0 is a member of sbyte, byte, short, ushort, int, uint, Integer, Number, and Object, while –2000.0 is a member of short, int, Integer, Number, and Object. ECMAScript does not distinguish between the literals 3 and 3.0 in any way.

All arithmetic operations and comparisons on sbyte, byte, short, ushort, int, and uint values treat them just like they would any other Number values — the operations are performed using full IEEE double-precision arithmetic.

Implicit Coercions

There are no predefined implicit coercions from values of type sbyte, byte, short, ushort, int, or uint other than the coercions predefined on the type Number. The following predefined implicit coercions are applicable when the destination type is sbyte, byte, short, ushort, int, or uint:

• undefined +0.0
• –0.0 +0.0
• long and ulong values within range of the destination type T are converted to equivalent values of type T
• finite integral float values within range of the destination type T are converted to equivalent values of type T

Note that there are no implicit coercions from +, –, or NaN to sbyte, byte, short, ushort, int, or uint.

Explicit Coercions

There are no predefined explicit coercions from values of type sbyte, byte, short, ushort, int, or uint other than the coercions predefined on the type Number. The predefined explicit coercions below are applicable when the destination type T is sbyte, byte, short, ushort, int, or uint. The notation |T| represents the range of the type T, where |sbyte| = |byte| = 256, |short| = |ushort| = 65536, and |int| = |uint| = 2³².

• undefined +0.0
• A long or ulong value x is converted to the one value y of type T that satisfies x = y (mod |T|)
• float values are first converted to equivalent Number values and then converted as below
• A Number value is first converted to an Integer value x by truncating towards zero if necessary. Then, if x is –0.0, +, –, or NaN, it is converted to +0.0; otherwise, x is converted to the one value y of type T that satisfies x = y (mod |T|)

64-bit Integers

The types long and ulong represent signed and unsigned 64-bit integers. long and ulong literals are written with the suffix L or UL and no exponent or decimal point. Literal values of type long are written as –9223372036854775808L through 9223372036854775807L. Literal values of type ulong are written as 0UL through 18446744073709551615UL.

The types long and ulong are disjoint from Number, so 5L and 5 are different objects, although they compare == and === to each other. 5L and 5UL are also different objects, although they compare == and === to each other.

Negation, addition, subtraction, and multiplication, and modulo (%) on long and ulong values is exact, and long and ulong values may be mixed in an expression. There are five possible cases depending on the mathematical result x:

• If –9223372036854775808  x  –1, then the result has type long.
• If 0  x  9223372036854775807, then the result has type ulong if at least one operand has type ulong; otherwise, the result has type long.
• If 9223372036854775808  x  18446744073709551615, then the result has type ulong.
• Otherwise, the result is the closest representable Number using the IEEE round-to-nearest mode.

Division involving two long or ulong operands returns the most precise quotient available from among the possible long, ulong, and Number values. In some cases the quotient will be a long or ulong; in other cases the quotient will be a Number. See the semantics for the details.

Division and modulo on long and ulong values can produce the Number values positive or negative infinity or NaN when the divisor is zero.

Addition, subtraction, multiplication, division, and modulo mixing a long or ulong operand with a Number (or any subtype of Number) or float operand first checks whether the Number or float operand is an exact integer (including either +0.0 or –0.0 but not infinities or NaN). If it is, then the computation uses the integral semantics above. If not, then the long or ulong operand is coerced to a Number and the operation is done using Number arithmetic.

The bitwise operations &, |, and ^ are 64 bits wide if at least one operand is a long or ulong, in which case the other operand is truncated to an integer and treated modulo 2⁶⁴ if necessary. The result is a ulong if at least one operand is a ulong; otherwise, the result is a long.

The bitwise shifts <<, >>, and >>> are 64 bits wide if the first operand is a long or ulong. The result is a ulong if the first operand is a ulong; otherwise, the result is a long. >> copies the most significant bit and >>> shifts in zero bits regardless of whether the first operand is a long or ulong.

Comparisons mixing a long or ulong operand with a Number (or any subtype of Number) or float operand compare exact mathematical values without any coercions.

Implicit Coercions

The following predefined implicit coercions are applicable when the destination type is long:

• undefined 0L
• ulong values between 0UL and 9223372036854775807UL are converted to equivalent long values
• Finite Integer values between –9223372036854775808 and 9223372036854775807 are converted to equivalent long values
• Finite integral float values between –9223372036854775808F and 9223372036854775807F are converted to equivalent long values

The following predefined implicit coercions are applicable when the destination type is ulong:

• undefined 0UL
• long values between 0L and 9223372036854775807L are converted to equivalent ulong values
• Finite Integer values between –0.0 and 18446744073709551615 are converted to equivalent ulong values
• Finite integral float values between –0.0F and 18446744073709551615F are converted to equivalent ulong values

Note that there are no implicit coercions from NaN or positive or negative infinity to long or ulong.

A long or ulong value can be implicitly coerced to type Number, Integer, or float. The result is the closest representable Number or float value using the same rounding as when a string is converted to a number. If the source is 0L or 0UL then the result is +0.0 or +0.0F.

Explicit Coercions

The predefined explicit coercions below are applicable when the destination type T is long or ulong.

• undefined 0L or 0UL
• A long or ulong value x is converted to the one value y of type T that satisfies x = y (mod 2⁶⁴)
• float values are first converted to equivalent Number values and then converted as below
• A Number value is first converted to an Integer value x by truncating towards zero if necessary. Then, if x is –0.0, +, –, or NaN, it is converted to 0L or 0UL; otherwise, x is converted to the one value y of type T that satisfies x = y (mod 2⁶⁴).

A long or ulong value x can be explicitly coerced to type Number, Integer, float or String. Explicit coercions to Number, Integer, float are the same as the implicit coercions. Explicit coercions to type String produce the x as a string of decimal digits. Negative values have a minus sign prepended. Zero produces the string "0"; all other values produce strings starting with a non-zero digit.

Single-Precision Floats

The type float represents single-precision IEEE floating-point numbers. float literals are written with the suffix F. float infinities and NaN are separate from Number infinities and NaN.

The type float is disjoint from Number, so 5F and 5 are different objects, although they compare == to each other.

Negating a float value returns a float value. All other arithmetic first converts the float value to the corresponding Number value. The bitwise operations &, |, ^, <<, >>, and >>> coerce any float operands to type Number before proceeding.

Implicit Coercions

The following predefined implicit coercions are applicable when the destination type is float:

• undefined float(NaN)
• Number values (including NaN and the infinities) are converted to the closest representable float values using the IEEE round-to-nearest mode
• long and ulong values are converted to the closest representable float values (excluding –0.0F)

A float value can be implicitly coerced to type Number. The result is the equivalent Number value.

Waldemar Horwat Last modified Tuesday, March 4, 2003