5. Bigloo -- Standard Library 5.1 Scheme Library

Browsing
Home: | Bigloo A ``practical Scheme compiler'' User manual for version 2.6b December 2003
Previous chapter: | Core Language
Next chapter: | Pattern Matching
Standard Library
5.1 | Scheme Library
| 5.1.1 | Booleans
| 5.1.2 | Equivalence predicates
| 5.1.3 | Pairs and lists
| 5.1.4 | Symbols
| 5.1.5 | Keywords
| 5.1.6 | Numbers
| 5.1.7 | Characters
| 5.1.8 | UCS-2 Characters
| 5.1.9 | Strings
| 5.1.10 | Unicode (UCS-2) Strings
| 5.1.11 | Vectors
| 5.1.12 | Control features
5.2 | Input and output
5.3 | Structures and Records
| 5.3.1 | Structures
| 5.3.2 | Records (SRFI-9)
5.4 | Serialization
5.5 | Bit manipulation
5.6 | Hash Tables
| 5.6.1 | Hash tables
| 5.6.2 | Deprecated Hash tables
5.7 | System programming
| 5.7.1 | Operating System interface
| 5.7.2 | Files
5.8 | Process support
5.9 | Socket support
5.10 | Date
5.11 | Posix Regular Expressions
| 5.11.1 | Regular Expressions Procedures
| 5.11.2 | Regular Expressions Pattern Language
| 5.11.3 | An Extended Example
Chapters
| Acknowledgements
1. | Table of contents
2. | Overview of Bigloo
3. | Modules
4. | Core Language
5. | Standard Library
6. | Pattern Matching
7. | Object System
8. | Threads
9. | Regular parsing
10. | Lalr(1) parsing
11. | Errors and Assertions
12. | Eval and code interpretation
13. | Macro expansion
14. | Command Line Parsing
15. | Explicit typing
16. | The C interface
17. | The Java interface
18. | Bigloo Libraries
19. | Extending the Runtime System
20. | SRFIs
21. | DSSSL support
22. | Compiler description
23. | User Extensions
24. | Bigloo Development Environment
25. | Global Index
26. | Library Index
| Bibliography
| 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''. ### 5.1.1 Booleans The standard boolean objects are `#t` and `#f`. Note: the empty list is true.
not obj | library procedure
`not` returns `#t` if `obj` is false, and returns `#f` otherwise.
    (not #t)                               => #f
    (not 3)                                => #f
    (not (list 3))                         => #f
    (not #f)                               => #t
    (not '())                              => #f
    (not (list))                           => #f
    (not 'nil)                             => #f

boolean? obj | library procedure
`Boolean?` returns `#t` if `obj` is either `#t` or `#f` and returns `#f` otherwise.
    (boolean? #f)                          => #t
    (boolean? 0)                           => #f
    (boolean? '())                         => #f

### 5.1.2 Equivalence predicates

eqv? obj1 obj2 | procedure
eq? obj1 obj2 | procedure
`eqv?` and `eq?` are equivalent in Bigloo.
    (eq? 'a 'a)                            =>  #t
    (eq? '(a) '(a))                        =>  unspecified
    (eq? (list 'a) (list 'a))              =>  #f
    (eq? "a" "a")                          =>  unspecified
    (eq? "" "")                            =>  unspecified
    (eq? '() '())                          =>  #t
    (eq? 2 2)                              =>  unspecified
    (eq? #\A #\A)                          =>  unspecified
    (eq? car car)                          =>  #t
    (let ((n (+ 2 3)))
      (eq? n n))                           =>  unspecified
    (let ((x '(a)))
      (eq? x x))                           =>  #t
    (let ((x '#()))
      (eq? x x))                           =>  #t
    (let ((p (lambda (x) x)))
      (eq? p p))                           =>  #t
Since Bigloo implements `eqv?` as `eq?`, the behavior is not always conforming to R5RS.
    (eqv? 'a 'a)                           =>  #t
    (eqv? 'a 'b)                           =>  #f
    (eqv? 2 2)                             =>  #t
    (eqv? '() '())                         =>  #t
    (eqv? 100000000 100000000)             =>  #t
    (eqv? (cons 1 2) (cons 1 2))           =>  #f
    (eqv? (lambda () 1)
          (lambda () 2))                   =>  #f
    (eqv? #f 'nil)                         =>  #f
    (let ((p (lambda (x) x)))
      (eqv? p p))                          =>  unspecified
The following examples illustrate cases in which the above rules do not fully specify the behavior of `eqv?`. All that can be said about such cases is that the value returned by `eqv?` must be a boolean.
    (eqv? "" "")                           =>  unspecified
    (eqv? '#() '#())                       =>  unspecified
    (eqv? (lambda (x) x)
          (lambda (x) x))                  =>  unspecified
    (eqv? (lambda (x) x)
          (lambda (y) y))                  =>  unspecified

    (define gen-counter
      (lambda ()
        (let ((n 0))
          (lambda () (set! n (+ n 1)) n))))
    (let ((g (gen-counter)))
      (eqv? g g))                          =>  #t
    (eqv? (gen-counter) (gen-counter))
                                           =>  #f
    (define gen-loser
      (lambda ()
        (let ((n 0))
          (lambda () (set! n (+ n 1)) 27))))
    (let ((g (gen-loser)))
      (eqv? g g))                          =>  #t
    (eqv? (gen-loser) (gen-loser))
                                           =>  unspecified

    (letrec ((f (lambda () (if (eqv? f g) 'both 'f)))
             (g (lambda () (if (eqv? f g) 'both 'g))))
      (eqv? f g))
                                           =>  unspecified

    (letrec ((f (lambda () (if (eqv? f g) 'f 'both)))
             (g (lambda () (if (eqv? f g) 'g 'both))))
      (eqv? f g))
                                           =>  #f
    (eqv? '(a) '(a))                       =>  unspecified
    (eqv? "a" "a")                         =>  unspecified
    (eqv? '(b) (cdr '(a b)))               =>  unspecified
    (let ((x '(a)))
      (eqv? x x))                          =>  #t

equal? obj1 obj2 | library procedure
    (equal? 'a 'a)                         =>  #t
    (equal? '(a) '(a))                     =>  #t
    (equal? '(a (b) c)
            '(a (b) c))                    =>  #t
    (equal? "abc" "abc")                   =>  #t
    (equal? 2 2)                           =>  #t
    (equal? (make-vector 5 'a)
            (make-vector 5 'a))            =>  #t
    (equal? (lambda (x) x)
            (lambda (y) y))                =>  unspecified

See r5rs, Equivalence predicates, for more details.

### 5.1.3 Pairs and lists

The form `()` is illegal.

pair? obj | procedure

pair-or-null? obj | bigloo procedure
Returns `#t` if `obj` is either a pair or the empty list. Otherwise it returns `#f`.

car pair | procedure
cdr pair | procedure
set-car! pair obj | procedure
set-cdr! pair obj | procedure

caar pair | library procedure
cadr pair | library procedure
...
cdddar pair | library procedure
cddddr pair | library procedure

null? obj | library procedure
list? obj | library procedure
list obj ... | library procedure
length list | library procedure
append list ... | library procedure
append! list ... | bigloo procedure
A destructive append.

reverse list | library procedure
reverse! list | bigloo procedure
A destructive reverse.

list-ref list k | library procedure
list-tail list k | library procedure
Returns the sublist of `list` obtained by omitting the first `k` elements.

last-pair list | bigloo procedure
Returns the last pair in the nonempty, possibly improper, `list`.

memq obj list | library procedure
memv obj list | library procedure
member obj list | library procedure
assq obj alist | library procedure
assv obj alist | library procedure
assoc obj alist | library procedure
remq obj list | bigloo procedure
Returns a new list which is a copy of `list` with all items `eq?` to `obj` removed from it.

remq! obj list | bigloo procedure
Same as `remq` but in a destructive way.

delete obj list | bigloo procedure
Returns a new list which is a copy of `list` with all items `equal?` to `obj` deleted from it.

delete! obj list | bigloo procedure
Same as `delete` but in a destructive way.

cons* obj ... | bigloo procedure
Returns an object formed by consing all arguments together from right to left. If only one `obj` is supplied, that `obj` is returned.

every? pred clist1 clist2 ... | bigloo procedure
Applies the predicate across the lists, returning true if the predicate returns true on every application.
    (every < '(1 2 3) '(2 3 4))            => #t
    (every < '(1 2 3) '(2 3 0))            => #f

any? pred clist1 clist2 ... | bigloo procedure
Applies the predicate across the lists, returning true if the predicate returns true for at least one application.
    (any < '(1 2 3) '(2 3 4))            => #t
    (any < '(1 2 3) '(2 3 0))            => #t

every fun clist1 clist2 ... | bigloo procedure
Applies the function `fun` across the lists, returning the last non-false if the function returns non-false on every application. If non-false, the result of `every` is the last value returned by the last application of `fun`.
    (every < '(1 2 3) '(2 3 4))            => #t
    (every < '(1 2 3) '(2 3 0))            => #f

any fun clist1 clist2 ... | bigloo procedure
Applies the function `fun` across the lists, returning non-false if the function returns non-false for at least one application. If non-false, the result of `any` is the first non-false value returned by `fun`.
    (any < '(1 2 3) '(2 3 4))            => #t
    (any < '(1 2 3) '(2 3 0))            => #t

make-list n [fill] | bigloo procedure
Returns an `n`-element list, whose elements are all the value `fill`. If the `fill` argument is not given, the elements of the list may be arbitrary values.
    (make-list 4 'c)                     => (c c c c)

list-tabulate n init-proc | bigloo procedure
Returns an `n`-element list. Element i of the list, where 0 <= i < `n`, is produced by `(init-proc i)`. No guarantee is made about the dynamic order in which `init-proc` is applied to these indices.
    (list-tabulate 4 values) => (0 1 2 3)

iota count [start step] | bigloo procedure
Returns a list containing the elements
    (start start+step ... start+(count-1)*step)
The `start` and `step` parameters default to `0` and `1`, respectively. This procedure takes its name from the APL primitive.
    (iota 5) => (0 1 2 3 4)
    (iota 5 0 -0.1) => (0 -0.1 -0.2 -0.3 -0.4)

See r5rs, Pairs and lists, for more details.

### 5.1.4 Symbols

Symbols are case sensitive and the reader is case sensitive too. So:

    (eq? 'foo 'FOO) => #f
    (eq? (string->symbol "foo") (string->symbol "FOO")) => #f

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

    (write 'foo) => foo
    (write 'Foo) =>Foo
    (write '|foo bar|) => |foo bar|

symbol? obj | procedure
symbol->string symbol | procedure
Returns the name of the symbol as a string. Modifying the string result of `symbol->string` could yield incoherent programs. It is better to copy the string before any physical update. For instance, don't write:
    (string-downcase! (symbol->string 'foo))
See r5rs, Symbols, for more details. but prefer:
    (string-downcase (symbol->string 'foo))

string->symbol string | procedure
string->symbol-ci string | bigloo procedure
symbol-append symbol ... | bigloo procedure
`String->symbol` returns a symbol whose name is `string`. `String->symbol` respects the case of `string`. `String->symbol-ci` returns a symbol whose name is `(string-upcase `string`)`. `Symbol-append` returns a symbol whose name is the concatenation of all the `symbol`'s names.

gensym [obj] | bigloo procedure
Returns a new fresh symbol. If `obj` is provided and is a string or a symbol, it is used as prefix for the new symbol.

symbol-plist symbol-or-keyword | bigloo procedure
Returns the property-list associated with `symbol-or-keyword`.

getprop symbol-or-keyword key | bigloo procedure
Returns the value that has the key `eq?` to `key` from the `symbol-or-keyword`'s property list. If there is no value associated with `key` then `#f` is returned.

putprop! symbol-or-keyword key val | bigloo procedure
Stores `val` using `key` on `symbol-or-keyword`'s property list.

remprop! symbol-or-keyword key | bigloo procedure
Removes the value associated with `key` in the `symbol-or-keyword`'s property list. The result is unspecified.

Here is an example of properties handling:

    (getprop 'a-sym 'a-key)       => #f
    (putprop! 'a-sym 'a-key 24)
    (getprop 'a-sym 'a-key)       => 24
    (putprop! 'a-sym 'a-key2 25)
    (getprop 'a-sym 'a-key)       => 24
    (getprop 'a-sym 'a-key2)      => 25
    (symbol-plist 'a-sym)         => (a-key2 25 a-key 24)
    (remprop! 'a-sym 'a-key)
    (symbol-plist 'a-sym)         => (a-key2 25)
    (putprop! 'a-sym 'a-key2 16)
    (symbol-plist 'a-sym)         => (a-key2 16)

### 5.1.5 Keywords

Keywords constitute an extension to Scheme required by Dsssl [Dsssl96]. Keywords syntax is: `<ident>:`
Keywords are autoquote and case insensitive. So

    (eq? toto: TOTO:) => #t

keyword? obj | bigloo procedure
keyword->string keyword | bigloo procedure
string->keyword string | bigloo procedure

### 5.1.6 Numbers

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 `complex?` and `rational?` exist. (In fact, `complex?` is the same as `number?` and `rational?` is the same as `real?` in Bigloo.) The binary radix is not implemented so the only accepted prefixes are `#o`, `#d` and `#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 `fx` or `fl`. A fixnum has the size of a C `integer` minus 2 bits. A flonum has the size of a C `double`.

number? obj | procedure
real? obj | procedure
integer? obj | procedure
complex? x | bigloo procedure
rational? x | bigloo procedure

fixnum? obj | bigloo procedure
flonum? obj | bigloo procedure
These two procedures are type checkers on types `integer` and `real`.

elong? obj | bigloo procedure
llong? obj | bigloo procedure
The `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 `llong?` procedure is a type checker for "hardware" long long integers.

make-elong int | bigloo procedure
Create an exact fixnum integer from the fixnum value `int`.

exact? z | procedure
inexact? z | procedure

zero? z | library procedure
positive? z | library procedure
negative? z | library procedure
odd? n | library procedure
even? n | library procedure

max x1 x2 ... | library procedure
min x1 x2 ... | library procedure

= z1 z2 z3 ... | procedure
=fx i1 i2 | bigloo procedure
=fl r1 r2 | bigloo procedure
< z1 z2 z3 ... | procedure
<fx i1 i2 | bigloo procedure
<fl r1 r2 | bigloo procedure
> z1 z2 z3 ... | procedure
>fx i1 i2 | bigloo procedure
>fl r1 r2 | bigloo procedure
<= z1 z2 z3 ... | procedure
<=fx i1 i2 | bigloo procedure
<=fl r1 r2 | bigloo procedure
>= z1 z2 z3 ... | procedure
>=fx i1 i2 | bigloo procedure
>=fl r1 r2 | bigloo procedure

+ z ... | procedure
+fx i1 i2 | bigloo procedure
+fl r1 r2 | bigloo procedure
* z ... | procedure
*fx i1 i2 | bigloo procedure
*fl r1 r2 | bigloo procedure
- z | procedure
- z1 z2 ... | procedure
-fx i1 i2 | bigloo procedure
-fl r1 r2 | bigloo procedure
negfx i | bigloo procedure
negfl r | bigloo procedure
These two functions implement the unary function `-`.

/ z1 z2 | procedure
/ z1 z2 ... | procedure
/fx i1 i2 | bigloo procedure
/fl r1 r2 | bigloo procedure

abs z | library procedure
quotient z1 z2 | procedure
remainder z1 z2 | procedure
modulo z1 z2 | procedure
gcd z ... | procedure
lcm z ... | procedure
floor z | procedure
ceiling z | procedure
truncate z | procedure
round z | procedure

exp z | procedure
log z | procedure
sin z | procedure
cos z | procedure
tan z | procedure
asin z | procedure
acos z | procedure
atan z1 z2 | procedure
sqrt z | procedure
expt z1 x2 | procedure

exact->inexact z | procedure
inexact->exact z | procedure
number->string z | procedure
integer->string i | bigloo procedure
integer->string i radix | bigloo procedure
elong->string i | bigloo procedure
elong->string i radix | bigloo procedure
llong->string i | bigloo procedure
llong->string i radix | bigloo procedure
real->string z | bigloo procedure

string->number string | procedure
string->number string radix | procedure
string->elong string radix | procedure
string->llong string radix | procedure
Bigloo implements a restricted version of `string->number`. If `string` denotes a floating point number then, the only radix `10` may be send to `string->number`. That is:
    (string->number "1243" 16)          => 4675
    (string->number "1243.0" 16)        -|
    # *** ERROR:bigloo:string->number
    # Only radix `10' is legal for floating point number -- 16
    (string->elong "234456353")         => #e234456353
In addition, `string->number` does not support radix encoded inside `string`. That is:
    (string->number "#x1243")          => #f

string->integer string | bigloo procedure
string->integer string radix | bigloo procedure
string->real string | bigloo procedure
fixnum->flonum i | bigloo procedure
flonum->fixnum r | bigloo procedure
elong->flonum i | bigloo procedure
flonum->elong r | bigloo procedure
llong->flonum i | bigloo procedure
flonum->llong r | bigloo procedure
These last procedures implement the natural translation from fixnum to flonum and vice versa.

See r5rs, Numerical operations, for more details.

### 5.1.7 Characters

Bigloo knows one more named character `#\tab` in addition to the `#\space` and `#\newline` of R5RS.
A new alternate syntax exists for characters: `#a<ascii-code>` where `<ascii-code>` is the three digit decimal ascii number of the character to be read. Thus, for instance, the character `#\space` can be written `#a032`.

char? obj | procedure

char=? char1 char2 | procedure
char<? char1 char2 | procedure
char>? char1 char2 | procedure
char<=? char1 char2 | procedure
char>=? char1 char2 | procedure
char-ci=? char1 char2 | library procedure
char-ci<? char1 char2 | library procedure
char-ci>? char1 char2 | library procedure
char-ci<=? char1 char2 | library procedure
char-ci>=? char1 char2 | library procedure

char-alphabetic? char | library procedure
char-numeric? char | library procedure
char-whitespace? char | library procedure
char-upper-case? char | library procedure
char-lower-case? char | library procedure

char->integer char | procedure
integer->char i | procedure

char-upcase char | library procedure
char-downcase char | library procedure

### 5.1.8 UCS-2 Characters

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

ucs2? obj | bigloo procedure

ucs2=? ucs2a ucs2b | bigloo procedure
ucs2<? ucs2a ucs2b | bigloo procedure
ucs2>? ucs2a ucs2b | bigloo procedure
ucs2<=? ucs2a ucs2b | bigloo procedure
ucs2>=? ucs2a ucs2b | bigloo procedure
ucs2-ci=? ucs2a ucs2b | bigloo procedure
ucs2-ci<? ucs2a ucs2b | bigloo procedure
ucs2-ci>? ucs2a ucs2b | bigloo procedure
ucs2-ci<=? ucs2a ucs2b | bigloo procedure
ucs2-ci>=? ucs2a ucs2b | bigloo procedure

ucs2-alphabetic? ucs2 | bigloo procedure
ucs2-numeric? ucs2 | bigloo procedure
ucs2-whitespace? ucs2 | bigloo procedure
ucs2-upper-case? ucs2 | bigloo procedure
ucs2-lower-case? ucs2 | bigloo procedure

ucs2->integer ucs2 | bigloo procedure
integer->ucs2 i | bigloo procedure

ucs2->char ucs2 | bigloo procedure
char->ucs2 char | bigloo procedure

ucs2-upcase ucs2 | bigloo procedure
ucs2-downcase ucs2 | bigloo procedure

### 5.1.9 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 r5rs, Lexical structure. With the foreign syntax, C escape sequences are interpreted as specified by ISO-C. In addition, Bigloo's reader evaluate `\x??` sequence as an hexadecimal escape character. For Unicode syntax, see 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: `#"([^"]|\")*"`.

*bigloo-strict-r5rs-strings* | variable
Traditional syntax conforms to the Revised Report if the variable `*bigloo-strict-r5rs-strings*` is not `#f`. Otherwise constant strings specified by the `"([^"]|\")*"` are considered as foreign strings. For example, after reading the expression `"1\n23\t4\"5"`, the following string is built, which is equal to `(string #\1 #\n #\2 #\3 #\t #\4 #\" #\5)` if `*bigloo-strict-r5rs-strings*` is not `#f`. It is `(string #\1 #\n #\2 #\3 #\tab #\4 #\" #\5)` otherwise. Printing this string will produce: `1n23t4"5`. The new foreign syntax allows C escape sequences to be recognized. For example, the expression `#"1\n23\t4\"5"` builds a string equal to: `(string #\1 #\newline #\2 #\3 #\t #\4 #\" #\5)` and printing this string will then produce:
    1
    23    4"5

The library functions for string processing are:

string? obj | procedure

make-string k | procedure
make-string k char | procedure
string char ... | library procedure

string-length string | procedure
string-ref string k | procedure
string-set! string k char | procedure

string=? string1 string2 | library procedure
substring=? string1 string2 len | bigloo procedure
This function returns `#t` if `string1` and `string2` have a common prefix of size `len`.
    (substring=? "abcdef" "ab9989898" 2)
       => #t
    (substring=? "abcdef" "ab9989898" 3)
       => #f

string-ci=? string1 string2 | library procedure
string<? string1 string2 | library procedure
string>? string1 string2 | library procedure
string<=? string1 string2 | library procedure
string>=? string1 string2 | library procedure
string-ci<? string1 string2 | library procedure
string-ci>? string1 string2 | library procedure
string-ci<=? string1 string2 | library procedure
string-ci>=? string1 string2 | library procedure

string-compare3 string1 string2 | bigloo procedure
string-compare3-ci string1 string2 | bigloo procedure
This function compares `string1` and `string2`. It returns a negative integer if `string1` < `string2`. It returns zero if the `string1` equal `string2`. It returns a positive integer if `string1` > `string2`.

substring string start end | library procedure
`string` must be a string, and `start` and `end` must be exact integers satisfying:
      0 <= START <= END <= (string-length STRING)
`substring` returns a newly allocated string formed from the characters of `STRING` beginning with index `START` (inclusive) and ending with index `END` (exclusive).
    (substring "abcdef" 0 5)
       => "abcde"
    (substring "abcdef" 1 5)
       => "bcde"

string-shrink! string end | library procedure
`string` must be a string, and `end` must be an exact integers satisfying:
      0 <= END <= (string-length STRING)
`string-shrink!` returns a newly allocated string formed from the characters of `STRING` beginning with index 0 (inclusive) and ending with index `END` (exclusive). As much as possible `string-shrink!` changes the argument `string`. That is, as much as possible, and for the back-ends that enable it, `string-shrink!` operate a side effect on its argument.
    (let ((s (string #\a #\b #\c #\d #\e)))
       (set! s (string-shrink! s 3))
       s)
       => "abc"

string-append string ... | library procedure
string->list string | library procedure
list->string list | library procedure
string-copy string | library procedure

string-fill! string char | bigloo procedure
Stores `char` in every element of the given `string` and returns an unspecified value.

string-downcase string | bigloo procedure
Returns a newly allocated version of string where each upper case letter is replaced by its lower case equivalent.

string-upcase string | bigloo procedure
Returns a newly allocated version of string where each lower case letter is replaced by its upper case equivalent.

string-capitalize string | bigloo procedure
Builds a newly allocated capitalized string.

string-downcase! string | bigloo procedure
Physically downcases the `string` argument.

string-upcase! string | bigloo procedure
Physically upcases the `string` argument.

string-capitalize! string | bigloo procedure
Physically capitalized the `string` argument.

string-for-read string | bigloo procedure
Returns a copy of `string` with each special character replaced by an escape sequence.

blit-string! string1 o1 string2 o2 len | bigloo procedure
Fill string `s2` starting at position `o2` with `len` characters taken out of string `s1` from position `o1`.
    (let ((s (make-string 20 #\-)))
            (blit-string! "toto" 0 s 16 4)
            s)
       => "----------------toto"

### 5.1.10 Unicode (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: `#u"([^]|\")*"`.
The library functions for Unicode string processing are:

ucs2-string? obj | bigloo procedure

make-ucs2-string k | bigloo procedure
make-ucs2-string k char | bigloo procedure
ucs2-string k ... | bigloo procedure

ucs2-string-length s-ucs2 | bigloo procedure
ucs2-string-ref s-ucs2 k | bigloo procedure
ucs2-string-set! s-ucs2 k char | bigloo procedure

ucs2-string=? s-ucs2a s-ucs2b | bigloo procedure
ucs2-string-ci=? s-ucs2a s-ucs2b | bigloo procedure
ucs2-string<? s-ucs2a s-ucs2b | bigloo procedure
ucs2-string>? s-ucs2a s-ucs2b | bigloo procedure
ucs2-string<=? s-ucs2a s-ucs2b | bigloo procedure
ucs2-string>=? s-ucs2a s-ucs2b | bigloo procedure
ucs2-string-ci<? s-ucs2a s-ucs2b | bigloo procedure
ucs2-string-ci>? s-ucs2a s-ucs2b | bigloo procedure
ucs2-string-ci<=? s-ucs2a s-ucs2b | bigloo procedure
ucs2-string-ci>=? s-ucs2a s-ucs2b | bigloo procedure

subucs2-string s-ucs2 start end | bigloo procedure
ucs2-string-append s-ucs2 ... | bigloo procedure
ucs2-string->list s-ucs2 | bigloo procedure
list->ucs2-string chars | bigloo procedure
ucs2-string-copy s-ucs2 | bigloo procedure

ucs2-string-fill! s-ucs2 char | bigloo procedure
Stores `char` in every element of the given s-ucs2 and returns an unspecified value.

ucs2-string-downcase s-ucs2 | bigloo procedure
Builds a newly allocated ucs2-string with lower case letters.

ucs2-string-upcase s-ucs2 | bigloo procedure
Builds a new allocated ucs2-string with upper case letters.

ucs2-string-downcase! s-ucs2 | bigloo procedure
Physically downcases the `s-ucs2` argument.

ucs2-string-upcase! s-ucs2 | bigloo procedure
Physically upcases the `s-ucs2` argument.

ucs2-string->utf8-string s-ucs2 | bigloo procedure
utf8-string->ucs2-string `string` | bigloo procedure
Convert UCS-2 strings to (or from) UTF-8 encoded ascii strings.

### 5.1.11 Vectors

Vectors are not autoquoted objects.

vector? obj | procedure

make-vector k | procedure
make-vector k obj | procedure
vector obj ... | library procedure

vector-length vector | procedure
vector-ref vector k | procedure
vector-set! vector k obj | procedure

vector->list vector | library procedure
list->vector list | library procedure

vector-fill! vector obj | library procedure
Stores `obj` in every element of `vector`. For instance:
    (let ((v (make-vector 5 #f)))
       (vector-fill! v #t)
       v)

copy-vector vector len | bigloo procedure
Allocate a new vector of size `len` and fills it with the first `len` element of `vector`. The new length `len` might be bigger than the old vector length.

vector-copy vector start end | bigloo procedure
`vector` must be a vector, and `start` and `end` must be exact integers satisfying:
      0 <= START <= END <= (vector-length VECTOR)
`vector-copy` returns a newly allocated vector formed from the elements of `VECTOR` beginning with index `START` (inclusive) and ending with index `END` (exclusive).
    (vector-copy '#(1 2 3 4) 0 4)
       => '#(1 2 3 4)
    (vector-copy '#(1 2 3 4) 1 3)
       => '#(2 3)

See r5rs, Vectors, for more details.

### 5.1.12 Control features

procedure? obj | procedure

apply proc arg1 ... args | procedure

map proc list1 list2 ... | library procedure
for-each proc list1 list2 ... | library procedure

filter pred list ... | library procedure
filter! pred list ... | library procedure
Strip out all elements of `list` for which the predicate `pred` is not true. The second version `filter!` is destructive:
    (filter number? '(1 2 #\a "foo" foo 3)) => (1 2 3)
    (let ((l (list 1 2 #\a "foo" 'foo 3)))
       (set! l (filter! number? l))
       l)                                   => (1 2 3)

sort obj proc | bigloo procedure
Sorts `obj` according to `proc` test. The argument `obj` can either be a vector or a list. In either case, a copy of the argument is returned. For instance:
    (let ((l '(("foo" 5) ("bar" 6) ("hux" 1) ("gee" 4))))
       (sort l (lambda (x y) (string<? (car x) (car y)))))
       => ((bar 6) (foo 5) (gee 4) (hux 1))

force promise | library procedure

call/cc proc | bigloo procedure
This function is the same as the `call-with-current-continuation` function of the R5RS, see r5rs, call-with-current-continuation, but it is necessary to compile the module with the `-call/cc` option to use it, see Section See The Bigloo command line. Note: Since `call/cc` is difficult to compile efficiently, one might consider using `bind-exit` instead. For this reason, we decided to enable `call/cc` only with a compiler option.

bind-exit escape body | bigloo syntax
This form provides an escape operator facility. `bind-exit` evaluates the `body`, which may refer to the variable `escape` which will denote an ``escape function'' of one argument: when called, this escape function will return from the `bind-exit` form with the given argument as the value of the `bind-exit` form. The `escape` can only be used while in the dynamic extent of the form. Bindings introduced by `bind-exit` are immutable.
    (bind-exit (exit)
     (for-each (lambda (x)
                 (if (negative? x)
                     (exit x)))
               '(54 0 37 -3 245 19))
     #t)                                  => -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))               => 4
    (list-length '(a b . c))               => #f

unwind-protect expr protect | bigloo syntax
This form provides protections. Expression `expr` is evaluated. If this evaluation requires the invocation of an escape procedure (a procedure bounded by the `bind-exit` special form), `protect` is evaluated before the control jump to the exit procedure. If `expr` does not raise any exit procedure, `unwind-protect` has the same behaviour as the `begin` special form except that the value of the form is always the value of `expr`.
    (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))))))

dynamic-wind before thunk after | procedure
Calls `thunk` without arguments, returning the result(s) of this call. `Before` and `after` are called, also without arguments, as required by the following rules (note that in the absence of calls to continuations captured using `call/cc` the three arguments are called once each, in order). `Before` is called whenever execution enters the dynamic extent of the call to `thunk` and `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 `call/cc`, the dynamic extent of a call may not be a single, connected time period. It is defined as follows: The dynamic extent is entered when execution of the body of the called procedure begins. The dynamic extent is also entered when execution is not within the dynamic extent and a continuation is invoked that was captured (using `call/cc`) during the dynamic extent. It is exited when the called procedure returns. 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. If a second call to `dynamic-wind` occurs within the dynamic extent of the call to `thunk` and then a continuation is invoked in such a way that the `after`s from these two invocations of `dynamic-wind` are both to be called, then the `after` associated with the second (inner) call to `dynamic-wind` is called first. If a second call to `dynamic-wind` occurs within the dynamic extent of the call to `thunk` and then a continuation is invoked in such a way that the `before`s from these two invocations of `dynamic-wind` are both to be called, then the `before` associated with the first (outer) call to `dynamic-wind` is called first. If invoking a continuation requires calling the `before` from one call to `dynamic-wind` and the `after` from another, then the `after` is called first. The effect of using a captured continuation to enter or exit the dynamic extent of a call to `before` or `after` is undefined.
    (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))))

       => (connect talk1 disconnect connect talk2 disconnect)

unspecified | bigloo procedure
Returns the unspecified (noted as `#unspecified`) object with no specific property.

try exp handler | bigloo syntax
This form is documented in Section Errors and Assertions.

values obj ... | procedure
Delivers all of its arguments to its continuation. Except for continuations created by the `call-with-values` procedure, all continuations take exactly one value. `Values` might be defined as follows:
    (define (values . things)
      (call/cc
        (lambda (cont) (apply cont things))))

call-with-values producer consumer | procedure
Calls its `producer` argument with no values and a continuation that, when passed some values, calls the `consumer` procedure with those values as arguments. The continuation for the call to `consumer` is the continuation of the call to `call-with-values`.
    (call-with-values (lambda () (values 4 5))
                      (lambda (a b) b))
        => 5
    (call-with-values * -)
        => -1

multiple-value-bind (var ...) producer exp ... | bigloo syntax
receive (var ...) producer exp ... | bigloo syntax
Evaluates `exp` ... in a environment where `var` ... are bound from the evaluation of `producer`. The result of `producer` must be a call to `values` where the number of argument is the number of bound variables.
    (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)
       -| 4 70

This Scribe page has been generated by `scribeinfo`.
Last update Tue Dec 16 13:46:41 2003