Next: Numeric Formatting Styles, Previous: Format Utility Functions, Up: Input and Output Formats [Contents][Index]
These functions work with enum fmt_type
s instead of the higher-level
struct fmt_spec
s. Their primary purpose is to report properties of
each possible format type, which in turn allows clients to abstract
away many of the details of the very heterogeneous requirements of
each format type.
The first group of functions works with format type names.
Returns the name for the given type, e.g. "COMMA"
for
FMT_COMMA
.
Tries to find the enum fmt_type
associated with name. If
successful, sets *type
to the type and returns true;
otherwise, returns false without modifying *type
.
The functions below query basic limits on width and decimal places for each kind of format.
Returns true if a format of the given type is allowed to have a
nonzero number of decimal places (the d
member of
struct fmt_spec
), false if not.
Returns the minimum or maximum width (the w
member of
struct fmt_spec
) allowed for an input or output format of the
specified type.
Returns the maximum number of decimal places allowed for an input or output format, respectively, of the given type and width. Returns 0 if the specified type does not allow any decimal places or if width is too narrow to allow decimal places.
Returns the “width step” for a struct fmt_spec
of the given
type. A struct fmt_spec
’s width must be a multiple of its
type’s width step. Most format types have a width step of 1, so that
their formats’ widths may be any integer within the valid range, but
hexadecimal numeric formats and AHEX string formats have a width step
of 2.
These functions allow clients to broadly determine how each kind of input or output format behaves.
Returns true if type is a format for numeric or string values, respectively, false otherwise.
Returns the category within which type falls.
A group of format types. Format type categories correspond to the input and output categories described in the PSPP user documentation (see Input and Output Formats in PSPP Users Guide).
Each format is in exactly one category. The categories have bitwise disjoint values to make it easy to test whether a format type is in one of multiple categories, e.g.
if (fmt_get_category (type) & (FMT_CAT_DATE | FMT_CAT_TIME))
{
/* …type
is a date or time format… */
}
The format categories are:
FMT_CAT_BASIC
Basic numeric formats.
FMT_CAT_CUSTOM
Custom currency formats.
FMT_CAT_LEGACY
Legacy numeric formats.
FMT_CAT_BINARY
Binary formats.
FMT_CAT_HEXADECIMAL
Hexadecimal formats.
FMT_CAT_DATE
Date formats.
FMT_CAT_TIME
Time formats.
FMT_CAT_DATE_COMPONENT
Date component formats.
FMT_CAT_STRING
String formats.
The PSPP input and output routines use the following pair of functions
to convert enum fmt_type
s to and from the separate set of codes used
in system and portable files:
Returns the format code used in system and portable files that corresponds to type.
Converts io, a format code used in system and portable files,
into a enum fmt_type
in *type
. Returns true if
successful, false if io is not valid.
These functions reflect the relationship between input and output formats.
Returns the output format type that is used by default by DATA LIST and other input procedures when type is specified as an input format. The conversion from input format to output format is more complicated than simply changing the format. See fmt_for_output_from_input, for a function that performs the entire conversion.
Returns true if type may be used as an input format type, false otherwise. The custom currency formats, in particular, may be used for output but not for input.
All format types are valid for output.
The final group of format type property functions obtain human-readable templates that illustrate the formats graphically.
Returns a formatting template for type, which must be a date or
time format type. These formats are used by data_in
and
data_out
to guide parsing and formatting date and time data.
Returns a string of the form $#,###.##
according to
format, which must be of type FMT_DOLLAR
. The caller
must free the string with free
.
Next: Numeric Formatting Styles, Previous: Format Utility Functions, Up: Input and Output Formats [Contents][Index]