@c =================================================================== @c
@c    serrano/prgm/project/bigloo/manuals/body.texi                    @c
@c    ------------------------------------------------------------     @c
@c    Author      :  Manuel Serrano                                    @c
@c    Creation    :  Sat Jun 13 09:08:34 1998                          @c
@c    Last change :  Mon Nov 19 21:01:14 2001 (serrano)                @c
@c    ------------------------------------------------------------     @c
@c    The documentation for Bigloo modules                             @c
@c =================================================================== @c

@c ------------------------------------------------------------------- @c
@c    Module body                                                      @c
@c ------------------------------------------------------------------- @c
@node Standard Library, Pattern Matching, Core Language, Top
@comment  node-name,  next,  previous,  up
@chapter Standard Library

This chapter presents the Bigloo standard library. Bigloo is mostly
R5RS compliant but it proposes many extensions to this standard and it
proposes many extensions. In a first section (@ref{Scheme Library})
the Bigloo R5RS support is presented. This section also contains various
function that are not standard (for instance, various functions used
to manage a file system). Then, in the following sections
(@ref{Structures and Records}, @ref{Serialization}, @ref{Bit Manipulation},
@ref{System Programming} and @ref{Posix Regular Expressions}
Bigloo specific extensions are presented. Bigloo input and output facilities
constitue a large superset of the standard Scheme definition. For this
reason they are presented in a separate section (@ref{Input and Output}).

@menu
* Scheme Library::   
* Input and Output::    
* Structures and Records::
* Serialization::              
* Bit Manipulation::            
* Hash Tables::   
* System Programming::
* Date::
* Posix Regular Expressions::
@end menu

@c ------------------------------------------------------------------- @c
@c    Base Library                                                     @c
@c ------------------------------------------------------------------- @c
@node Scheme Library, Input and Output, , Standard Library
@comment  node-name,  next,  previous,  up
@section Scheme Library
@cindex Module body language

When the definition of a procedure or a special form is the
same in Bigloo and Scheme, we just mention its name;
otherwise, we explain it and qualify it as a ``bigloo
procedure''.

@menu
* Booleans::                    
* Equivalence Predicates::      
* Pairs And Lists::             
* Symbols::                     
* Keywords::                    
* Numbers::                     
* Characters::                  
* UCS-2 Characters::            
* Strings::                     
* Unicode (UCS-2) Strings::     
* Vectors::                     
* Control Features::            
@end menu

@c -- booleans ------------------------------------------------------- @c
@node  Booleans, Equivalence Predicates, , Scheme Library
@comment  node-name,  next,  previous,  up
@subsection Booleans
@cindex Booleans
The standard boolean objects are @code{#t} and @code{#f}.
Note: the empty list is true.

@deffn {library procedure} not obj
@code{not} returns @t{#t} if @var{obj} is false, and returns
@code{#f} otherwise.

@smalllisp
(not #t)                               @result{} #f
(not 3)                                @result{} #f
(not (list 3))                         @result{} #f
(not #f)                               @result{} #t
(not '())                              @result{} #f
(not (list))                           @result{} #f
(not 'nil)                             @result{} #f
@end smalllisp
@end deffn

@deffn {library procedure} boolean?  obj
@code{Boolean?} returns @t{#t} if @var{obj} is either @t{#t} or
@t{#f} and returns @t{#f} otherwise.

@smalllisp
(boolean? #f)                          @result{} #t
(boolean? 0)                           @result{} #f
(boolean? '())                         @result{} #f
@end smalllisp
@end deffn

@c -- Equivalence predicates ----------------------------------------- @c
@node Equivalence Predicates, Pairs And Lists, Booleans, Scheme Library
@comment  node-name,  next,  previous,  up
@subsection Equivalence predicates
@cindex Equivalence predicates

@deffn {procedure} eqv? obj1 obj2
@deffnx {procedure} eq? obj1 obj2
@code{eqv?} and @code{eq?} are equivalent in Bigloo.

@smalllisp
(eq? 'a 'a)                            @result{}  #t
(eq? '(a) '(a))                        @result{}  @emph{unspecified}
(eq? (list 'a) (list 'a))              @result{}  #f
(eq? "a" "a")                          @result{}  @emph{unspecified}
(eq? "" "")                            @result{}  @emph{unspecified}
(eq? '() '())                          @result{}  #t
(eq? 2 2)                              @result{}  @emph{unspecified}
(eq? #\A #\A)                          @result{}  @emph{unspecified}
(eq? car car)                          @result{}  #t
(let ((n (+ 2 3)))
  (eq? n n))                           @result{}  @emph{unspecified}
(let ((x '(a)))
  (eq? x x))                           @result{}  #t
(let ((x '#()))
  (eq? x x))                           @result{}  #t
(let ((p (lambda (x) x)))
  (eq? p p))                           @result{}  #t
@end smalllisp

Since Bigloo implements @code{eqv?} as @code{eq?}, the behavior is not
always conforming to R5RS.
@smalllisp
(eqv? 'a 'a)                           @result{}  #t
(eqv? 'a 'b)                           @result{}  #f
(eqv? 2 2)                             @result{}  #t
(eqv? '() '())                         @result{}  #t
(eqv? 100000000 100000000)             @result{}  #t
(eqv? (cons 1 2) (cons 1 2))           @result{}  #f
(eqv? (lambda () 1)
      (lambda () 2))                   @result{}  #f
(eqv? #f 'nil)                         @result{}  #f
(let ((p (lambda (x) x)))
  (eqv? p p))                          @result{}  @emph{unspecified}
@end smalllisp


The following examples illustrate cases in which the above rules do
not fully specify the behavior of @samp{eqv?}.  All that can be said
about such cases is that the value returned by @samp{eqv?} must be a
boolean.

@smalllisp
(eqv? "" "")                           @result{}  @emph{unspecified}
(eqv? '#() '#())                       @result{}  @emph{unspecified}
(eqv? (lambda (x) x)
      (lambda (x) x))                  @result{}  @emph{unspecified}
(eqv? (lambda (x) x)
      (lambda (y) y))                  @result{}  @emph{unspecified}

(define gen-counter
  (lambda ()
    (let ((n 0))
      (lambda () (set! n (+ n 1)) n))))
(let ((g (gen-counter)))
  (eqv? g g))                          @result{}  #t
(eqv? (gen-counter) (gen-counter))
                                       @result{}  #f
(define gen-loser
  (lambda ()
    (let ((n 0))
      (lambda () (set! n (+ n 1)) 27))))
(let ((g (gen-loser)))
  (eqv? g g))                          @result{}  #t
(eqv? (gen-loser) (gen-loser))
                                       @result{}  @emph{unspecified}

(letrec ((f (lambda () (if (eqv? f g) 'both 'f)))
         (g (lambda () (if (eqv? f g) 'both 'g))))
  (eqv? f g))
                                       @result{}  @emph{unspecified}

(letrec ((f (lambda () (if (eqv? f g) 'f 'both)))
         (g (lambda () (if (eqv? f g) 'g 'both))))
  (eqv? f g))
                                       @result{}  #f
(eqv? '(a) '(a))                       @result{}  @emph{unspecified}
(eqv? "a" "a")                         @result{}  @emph{unspecified}
(eqv? '(b) (cdr '(a b)))               @result{}  @emph{unspecified}
(let ((x '(a)))
  (eqv? x x))                          @result{}  #t
@end smalllisp

@end deffn

@deffn {library procedure} equal? obj1 obj2
@smalllisp
(equal? 'a 'a)                         @result{}  #t
(equal? '(a) '(a))                     @result{}  #t
(equal? '(a (b) c)
        '(a (b) c))                    @result{}  #t
(equal? "abc" "abc")                   @result{}  #t
(equal? 2 2)                           @result{}  #t
(equal? (make-vector 5 'a)
        (make-vector 5 'a))            @result{}  #t
(equal? (lambda (x) x)
        (lambda (y) y))                @result{}  @emph{unspecified}
@end smalllisp
@end deffn

@xref{Equivalence predicates,,r5rs.info,R5RS}, for more details.

@c -- Pairs and lists ------------------------------------------------ @c
@node Pairs And Lists, Symbols, Equivalence Predicates, Scheme Library
@comment  node-name,  next,  previous,  up
@subsection Pairs and lists
@cindex Pairs and lists

The form @code{()} is @emph{illegal}. 

@deffn {procedure} pair? obj
@end deffn

@deffn {bigloo procedure} pair-or-null? obj
Returns @code{#t} if @var{obj} is either a pair or the empty list. Otherwise
it returns @code{#f}.
@end deffn

@deffn {procedure} car pair
@deffnx {procedure} cdr pair
@deffnx {procedure} set-car! pair obj
@deffnx {procedure} set-cdr! pair obj
@end deffn

@deffn {library procedure} caar pair
@deffnx {library procedure} cadr pair
@dots{}

@deffnx {library procedure} cdddar pair
@deffnx {library procedure} cddddr pair
@end deffn

@deffn {library procedure} null? obj
@deffnx {library procedure} list? obj
@deffnx {library procedure} list obj @dots{}
@deffnx {library procedure} length list
@deffnx {library procedure} append list @dots{}
@deffnx {bigloo procedure} append! list @dots{}

A destructive append.
@end deffn

@deffn {library procedure} reverse list
@deffnx {bigloo procedure} reverse! list

A destructive reverse.
@end deffn

@deffn {library procedure} list-ref list k
@deffnx {library procedure} list-tail list k

Returns the sublist of @var{list} obtained by omitting the 
first @var{k} elements.
@end deffn

@deffn {bigloo procedure} last-pair list
Returns the last pair in the nonempty, possibly improper, @var{list}.
@end deffn

@deffn {library procedure} memq obj list
@deffnx {library procedure} memv obj list
@deffnx {library procedure} member obj list
@deffnx {library procedure} assq obj alist
@deffnx {library procedure} assv obj alist
@deffnx {library procedure} assoc obj alist
@deffnx {bigloo procedure} remq obj list

Returns a new list which is a copy of @var{list} with all items
@code{eq?} to @var{obj} removed from it.
@end deffn

@deffn {bigloo procedure} remq! obj list
Same as @code{remq} but in a destructive way.
@end deffn

@deffn {bigloo procedure} delete obj list
Returns a new list which is a copy of @var{list} with all items
@code{equal?} to @var{obj} deleted from it.
@end deffn

@deffn {bigloo procedure} delete! obj list
Same as @code{delete} but in a destructive way.
@end deffn

@deffn {bigloo procedure} cons* obj @dots{}
Returns an object formed by consing all arguments together from right to left.
If only one @var{obj} is supplied, that @var{obj} is returned.
@end deffn

@deffn {bigloo procedure} every? pred clist1 clist2 ...
Applies the predicate across the lists, returning true if the
predicate returns true on every application.

@smalllisp
(every < '(1 2 3) '(2 3 4))            @result{} #t
(every < '(1 2 3) '(2 3 0))            @result{} #f
@end smalllisp
@end deffn

@deffn {bigloo procedure} any? pred clist1 clist2 ...
Applies the predicate across the lists, returning true if the
predicate returns true for at least one application.

@smalllisp
(any < '(1 2 3) '(2 3 4))            @result{} #t
(any < '(1 2 3) '(2 3 0))            @result{} #t
@end smalllisp
@end deffn

@deffn {bigloo procedure} every fun clist1 clist2 ...
@cindex SRFI-1
Applies the function @var{fun} across the lists, returning the last 
non-false if the function returns non-false on every application. If 
non-false, the result of @code{every} is the last value returned by the
last application of @var{fun}.

@smalllisp
(every < '(1 2 3) '(2 3 4))            @result{} #t
(every < '(1 2 3) '(2 3 0))            @result{} #f
@end smalllisp
@end deffn

@deffn {bigloo procedure} any fun clist1 clist2 ...
@cindex SRFI-1
Applies the function @var{fun} across the lists, returning non-false if the
function returns non-false for at least one application. If non-false,
the result of @code{any} is the first non-false value returned by @var{fun}.

@smalllisp
(any < '(1 2 3) '(2 3 4))            @result{} #t
(any < '(1 2 3) '(2 3 0))            @result{} #t
@end smalllisp
@end deffn

@deffn {bigloo procedure} make-list n [fill]
@cindex SRFI-1
Returns an @var{n}-element list, whose elements are all the value @var{fill}. 
If the @var{fill} argument is not given, the elements of the list may be
arbitrary values.

@smalllisp
(make-list 4 'c)                     @result{} (c c c c)
@end smalllisp
@end deffn

@deffn {bigloo procedure} list-tabulate n init-proc
@cindex SRFI-1
Returns an @var{n}-element list. Element i of the list, where 0 <= i <
@var{n}, is produced by @code{(init-proc i)}. No guarantee is made about the
dynamic order in which @var{init-proc} is applied to these indices.

@smalllisp
(list-tabulate 4 values) => (0 1 2 3)
@end smalllisp
@end deffn

@deffn {bigloo procedure} iota count [start step]
@cindex SRFI-1

Returns a list containing the elements

@smalllisp
(start start+step ... start+(count-1)*step)
@end smalllisp

The @var{start} and @var{step} parameters default to @code{0} and @code{1}, 
respectively. This procedure takes its name from the APL primitive.

@smalllisp
(iota 5) => (0 1 2 3 4)
(iota 5 0 -0.1) => (0 -0.1 -0.2 -0.3 -0.4)
@end smalllisp
@end deffn

@xref{Pairs and lists,,r5rs.info,R5RS}, for more details.

@c -- Symbols -------------------------------------------------------- @c
@node  Symbols, Keywords, Pairs And Lists, Scheme Library
@comment  node-name,  next,  previous,  up
@subsection Symbols
@cindex symbols

Symbols are case sensitive and the reader is case sensitive too. So:
@smalllisp
(eq? 'foo 'FOO) @result{} #f
(eq? (string->symbol "foo") (string->symbol "FOO")) @result{} #f
@end smalllisp

Symbols may contain special characters (such as #\Newline or #\Space).
Such symbols that have to be read must be written: @code{|[^]+|}. The
function @code{write} uses that notation when it encounters symbols
containing special characters.

@smalllisp
(write 'foo) @result{} foo
(write 'Foo) @result{}Foo
(write '|foo bar|) @result{} |foo bar|
@end smalllisp

@deffn {procedure} symbol? obj
@deffnx {procedure} symbol->string symbol
Returns the name of the symbol as a string. Modifying the string result
of @code{symbol->string} could yield incoherent programs. It is better
to copy the string before any physical update. For instance, don't write:
@smalllisp
(string-downcase! (symbol->string 'foo))
@end smalllisp

@xref{Symbols,,r5rs.info, R5RS}, for more details.

but prefer:
@smalllisp
(string-downcase (symbol->string 'foo))
@end smalllisp
@end deffn

@deffn {procedure} string->symbol string
@deffnx {bigloo procedure} string->symbol-ci string
@deffnx {bigloo procedure} symbol-append symbol @dots{}
@code{String->symbol} returns a symbol whose name is @var{string}.
@code{String->symbol} respects the case of @var{string}. 
@code{String->symbol-ci} returns a symbol whose name is
@code{(string-upcase @var{string})}. @code{Symbol-append} returns a 
symbol whose name is the concatenation of all the @var{symbol}'s names.
@end deffn

@deffn {bigloo procedure} gensym [obj]

Returns a new fresh symbol. If @var{obj} is provided and is a string or
a symbol, it is used as prefix for the new symbol.
@end deffn

@deffn {bigloo procedure} symbol-plist symbol-or-keyword
Returns the property-list associated with @var{symbol-or-keyword}. 
@end deffn

@deffn {bigloo procedure} getprop symbol-or-keyword key

Returns the value that has the key @code{eq?} to @var{key} from the
@var{symbol-or-keyword}'s property list. If there is no value associated 
with @var{key} then @code{#f} is returned.
@end deffn

@deffn {bigloo procedure} putprop! symbol-or-keyword key val
Stores @var{val} using @var{key} on @var{symbol-or-keyword}'s property list.
@end deffn

@deffn {bigloo procedure} remprop! symbol-or-keyword key
Removes the value associated with @var{key} in the @var{symbol-or-keyword}'s
property list. The result is unspecified.
@end deffn

Here is an example of properties handling:

@smalllisp
(getprop 'a-sym 'a-key)       @result{} #f
(putprop! 'a-sym 'a-key 24)  
(getprop 'a-sym 'a-key)       @result{} 24
(putprop! 'a-sym 'a-key2 25)  
(getprop 'a-sym 'a-key)       @result{} 24
(getprop 'a-sym 'a-key2)      @result{} 25
(symbol-plist 'a-sym)         @result{} (a-key2 25 a-key 24)
(remprop! 'a-sym 'a-key)
(symbol-plist 'a-sym)         @result{} (a-key2 25)
(putprop! 'a-sym 'a-key2 16)  
(symbol-plist 'a-sym)         @result{} (a-key2 16)
@end smalllisp

@c -- Keywords ------------------------------------------------------- @c
@node  Keywords, Numbers, Symbols, Scheme Library
@comment  node-name,  next,  previous,  up
@subsection Keywords
@cindex keywords

Keywords constitute an extension to Scheme required by Dsssl [Dsssl96].
Keywords syntax is: @code{<@r{ident}>:}

Keywords are autoquote and case insensitive. So
@smalllisp
(eq? toto: TOTO:) @result{} #t
@end smalllisp

@deffn {bigloo procedure} keyword? obj
@deffnx {bigloo procedure} keyword->string keyword
@deffnx {bigloo procedure} string->keyword string
@end deffn

@c -- Numbers -------------------------------------------------------- @c
@node  Numbers, Characters, Keywords, Scheme Library
@comment  node-name,  next,  previous,  up
@subsection Numbers
@cindex Numbers
@cindex fixnum
@cindex fixnum (long)
@cindex long fixnum
@cindex exact fixnum
@cindex hardware fixnum
@cindex flonum

Bigloo has only three kinds of numbers: fixnum, long fixnum and flonum.
Operations on complexes and rationals are not implemented but for
compatibility purposes, the functions @code{complex?} and
@code{rational?} exist.  (In fact, @code{complex?} is the same as
@code{number?} and @code{rational?}  is the same as @code{real?} in
Bigloo.)  The binary radix is not implemented so the only accepted
prefixes are @code{#o}, @code{#d} and @code{#x}. For each generic
arithmetic procedure, Bigloo provides two specialized procedures, one
for fixnums and one for flonums. The names of these two specialized
procedures is the name of the original one suffixed by @code{fx} or
@code{fl}.  A fixnum has the size of a C @code{integer} minus 2 bits.  A
flonum has the size of a C @code{double}.

@deffn {procedure} number? obj
@deffnx {procedure} real? obj
@deffnx {procedure} integer? obj
@deffnx {bigloo procedure} complex? x
@deffnx {bigloo procedure} rational? x
@c These last two procedures always return @code{#t}.
@end deffn

@deffn {bigloo procedure} fixnum? obj
@deffnx {bigloo procedure} flonum? obj
These two procedures are type checkers on 
types @code{integer} and @code{real}.
@end deffn

@deffn {bigloo procedure} elong? obj
@deffnx {bigloo procedure} llong? obj
The @code{elong?} procedures is a type checker for "hardware" integers, that is
integers that have the very same size has the host platform permits (e.g., 
32 bits or 64 bits integers). The @code{llong?} procedure is a type checker
for "hardware" long long integers.
@end deffn

@deffn {bigloo procedure} make-elong int
Create an exact fixnum integer from the fixnum value @var{int}.
@end deffn


@deffn {procedure} exact? z
@deffnx {procedure} inexact? z
@end deffn

@deffn {library procedure} zero? z
@deffnx {library procedure} positive? z
@deffnx {library procedure} negative? z
@deffnx {library procedure} odd? n
@deffnx {library procedure} even? n
@end deffn

@deffn {library procedure} max x1 x2 @dots{}
@deffnx {library procedure} min x1 x2 @dots{}
@end deffn

@deffn {procedure} = z1 z2 z3 @dots{}
@deffnx {bigloo procedure} =fx i1 i2
@deffnx {bigloo procedure} =fl r1 r2
@deffnx {procedure} < z1 z2 z3 @dots{}
@deffnx {bigloo procedure} <fx i1 i2
@deffnx {bigloo procedure} <fl r1 r2
@deffnx {procedure} > z1 z2 z3 @dots{}
@deffnx {bigloo procedure} >fx i1 i2
@deffnx {bigloo procedure} >fl r1 r2
@deffnx {procedure} <= z1 z2 z3 @dots{}
@deffnx {bigloo procedure} <=fx i1 i2
@deffnx {bigloo procedure} <=fl r1 r2
@deffnx {procedure} >= z1 z2 z3 @dots{}
@deffnx {bigloo procedure} >=fx i1 i2
@deffnx {bigloo procedure} >=fl r1 r2
@end deffn

@deffn {procedure} + z @dots{}
@deffnx {bigloo procedure} +fx i1 i2
@deffnx {bigloo procedure} +fl r1 r2
@deffnx {procedure} * z @dots{}
@deffnx {bigloo procedure} *fx i1 i2
@deffnx {bigloo procedure} *fl r1 r2
@deffnx {procedure} - z
@deffnx {procedure} - z1 z2 @dots{}
@deffnx {bigloo procedure} -fx i1 i2
@deffnx {bigloo procedure} -fl r1 r2
@deffnx {bigloo procedure} negfx i
@deffnx {bigloo procedure} negfl r
These two functions implement the unary function @code{-}.
@end deffn

@deffn {procedure} / z1 z2
@deffnx {procedure} / z1 z2 @dots{}
@deffnx {bigloo procedure} /fx i1 i2
@deffnx {bigloo procedure} /fl r1 r2
@end deffn

@deffn {library procedure} abs z
@deffnx {procedure} quotient z1 z2
@deffnx {procedure} remainder z1 z2
@deffnx {procedure} modulo z1 z2
@deffnx {procedure} gcd z @dots{}
@deffnx {procedure} lcm z @dots{}
@deffnx {procedure} floor z
@deffnx {procedure} ceiling z
@deffnx {procedure} truncate z
@deffnx {procedure} round z
@end deffn

@deffn {procedure} exp z
@deffnx {procedure} log z
@deffnx {procedure} sin z
@deffnx {procedure} cos z
@deffnx {procedure} tan z
@deffnx {procedure} asin z
@deffnx {procedure} acos z
@deffnx {procedure} atan z1 z2
@deffnx {procedure} sqrt z
@deffnx {procedure} expt z1 x2
@end deffn

@deffn {procedure} exact->inexact z
@deffnx {procedure} inexact->exact z
@deffnx {procedure} number->string z
@deffnx {bigloo procedure} integer->string i
@deffnx {bigloo procedure} integer->string i radix
@deffnx {bigloo procedure} elong->string i
@deffnx {bigloo procedure} elong->string i radix
@deffnx {bigloo procedure} llong->string i
@deffnx {bigloo procedure} llong->string i radix
@deffnx {bigloo procedure} real->string z
@end deffn

@deffn {procedure} string->number string 
@deffnx {procedure} string->number string radix
@deffnx {procedure} string->elong string radix
@deffnx {procedure} string->llong string radix
Bigloo implements a restricted version of @code{string->number}. If
@var{string} denotes a floating point number then, the only radix
@code{10} may be send to @code{string->number}. That is:

@smalllisp
(string->number "1243" 16)          @result{} 4675
(string->number "1243.0" 16)        @print{}
# *** ERROR:bigloo:string->number
# Only radix `10' is legal for floating point number -- 16
(string->elong "234456353")         @result{} #e234456353
@end smalllisp

In addition, @code{string->number} does not support radix encoded inside 
@var{string}. That is:

@smalllisp
(string->number "#x1243")          @result{} #f
@end smalllisp
@end deffn

@deffn {bigloo procedure} string->integer string
@deffnx {bigloo procedure} string->integer string radix
@deffnx {bigloo procedure} string->real string
@deffnx {bigloo procedure} fixnum->flonum i
@deffnx {bigloo procedure} flonum->fixnum r
@deffnx {bigloo procedure} elong->flonum i
@deffnx {bigloo procedure} flonum->elong r
@deffnx {bigloo procedure} llong->flonum i
@deffnx {bigloo procedure} flonum->llong r
These last procedures implement the natural translation
from fixnum to flonum and vice versa.
@end deffn

@xref{Numerical operations,,r5rs.info,R5RS}, for more details.

@c -- Characters ----------------------------------------------------- @c
@node  Characters, UCS-2 Characters, Numbers, Scheme Library
@comment  node-name,  next,  previous,  up
@subsection Characters
@cindex characters

Bigloo knows one more named character @code{#\tab} in addition to the
@code{#\space} and @code{#\newline} of R5RS.

A new alternate syntax exists for characters:
@code{#a<ascii-code>}
where @code{<ascii-code>} is the three digit decimal ascii number
of the character to be read. Thus, for instance, the character @code{#\space}
can be written @code{#a032}.

@deffn {procedure} char? obj
@end deffn

@deffn {procedure} char=? char1 char2
@deffnx {procedure} char<? char1 char2
@deffnx {procedure} char>? char1 char2
@deffnx {procedure} char<=? char1 char2
@deffnx {procedure} char>=? char1 char2
@deffnx {library procedure} char-ci=? char1 char2
@deffnx {library procedure} char-ci<? char1 char2
@deffnx {library procedure} char-ci>? char1 char2
@deffnx {library procedure} char-ci<=? char1 char2
@deffnx {library procedure} char-ci>=? char1 char2
@end deffn

@deffn {library procedure} char-alphabetic? char
@deffnx {library procedure} char-numeric? char
@deffnx {library procedure} char-whitespace? char
@deffnx {library procedure} char-upper-case? char
@deffnx {library procedure} char-lower-case? char
@end deffn

@deffn {procedure} char->integer char
@deffnx {procedure} integer->char i
@end deffn

@deffn {library procedure} char-upcase char
@deffnx {library procedure} char-downcase char
@end deffn

@c -- UCS-2 characters ----------------------------------------------- @c
@node  UCS-2 Characters, Strings, Characters, Scheme Library
@comment  node-name,  next,  previous,  up
@subsection UCS-2 Characters
@cindex UCS-2 characters

UCS-2 Characters are two byte encoded characters. They can be read with
the syntax:
@code{#u<unicode>}
where @code{<unicode>} is the four digit hexadecimal unicode value
of the character to be read. Thus, for instance, the character @code{#\space}
can be written @code{#u0020}.

@deffn {bigloo procedure} ucs2? obj
@end deffn

@deffn {bigloo procedure} ucs2=? ucs2a ucs2b
@deffnx {bigloo procedure} ucs2<? ucs2a ucs2b
@deffnx {bigloo procedure} ucs2>? ucs2a ucs2b
@deffnx {bigloo procedure} ucs2<=? ucs2a ucs2b
@deffnx {bigloo procedure} ucs2>=? ucs2a ucs2b
@deffnx {bigloo procedure} ucs2-ci=? ucs2a ucs2b
@deffnx {bigloo procedure} ucs2-ci<? ucs2a ucs2b
@deffnx {bigloo procedure} ucs2-ci>? ucs2a ucs2b
@deffnx {bigloo procedure} ucs2-ci<=? ucs2a ucs2b
@deffnx {bigloo procedure} ucs2-ci>=? ucs2a ucs2b
@end deffn

@deffn {bigloo procedure} ucs2-alphabetic? ucs2
@deffnx {bigloo procedure} ucs2-numeric? ucs2
@deffnx {bigloo procedure} ucs2-whitespace? ucs2
@deffnx {bigloo procedure} ucs2-upper-case? ucs2
@deffnx {bigloo procedure} ucs2-lower-case? ucs2
@end deffn

@deffn {bigloo procedure} ucs2->integer ucs2
@deffnx {bigloo procedure} integer->ucs2 i
@end deffn

@deffn {bigloo procedure} ucs2->char ucs2
@deffnx {bigloo procedure} char->ucs2 char
@end deffn

@deffn {bigloo procedure} ucs2-upcase ucs2
@deffnx {bigloo procedure} ucs2-downcase ucs2
@end deffn

@c -- Strings -------------------------------------------------------- @c
@node  Strings, Unicode (UCS-2) Strings, UCS-2 Characters, Scheme Library
@comment  node-name,  next,  previous,  up
@subsection Strings
@cindex Strings

There are three different syntaxes for strings in Bigloo: traditional,
foreign or Unicode. The traditional syntax for strings may conform to
the Revised Report, see @ref{Lexical structure,,r5rs.info,R5RS}. 
With the foreign syntax, C escape
sequences are interpreted as specified by ISO-C. In addition, Bigloo's
reader evaluate @code{\x??} sequence as an hexadecimal escape
character. For Unicode syntax, see @ref{Unicode (UCS-2) Strings}. Only
the reader distinguishes between these three appearances of strings;
i.e., there is only one type of string at evaluation-time. The regular
expression describing the syntax for foreign string is:
@code{#"([^"]|\")*"}.

@deffn {variable} *bigloo-strict-r5rs-strings*

Traditional syntax conforms to the Revised Report if the variable 
@code{*bigloo-strict-r5rs-strings*} is not @code{#f}. Otherwise
constant strings specified by the @code{"([^"]|\")*"} are considered
as foreign strings.


For example, after reading the expression 
@code{"1\n23\t4\"5"}, the following string is built, which is equal to
@code{(string #\1 #\n #\2 #\3 #\t #\4 #\" #\5)} if 
@code{*bigloo-strict-r5rs-strings*} is not @code{#f}. It is 
@code{(string #\1 #\n #\2 #\3 #\tab #\4 #\" #\5)} otherwise.

Printing this string will produce: @code{1n23t4"5}.

@c The new foreign syntax allows C escape sequences to be recognized as in:
@c @code{#"1\n23\t4\"5"} This expression builds a string equal to:

The new foreign syntax allows C escape sequences to be recognized. For
example, the expression @code{#"1\n23\t4\"5"} builds a string equal to:

@code{(string #\1 #\newline #\2 #\3 #\t #\4 #\" #\5)}

@noindent and printing this string will then produce: 
@smalllisp
1
23    4"5
@end smalllisp
@end deffn

The library functions for string processing are:
@deffn {procedure} string? obj
@end deffn

@deffn {procedure} make-string k
@deffnx {procedure} make-string k char
@deffnx {library procedure} string char @dots{}
@end deffn

@deffn {procedure} string-length string
@deffnx {procedure} string-ref string k
@deffnx {procedure} string-set! string k char
@end deffn

@deffn {library procedure} string=? string1 string2
@deffnx {bigloo procedure} substring=? string1 string2 len

This function returns @code{#t} if @var{string1} and @var{string2} have a
common prefix of size @var{len}. 

@smalllisp
(substring=? "abcdef" "ab9989898" 2)
   @result{} #t
(substring=? "abcdef" "ab9989898" 3)
   @result{} #f
@end smalllisp
@end deffn

@deffn {library procedure} string-ci=? string1 string2
@deffnx {library procedure} string<? string1 string2
@deffnx {library procedure} string>? string1 string2
@deffnx {library procedure} string<=? string1 string2
@deffnx {library procedure} string>=? string1 string2
@deffnx {library procedure} string-ci<? string1 string2
@deffnx {library procedure} string-ci>? string1 string2
@deffnx {library procedure} string-ci<=? string1 string2
@deffnx {library procedure} string-ci>=? string1 string2
@end deffn

@deffn {bigloo procedure} string-compare3 string1 string2
@deffnx {bigloo procedure} string-compare3-ci string1 string2
This function compares @var{string1} and @var{string2}. It returns
a negative integer if @var{string1} < @var{string2}. It returns
zero if the @var{string1} equal @var{string2}. It returns
a positive integer if @var{string1} > @var{string2}.
@end deffn

@deffn {library procedure} substring string start end

@var{string} must be a string, and @var{start} and @var{end} must be
exact integers satisfying:

@smallexample
  0 <= START <= END <= (string-length STRING)
@end smallexample

@code{substring} returns a newly allocated string formed from the
characters of @var{STRING} beginning with index @var{START} (inclusive) 
and ending with index @var{END} (exclusive).

@smalllisp
(substring "abcdef" 0 5)
   @result{} "abcde"
(substring "abcdef" 1 5)
   @result{} "bcde"
@end smalllisp
@end deffn

@deffn {library procedure} string-shrink! string end

@var{string} must be a string, and @var{end} must be
an exact integers satisfying:

@smallexample
  0 <= END <= (string-length STRING)
@end smallexample

@code{string-shrink!} returns a newly allocated string formed from the
characters of @var{STRING} beginning with index 0 (inclusive) 
and ending with index @var{END} (exclusive). As much as possible 
@code{string-shrink!} changes the argument @var{string}. That is, as much
as possible, and for the back-ends that enable it, @var{string-shrink!}
operate a side effect on its argument.

@smalllisp
(let ((s (string #\a #\b #\c #\d #\e)))
   (set! s (string-shrink! s 3))
   s)
   @result{} "abc"
@end smalllisp
@end deffn

@deffn {library procedure} string-append string @dots{}
@deffnx {library procedure} string->list string
@deffnx {library procedure} list->string list
@deffnx {library procedure} string-copy string
@end deffn

@deffn {bigloo procedure} string-fill! string char
Stores @var{char} in every element of the given @var{string}
and returns an unspecified value.
@end deffn

@deffn {bigloo procedure} string-downcase string
Returns a newly allocated version of string where each upper case
letter is replaced by its lower case equivalent.
@end deffn

@deffn {bigloo procedure} string-upcase string
Returns a newly allocated version of string where each lower case
letter is replaced by its upper case equivalent.
@end deffn

@deffn {bigloo procedure} string-capitalize string
Builds a newly allocated capitalized string.
@end deffn

@deffn {bigloo procedure} string-downcase! string
Physically downcases the @var{string} argument.
@end deffn

@deffn {bigloo procedure} string-upcase! string
Physically upcases the @var{string} argument.
@end deffn

@deffn {bigloo procedure} string-capitalize! string
Physically capitalized the @var{string} argument.
@end deffn

@deffn {bigloo procedure} string-for-read string
Returns a copy of @var{string} with each special character
replaced by an escape sequence.
@end deffn

@deffn {bigloo procedure} blit-string! string1 o1 string2 o2 len
Fill string @var{s2} starting at position @var{o2} with
@var{len} characters taken out of string @var{s1} from
position @var{o1}.

@smalllisp
(let ((s (make-string 20 #\-)))
	(blit-string! "toto" 0 s 16 4)
	s)
   @result{} "----------------toto"
@end smalllisp
@end deffn

@c -- Unicode (UCS-2) strings ---------------------------------------- @c
@node  Unicode (UCS-2) Strings, Vectors, Strings, Scheme Library
@comment  node-name,  next,  previous,  up
@subsection Unicode (UCS-2) Strings
@cindex UCS-2 strings

UCS-2 strings cannot be read by the standard reader but UTF-8 strings
can. The special syntax for UTF-8 is described by the
regular expression:
@code{#u"([^]|\")*"}.

The library functions for Unicode string processing are:
@deffn {bigloo procedure} ucs2-string? obj
@end deffn

@deffn {bigloo procedure} make-ucs2-string k
@deffnx {bigloo procedure} make-ucs2-string k char
@deffnx {bigloo procedure} ucs2-string k @dots{}
@end deffn

@deffn {bigloo procedure} ucs2-string-length s-ucs2
@deffnx {bigloo procedure} ucs2-string-ref s-ucs2 k
@deffnx {bigloo procedure} ucs2-string-set! s-ucs2 k char
@end deffn

@deffn {bigloo procedure} ucs2-string=? s-ucs2a s-ucs2b
@deffnx {bigloo procedure} ucs2-string-ci=? s-ucs2a s-ucs2b
@deffnx {bigloo procedure} ucs2-string<? s-ucs2a s-ucs2b
@deffnx {bigloo procedure} ucs2-string>? s-ucs2a s-ucs2b
@deffnx {bigloo procedure} ucs2-string<=? s-ucs2a s-ucs2b
@deffnx {bigloo procedure} ucs2-string>=? s-ucs2a s-ucs2b
@deffnx {bigloo procedure} ucs2-string-ci<? s-ucs2a s-ucs2b
@deffnx {bigloo procedure} ucs2-string-ci>? s-ucs2a s-ucs2b
@deffnx {bigloo procedure} ucs2-string-ci<=? s-ucs2a s-ucs2b
@deffnx {bigloo procedure} ucs2-string-ci>=? s-ucs2a s-ucs2b
@end deffn

@deffn {bigloo procedure} subucs2-string s-ucs2 start end
@deffnx {bigloo procedure} ucs2-string-append s-ucs2 @dots{}
@deffnx {bigloo procedure} ucs2-string->list s-ucs2
@deffnx {bigloo procedure} list->ucs2-string chars
@deffnx {bigloo procedure} ucs2-string-copy s-ucs2
@end deffn

@deffn {bigloo procedure} ucs2-string-fill! s-ucs2 char
Stores @var{char} in every element of the given s-ucs2
and returns an unspecified value.
@end deffn

@deffn {bigloo procedure} ucs2-string-downcase s-ucs2
Builds a newly allocated ucs2-string with lower case letters.
@end deffn

@deffn {bigloo procedure} ucs2-string-upcase s-ucs2
Builds a new allocated ucs2-string with upper case letters.
@end deffn

@deffn {bigloo procedure} ucs2-string-downcase! s-ucs2
Physically downcases the @var{s-ucs2} argument.
@end deffn

@deffn {bigloo procedure} ucs2-string-upcase! s-ucs2
Physically upcases the @var{s-ucs2} argument.
@end deffn

@deffn {bigloo procedure} ucs2-string->utf8-string s-ucs2
@deffnx {bigloo procedure} utf8-string->ucs2-string @var{string}
Convert UCS-2 strings to (or from) UTF-8 encoded ascii strings.
@end deffn

@c -- Vectors -------------------------------------------------------- @c
@node  Vectors, Control Features, Unicode (UCS-2) Strings, Scheme Library
@comment  node-name,  next,  previous,  up
@subsection Vectors
@cindex vectors

Vectors are not autoquoted objects.

@deffn {procedure} vector? obj
@end deffn

@deffn {procedure} make-vector k
@deffnx {procedure} make-vector k obj
@deffnx {library procedure} vector obj @dots{}
@end deffn

@deffn {procedure} vector-length vector
@deffnx {procedure} vector-ref vector k
@deffnx {procedure} vector-set! vector k obj
@end deffn

@deffn {library procedure} vector->list vector
@deffnx {library procedure} list->vector list
@end deffn

@deffn {library procedure} vector-fill! vector obj
Stores  @var{obj} in every element of @var{vector}. For instance:

@smalllisp
(let ((v (make-vector 5 #f)))
   (vector-fill! v #t)
   v)
@end smalllisp
@end deffn

@deffn {bigloo procedure} copy-vector vector len
Allocate a new vector of size @var{len} and fills it with the first @var{len}
element of @var{vector}. The new length @var{len} might be bigger than
the old vector length.
@end deffn

@deffn {bigloo procedure} vector-copy vector start end
@var{vector} must be a vector, and @var{start} and @var{end} must be
exact integers satisfying:

@smallexample
  0 <= START <= END <= (vector-length VECTOR)
@end smallexample

@code{vector-copy} returns a newly allocated vector formed from the
elements of @var{VECTOR} beginning with index @var{START} (inclusive) 
and ending with index @var{END} (exclusive).

@smalllisp
(vector-copy '#(1 2 3 4) 0 4)
   @result{} '#(1 2 3 4)
(vector-copy '#(1 2 3 4) 1 3)
   @result{} '#(2 3)
@end smalllisp
@end deffn

@xref{Vectors,,r5rs.info}, for more details.

@c -- Control features ----------------------------------------------- @c
@node Control Features, , Vectors, Scheme Library
@comment  node-name,  next,  previous,  up
@subsection Control features
@cindex control features

@deffn {procedure} procedure? obj
@end deffn
 
@deffn {procedure} apply proc arg1 @dots{} args
@end deffn

@deffn {library procedure} map proc list1 list2 @dots{}
@deffnx {library procedure} for-each proc list1 list2 @dots{}
@end deffn

@deffn {library procedure} filter pred list @dots{}
@deffnx {library procedure} filter! pred list @dots{}
Strip out all elements of @var{list} for which the predicate @var{pred}
is not true. The second version @code{filter!} is destructive:

@smalllisp
(filter number? '(1 2 #\a "foo" foo 3)) @result{} (1 2 3)
(let ((l (list 1 2 #\a "foo" 'foo 3)))
   (set! l (filter! number? l))
   l)                                   @result{} (1 2 3)
@end smalllisp

@end deffn

@deffn {bigloo procedure} sort obj proc
Sorts @var{obj} according to @var{proc} test. The argument @var{obj} can
either be a vector or a list. In either case, a copy of the argument
is returned. For instance:

@smalllisp
(let ((l '(("foo" 5) ("bar" 6) ("hux" 1) ("gee" 4))))
   (sort l (lambda (x y) (string<? (car x) (car y)))))
   @result{} ((bar 6) (foo 5) (gee 4) (hux 1))
@end smalllisp
@end deffn

@deffn {library procedure} force promise
@end deffn

@deffn {bigloo procedure} call/cc proc
This function is the same as the @code{call-with-current-continuation}
function of the R5RS, see @ref{call-with-current-continuation,,r5rs.info,R5RS},
but it is necessary to compile the module with the @code{-call/cc} 
option to use it, see Section
@xref{Compiler Description, , The Bigloo command line}.

Note: Since @code{call/cc} is difficult to compile efficiently, 
one might consider using @code{bind-exit} instead. 
For this reason, we decided to enable @code{call/cc} only with a 
compiler option.
@end deffn

@deffn {bigloo syntax} bind-exit escape body
This form provides an escape operator facility. @code{bind-exit}
evaluates the @var{body}, which may refer to the variable 
@var{escape} which will denote an ``escape function'' of one
argument: when called, this escape function will return from
the @code{bind-exit} form with the given argument as the value of
the @code{bind-exit} form. The @var{escape} can only be used
while in the dynamic extent of the form. Bindings introduced by
@code{bind-exit} are immutable.

@smalllisp
(bind-exit (exit)
 (for-each (lambda (x)
             (if (negative? x)
                 (exit x)))
           '(54 0 37 -3 245 19))
 #t)                                  @result{} -3

(define list-length
  (lambda (obj)
    (bind-exit (return)
     (letrec ((r (lambda (obj)
                    (cond ((null? obj) 0)
                          ((pair? obj)
                           (+ (r (cdr obj)) 1))
                          (else (return #f))))))
          (r obj)))))

(list-length '(1 2 3 4))               @result{} 4
(list-length '(a b . c))               @result{} #f
@end smalllisp
@end deffn

@deffn {bigloo syntax} unwind-protect expr protect
This form provides protections. Expression @var{expr} is
evaluated. If this evaluation requires the invocation of an
escape procedure (a procedure bounded by the @code{bind-exit}
special form), @var{protect} is evaluated before the control
jump to the exit procedure. If @var{expr} does not raise any
exit procedure, @code{unwind-protect} has the same behaviour as
the @code{begin} special form except that the value of the form is 
always the value of @var{expr}.

@smalllisp
(define (my-open f)
   (if (file-exists? f)
       (let ((port (open-input-file f)))
          (if (input-port? port)
              (unwind-protect
                 (bar port)
                 (close-input-port port))))))
@end smalllisp
@end deffn

@deffn {procedure} dynamic-wind  before thunk after

Calls @var{thunk} without arguments, returning the result(s) of this call.
@var{Before} and @var{after} are called, also without arguments, as required
by the following rules (note that in the absence of calls to continuations
captured using @code{call/cc} the three arguments are
@vindex @w{call/cc}
called once each, in order).  @var{Before} is called whenever execution
enters the dynamic extent of the call to @var{thunk} and @var{after} is called
whenever it exits that dynamic extent.  The dynamic extent of a procedure
call is the period between when the call is initiated and when it
returns.  In Scheme, because of @code{call/cc}, the
dynamic extent of a call may not be a single, connected time period.
It is defined as follows:

@itemize @bullet

@item
The dynamic extent is entered when execution of the body of the
called procedure begins.

@item
The dynamic extent is also entered when execution is not within
the dynamic extent and a continuation is invoked that was captured
(using @code{call/cc}) during the dynamic extent.

@item
It is exited when the called procedure returns.

@item
It is also exited when execution is within the dynamic extent and
a continuation is invoked that was captured while not within the
dynamic extent.

@end itemize

If a second call to @code{dynamic-wind} occurs within the dynamic extent of the
call to @var{thunk} and then a continuation is invoked in such a way that the
@var{after}s from these two invocations of @code{dynamic-wind} are both to be
called, then the @var{after} associated with the second (inner) call to
@code{dynamic-wind} is called first.

If a second call to @code{dynamic-wind} occurs within the dynamic extent of the
call to @var{thunk} and then a continuation is invoked in such a way that the
@var{before}s from these two invocations of @code{dynamic-wind} are both to be
called, then the @var{before} associated with the first (outer) call to
@code{dynamic-wind} is called first.

If invoking a continuation requires calling the @var{before} from one call
to @code{dynamic-wind} and the @var{after} from another, then the @var{after}
is called first.

The effect of using a captured continuation to enter or exit the dynamic
extent of a call to @var{before} or @var{after} is undefined.


@smalllisp
(let ((path '())
      (c #f))
  (let ((add (lambda (s)
               (set! path (cons s path)))))
    (dynamic-wind
      (lambda () (add 'connect))
      (lambda ()
        (add (call/cc
               (lambda (c0)
                 (set! c c0)
                 'talk1))))
      (lambda () (add 'disconnect)))
    (if (< (length path) 4)
        (c 'talk2)
        (reverse path))))
    
   @result{} (connect talk1 disconnect connect talk2 disconnect)
@end smalllisp

@end deffn

@deffn {bigloo procedure} unspecified
Returns the @emph{unspecified} (noted as @code{#unspecified}) object with 
no specific property.
@end deffn

@deffn {bigloo syntax} try exp handler
This form is documented in Section @ref{Errors and Assertions}.
@end deffn

@deffn {procedure} values  obj @dots{}

Delivers all of its arguments to its continuation.
Except for continuations created by the @code{call-with-values}
@vindex @w{call-with-values}
procedure, all continuations take exactly one value.
@t{Values} might be defined as follows:

@smalllisp
(define (values . things)
  (call/cc
    (lambda (cont) (apply cont things))))
@end smalllisp

@end deffn

@deffn {procedure} call-with-values  producer consumer
Calls its @var{producer} argument with no values and
a continuation that, when passed some values, calls the
@var{consumer} procedure with those values as arguments.
The continuation for the call to @var{consumer} is the
continuation of the call to @t{call-with-values}.

@smalllisp
(call-with-values (lambda () (values 4 5))
                  (lambda (a b) b))
    @result{} 5
(call-with-values * -)
    @result{} -1
@end smalllisp

@end deffn

@deffn {bigloo syntax} multiple-value-bind (var @dots{}) producer exp @dots{}
@deffnx {bigloo syntax} receive (var @dots{}) producer exp @dots{}
@cindex SRFI-8
Evaluates @var{exp} @dots{} in a environment where @var{var} @dots{} are bound 
from the evaluation of @var{producer}. The result of @var{producer} must 
be a call to @code{values} where the number of argument is the number of 
bound variables.
@smalllisp
(define (bar a)
   (values (modulo a 5) (quotient a 5)))

(define (foo a)
   (multiple-value-bind (x y)
      (bar a)
      (print x " " y)))

(foo 354)
   @print{} 4 70
@end smalllisp
@end deffn

@c ------------------------------------------------------------------- @c
@c    io                                                               @c
@c ------------------------------------------------------------------- @c
@include io.texi

@c ------------------------------------------------------------------- @c
@c    Structures                                                       @c
@c ------------------------------------------------------------------- @c
@include struct.texi

@c ------------------------------------------------------------------- @c
@c    Serialization                                                    @c
@c ------------------------------------------------------------------- @c
@include serialization.texi

@c ------------------------------------------------------------------- @c
@c    Bit                                                              @c
@c ------------------------------------------------------------------- @c
@include bit.texi

@c ------------------------------------------------------------------- @c
@c    Hash tables                                                      @c
@c ------------------------------------------------------------------- @c
@include hash.texi

@c ------------------------------------------------------------------- @c
@c    System                                                           @c
@c ------------------------------------------------------------------- @c
@include system.texi

@c ------------------------------------------------------------------- @c
@c    Date                                                             @c
@c ------------------------------------------------------------------- @c
@include date.texi

@c ------------------------------------------------------------------- @c
@c    Pregexp                                                          @c
@c ------------------------------------------------------------------- @c
@include pregexp.texi

