Testcase file format

The files are encoded using one byte per character, using 7-bit ASCII encoding. These may be converted to Unicode by treating them as UTF-8-encoded files or by directly converting each 7-bit character to Unicode by prefixing nine 0 bits.

Testcase syntax

Each line is treated as a sequence of tokens, delimited by the start of the line, spaces between tokens, or (after the final token) the end of the line. There may be more than one space between tokens, and spaces may also appear before the first token on a line and after the last token on a line. Tokens may also be quoted, to include spaces (see below).

If the first two characters of a token are two hyphens (--) the token indicates the start of a comment. The two-hyphen sequence and any characters that follow it, up to the end of the line on which the sequence occurs, are ignored (that is, they are treated as commentary).

The lines in a file may be:

empty

Lines with no characters, or only space characters. These lines are treated as commentary and are ignored.

comments

Lines whose first token starts a comment. These are also ignored.

directives

Lines which are used to control the testcase environment in some way, for example to change the working precision. These lines have two tokens and are of the form:

  keyword: value

where the case-independent keyword describes the purpose of the directive, and the value is a parameter associated with the directive. The possible keywords and their values are described below.

tests

Lines which describe a specific test. These lines have at least five tokens, and are of the form:

  id operation operand1 operand2 operand3 -> result conditions

where the named tokens are as follows:

id

A short name which identifies the test. It is case-independent and unique in the file. In the current testcases it comprises three or four alphabetic characters followed by three or four digits (for example, divx101).

operation

A case-independent keyword which describes the operation to be carried out for this test (for example, divide).

operand1

The first (or only) operand required for the operation. The token may be quoted (see below). If it is not quoted then its value is the sequence of characters comprising the token, taken exactly as written.

If the value of a token includes an octothorpe character (#, also called the hash or pound sign), the operand is a specific format-dependent representation, as described below.

Otherwise, the value of the token is treated as a string, which should be converted to a number using the to-number conversion of the arithmetic specification.

operand2

An optional second operand, if required for the operation. If present, it has the same syntax and follows the same rules as operand1.

operand3

An optional third operand, if required for the operation. If present, it has the same syntax and follows the same rules as operand1 and there must be an operand2.

result

This defines the result of carrying out the operation on the operand or operands, and may also be quoted. It will either be the string form of a valid number or a format-dependent representation (see below), or the question mark character (?) which indicates that the result is undefined. The latter is only used in tests for the X3.274 subset of the specification, for error results.

conditions

Zero or more tokens each of which is the case-independent name of a condition set by the operation. If no condition is set then no condition tokens will be present.

Quoted tokens

The content of the quoted token (after the delimiters have been removed and any doubled delimiter quotes have been reduced to a single instance) forms the value of the token. The value may contain any 7-bit ASCII characters (other than the control characters, whose encodings are in the range 0 through 31), including spaces or the comment start sequence.

If the value of an operand token is not a valid number or format-dependent representation (that is, its syntax is not valid) then the token must be quoted.^[1]  Result tokens must always have correct syntax.

Processing of a test case line

In contrast, the value of a result token is effectively converted to a number without constraints – no flags will be set by this process. The ‘perfect’ result number is compared with the result of the operation on the operand(s) and must match exactly if the test is to succeed.

Note that in all cases the actual processing by a test case interpreter need only act as though the steps described here are carried out.

Format-dependent representations

The operand or result token must have one of the following syntaxes:

• The octothorpe alone. For example, "#".
  In this case, the token is a null reference, which can only be used as an operand. Null references are used for testing the behavior of implementations which can be passed numbers by reference, where a null reference would be an error. If this concept is not supported then tests containing null references should be skipped.
• The octothorpe followed by exactly 8, 16, or 32 hexadecimal digits, where a hexadecimal digit is one of the characters ’0’ through ’9’ or ’a’ through ’f’ (in uppercase or lowercase). For example, "#A23003D0".
  In this case, the token is an explicit hexadecimal representation in one of the decimal floating-point formats (decimal16, decimal32, or decimal128, respectively) described in the IEEE 754 standard.
  When used as an operand, these formats are decoded without loss or constraint and are then subject to the values set by directives, except that the precision directive is only used when the operation is toSci, toEng, or apply. For other operations, sufficient precision is used so that rounding of the operand is avoided (these are the same rules as are applied to operands supplied as numerical strings).
  When used as a result, these formats imply encoding of the result of the operation into the given format. This may modify or clamp the result to fit the format, giving a different result than if the result had been expressed as a string and possibly raising new conditions. Note that the toSci and toEng operations cannot be used if the result is format-dependent, as these require specific string results (use apply instead).
• One of the strings "32#", "64#", or "128#", immediately followed by a numeric string. For example, "32#-7.50".
  In this case, the token forms an alternative method of specifying a number in a particular format, with the characters before the # selecting the target format.
  For an operand, the numeric string is first converted to a number and is then encoded in the selected format (this may cause rounding or other conditions, and these conditions will be set as usual). The resulting encoding is then used as though it had been specified in explicit hexadecimal form, as described above.
  For a result, the numeric string is again first converted to a number and is then encoded in the selected format (this may cause rounding or other conditions, but no conditions will be set by this process). The resulting encoding is then used as though it had been specified as the result in explicit hexadecimal form, as described above.

Example

  -- simple.decTest
  -- Testcase for some simple operations.
  Version: 2.44
  
  Precision:   9
  Rounding:    half_up
  MaxExponent: 999
  MinExponent: -999
  
  simp001  add       1 1 -> 2   -- can we get this right?
  simp002  multiply  2 2 -> 4
  simp003  divide    1 3 -> 0.333333333  Inexact Rounded
  simp004  divide    1 0 -> NaN Division_by_zero
  simp005  toSci  ’1..2’ -> NaN Conversion_syntax

Note: Tokens and lines do not have a defined length limit, however the current testcases are limited to a maximum token length of 1050 characters and a maximum line length of 4000 characters.

Directives

The first four directives are required; no tests can be run without these settings being specified (that is, there is no default value for these settings). Once set, each setting remains in force until a new directive with the same keyword is encountered; the setting is then replaced by the new value.

Keyword Value precision An unsigned positive integer. Its value is used to set the precision in the context for the following tests. If the setting exceeds the maximum precision that can be handled by an implementation then following tests should be skipped (until the setting is suitably reduced or the end of the file is reached). rounding A word which describes the rounding mode to set in the context for the following tests. It is case-independent and will be one of:   ceiling   down   floor   half_down   half_even   half_up   up   05up If an unsupported rounding mode is set, then following tests should be skipped (until the setting is changed to a supported mode or the end of the file is reached). maxexponent An unsigned integer which may be zero or positive. This value describes the value of the adjusted exponent beyond which overflow will be raised. The following tests will indicate an overflow condition if the adjusted exponent exceeds this setting. Implementations, in general, will have fixed maximum exponent limits, which may not match the setting in the testcase: If the setting of maxexponent is larger than can be handled, then following tests should be skipped (until the setting is suitably reduced or the end of the file is reached). If the setting of maxexponent is smaller than can be enforced, then following tests which indicate an overflow condition should be skipped (until the setting is suitably changed or the end of the file is reached). minexponent An unsigned integer which may be zero or negative. This value describes the value of the adjusted exponent below which underflow will be raised. The following tests will indicate an underflow condition if the adjusted exponent is less than this setting. (Note that if extended is set, smaller exponents down to minexponent – precision + 1 are possible because subnormal values are allowed.) Implementations, in general, will have fixed minimum exponent limits, which may not match the setting in the testcase: If the setting of minexponent is smaller than can be handled, then following tests should be skipped (until the setting is suitably reduced or the end of the file is reached). If the setting of minexponent is smaller than can be enforced, then following tests which indicate an underflow or subnormal condition should be skipped (until the setting is suitably changed or the end of the file is reached).

The next three directives are optional:

Keyword Value version A number which describes the version of the testcases which follow. This may be up to five digits, or four digits with an embedded decimal point. For example:   version: 2.40 The meaning of the version number is not defined, except that later versions of testcases should have a larger version number. extended Either 0 or 1. This directive indicates the level of arithmetic needed for the following tests. When set to 1 (the default), numbers whose value is zero may have non-zero sign and exponent, operations may result in subnormal values, extra checking is performed on the length of operands, and the results of operations are defined after errors (they may be 0, infinite, or NaN values). For example:   extended: 1 -- enable extended values   div0 divide -1 0 -> -Infinity Division_by_zero When set to 0, only the X3.274 subset of the arithmetic is required, where the sign of a zero value result is always 0, subnormal values raise underflow, and some other differences are expected. If an implementation does not support testcases as selected by the extended setting then following tests should be skipped (until the extended setting is changed to an acceptable value or the end of the file is reached). clamp Either 0 or 1. This directive indicates whether explicit exponent clamping is applied. If 0 (the default), the only clamping applies to zero results, which will have maximum and minimum exponents as described under maxexponent and minexponent above. If 1, a restricted exponent range (as used in certain concrete representations) applies: the maximum exponent is reduced to maxexponent – precision + 1. This will clamp zeros at a lower value and may cause the coefficient and exponent of certain normal values to be ‘folded down’. If an implementation does not support testcases with the clamp option as selected by the clamp setting then following tests should be skipped (until the clamp setting is changed to an acceptable value or the end of the file is reached).

The final directive allows testcase groups (files) to themselves be grouped together in a hierarchy:

Keyword Value dectest A word specifying the file name (without extension) of another testcase file to be processed at this point. For example, a testcase which simply runs the testcases for the three division operations might read:   -- divides.decTest -- Test divisions   dectest: divide   dectest: divideint   dectest: remainder Note that this directive is not an ‘include’; the current settings are not inherited by the file to be processed – that file must be processed in exactly the same way as if it were the only testcase being run.

Operations

Conditions

Only those conditions occuring during the tested operation are listed unless the operation is toSci, toEng, or apply. For these operations, conditions raised during the conversion of the operand are included (this allows the testing of conversions in both directions).

The following condition names are defined, together with the name used for it in the arithmetic specification and the IEEE 754 exception which would be raised by the condition.

Condition Specification name IEEE exception clamped Clamped (no equivalent) conversion_syntax Conversion syntax Invalid operation division_by_zero Division by zero Division by zero division_impossible Division impossible Invalid operation division_undefined Division undefined Invalid operation inexact Inexact Inexact insufficient_storage Insufficient storage Invalid operation invalid_context Invalid context Invalid operation invalid_operation Invalid operation Invalid operation lost_digits Lost digits (no equivalent) overflow Overflow Overflow rounded Rounded (no equivalent) subnormal Subnormal (no equivalent) underflow Underflow Underflow

Notes:

1. The condition names are simply the names from the arithmetic specification, with spaces changed to underscores so each forms a single token.
2. The inexact, rounded, and subnormal conditions are included in the testcases, even when extended is 0, to aid analysis and debugging. (Underflow implies all three.)
   The rounded condition indicates that an operand or the result of a test has had one or more zero or non-zero digits removed by rounding. That is, the number of digits in the coefficient of the result is fewer than in the coefficient of the ‘ideal’ result.
   In contrast, the inexact condition indicates only that non-zero trailing digits were removed (that is, the result would compare unequal to the ideal result).
3. Similarly, the clamped condition, which can only occur if extended is 1, is included. This indicates when a zero is clamped to the maximum or minimum adjusted or representable exponent, or when a normal number is ‘folded-down’ in order to fit in a specific encoding.
4. The lost_digits condition can only occur if extended is 0.
5. The insufficient_storage condition is not a predictable condition and so will not appear in any testcases. It is listed here as a reminder that some implementations could raise this condition for some tests.