You are looking at historical revision 10510 of this page. It may differ significantly from its current revision.

• manual

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.

String-port extensions

call-with-input-string

[procedure] (call-with-input-string STRING PROC)

Calls the procedure PROC with a single argument that is a string-input-port with the contents of STRING.

call-with-output-string

[procedure] (call-with-output-string PROC)

Calls the procedure PROC with a single argument that is a string-output-port. Returns the accumulated output-string.

with-input-from-string

[procedure] (with-input-from-string STRING THUNK)

Call procedure THUNK with the current input-port temporarily bound to an input-string-port with the contents of STRING.

with-output-to-string

[procedure] (with-output-to-string THUNK)

Call procedure THUNK with the current output-port temporarily bound to a string-output-port and return the accumulated output string.

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

make-input-port

[procedure] (make-input-port READ READY? CLOSE [PEEK])

Returns a custom input port. Common operations on this port are handled by the given parameters, which should be procedures of no arguments. READ is called when the next character is to be read and should return a character or #!eof. READY? is called when char-ready? is called on this port and should return #t or #f. CLOSE is called when the port is closed. PEEK is called when peek-char is called on this port and should return a character or #!eof. if the argument PEEK is not given, then READ is used instead and the created port object handles peeking automatically (by calling READ and buffering the character).

make-output-port

[procedure] (make-output-port WRITE CLOSE [FLUSH])

Returns a custom output port. Common operations on this port are handled by the given parameters, which should be procedures. WRITE is called when output is sent to the port and receives a single argument, a string. CLOSE is called when the port is closed and should be a procedure of no arguments. FLUSH (if provided) is called for flushing the output port.

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.

with-error-output-to-port

[procedure] (with-error-output-to-port PORT THUNK)

Call procedure THUNK with the current error output-port temporarily bound to PORT.

with-input-from-port

[procedure] (with-input-from-port PORT THUNK)

Call procedure THUNK with the current input-port temporarily bound to PORT.

with-output-to-port

[procedure] (with-output-to-port PORT THUNK)

Call procedure THUNK with the current output-port temporarily bound to PORT.

Previous: Unit data-structures

Next: Unit srfi-1