# Unit extras

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

## Random numbers

### random-seed

     [procedure] (random-seed [SEED])

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

### randomize

     [procedure] (randomize [SEED])

Set random-number seed. If `SEED` (an `exact integer`) is not supplied, the current time is used. On startup (when Unit `extras` is initialized), the random number generator is initialized with the current time.

### random

     [procedure] (random N)

Returns a random `integer` in `[0 N-1]`. `N` is an `integer`.
On Windows `N` and the random value are `exact integer`.

## 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`.
The optional `DESTINATION`, when supplied, performs:

`#f`
  `sprintf`
`#t`
  `printf`
`output-port`
  `fprintf`
  `sprintf`

## 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 regex