---

2.2.3 Obtaining Properties of Format Types

These functions work with enum fmt_types instead of the higher-level struct fmt_specs. 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.

Function: const char *fmt_name (enum fmt_type type) ¶

Returns the name for the given type, e.g. "COMMA" for FMT_COMMA.

Function: bool fmt_from_name (const char *name, enum fmt_type *type) ¶

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.

Function: bool fmt_takes_decimals (enum fmt_type type) ¶

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.

Function: int fmt_min_input_width (enum fmt_type type) ¶

Function: int fmt_max_input_width (enum fmt_type type) ¶

Function: int fmt_min_output_width (enum fmt_type type) ¶

Function: int fmt_max_output_width (enum fmt_type type) ¶

Returns the minimum or maximum width (the w member of struct fmt_spec) allowed for an input or output format of the specified type.

Function: int fmt_max_input_decimals (enum fmt_type type, int width) ¶

Function: int fmt_max_output_decimals (enum fmt_type type, int width) ¶

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.

Function: int fmt_step_width (enum fmt_type type) ¶

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.

Function: bool fmt_is_string (enum fmt_type type) ¶

Function: bool fmt_is_numeric (enum fmt_type type) ¶

Returns true if type is a format for numeric or string values, respectively, false otherwise.

Function: enum fmt_category fmt_get_category (enum fmt_type type) ¶

Returns the category within which type falls.

Enumeration: enum fmt_category ¶

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_types to and from the separate set of codes used in system and portable files:

Function: int fmt_to_io (enum fmt_type type) ¶

Returns the format code used in system and portable files that corresponds to type.

Function: bool fmt_from_io (int io, enum fmt_type *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.

Function: enum fmt_type fmt_input_to_output (enum fmt_type type) ¶

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.

Function: bool fmt_usable_for_input (enum fmt_type type) ¶

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.

Function: const char *fmt_date_template (enum fmt_type type) ¶

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.

Function: char *fmt_dollar_template (const struct fmt_spec *format) ¶

Returns a string of the form $#,###.## according to format, which must be of type FMT_DOLLAR. The caller must free the string with free.