### 4.3 Standard Formatted I/O ¶

#### 4.3.1 stdio ¶

`(require 'stdio)`

`require`s `printf` and `scanf` and additionally defines the symbols:

Variable: stdin ¶

  Defined to be `(current-input-port)`.

Variable: stdout ¶

  Defined to be `(current-output-port)`.

Variable: stderr ¶

  Defined to be `(current-error-port)`.

#### 4.3.2 Standard Formatted Output ¶

`(require 'printf)`

Procedure: printf format arg1 … ¶
Procedure: fprintf port format arg1 … ¶
Procedure: sprintf str format arg1 … ¶
Procedure: sprintf #f format arg1 … ¶
Procedure: sprintf k format arg1 … ¶

  Each function converts, formats, and outputs its arg1 … arguments according to the control string format argument and returns the number of characters output.

  `printf` sends its output to the port `(current-output-port)`. `fprintf` sends its output to the port port. `sprintf` `string-set!`s locations of the non-constant string argument str to the output characters.

  Two extensions of `sprintf` return new strings. If the first argument is `#f`, then the returned string’s length is as many characters as specified by the format and data; if the first argument is a non-negative integer k, then the length of the returned string is also bounded by k.

  The string format contains plain characters which are copied to the output stream, and conversion specifications, each of which results in fetching zero or more of the arguments arg1 …. The results are undefined if there are an insufficient number of arguments for the format. If format is exhausted while some of the arg1 … arguments remain unused, the excess arg1 … arguments are ignored.

  The conversion specifications in a format string have the form:

      % [ flags ] [ width ] [ . precision ] [ type ] conversion

  An output conversion specifications consist of an initial ‘`%`’ character followed in sequence by:

  - Zero or more flag characters that modify the normal behavior of the conversion specification.
    ‘`-`’

      Left-justify the result in the field. Normally the result is right-justified.

    ‘`+`’

      For the signed ‘`%d`’ and ‘`%i`’ conversions and all inexact conversions, prefix a plus sign if the value is positive.

    ‘`` ’

      For the signed ‘`%d`’ and ‘`%i`’ conversions, if the result doesn’t start with a plus or minus sign, prefix it with a space character instead. Since the ‘`+`’ flag ensures that the result includes a sign, this flag is ignored if both are specified.

    ‘`#`’

      For inexact conversions, ‘`#`’ specifies that the result should always include a decimal point, even if no digits follow it. For the ‘`%g`’ and ‘`%G`’ conversions, this also forces trailing zeros after the decimal point to be printed where they would otherwise be elided.

      For the ‘`%o`’ conversion, force the leading digit to be ‘`0`’, as if by increasing the precision. For ‘`%x`’ or ‘`%X`’, prefix a leading ‘`0x`’ or ‘`0X`’ (respectively) to the result. This doesn’t do anything useful for the ‘`%d`’, ‘`%i`’, or ‘`%u`’ conversions. Using this flag produces output which can be parsed by the `scanf` functions with the ‘`%i`’ conversion (see Standard Formatted Input).

    ‘`0`’

      Pad the field with zeros instead of spaces. The zeros are placed after any indication of sign or base. This flag is ignored if the ‘`-`’ flag is also specified, or if a precision is specified for an exact converson.

  - An optional decimal integer specifying the minimum field width. If the normal conversion produces fewer characters than this, the field is padded (with spaces or zeros per the ‘`0`’ flag) to the specified width. This is a minimum width; if the normal conversion produces more characters than this, the field is not truncated.

    Alternatively, if the field width is ‘`*`’, the next argument in the argument list (before the actual value to be printed) is used as the field width. The width value must be an integer. If the value is negative it is as though the ‘`-`’ flag is set (see above) and the absolute value is used as the field width.

  - An optional precision to specify the number of digits to be written for numeric conversions and the maximum field width for string conversions. The precision is specified by a period (‘`.`’) followed optionally by a decimal integer (which defaults to zero if omitted).

    Alternatively, if the precision is ‘`.*`’, the next argument in the argument list (before the actual value to be printed) is used as the precision. The value must be an integer, and is ignored if negative. If you specify ‘`*`’ for both the field width and precision, the field width argument precedes the precision argument. The ‘`.*`’ precision is an enhancement. C library versions may not accept this syntax.

    For the ‘`%f`’, ‘`%e`’, and ‘`%E`’ conversions, the precision specifies how many digits follow the decimal-point character. The default precision is `6`. If the precision is explicitly `0`, the decimal point character is suppressed.

    For the ‘`%g`’ and ‘`%G`’ conversions, the precision specifies how many significant digits to print. Significant digits are the first digit before the decimal point, and all the digits after it. If the precision is `0` or not specified for ‘`%g`’ or ‘`%G`’, it is treated like a value of `1`. If the value being printed cannot be expressed accurately in the specified number of digits, the value is rounded to the nearest number that fits.

    For exact conversions, if a precision is supplied it specifies the minimum number of digits to appear; leading zeros are produced if necessary. If a precision is not supplied, the number is printed with as many digits as necessary. Converting an exact ‘`0`’ with an explicit precision of zero produces no characters.

  - An optional one of ‘`l`’, ‘`h`’ or ‘`L`’, which is ignored for numeric conversions. It is an error to specify these modifiers for non-numeric conversions.
  - A character that specifies the conversion to be applied.

  Exact Conversions

  ‘`b`’, ‘`B`’

    Print an integer as an unsigned binary number.

    Note: ‘`%b`’ and ‘`%B`’ are SLIB extensions.

  ‘`d`’, ‘`i`’

    Print an integer as a signed decimal number. ‘`%d`’ and ‘`%i`’ are synonymous for output, but are different when used with `scanf` for input (see Standard Formatted Input).

  ‘`o`’

    Print an integer as an unsigned octal number.

  ‘`u`’

    Print an integer as an unsigned decimal number.

  ‘`x`’, ‘`X`’

    Print an integer as an unsigned hexadecimal number. ‘`%x`’ prints using the digits ‘`0123456789abcdef`’. ‘`%X`’ prints using the digits ‘`0123456789ABCDEF`’.

  Inexact Conversions

  ‘`f`’

    Print a floating-point number in fixed-point notation.

  ‘`e`’, ‘`E`’

    Print a floating-point number in exponential notation. ‘`%e`’ prints ‘`e`’ between mantissa and exponont. ‘`%E`’ prints ‘`E`’ between mantissa and exponont.

  ‘`g`’, ‘`G`’

    Print a floating-point number in either fixed or exponential notation, whichever is more appropriate for its magnitude. Unless an ‘`#`’ flag has been supplied, trailing zeros after a decimal point will be stripped off. ‘`%g`’ prints ‘`e`’ between mantissa and exponont. ‘`%G`’ prints ‘`E`’ between mantissa and exponent.

  ‘`k`’, ‘`K`’

    Print a number like ‘`%g`’, except that an SI prefix is output after the number, which is scaled accordingly. ‘`%K`’ outputs a dot between number and prefix, ‘`%k`’ does not.

  Other Conversions

  ‘`c`’

    Print a single character. The ‘`-`’ flag is the only one which can be specified. It is an error to specify a precision.

  ‘`s`’

    Print a string. The ‘`-`’ flag is the only one which can be specified. A precision specifies the maximum number of characters to output; otherwise all characters in the string are output.

  ‘`a`’, ‘`A`’

    Print a scheme expression. The ‘`-`’ flag left-justifies the output. The ‘`#`’ flag specifies that strings and characters should be quoted as by `write` (which can be read using `read`); otherwise, output is as `display` prints. A precision specifies the maximum number of characters to output; otherwise as many characters as needed are output.

    Note: ‘`%a`’ and ‘`%A`’ are SLIB extensions.

  ‘`%`’

    Print a literal ‘`%`’ character. No argument is consumed. It is an error to specify flags, field width, precision, or type modifiers with ‘`%%`’.

#### 4.3.3 Standard Formatted Input ¶

`(require 'scanf)`

Function: scanf-read-list format ¶
Function: scanf-read-list format port ¶
Function: scanf-read-list format string ¶

Macro: scanf format arg1 … ¶
Macro: fscanf port format arg1 … ¶
Macro: sscanf str format arg1 … ¶

  Each function reads characters, interpreting them according to the control string format argument.

  `scanf-read-list` returns a list of the items specified as far as the input matches format. `scanf`, `fscanf`, and `sscanf` return the number of items successfully matched and stored. `scanf`, `fscanf`, and `sscanf` also set the location corresponding to arg1 … using the methods:

  symbol

    `set!`

  car expression

    `set-car!`

  cdr expression

    `set-cdr!`

  vector-ref expression

    `vector-set!`

  substring expression

    `substring-move-left!`

  The argument to a `substring` expression in arg1 … must be a non-constant string. Characters will be stored starting at the position specified by the second argument to `substring`. The number of characters stored will be limited by either the position specified by the third argument to `substring` or the length of the matched string, whichever is less.

  The control string, format, contains conversion specifications and other characters used to direct interpretation of input sequences. The control string contains:

  - White-space characters (blanks, tabs, newlines, or formfeeds) that cause input to be read (and discarded) up to the next non-white-space character.
  - An ordinary character (not ‘`%`’) that must match the next character of the input stream.
  - Conversion specifications, consisting of the character ‘`%`’, an optional assignment suppressing character ‘`*`’, an optional numerical maximum-field width, an optional ‘`l`’, ‘`h`’ or ‘`L`’ which is ignored, and a conversion code.

  Unless the specification contains the ‘`n`’ conversion character (described below), a conversion specification directs the conversion of the next input field. The result of a conversion specification is returned in the position of the corresponding argument points, unless ‘`*`’ indicates assignment suppression. Assignment suppression provides a way to describe an input field to be skipped. An input field is defined as a string of characters; it extends to the next inappropriate character or until the field width, if specified, is exhausted.

  > Note: This specification of format strings differs from the ANSI C and POSIX specifications. In SLIB, white space before an input field is not skipped unless white space appears before the conversion specification in the format string. In order to write format strings which work identically with ANSI C and SLIB, prepend whitespace to all conversion specifications except ‘`[`’ and ‘`c`’.

  The conversion code indicates the interpretation of the input field; For a suppressed field, no value is returned. The following conversion codes are legal:

  ‘`%`’

    A single % is expected in the input at this point; no value is returned.

  ‘`d`’, ‘`D`’

    A decimal integer is expected.

  ‘`u`’, ‘`U`’

    An unsigned decimal integer is expected.

  ‘`o`’, ‘`O`’

    An octal integer is expected.

  ‘`x`’, ‘`X`’

    A hexadecimal integer is expected.

  ‘`i`’

    An integer is expected. Returns the value of the next input item, interpreted according to C conventions; a leading ‘`0`’ implies octal, a leading ‘`0x`’ implies hexadecimal; otherwise, decimal is assumed.

  ‘`n`’

    Returns the total number of bytes (including white space) read by `scanf`. No input is consumed by `%n`.

  ‘`f`’, ‘`F`’, ‘`e`’, ‘`E`’, ‘`g`’, ‘`G`’

    A floating-point number is expected. The input format for floating-point numbers is an optionally signed string of digits, possibly containing a radix character ‘`.`’, followed by an optional exponent field consisting of an ‘`E`’ or an ‘`e`’, followed by an optional ‘`+`’, ‘`-`’, or space, followed by an integer.

  ‘`c`’, ‘`C`’

    Width characters are expected. The normal skip-over-white-space is suppressed in this case; to read the next non-space character, use ‘`%1s`’. If a field width is given, a string is returned; up to the indicated number of characters is read.

  ‘`s`’, ‘`S`’

    A character string is expected The input field is terminated by a white-space character. `scanf` cannot read a null string.

  ‘`[`’

    Indicates string data and the normal skip-over-leading-white-space is suppressed. The left bracket is followed by a set of characters, called the scanset, and a right bracket; the input field is the maximal sequence of input characters consisting entirely of characters in the scanset. ‘`^`’, when it appears as the first character in the scanset, serves as a complement operator and redefines the scanset as the set of all characters not contained in the remainder of the scanset string. Construction of the scanset follows certain conventions. A range of characters may be represented by the construct first-last, enabling ‘`[0123456789]`’ to be expressed ‘`[0-9]`’. Using this convention, first must be lexically less than or equal to last; otherwise, the dash stands for itself. The dash also stands for itself when it is the first or the last character in the scanset. To include the right square bracket as an element of the scanset, it must appear as the first character (possibly preceded by a ‘`^`’) of the scanset, in which case it will not be interpreted syntactically as the closing bracket. At least one character must match for this conversion to succeed.

  The `scanf` functions terminate their conversions at end-of-file, at the end of the control string, or when an input character conflicts with the control string. In the latter case, the offending character is left unread in the input stream.