VFMT_$INTRO Domain/OS VFMT_$INTRO
NAME
intro - variable formatting package
SYNOPSIS (C)
#include <apollo/base.h>
#include <apollo/vfmt.h>
SYNOPSIS (Pascal)
%include '/sys/ins/base.ins.pas';
%include '/sys/ins/vfmt.ins.pas';
SYNOPSIS (FORTRAN)
%include '/sys/ins/base.ins.ftn'
%include '/sys/ins/vfmt.ins.ftn'
DESCRIPTION
The vfmt_$ calls facilitate formatted I/O, and arithmetic-to-ASCII
conversions. They are most useful in Pascal or FORTRAN programs because
their functionality largely overlaps that of C's stdio package.
The following is a list of the vfmt_$ calls.
vfmt_$decode10 formatted read from a string
vfmt_$decode2
vfmt_$decode5
vfmt_$encode formatted write to a string
vfmt_$encode10
vfmt_$encode2
vfmt_$encode5
vfmt_$read10 formatted read from standard input
vfmt_$read2
vfmt_$read5
vfmt_$rs10 formatted read from a stream
vfmt_$rs2
vfmt_$rs5
vfmt_$write formatted write to standard output
vfmt_$write10
vfmt_$write2
vfmt_$write5
vfmt_$ws formatted write to a stream
vfmt_$ws10
vfmt_$ws2
vfmt_$ws5
Control Strings
All vfmt_$ calls take a control string argument. The control string
defines fields in an ASCII string that correspond to source or destina-
tion variables also provided in the call. Each vfmt_$ call either writes
data from source variables into fields of an ASCII string defined by the
control string, or reads ASCII data fields defined by the control string
into destination variables. The control string defines the types and the
sizes of the data fields in the ASCII string, which must be compatible
with the types of the source or destination variables. Control strings
are made up of "format directives" that begin with a percent sign (%) and
end with some terminating character defining their function. The vfmt_$
calls ignore case in their control strings.
Data Directives
Each data field is defined by a single format directive in the control
string. The vfmt_$ calls recognize six different data formats: ASCII
(%A), decimal (%D), scientific (%E), floating (%F), hexadecimal (%H), and
octal (%O). Each basic data directive can take options between the per-
cent sign and the terminating format character that modify the field
definition. The following table summarizes the options appropriate for
each data directive.
_______________________________________________________________________
| Data-Related Format Directives |
|______________________________________________________________________|
| [Options] Directive Function |
|______________________________________________________________________|
|% [fw][M length][E][Z][K][U|L] A encode/decode ASCII |
|______________________________________________________________________|
|% [fw][E][Z][J][U|S|P][W|L] D encode/decode integer decimal |
|______________________________________________________________________|
|% [fw|fw.dr][Z][J][S|P][W|L] E encode scientific floating |
|______________________________________________________________________|
|% [fw|fw.dr][E][Z][J][S|P][W|L] F encode/decode floating point |
|______________________________________________________________________|
|% [fw][E][Z][J][U|S|P][W|L][Y] H encode/decode integer hexadecimal |
|______________________________________________________________________|
|% [fw][E][Z][J][U|S|P][W|L] O encode/decode integer octal |
|______________________________________________________________________|
ASCII Data (%A)
The %A directive is used to define ASCII fields, and can be used in con-
trol strings with both read and write calls.
The options have the following effects on ASCII data:
fw Fw is an integer between 1 and 65536 inclusive, indicating the
width of the field. A field width option means read or write
exactly this many characters, padding with blanks if necessary,
unless overridden by the Z, E, or M options. If no field width
is specified, a vfmt_$ call will read or write only non-blank
characters.
M length
Length is an integer between 1 and 65536 inclusive, indicating
the number of significant bytes in a source variable, or the
number of bytes provided in a destination buffer. The M option
can be used to specify the number of bytes read from a source
variable or written to a destination variable. If the M option
is not used and there is no fw specifier, a read call will look
at the value passed in a destination variable allocated to
receive a string length.
E The E option is only valid in read calls, where it forces early
termination of a data field when a delimiter is encountered.
The default delimiters are blank and comma, but other delim-
iters can be declared with the %"..." directive.
K The K option is only valid in read calls, where it means ignore
leading spaces in the input field; that is, spaces that precede
the first visible character. K overrides E.
Z The Z option means include trailing spaces in the data field;
that is, spaces that follow the last visible character. The Z
option causes write calls to include trailing spaces from the
source variable in the output. The Z option causes read calls
to include trailing spaces from the input field when filling
the destination variable. Without Z, trailing blanks are
ignored.
L The L option means convert all characters read or written to
lowercase. It is not valid with the U option.
U The U option means convert all characters read or written to
uppercase. It is not valid with the L option.
Floating-Point Data (%E and %F)
The %E and %F directives are used to define floating-point fields. The
%E directive is only valid in write calls, but the %F directive can be
used in any control string.
The options have the following effects on floating-point data:
fw Fw is an integer between 1 and 100 inclusive, indicating the
total width of the data field including integer and fractional
parts of the mantissa, the sign, decimal point, and exponent
(if any). In a write call, if the field width specified is too
small to contain the value to be written, the field will be
filled with asterisks (*) to indicate an overflow condition.
If no field width is specified, a write call uses a field just
large enough to hold the value, and a read call stops at the
first field delimiter it encounters.
dw Dw is an integer specifying the width of the fractional part of
the mantissa; that is, the number of digits to the right of the
decimal point. It is only valid in write calls, and the
default is 2.
E The E option is only valid in read calls, where it forces early
termination of a data field when a delimiter is encountered.
The default delimiters are blank and comma, but other delim-
iters can be declared with the %"..." directive. The E option
overrides the field width specifier.
Z The Z option is only valid in write calls, where it means add
zeros (0) to the left of the number to fill the output data
field. Z is not valid without a field width specifier (fw).
J The J option is only valid in write calls, where it means
left-justify the number in the output data field. Without the
J option, numbers are right justified in the field.
S The S option means the number to be read or written has a minus
sign if it is negative, and no sign if it is positive. This is
the default unless the P option is specified. S is always
redundant for read calls because ASCII data must be signed if
negative.
P The P option is only valid in write calls, and means prepend a
minus sign to the number if it is negative, and prepend a plus
sign if it is positive.
W The W option means the number to be read or written is a
single-precision floating-point value. If W is not specified,
L is the default.
L The L option means the number to be read or written is a
double-precision floating-point value. It is not a valid
option if W is specified.
Integer Data (%D, %H, and %O)
The %D, %H, and %O directives are used to define integer fields. They
can be used in both read and write calls.
fw Fw is an integer between 1 and 65536 inclusive, indicating the
minimum width of the data field. If the specified field width
is too small to hold the number, the field is widened to accom-
modate the number. If no field width is specified, a write
call uses a field just large enough to hold the value, and a
read call stops at the first field delimiter it encounters.
E The E option is only valid in read calls, where it forces early
termination of a data field when a delimiter is encountered.
The default delimiters are blank and comma, but other delim-
iters can be declared with the %"..." directive. The E option
overrides the field width specifier.
Z The Z option is only valid in write calls, where it means add
zeros (0) to the left of the number to fill the output data
field. Z is not valid without a field width specifier (fw).
J The J option is only valid in write calls, where it means
left-justify the number in the output data field. Without the
J option, numbers are right justified in the field.
U The U option means the number to be read or written is
unsigned, and the call should ignore any evidence to the con-
trary. A write call will write an unsigned (and possibly very
large) positive integer into the field even if the source vari-
able appears negative. A read call will ignore plus and minus
signs in the data field. The U option is most often used when
writing via the %H and %O directives.
S The S option means the number to be read or written has a minus
sign if it is negative, and no sign if it is positive. This is
the default unless the P option is specified. S is always
redundant for read calls because ASCII data must be signed if
negative.
P The P option is only valid in write calls, and means prepend a
minus sign to the number if it is negative, and prepend a plus
sign if it is positive.
W The W option means the number to be read or written is a 2-byte
integer value. If W is not specified, L is the default.
L The L option means the number to be read or written is a 4-byte
integer value. It is not a valid option if W is specified.
Y The Y option means write hexadecimal integers with lowercase
letters instead of uppercase. It is only valid with hexade-
cimal output fields in write call control strings.
Control String Directives
The control string directives modify a call's interpretation of the con-
trol string passed to it. The following table summarizes the control
string directives:
_______________________________________________________________
Control String-Related Format Directives
|______________________________________________________________|
|Directive Function |
|__________|___________________________________________________|
|%"..." | declare characters to be used as field delimiters |
|__________|___________________________________________________|
|%$ | end control string |
|__________|___________________________________________________|
|%. | end control string, inserting new line character |
|__________|___________________________________________________|
|%n( | repeat string n times start |
|__________|___________________________________________________|
|%) | repeat string n times stop |
|__________|___________________________________________________|
| | |
%"..."
The %"..." directive defines the field delimiters that read calls
use when the E option is specified in a data directive. When the
%"..." directive appears in a control string, the characters between
the double quotes, following the percent sign, become the field del-
imiters for that string. If no %"..." directive appears, then the
read call uses the default delimiters, comma (,) and space ( ),
equivalent to %", ". For example, %", "";" adds a double quote (")
and semicolon (;) to the default delimiters.
%$ The %$ directive marks the end of a control string. It has no other
effect.
%. The %. directive marks the end of a control string too. When used
in a write call, it also means add a record terminator to the out-
put. The record terminator is usually an ASCII newline character.
When used in a read call, "%." is identical to "%$".
%n( and %)
Together, the %n( and %) directives delimit a portion of a control
string to be repeated n times. N is required, and must be an
integer between 1 and 65536 inclusive. For example, the fragment
"%5( ... %)" is identical to writing the delimited portion, denoted
here as "..." five times in succession in the control string that
contains it. Repeat directives cannot be nested.
Format Directives
The format directives modify the format of input or output between data
fields. The following table summarizes the format directives:
_________________________________________________
| Format-Related Format Directives |
|________________________________________________|
|Directive | Function |
|__________|_____________________________________|
|%% | write a single % |
|__________|_____________________________________|
|%/ | write a record terminator |
|__________|_____________________________________|
|%nT | tab to column n |
|__________|_____________________________________|
|%nX | skip n characters |
|__________|_____________________________________|
|%n@ | move argument pointer to argument n |
|__________|_____________________________________|
%% When a write call encounters a "%%" in a control string, it writes a
single percent sign (%) to the output.
%/ When a write call encounters a "%/" in a control string, it writes a
record terminator to the output. The record terminator is usually
an ASCII newline character.
%nT The %nT directive causes a read or write call to tab to column n
before interpreting the control string further. N is optional; if
it is omitted (%T), the call uses the next variable in the calling
sequence for the tab value. Write calls use space as the tab fill
character.
%nX The %nX directive causes a read or write call to skip n spaces
before interpreting the control string further. The directive
causes a write call to write n spaces to the output, and causes a
read call to skip n characters in the input. N is optional; if it
is omitted (%X), the call uses the next variable in the calling
sequence for the number of spaces.
%n@ The %n@ directive causes a write call to move it's argument pointer
to the nth source argument. It allows programs interpret source
arguments in an order specified by the control string, but does not
generate any output. For example, "%1@" resets the argument
pointer. N is required.
Data Types
vfmt_$string_t
A 200-byte array for passing control strings to vfmt_$ calls.
Errors
vfmt_$unterminated_ctl_string
Unterminated control string.
vfmt_$invalid_ctl_string
Invalid control string.
vfmt_$too_few_args
Too few arguments supplied for a read or decode call.
vfmt_$fw_required
Field width missing on "(" designator.
vfmt_$eos
Encountered end of string where more text was expected.
vfmt_$null_token
Encountered null token where numeric token was expected.
vfmt_$nonnumeric_char
Non-numeric character found where numeric was expected.
vfmt_$sign_not_allowed
Sign encountered in unsigned field.
vfmt_$value_too_large
Value out of range in text string.
vfmt_$nonmatching_char
Character in text string does not match control string.
vfmt_$nonmatching_delimiter
Terminator in text string does not match specified terminator.