guile/doc/ref/new-docstrings.texi

@c module-for-docstring (guile)

@c This one crops up here constantly although it is already
@c in api-data.texi.  Have to investigate somewhen.

@deffn {Scheme Procedure} inf? x
@deffnx {C Function} scm_inf_p (x)
Return @code{#t} if @var{x} is either @samp{+inf.0}
or @samp{-inf.0}, @code{#f} otherwise.
@end deffn






@deffn {Scheme Procedure} uniform-vector? obj
@deffnx {C Function} scm_uniform_vector_p (obj)
Return @code{#t} if @var{obj} is a uniform vector.
@end deffn

@deffn {Scheme Procedure} uniform-vector-set! v idx val
@deffnx {C Function} scm_uniform_vector_set_x (v, idx, val)
Set the element at index @var{idx} of the
homogenous numeric vector @var{v} to @var{val}.
@end deffn

@deffn {Scheme Procedure} uniform-vector->list uvec
@deffnx {C Function} scm_uniform_vector_to_list (uvec)
Convert the homogeneous numeric vector @var{uvec} to a list.
@end deffn

@deffn {Scheme Procedure} make-u8vector len [fill]
@deffnx {C Function} scm_make_u8vector (len, fill)
Return a newly allocated uniform numeric vector which can
hold @var{len} elements.  If @var{fill} is given, it is used to
initialize the elements, otherwise the contents of the vector
is unspecified.
@end deffn

@deffn {Scheme Procedure} u8vector . l
@deffnx {C Function} scm_u8vector (l)
Return a newly allocated uniform numeric vector containing
all argument values.
@end deffn

@deffn {Scheme Procedure} list->u8vector l
@deffnx {C Function} scm_list_to_u8vector (l)
Convert the list @var{l} to a numeric uniform vector.
@end deffn

@deffn {Scheme Procedure} any->u8vector obj
@deffnx {C Function} scm_any_to_u8vector (obj)
Convert @var{obj}, which can be a list, vector, or
uniform vector, to a numeric uniform vector of
type u8.
@end deffn

@deffn {Scheme Procedure} with-continuation-barrier proc
@deffnx {C Function} scm_with_continuation_barrier (proc)
Call @var{proc} and return the returned value but do not allow the invocation of continuations that would exit or reenter the dynamic extent of the call to @var{proc}.  When a uncaught throw happens during the call to @var{proc}, a message is printed to the current error port and @code{#f} is returned.
@end deffn

@deffn {Scheme Procedure} dynamic-state? obj
@deffnx {C Function} scm_dynamic_state_p (obj)
Return @code{#t} if @var{obj} is a dynamic state object;
return @code{#f} otherwise
@end deffn

@deffn {Scheme Procedure} current-dynamic-state
@deffnx {C Function} scm_current_dynamic_state ()
Return the current dynamic state object.
@end deffn

@deffn {Scheme Procedure} set-current-dynamic-state state
@deffnx {C Function} scm_set_current_dynamic_state (state)
Set the current dynamic state object to @var{state}
and return the previous current dynamic state object.
@end deffn

@deffn {Scheme Procedure} with-dynamic-state state proc
@deffnx {C Function} scm_with_dynamic_state (state, proc)
Call @var{proc} while @var{state} is the current dynamic
state object.
@end deffn

@deffn {Scheme Procedure} call-with-dynamic-root thunk handler
@deffnx {C Function} scm_call_with_dynamic_root (thunk, handler)
Evaluate @code{(thunk)} in a new dynamic context, returning its value.

If an error occurs during evaluation, apply @var{handler} to the
arguments to the throw, just as @code{throw} would.  If this happens,
@var{handler} is called outside the scope of the new root -- it is
called in the same dynamic context in which
@code{call-with-dynamic-root} was evaluated.

If @var{thunk} captures a continuation, the continuation is rooted at
the call to @var{thunk}.  In particular, the call to
@code{call-with-dynamic-root} is not captured.  Therefore,
@code{call-with-dynamic-root} always returns at most one time.

Before calling @var{thunk}, the dynamic-wind chain is un-wound back to
the root and a new chain started for @var{thunk}.  Therefore, this call
may not do what you expect:

@lisp
;; Almost certainly a bug:
(with-output-to-port
 some-port

 (lambda ()
   (call-with-dynamic-root
    (lambda ()
      (display 'fnord)
      (newline))
    (lambda (errcode) errcode))))
@end lisp

The problem is, on what port will @samp{fnord} be displayed?  You
might expect that because of the @code{with-output-to-port} that
it will be displayed on the port bound to @code{some-port}.  But it
probably won't -- before evaluating the thunk, dynamic winds are
unwound, including those created by @code{with-output-to-port}.
So, the standard output port will have been re-set to its default value
before @code{display} is evaluated.

(This function was added to Guile mostly to help calls to functions in C
libraries that can not tolerate non-local exits or calls that return
multiple times.  If such functions call back to the interpreter, it should
be under a new dynamic root.)
@end deffn

@deffn {Scheme Procedure} dynamic-root
@deffnx {C Function} scm_dynamic_root ()
Return an object representing the current dynamic root.

These objects are only useful for comparison using @code{eq?}.

@end deffn

@deffn {Scheme Procedure} uniform-vector-ref v idx
@deffnx {C Function} scm_uniform_vector_ref (v, idx)
Return the element at index @var{idx} of the
homogenous numeric vector @var{v}.
@end deffn

@deffn {Scheme Procedure} uniform-vector-length v
@deffnx {C Function} scm_uniform_vector_length (v)
Return the number of elements in the uniform vector @var{v}.
@end deffn

@deffn {Scheme Procedure} uniform-vector-read! uvec [port_or_fd [start [end]]]
@deffnx {C Function} scm_uniform_vector_read_x (uvec, port_or_fd, start, end)
Fill the elements of @var{uvec} by reading
raw bytes from @var{port-or-fdes}, using host byte order.

The optional arguments @var{start} (inclusive) and @var{end}
(exclusive) allow a specified region to be read,
leaving the remainder of the vector unchanged.

When @var{port-or-fdes} is a port, all specified elements
of @var{uvec} are attempted to be read, potentially blocking
while waiting formore input or end-of-file.
When @var{port-or-fd} is an integer, a single call to
read(2) is made.

An error is signalled when the last element has only
been partially filled before reaching end-of-file or in
the single call to read(2).

@code{uniform-vector-read!} returns the number of elements
read.

@var{port-or-fdes} may be omitted, in which case it defaults
to the value returned by @code{(current-input-port)}.
@end deffn

@deffn {Scheme Procedure} uniform-vector-write uvec [port_or_fd [start [end]]]
@deffnx {C Function} scm_uniform_vector_write (uvec, port_or_fd, start, end)
Write the elements of @var{uvec} as raw bytes to
@var{port-or-fdes}, in the host byte order.

The optional arguments @var{start} (inclusive)
and @var{end} (exclusive) allow
a specified region to be written.

When @var{port-or-fdes} is a port, all specified elements
of @var{uvec} are attempted to be written, potentially blocking
while waiting for more room.
When @var{port-or-fd} is an integer, a single call to
write(2) is made.

An error is signalled when the last element has only
been partially written in the single call to write(2).

The number of objects actually written is returned.
@var{port-or-fdes} may be
omitted, in which case it defaults to the value returned by
@code{(current-output-port)}.
@end deffn

@deffn {Scheme Procedure} string-any-c-code char_pred s [start [end]]
@deffnx {C Function} scm_string_any (char_pred, s, start, end)
Check if the predicate @var{pred} is true for any character in
the string @var{s}.

Calls to @var{pred} are made from left to right across @var{s}.
When it returns true (ie.@: non-@code{#f}), that return value
is the return from @code{string-any}.

The SRFI-13 specification requires that the call to @var{pred}
on the last character of @var{s} (assuming that point is
reached) be a tail call, but currently in Guile this is not the
case.
@end deffn

@deffn {Scheme Procedure} string-every-c-code char_pred s [start [end]]
@deffnx {C Function} scm_string_every (char_pred, s, start, end)
Check if the predicate @var{pred} is true for every character
in the string @var{s}.

Calls to @var{pred} are made from left to right across @var{s}.
If the predicate is true for every character then the return
value from the last @var{pred} call is the return from
@code{string-every}.

If there are no characters in @var{s} (ie.@: @var{start} equals
@var{end}) then the return is @code{#t}.

The SRFI-13 specification requires that the call to @var{pred}
on the last character of @var{s} (assuming that point is
reached) be a tail call, but currently in Guile this is not the
case.
@end deffn

@deffn {Scheme Procedure} make-recursive-mutex
@deffnx {C Function} scm_make_recursive_mutex ()
Create a new recursive mutex. 
@end deffn

@deffn {Scheme Procedure} vector-copy vec
@deffnx {C Function} scm_vector_copy (vec)
Return a copy of @var{vec}.
@end deffn

@deffn {Scheme Procedure} dimensions->uniform-array dims prot [fill]
@deffnx {Scheme Procedure} make-uniform-vector length prototype [fill]
@deffnx {C Function} scm_dimensions_to_uniform_array (dims, prot, fill)
Create and return a uniform array or vector of type
corresponding to @var{prototype} with dimensions @var{dims} or
length @var{length}.  If @var{fill} is supplied, it's used to
fill the array, otherwise @var{prototype} is used.
@end deffn

@deffn {Scheme Procedure} list->uniform-array ndim prot lst
@deffnx {C Function} scm_list_to_uniform_array (ndim, prot, lst)
Return a uniform array of the type indicated by prototype
@var{prot} with elements the same as those of @var{lst}.
Elements must be of the appropriate type, no coercions are
done.

The argument @var{ndim} determines the number of dimensions
of the array.  It is either an exact integer, giving the
number directly, or a list of exact integers, whose length
specifies the number of dimensions and each element is the
lower index bound of its dimension.
@end deffn

@deffn {Scheme Procedure} array-prototype ra
@deffnx {C Function} scm_array_prototype (ra)
Return an object that would produce an array of the same type
as @var{array}, if used as the @var{prototype} for
@code{make-uniform-array}.
@end deffn