Previous: Numeric Formatting Styles, Up: Input and Output Formats


2.2.5 Formatted Data Input and Output

These functions provide the ability to convert data fields into union values and vice versa.

— Function: bool data_in (struct substring input, enum legacy_encoding legacy_encoding, enum fmt_type type, int implied_decimals, int first_column, union value *output, int width)

Parses input as a field containing data in the given format type. The resulting value is stored in output, which has the given width. For consistency, width must be 0 if type is a numeric format type and greater than 0 if type is a string format type.

Ordinarily legacy_encoding should be LEGACY_NATIVE, indicating that input is encoded in the character set conventionally used on the host machine. It may be set to LEGACY_EBCDIC to cause input to be re-encoded from EBCDIC during data parsing.

If input is the empty string (with length 0), output is set to the value set on SET BLANKS (see SET BLANKS) for a numeric value, or to all spaces for a string value. This applies regardless of the usual parsing requirements for type.

If implied_decimals is greater than zero, then the numeric result is shifted right by implied_decimals decimal places if input does not contain a decimal point character or an exponent. Only certain numeric format types support implied decimal places; for string formats and other numeric formats, implied_decimals has no effect. DATA LIST FIXED is the primary user of this feature (see DATA LIST FIXED). Other callers should generally specify 0 for implied_decimals, to disable this feature.

When input contains invalid input data, data_in outputs a message using msg. If first_column is nonzero, it is included in any such error message as the 1-based column number of the start of the field. The last column in the field is calculated as first_column + input - 1. To suppress error output, enclose the call to data_in by calls to msg_disable and msg_enable.

This function returns true on success, false if a message was output (even if suppressed). Overflow and underflow provoke warnings but are not propagated to the caller as errors.

This function is declared in data/data-in.h.

— Function: void data_out (const union value *input, const struct fmt_spec *format, char *output)
— Function: void data_out_legacy (const union value *input, enum legacy_encoding legacy_encoding, const struct fmt_spec *format, char *output)

Converts the data pointed to by input into a data field in output according to output format specifier format, which must be a valid output format. Exactly format->w bytes are written to output. The width of input is also inferred from format using an algorithm equivalent to fmt_var_width.

If data_out is called, or data_out_legacy is called with legacy_encoding set to LEGACY_NATIVE, output will be encoded in the character set conventionally used on the host machine. If legacy_encoding is set to LEGACY_EBCDIC, output will be re-encoded from EBCDIC during data output.

When input contains data that cannot be represented in the given format, data_out may output a message using msg, although the current implementation does not consistently do so. To suppress error output, enclose the call to data_out by calls to msg_disable and msg_enable.

This function is declared in data/data-out.h.