.ds Vv 1.2.14
.TH VistaIOConst 3 "26 January 1994" "VistaIO Version \*(Vv"
.SH NAME
VistaIOConst \- generate constants of the appropriate type
.SH SYNOPSIS
.B "VistaIOFloat VistaIOFloatConst (\fIf\fP)"
.PP
.B "VistaIODouble VistaIODoubleConst (\fIf\fP)"
.PP
.B "VistaIOBit VistaIOBitConst (\fIi\fP)"
.PP
.B "VistaIOUByte VistaIOUByteConst (\fIi\fP)"
.PP
.B "VistaIOSByte VistaIOSByteConst (\fIi\fP)"
.PP
.B "VistaIOShort VistaIOShortConst (\fIi\fP)"
.PP
.B "VistaIOLong VistaIOLongConst (\fIi\fP)"
.SH ARGUMENTS
.IP \fIf\fP 10n
Specifies a floating-point constant.
.IP \fIi\fP 10n
Specifies an integer constant.
.SH DESCRIPTION
In expressions that get executed within inner loops, you may wish to avoid
unnecessary coercions between the C types \fBfloat\fP and \fBdouble\fP, or
between \fBint\fP and \fBlong\fP. By allowing you to specify constants of
the appropriate type in a portable, platform-independent manner, these
macros allow you to avoid unintended coercions.
.PP
In ANSI C, one can specify that a floating point constant is of type
\fBfloat\fP be appending an \fBf\fP character to it. This can be used to
avoid coercions in expressions involving other \fBfloat\fP values. For
example, this fragment of code uses a \fBfloat\fP constant within its loop:
.PP
.RS
.nf
.ft B
int i;
float f = 0.0;

for (i = 0; i < 10000000; i++)
    f += 1.0f;
.fi
.RE
.PP
It runs about three times faster than this one, which uses a \fBdouble\fP
constant:
.PP
.RS
.nf
.ft B
int i;
float f = 0.0;

for (i = 0; i < 10000000; i++)
    f += 1.0;
.fi
.RE
.PP
The \fBVistaIOFloatConst\fP and \fBVistaIODoubleConst\fP macros allow you to avoid
unnecessary coercions in expressions involving values of type \fBVistaIOFloat\fP
and \fBVistaIODouble\fP.  Whether or not \fBVistaIOFloat\fP and \fBVistaIODouble\fP are
equivalent to \fBfloat\fP and \fBdouble\fP may depend on what platform your
code is being compiled for.  Regardless, you can generate constants of the
appropriate type by using the \fBVistaIOFloatConst\fP and \fBVistaIODoubleConst\fP macros.
On a platform where \fBVistaIOFloat\fP is defined as \fBfloat\fP,
\fBVistaIOFloatConst(1.0)\fP expands to \fB1.0f\fP; where \fBVistaIOFloat\fP is defined
as \fBdouble\fP, it expands to \fB1.0\fP.  Similarly, \fBVistaIODoubleConst\fP
may or may not append an \fBf\fP character to the constant, depending on
how \fBVistaIODouble\fP is defined.
.PP
Similarly, the \fBVistaIOBitConst\fP, \fBVistaIOUByteConst\fP, \fBVistaIOSByteConst\fP,
\fBVistaIOShortConst\fP, and \fBVistaIOLongConst\fP take an integer constant; each one,
depending on the platform, may or may not append an \fBl\fP character to
the constant to specify that it is of type \fBlong\fP. On platforms where
\fBint\fP and \fBlong\fP have different representations, using these macros
may prevent unintended coercions between the two representations.
.PP
So if your want your inner loops to run blindingly fast on any platform,
you should write them like this to avoid unnecessary coercions:
.PP
.RS
.nf
.ft B
int i;
VistaIOFloat f = 0.0;

for (i = 0; i < 10000000; i++)
    f += VistaIOFloatConst (1.0);
.fi
.RE
.SH "SEE ALSO"
.BR VistaIORepn (3),

.SH NOTES
The macros can be used with a C compiler that doesn't meet the ANSI standard,
but in that case they may not eliminate all type coercions between
\fBfloat\fP and \fBdouble\fP.
.PP
If you're more concerned about your code being easy to read, you may be
better off not using these macros.
.SH AUTHOR
Art Pope <pope@cs.ubc.ca>

Adaption to vistaio: Gert Wollny <gw.fossdev@gmail.com>