[[tags: manual]]
[[toc:]]

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


==== randomize

<procedure>(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

<procedure>(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

<procedure>(fprintf PORT FORMATSTRING [ARG...])</procedure><br>
<procedure>(printf FORMATSTRING [ARG...])</procedure><br>
<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:

<table>
<tr><td>~%</td><td>
write newline character
</td></tr><tr><td> ~N</td><td>
the same as {{~%}}
</td></tr><tr><td> ~S</td><td>
write the next argument
</td></tr><tr><td> ~A</td><td>
display the next argument
</td></tr><tr><td> ~\n</td><td>
skip all whitespace in the format-string until the next non-whitespace character
</td></tr><tr><td> ~B</td><td>
write the next argument as a binary number
</td></tr><tr><td> ~O</td><td>
write the next argument as an octal number
</td></tr><tr><td> ~X</td><td>
write the next argument as a hexadecimal number
</td></tr><tr><td> ~C</td><td>
write the next argument as a character
</td></tr><tr><td> ~~</td><td>
display `~'
</td></tr><tr><td> ~!</td><td>
flush all pending output
</td></tr><tr><td> ~?</td><td>
invoke formatted output routine recursively with the next two arguments as format-string and list of parameters
</td></tr></table>


==== format

<procedure>(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

<procedure>(pretty-print EXP [PORT])</procedure><br>
<procedure>(pp EXP [PORT])</procedure>

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


==== pretty-print-width
<parameter>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

<procedure>(read-byte [PORT])</procedure><br>
<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

<procedure>(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

<procedure>(read-line [PORT [LIMIT]])</procedure><br>
<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

<procedure>(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

<procedure>(read-string [NUM [PORT]])</procedure><br>
<procedure>(read-string! NUM STRING [PORT [START]])</procedure><br>
<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

<procedure>(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 regex]]
