Skip to content

Numeric questions and variables

Fundamentals

TO BE DECIDED

This documentation is based on the documented behaviour of Javascript, and also the capabilities of JSON, which is likely to be a used extensively throughout CAWI v3 to store metadata. So whilst the documented behaviour might not be what we would ideally want, it wouldn't be easy to do something different.

But it's important that we document the behaviour in detail, so we can ensure compliance in all new tools written for the CAWI.

The CAWI language has a single underlying "number" type, with values stored as double precision floating point numbers, following the international IEEE 754 standard.

When defining questions or variables in the CAWI language, the keywords INTEGER and DECIMAL are used, with optional parameters to specify the allowed range (minimum and maximum values with inclusive/exclusive/unlimited options), scale and precision.

The range, scale and precision are validated on input from a questionnaire and an error given if the input is either outside the allowed range or provided to too large a scale or precision.

The following syntaxes are deprecated in CAWI v3 and may be removed from future versions of the language:

  • FLOAT
  • FRANGE - e.g. 1.0..100.0 or 1.0:100.0 (TO BE DECIDED)
  • IRANGE - e.g. 0..100 (TO BE DECIDED)

In CAWI v3 these syntaxes are converted to the equivalent INTEGER or DECIMAL syntax in the JSON description generated from the DSC.

Technical details

The binary representation stores numbers in 64 bits, where the number (the fraction) is stored in bits 0 to 51, the exponent in bits 52 to 62, and the sign in bit 63. This allows integers with 15 decimal digits without rounding errors.

This is consistent with the Javascript Number type and the C double type. For storage of integers, a 64-bit integer type may be used.

For textual representation (including XML and JSON documents), numbers are normalised to decimal form without any leading or trailing zeros. 1 and 1.0 have the same binary representation, and are both represented as the string "1".

This only applies to the storage of data within the CAWI system - data can be imported or exported in other formats.

Scale and precision

For DECIMAL values, the "scale" refers to the number of digits after the decimal point, and the precision refers to the total number of significant digits.

For example, the number 123.456 has scale 3 and precision 6.

A single leading 0 before the decimal point does not count towards the precision. i.e. 0.31 is treated as .31 and has precision 2.

A precision can also be specified for INTEGER values, as an alternative to specifying the min/max. So precision=2 would be the same as the range -99 to 99.

Numeric expressions

In the CAWI routing language, numeric expressions are processed as follows:

  1. The result is calculated as a full-precision "number" variable.
  2. Depending on the context, the value is co-erced to the required type as follows:
    • Assignment an INTEGER - the value is truncated;
    • Assigment to a DECIMAL - the value is rounded to the specified scale
    • TODO: What about other operations, such as comparisons?

Note that precision and min/max constraints are not enforced in the ROUTE language - this is the responsibility of the DSC scripter.

Adding numbers and strings

Warning

The CAWI uses the + operator for both addition and concatenation. Numbers are added, strings are concatenated.