Decimal Testcases, version 2.09 Copyright (c) IBM Corporation, 2002. All rights reserved. © | 3 Nov 2002
[previous | contents | next]

# Testcase file format

This section describes the format of the testcase files. These are distributed as plain text files with a file name that identifies the group of tests contained in the file and a file extension (if appropriate) of `.decTest`. File names will not have embedded blanks.

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 testcase file consists of one or more lines (the line delimiter mechanism may vary, depending on the operating system). Within each line, control characters (those with encodings in the range 0 through 31) are not used.

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

Directives are used to control the testcase environment in some way. Each has a keyword (which is immediately followed by a colon) and a value.

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

Each test line identifies an operation by means of a case-independent keyword, which is always the second token of the line. The following operations are defined.

Keyword | Definition
`abs` | If the operand is negative, this is the same as `minus`; otherwise it is the same as `plus`.
`add` | The two operands are added together using add.
`compare` | The operands are compared using compare.
`divide` | The first operand (the dividend) is divided by the second (the divisor) using divide.
`divideint` | The first operand (the dividend) is divided by the second (the divisor) to give an integer result, using divide-integer.
`integer` | The operand is rounded to an integer, using round-to-integer.
`max` | The operands are compared using compare and the larger is returned (or the first, if they are equal).
`min` | The operands are compared using compare and the smaller is returned (or the first, if they are equal).
`minus` | The operand is subtracted from zero, using minus.
`multiply` | The operands are multiplied together using multiply.
`normalize` | Trailing zeros are removed, using normalize.
`plus` | The operand is added to zero, using plus.
`power` | The first operand is raised to an integer power (the second operand), using power.
`remainder` | The first operand (the dividend) is divided by the second (the divisor) to give a remainder after integer division, using remainder.
`remaindernear` | The first operand (the dividend) is divided by the second (the divisor) to give a remainder after division to the nearest integer, using remainder-near from the extended specification (IEEE remainder).
`rescale` | The first operand is rescaled so that its exponent is set to the value of the second operand, using rescale.
`squareroot` | The square root of the operand is computed, using square-root.
`subtract` | The second operand is subtracted from the first, using subtract.
`toEng` | The operand is converted to a string using to-engineering-string.
`toSci` | The operand is converted to a string using to-scientific-string. This operation is the ‘base’ test for conversions – typically, the value of the first operand is converted to some internal representation and is then converted to the canonical string form.
`trim` | Insignificant fractional zeros are removed, using trim.

### Conditions

Each test may cause zero or more conditions to be raised. The case-independent names of these conditions (if any) are listed following the result token of each test.

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.

Footnotes:

[1] | This rule allows future extensions to the syntax of tests.
[2] | This rule allows the testing of rounding in the `toSci` and `toEng` operations, and also permits the testing of the `lost_digits` condition in the other operations.

[previous | contents | next]