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