# Unit extras

This unit contains a collection of useful utility definitions. This unit is used by default, unless the program is compiled with the `-explicit-use` option.

## Formatted output

### printf

### fprintf

### sprintf

    [procedure] (fprintf PORT FORMATSTRING ARG ...)
    [procedure] (printf FORMATSTRING ARG ...)
    [procedure] (sprintf FORMATSTRING ARG ...)

Simple formatted output to a given port (`fprintf`), the value of `(current-output-port)` (`printf`), or a string (`sprintf`). The `FORMATSTRING` can contain any sequence of characters. There must be at least as many `ARG` arguments given as there are format directives that require an argument in `FORMATSTRING`. Extra `ARG` arguments are ignored. The character `~' prefixes special formatting directives:

    ~%

write newline character

    ~N

the same as `~%`

    ~S

write the next argument

    ~A

display the next argument

    ~\n

skip all whitespace in the format-string until the next non-whitespace character

    ~B

write the next argument as a binary number

    ~O

write the next argument as an octal number

    ~X

write the next argument as a hexadecimal number

    ~C

write the next argument as a character

    ~~

display `~'

    ~!

flush all pending output

    ~?

invoke formatted output routine recursively with the next two arguments as format-string and list of parameters

### format

    [procedure] (format [DESTINATION] FORMATSTRING ARG ...)

The parameters `FORMATSTRING` and `ARG ...` are as for (`printf`/`sprintf`/`fprintf`).

The optional `DESTINATION`, when supplied, performs a (`sprintf`) for a `#f`, a (`printf`) for a `#t`, and a (`fprintf`) for an output-port. When missing a (`sprintf`) is performed.

## Random numbers

### random-seed

    [procedure] (random-seed [SEED])

Seeds the random number generator with `SEED` (an exact integer) or `(current-seconds)` if `SEED` is not given.

### random

    [procedure] (random N)

Returns an exact random integer from 0 to `N`-1.

### randomize

    [procedure] (randomize [X])

Set random-number seed. If `X` is not supplied, the current time is used. On startup (when the `extras` unit is initialized), the random number generator is initialized with the current time.

## Input/Output extensions

### pretty-print

    [procedure] (pretty-print EXP [PORT])
    [procedure] (pp EXP [PORT])

Print expression nicely formatted. `PORT` defaults to the value of `(current-output-port)`.

### pretty-print-width

(Parameter) Specifies the maximal line-width for pretty printing, after which line wrap will occur.

### read-byte

### write-byte

    [procedure] (read-byte [PORT])
    [procedure] (write-byte BYTE [PORT])

Read/write a byte to the port given in `PORT`, which default to the values of `(current-input-port)` and `(current-output-port)`, respectively.

### read-file

    [procedure] (read-file [FILE-OR-PORT [READER [MAXCOUNT]]])

Returns a list containing all toplevel expressions read from the file or port `FILE-OR-PORT`. If no argument is given, input is read from the port that is the current value of `(current-input-port)`. After all expressions are read, and if the argument is a port, then the port will not be closed. The `READER` argument specifies the procedure used to read expressions from the given file or port and defaults to `read`. The reader procedure will be called with a single argument (an input port). If `MAXCOUNT` is given then only up to `MAXCOUNT` expressions will be read in.

### read-line

### write-line

    [procedure] (read-line [PORT [LIMIT]])
    [procedure] (write-line STRING [PORT])

Line-input and -output. `PORT` defaults to the value of `(current-input-port)` and `(current-output-port)`, respectively. If the optional argument `LIMIT` is given and not `#f`, then `read-line` reads at most `LIMIT` characters per line. `read-line` returns a string without the terminating newline and `write-line` adds a terminating newline before outputting.

### read-lines

    [procedure] (read-lines [PORT [MAX]])

Read `MAX` or fewer lines from `PORT`. `PORT` defaults to the value of `(current-input-port)`. `PORT` may optionally be a string naming a file. Returns a list of strings, each string representing a line read, not including any line separation character(s).

### read-string

### read-string!

### write-string

    [procedure] (read-string [NUM [PORT]])
    [procedure] (read-string! NUM STRING [PORT [START]])
    [procedure] (write-string STRING [NUM [PORT]]

Read or write `NUM` characters from/to `PORT`, which defaults to the value of `(current-input-port)` or `(current-output-port)`, respectively. If `NUM` is `#f` or not given, then all data up to the end-of-file is read, or, in the case of `write-string` the whole string is written. If no more input is available, `read-string` returns the empty string. `read-string!` reads destructively into the given `STRING` argument, but never more characters that would fit into `STRING`. If `START` is given, then the read characters are stored starting at that position. `read-string!` returns the actual number of characters read.

### read-token

    [procedure] (read-token PREDICATE [PORT])

Reads characters from `PORT` (which defaults to the value of `(current-input-port)`) and calls the procedure `PREDICATE` with each character until `PREDICATE` returns false. Returns a string with the accumulated characters.

Previous: Unit files

Next: Unit srfi-1