MAINSAIL Language Manual, Section 32.95

previous   next   top   contents   index   framed top   this page unframed

32.95. cvs

Figure 32–105. cvs (GENERIC)
STRING
PROCEDURE   cvs         (BOOLEAN v;
                         OPTIONAL POINTER($area) area);

COMPILETIME
STRING
PROCEDURE   cvs         (INTEGER i;
                         OPTIONAL POINTER($area) area);

STRING
PROCEDURE   cvs         (BITS b;
                         OPTIONAL BITS form;
                         OPTIONAL POINTER($area) area);

STRING
PROCEDURE   cvs         (REAL x;
                         OPTIONAL BITS form;
                         OPTIONAL POINTER($area) area);

COMPILETIME
STRING
PROCEDURE   cvs         (LONG INTEGER i;
                         OPTIONAL POINTER($area) area);

STRING
PROCEDURE   cvs         (LONG REAL x;
                         OPTIONAL BITS form;
                         OPTIONAL POINTER($area) area);

STRING
PROCEDURE   cvs         (LONG BITS b;
                         OPTIONAL BITS form;
                         OPTIONAL POINTER($area) area);

$BUILTIN COMPILETIME
STRING
PROCEDURE   cvs         (STRING s);

cvs converts to STRING.

In all forms of cvs with an area parameter, area specifies the destination area for the resulting STRING if new STRING text is generated; see Section 29.4.

32.95.1. The BOOLEAN Form of cvs

The BOOLEAN form of cvs returns "TRUE" if the BOOLEAN value is TRUE and "FALSE" if it is FALSE.

32.95.2. The (LONG) INTEGER Forms of cvs

The (LONG) INTEGER forms convert to the STRING that is the MAINSAIL constant representation of i, except that the LONG INTEGER form does not append L.

Example 32–106. Use of (LONG) INTEGER Forms of cvs
cvs(123)                    = "123"
cvs(456L)                   = "456"

32.95.3. The (LONG) REAL Forms of cvs

The (LONG) REAL forms create the STRING that is the MAINSAIL constant representation of x, except that the LONG REAL form does not append L. The OPTIONAL form argument gives the programmer some control over the format. The rightmost 8 bits of form, i.e., cvi(form MSK 'HFF), specify the number of digits to follow the decimal point. Roundoff or addition of trailing zeros is used to make the proper number of fraction digits. If $minFractionDigits is specified, the rightmost 8 bits of form are not used.

The valid predefined BITS constants that may be set in form for the (LONG) REAL forms of cvs are as follows:

Bit Name Meaning
fixed Do not use an exponent.
exponent Do use an exponent.
$minFractionDigits Include only as many fraction digits as necessary to denote the value; suppress trailing zeros.
$leadingDigitBeforeDot Leading digit appears before decimal point.
$atLeastOneDigitAfterDot Include at least one fraction digit.
$includeDot Include a decimal point in the result even if there is no fraction part.

In the following discussion, representable digit means a (decimal) digit that can fit within the floating point representation in question. For example, on machines that follow the IEEE standard for floating point, REAL values have 7 representable digits, and LONG REALs, 16.

In the result, the exponent, if included, is always the letter E followed by a sign (+ or -) and at least two digits (with a leading 0 if the magnitude of the exponent is less than 10). If the result of cvs contains an exponent, because either the exponent bit was specified or the default representation of the value being converted includes an exponent, then the $leadingDigitBeforeDot bit controls whether or not all digits appear after the decimal point. If $leadingDigitBeforeDot is specified, the leftmost digit appears before the decimal point and any other digits appear after the decimal point. Otherwise, all digits appear after the decimal point.

If exponent is specified, $minFractionDigits is not specified, and form MSK 'HFF is Zero, then the number of digits in the result is the number of representable digits, minus one. The $leadingDigitBeforeDot bit controls whether or not all those digits appear after the decimal point.

If the result of cvs is fixed, either because the fixed bit was specified or the default representation of the value being converted does not contain an exponent, then the $leadingDigitBeforeDot bit controls whether or not a leading zero appears before the decimal point for values whose magnitudes are less than 1.

If fixed is specified but $minFractionDigits is not, the $atLeastOneDigitAfterDot bit is ignored. To obtain the effect of setting this bit, form MSK 'HFF should be non-Zero.

If the result of cvs has no fraction digits, the $includeDot bit controls whether or not the result contains a decimal point. If $includeDot is specified, the result always contains a decimal point. If $includeDot is not specified, the decimal point is omitted if there is no fraction part.

If none of the above bits is specified in form (the default), an attempt is made to give the simplest representation; form MSK 'HFF is not used. The width of the resulting STRINGs is not the same for every possible value.

When forming the default representation, roundoff occurs at the last representable digit if there are any fraction digits (this helps prevent values like .9999999 for 1). No exponent appears in the result STRING if the decimal point would fall immediately before, within, or immediately after the representable digits; otherwise, an exponent is used.

If form MSK 'HFF is Zero, and exponent is specified, the number of fraction digits is taken to be the number of representable digits in x, minus one.

Example 32–107. Use of (LONG) REAL Forms of cvs
cvs(123.456L,exponent) =
        ".123456000000000E+03"
cvs(123.456L,exponent!$minFractionDigits) =
        ".123456E+03"
cvs(123.456L,
    exponent!$minFractionDigits!$leadingDigitBeforeDot) =
        "1.23456E+02"

cvs(1.L,exponent!$minFractionDigits) =
        ".1E+01"
cvs(1.L,exponent!$minFractionDigits!$leadingDigitBeforeDot) =
        "1E+00"
cvs(1.L,
    exponent!$minFractionDigits!$leadingDigitBeforeDot
        !$includeDot) =
        "1.E+00"
cvs(1.L,
    exponent!$minFractionDigits!$leadingDigitBeforeDot
        !$atLeastOneDigitAfterDot) =
        "1.0E+00"

cvs(0.) =
        "0"
cvs(0.,$includeDot) =
        "0."
cvs(0.,$atLeastOneDigitAfterDot) =
        ".0"
cvs(0.,$leadingDigitBeforeDot!$atLeastOneDigitAfterDot) =
        "0.0"

cvs(1E10L,
    exponent!$minFractionDigits!$leadingDigitBeforeDot
        !$atLeastOneDigitAfterDot) =
        "1.0E+10"

cvs(1234.5E10L,
    exponent!$minFractionDigits!$leadingDigitBeforeDot
        !$atLeastOneDigitAfterDot) =
        "1.2345E+13"

32.95.4. The (LONG) BITS Forms of cvs

The (LONG) BITS forms create the STRING that is the MAINSAIL constant representation of b, except that the LONG BITS form does not append L. The form argument gives the programmer some control over the format. The valid BITS constants predefined for form are:

Bit Name Meaning
binary output in base 2
octal output in base 8
hex output in base 16
formatted precede constant with single quote and base letter, as in program text

The octal format is used if neither binary nor hex is specified. $preferredRadix may be used to determine the conventional radix for displaying (LONG) BITS values on the current system.

Example 32–108. Use of (LONG) BITS Forms of cvs
cvs('H123)                  = "443"
cvs('H123,formatted)        = "'O443"
cvs('H123,binary)           = "100100011"
cvs('H123,formatted!binary) = "'B100100011"
cvs('H123,hex)              = "123"
cvs('H123,formatted!hex)    = "'H123"

32.95.5. The STRING Form of cvs

The STRING form returns its argument.
previous   next   top   contents   index   framed top   this page unframed

MAINSAIL Language Manual, Section 32.95