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.

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 -> 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 token is not quoted and its value is the octothorpe character (#, also called the hash or pound sign), the operand is a null reference. 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.

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. This will raise a condition if the token is not a valid number. If the value of the token is not a valid number then it must be quoted.^[1] 

operand2

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

result

This defines the result of carrying out the operation on the operand or operands. It will either be the string form of a valid number (which may be quoted) or it will be the question mark character (?) which indicates that the result is undefined (for example, in tests for the X3.274 subset of the specification this is used when an error condition is expected).

When the result is a number, the string will be that produced by the to-scientific-string conversion in the specification, unless the operation is toEng in which case the string will be that produced by the to-engineering-string conversion.

Note that when extended is set (see below) then results will be defined even after an error, and may have the values NaN (Not a Number), sNaN (signaling NaN), Infinity, -Infinity, or -0. Zeros may also have a fractional part.

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.

Any operand or result token may be quoted. That is, it may begin with a delimiter which is a single or double quote character and it is then only ended by a matching quote (which must be present and on the same line). A quote which matches the starting quote may be included inside a quoted operand by doubling up the quote; in this case it does not end the token.

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.

When the value of an operand token is converted to a number before use, using the to-number conversion, it is subject to the values set by directives, except that the precision directive is only used when the operation is toSci or toEng. For other operations, sufficient precision is used so that rounding of the operand is avoided.^[2] 

Example:

Here is an example of a small testcase file, comprising some commentary, four directives which set the version and context, and some tests.

  -- simple.decTest
  -- Testcase for some simple operations.
  Version: 2.09

  Extended:    1
  Precision:   9
  Rounding:    half_up
  MaxExponent: 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 three directives are required; no tests can be run without these three 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 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 absolute value of the adjusted exponent beyond which overflow or underflow will be raised. The following tests will indicate an overflow or underflow condition if the magnitude of the adjusted exponent exceeds this setting. (Note that if extended is set, a larger range of exponents can be handled because subnormal values are allowed.) 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 or underflow condition should be skipped (until the setting is suitably changed or the end of the file is reached).

The next two 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.01 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, 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, the power operator has extra checking, 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 (the default), 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).

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 or toEng. 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 854 exception which would be raised by the condition.

Condition Specification name IEEE exception 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. The lost_digits condition can only occur if extended is 0.
4. 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.