## Unit extras

This unit contains a collection of useful utility definitions. The unit is used in `csi` by default.

### Random numbers

#### randomize

`(randomize [SEED])` procedure

  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

`(random N)` procedure

  Returns a pseudo-random `integer` in `[0, N-1]`. `N` is an `integer`.

  On Windows, `N` and the random value are `exact integer`.

  Warning: This procedure uses rand(3) internally and exhibits its deficiencies, including low quality pseudo-randomness:

  - On Windows and Solaris, only 32768 unique random values can be generated in the range `[0, N-1]`. If `N >= 32768`, there will be gaps in the result set.
  - On Mac OS X, Windows and some other platforms, little variance in output is seen with nearby seeds. Since the random generator is seeded with `current-seconds` at startup, new processes may see similar or identical random sequences for up to a minute.
  - On Linux, rand(3) is an alias to random(3), which provides output of reasonable quality.

### Formatted output

#### printf

#### fprintf

#### sprintf

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

  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

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

  The parameters `FORMATSTRING` and `ARG...` are as for `printf`.

  The optional `DESTINATION`, when supplied, performs:

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

### Pretty-printing

#### pretty-print

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

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

#### pretty-print-width

`pretty-print-width` parameter

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

### Input/Output extensions

#### read-byte

#### write-byte

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

  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

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

  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

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

  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

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

  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

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

  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 than 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

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

  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 irregex