s48-refman/library/utility.texi

@node Library utilities
@section Library utilities

Scheme48 provides various miscellaneous library utilities for common
general-purpose tasks.

@subsection Destructuring

@cindex S-expression destructuring
@cindex destructuring S-expressions
@stindex destructuring
The @code{destructuring} structure exports a form for destructuring
S-expressions.

@deffn syntax destructure ((pattern value) @dots{}) body
For each @code{(@var{pattern} @var{value})} pair, binds every name in
@var{pattern} to the corresponding location in the S-expression
@var{value}.  For example,

@lisp
(destructure (((x . y) (cons 5 3))
              ((#(a b) c) '(#((1 2) 3) (4 5))))
  @var{body})@end lisp

@noindent
binds @var{x} to @code{5}, @var{y} to @code{3}, @var{a} to
@code{(1 2)}, @var{b} to @code{3}, and @var{c} to @code{(4 5)}, in
@var{body}.
@end deffn

@subsection Pretty-printing

@cindex pretty-printing
@cindex printing
@stindex pp
The @code{pp} structure exports a simple pretty-printer.

@deffn procedure p object [port] @returns{} unspecified
@deffnx procedure pretty-print object port position @returns{} unspecified
@code{P} is a convenient alias for @code{pretty-print}; it passes 0 for
@var{position} and the value of @code{(current-output-port)} if
@var{port} is not passed.  @code{Pretty-print} pretty-prints
@var{object} to @var{port}, using a left margin of @var{position}.  For
example:

@lisp
(p '(define (fact n)
      (let loop ((p 1) (c 1))
        (if (> c n) p (loop (* p c) (+ c 1))))))
    @print{} (define (fact n)
    @print{}   (let loop ((p 1) (c 1))
    @print{}     (if (> c n)
    @print{}         p
    @print{}         (loop (* p c) (+ c 1)))))@end lisp
@end deffn

The pretty-printer is somewhat extensible as well:

@deffn procedure define-indentation name count @returns{} unspecified
Sets the number of subforms to be indented past @var{name} in
pretty-printed output to be @var{count}.  For example:

@lisp
(define-indentation 'frobozz 3)
(p '(frobozz (foo bar baz quux zot) (zot quux baz bar foo)
             (mumble frotz gargle eek) (froomble zargle hrumph)))
    @print{} (frobozz (foo bar baz quux zot)
    @print{}          (zot quux baz bar foo)
    @print{}          (mumble frotz gargle eek)
    @print{}   (froomble zargle hrumph))@end lisp
@end deffn

@subsection Strongly connected graph components

@cindex strongly-connected graph components
@cindex graph algorithms
@stindex strong
The @code{strong} structure exports a routine for finding a list of the
strongly connected components in a graph.

@deffn procedure strongly-connected-components vertices to slot set-slot! @returns{} sorted-strong-vertices
Returns the components of a graph containing vertices from the list
@var{vertices} that are strongly connected, in a reversed topologically
sorted list.  @var{To} should be a procedure of one argument, a vertex,
that returns a list of all vertices that have an edge to its argument.
@var{Slot} & @var{set-slot!} should be procedures of one & two
arguments, respectively, that access & modify arbitrary slots used by
the algorithm.  The slot for every vertex should initially be @code{#f}
before calling @code{strongly-connected-components}, and the slots are
reverted to @code{#f} before @code{strongly-connected-components}
returns.
@end deffn

@subsection Nondeterminism

@cindex nondeterminism
@cindex backtracking
@cindex @code{amb} operator
@stindex nondeterminism
The @code{nondeterminism} structure provides a simple nondeterministic
ambivalence operator, like McCarthy's @code{AMB}, and a couple utilities
atop it, built with Scheme's @code{call-with-current-continuation}.

@deffn procedure with-nondeterminism thunk @returns{} values
Initializes the nondeterminism system and calls @var{thunk}; this
returns the values @var{thunk} returns after then tearing down what was
set up.
@end deffn

@deffn syntax either option @dots{} @returns{} value
@deffnx syntax one-value exp @returns{} value
@deffnx syntax all-values exp @returns{} list
@code{Either} evaluates to the value of any one of the options.  It is
equivalent to McCarthy's @code{AMB}.  It may return any number of times.
@code{One-value} returns the only value that @var{exp} could produce; it
will return only once, although it may actually return any number of
values (if @var{exp} contains a call to @code{values}).
@code{All-values} returns a list of all of the single values, not
multiple values, that @var{exp} could nondeterministically evaluate to.
@end deffn

@deffn procedure fail @returns{} does not return
Signals a nondeterministic failure.  This is invalid outside of a
@code{with-nondeterminism}-protected dynamic extent.
@end deffn

@subsection Miscellaneous utilities

@stindex big-util
The @code{big-util} structure exports a variety of miscellaneous
utilities.

@deffn procedure concatenate-symbol elt @dots{} @returns{} symbol
Returns a symbol containing the contents of the sequence @var{elt}
@dots{}.  Each @var{elt} may be another symbol, a string, or a number.
Numbers are converted to strings in base ten.
@end deffn

@deffn procedure error format-string argument @dots{} @returns{} values (may not return)
@deffnx procedure breakpoint format-string argument @dots{} @returns{} values (may not return)
@code{Error} signals an error whose message is formatted by
@embedref{Common-Lisp-style formatting, @code{format}} with the given
formatting template string and arguments.  @code{Breakpoint} signals a
breakpoint with a message similarly constructed and causes the command
processor to push a new @embedref{Command levels,command level}.
@end deffn

@deffn procedure atom? x @returns{} boolean
Returns true if @var{x} is not a pair or false if it is.
@end deffn

@deffn procedure neq? x y @returns{} boolean
@deffnx procedure n= x y @returns{} boolean
Negations of the @code{eq?} and @code{=} predicates.
@end deffn

@deffn procedure identity value @returns{} value
@deffnx procedure no-op value @returns{} value
These simply return their arguments.  The difference between them is
that @code{no-op} is guaranteed not to be integrated by the compiler,
whereas @code{identity} may be.
@end deffn

@deffn procedure null-list? object @returns{} boolean
Returns @code{#t} if @var{object} is the null list, returns @code{#f}
if @var{object} is a pair, or signals an error if @var{object} is
neither the null list nor a pair.
@end deffn

@deffn procedure reverse! list @returns{} reversed-list
Returns a list containing the reverse elements of @var{list}.  Note
that the original @var{list} is @emph{not} reversed; it becomes
garbage.  @code{Reverse!} simply re-uses its structure.
@end deffn

@deffn procedure memq? object list @returns{} boolean
Returns @code{#t} if @var{object} is a member of @var{list}, as
determined by @code{eq?}; or @code{#f} if not.
@end deffn

@deffn procedure first predicate list @returns{} elt or @code{#f}
@deffnx procedure any predicate list @returns{} elt or @code{#f}
@code{First} returns the first element of @var{list} that satisfies
@var{predicate}, or @code{#f} if no element does.  @code{Any} returns
an element of @var{list} that satisfies @var{predicate}.  Note that
@code{any} may choose any element of the list, whereas @code{first}
explicitly returns the @emph{first} element that satisfies
@var{predicate}.
@end deffn

@deffn procedure any? predicate list @returns{} boolean
@deffnx procedure every? predicate list @returns{} boolean
@code{Any?} returns @code{#t} if any element of @var{list} satisfies
@var{predicate}, or @code{#f} if none do.  @code{Every?} returns
@code{#t} if every element of @var{list} satisfies @var{predicate}, or
@code{#f} if there exists an element that does not.
@end deffn

@deffn procedure filter predicate list @returns{} filtered-list
@deffnx procedure filter! predicate list @returns{} filtered-list
These return a list of all elements in @var{list} that satisfy
@var{predicate}.  @code{Filter} is not allowed to modify @var{list}'s
structure; @code{filter!} may, however.
@end deffn

@deffn procedure filter-map proc list @returns{} list
This is a combination of @code{filter} and @code{map}.  For each
element @var{e} in @var{list}: if @code{(@var{proc} @var{e})} returns a
true value, that true value is collected in the output list.
@code{Filter-map} does not modify @var{list}'s structure.
@end deffn

@deffn procedure remove-duplicates list @returns{} uniquified-list
Returns a unique list of all elements in @var{list}; that is, if there
were any duplicates of any element @var{e} in @var{list}, only a single
@var{e} will occur in the returned list.  @code{Remove-duplicates} does
not modify @var{list}'s structure.
@end deffn

@deffn procedure partition-list predicate list @returns{} [satisfied unsatisfied]
@deffnx procedure partition-list! predicate list @returns{} [satisfied unsatisfied]
These return two values: a list of all elements in @var{list} that do
satisfy @var{predicate} and a list of all elements that do not.
@code{Partition-list} is not allowed to modify @var{list}'s structure;
@code{partition-list!} is.
@end deffn

@deffn procedure delq object list @returns{} list
@deffnx procedure delq! object list @returns{} list
These return a list containing all elements of @var{list} except for
@var{object}.  @code{Delq} is not allowed to modify @var{list}'s
structure; @code{delq!} is.
@end deffn

@deffn procedure delete predicate list @returns{} list
Returns a list of all elements in @var{list} that do not satisfy
@var{predicate}.  Note that, despite the lack of exclamation mark in
the name, this @emph{may} modify @var{list}'s structure.
@end deffn

@deffn procedure string->immutable-string string @returns{} immutable-string
Returns an immutable string with @var{string}'s contents.  If
@var{string} is already immutable, it is returned; otherwise, an
immutable copy is returned.
@end deffn

@subsection Multiple value binding

@cindex binding multiple values
@cindex multiple value binding
@stindex receiving
The @code{receiving} structure exports the @code{receive} macro, a
convenient syntax atop R5RS's @code{call-with-values}.

@deffn syntax receive formals producer body
Binds the variables in the lambda parameter list @var{formals} to the
return values of @var{producer} in @var{body}.

@lisp
(receive @var{formals}
         @var{producer}
  @var{body})
    @equiv{}
(call-with-values
    (lambda () @var{producer})
  (lambda @var{formals} @var{body}))@end lisp
@end deffn

@stindex mvlet
For sequences of multiple value bindings, the @code{mvlet} structure
exports two convenient macros.

@deffn syntax mvlet*
@deffnx syntax mvlet
@code{Mvlet*} is a multiple-value version of @code{let} or a linearly
nested version of @code{receive}:

@lisp
(mvlet* ((@var{formals@sub{0}} @var{producer@sub{0}})
         (@var{formals@sub{1}} @var{producer@sub{1}})
         @dots{})
  @var{body})
    @equiv{}
(call-with-values
    (lambda () @var{producer@sub{0}})
  (lambda @var{formals@sub{0}}
    (call-with-values
        (lambda () @var{producer@sub{1}})
      (lambda @var{formals@sub{1}}
        @dots{}@var{body}@dots{}))))@end lisp

@code{Mvlet} is similar, but each @var{producer} is evaluated in an
environment where none of the variables in any of the @var{formals} is
bound, and the order in which each producer expression is evaluated is
unspecified.
@end deffn

@subsection Object dumper

@cindex serialization
@cindex marshalling
@cindex object dumping
@stindex dump/restore
Scheme48 has a rudimentary object dumper and retriever in the structure
@code{dump/restore}.  It is not a `real' object dumper in the sense that
it will not handle cycles in object graphs correctly; it simply performs
a recursive descent and will diverge if it reaches a cycle or stop after
a recursive depth parameter.

The types of objects that the dumper supports are: several miscellaneous
constants (@code{()}, @code{#t}, @code{#f}, & the unspecific token),
pairs, vectors, symbols, numbers, strings, characters, and byte vectors.

@deffn procedure dump object char-writer depth @returns{} unspecified
Dumps @var{object} by repeatedly calling @var{char-writer}, which must
be a procedure that accepts exactly one character argument, on the
characters of the serialized representation.  If the dumper descends
into the object graph whose root is @var{object} for more than
@var{depth} recursions, an ellipsis token is dumped in the place of the
vertex at @var{depth}.
@end deffn

@deffn procedure restore char-reader @returns{} object
Restores the object whose serialized components are retrieved by
repeatedly calling @var{char-reader}, which must be a procedure that
accepts zero arguments and returns a character.
@end deffn

@subsection Simple time access

@cindex time
@cindex run time
@cindex real time
@stindex time
The @code{time} structure exports a simple facility for accessing time
offsets in two different flavours.

@deffn procedure real-time @returns{} milliseconds
Returns the real time in milliseconds that has passed since some
unspecified moment in time.@footnote{In the current implementation on
Unix, this moment happens to be the first call to @code{real-time}; on
Win32, this is the start of the Scheme process.}  Though not suitable
for measurements relative to entities outside the Scheme48 image, the
real time is useful for measuring time differences within the Scheme
image with reasonable precision; for example, thread sleep timing is
implemented with this real time primitive.
@end deffn

@deffn procedure run-time @returns{} ticks
Returns the run time as an integer representing processor clock ticks
since the start of the Scheme48 process.  This is much less precise
than the real time, but it is useful for measuring time actually spent
in the Scheme48 process, as opposed to time in general.
@end deffn