This chapter describes operations specific to Chez Scheme on nonnumeric objects, including standard objects such as pairs and numbers and Chez Scheme extensions such as boxes and records. Chapter 8 describes operations on numbers. See Chapter 6 of The Scheme Programming Language, 4th Edition or the Revised6 Report on Scheme for a description of standard operations on objects.
procedure: (enum-set? obj)
returns: #t if obj is an enum set, #f otherwise
libraries: (chezscheme)
This predicate is not defined by the Revised6 Report, but should be.
procedure: (record-constructor-descriptor? obj)
returns: #t if obj is a record constructor descriptor, #f otherwise
libraries: (chezscheme)
This predicate is not defined by the Revised6 Report, but should be.
procedure: (atom? obj)
returns: #t if obj is not a pair, #f otherwise
libraries: (chezscheme)
atom? is equivalent to (lambda (x) (not (pair? x))).
(atom? '(a b c)) #f
(atom? '(3 . 4)) #f
(atom? '()) #t
(atom? 3) #t
procedure: (list-head list n)
returns: a list of the first n elements of list
libraries: (chezscheme)
n must be an exact nonnegative integer less than or equal to the length of list.
list-head and the standard Scheme procedure list-tail may be used together to split a list into two separate lists. While list-tail performs no allocation but instead returns a sublist of the original list, list-head always returns a copy of the first portion of the list.
list-head may be defined as follows.
(define list-head
(lambda (ls n)
(if (= n 0)
'()
(cons (car ls) (list-head (cdr ls) (- n 1))))))
(list-head '(a b c) 0) ()
(list-head '(a b c) 2) (a b)
(list-head '(a b c) 3) (a b c)
(list-head '(a b c . d) 2) (a b)
(list-head '(a b c . d) 3) (a b c)
(list-head '#1=(a . #1#) 5) (a a a a a)
procedure: (last-pair list)
returns: the last pair of a list
libraries: (chezscheme)
list must not be empty. last-pair returns the last pair (not the last element) of list. list may be an improper list, in which case the last pair is the pair containing the last element and the terminating object.
(last-pair '(a b c d)) (d)
(last-pair '(a b c . d)) (c . d)
procedure: (list-copy list)
returns: a copy of list
libraries: (chezscheme)
list-copy returns a list equal? to list, using new pairs to reform the top-level list structure.
(list-copy '(a b c)) (a b c)
(let ([ls '(a b c)])
(equal? ls (list-copy ls))) #t
(let ([ls '(a b c)])
(let ([ls-copy (list-copy ls)])
(or (eq? ls-copy ls)
(eq? (cdr ls-copy) (cdr ls))
(eq? (cddr ls-copy) (cddr ls))))) #f
procedure: (list* obj ... final-obj)
returns: a list of obj ... terminated by final-obj
libraries: (chezscheme)
list* is identical to the Revised6 Report cons*.
procedure: (make-list n)
procedure: (make-list n obj)
returns: a list of n objs
libraries: (chezscheme)
n must be a nonnegative integer. If obj is omitted, the elements of the list are unspecified.
(make-list 0 '()) ()
(make-list 3 0) (0 0 0)
(make-list 2 "hi") ("hi" "hi")
procedure: (iota n)
returns: a list of integers from 0 (inclusive) to n (exclusive)
libraries: (chezscheme)
n must be an exact nonnegative integer.
(iota 0) ()
(iota 5) (0 1 2 3 4)
procedure: (enumerate ls)
returns: a list of integers from 0 (inclusive) to the length of ls (exclusive)
libraries: (chezscheme)
(enumerate '()) ()
(enumerate '(a b c)) (0 1 2)
(let ([ls '(a b c)])
(map cons ls (enumerate ls))) ((a . 0) (b . 1) (c . 2))
procedure: (remq! obj list)
procedure: (remv! obj list)
procedure: (remove! obj list)
returns: a list containing the elements of list with all occurrences of obj removed
libraries: (chezscheme)
These procedures are similar to the Revised6 Report remq, remv, and remove procedures, except remq!, remv! and remove! use pairs from the input list to build the output list. They perform less allocation but are not necessarily faster than their nondestructive counterparts. Their use can easily lead to confusing or incorrect results if used indiscriminately.
(remq! 'a '(a b a c a d)) (b c d)
(remv! #\a '(#\a #\b #\c)) (#\b #\c)
(remove! '(c) '((a) (b) (c))) ((a) (b))
procedure: (substq new old tree)
procedure: (substv new old tree)
procedure: (subst new old tree)
procedure: (substq! new old tree)
procedure: (substv! new old tree)
procedure: (subst! new old tree)
returns: a tree with new substituted for occurrences of old in tree
libraries: (chezscheme)
These procedures traverse tree, replacing all objects equivalent to the object old with the object new.
The equivalence test for substq and substq! is eq?, for substv and substv! is eqv?, and for subst and subst! is equal?.
substq!, substv!, and subst! perform the substitutions destructively. They perform less allocation but are not necessarily faster than their nondestructive counterparts. Their use can easily lead to confusing or incorrect results if used indiscriminately.
(substq 'a 'b '((b c) b a)) ((a c) a a)
(substv 2 1 '((1 . 2) (1 . 4) . 1)) ((2 . 2) (2 . 4) . 2)
(subst 'a
'(a . b)
'((a . b) (c a . b) . c)) (a (c . a) . c)
(let ([tr '((b c) b a)])
(substq! 'a 'b tr)
tr) ((a c) a a)
procedure: (reverse! list)
returns: a list containing the elements of list in reverse order
libraries: (chezscheme)
reverse! destructively reverses list by reversing its links. Using reverse! in place of reverse reduces allocation but is not necessarily faster than reverse. Its use can easily lead to confusing or incorrect results if used indiscriminately.
(reverse! '()) ()
(reverse! '(a b c)) (c b a)
(let ([x '(a b c)])
(reverse! x)
x) (a)
(let ([x '(a b c)])
(set! x (reverse! x))
x) (c b a)
procedure: (append! list ...)
returns: the concatenation of the input lists
libraries: (chezscheme)
Like append, append! returns a new list consisting of the elements of the first list followed by the elements of the second list, the elements of the third list, and so on. Unlike append, append! reuses the pairs in all of the arguments in forming the new list. That is, the last cdr of each list argument but the last is changed to point to the next list argument. If any argument but the last is the empty list, it is essentially ignored. The final argument (which need not be a list) is not altered.
append! performs less allocation than append but is not necessarily faster. Its use can easily lead to confusing or incorrect results if used indiscriminately.
(append! '(a b) '(c d)) (a b c d)
(let ([x '(a b)])
(append! x '(c d))
x) (a b c d)
Chez Scheme extends the syntax of characters in two ways. First, a #\ prefix followed by exactly three octal digits is read as a character whose numeric code is the octal value of the three digits, e.g., #\044 is read as #\$. Second, it recognizes several nonstandard named characters: #\rubout (which is the same as #\delete), #\bel (which is the same as #\alarm), #\vt (which is the same as #\vtab), #\nel (the Unicode NEL character), and #\ls (the Unicode LS character). The set of nonstandard character names may be changed via the procedure char-name (page 9.14).
These extensions are disabled in an input stream after #!r6rs has been seen by the reader, unless #!chezscheme has been seen more recently.
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 ...)
procedure: (char-ci<? char1 char2 ...)
procedure: (char-ci>? char1 char2 ...)
procedure: (char-ci<=? char1 char2 ...)
procedure: (char-ci>=? char1 char2 ...)
returns: #t if the relation holds, #f otherwise
libraries: (chezscheme)
These predicates are identical to the Revised6 Report counterparts, except they are extended to accept one or more rather than two or more arguments. When passed one argument, each of these predicates returns #t.
(char>? #\a) #t
(char<? #\a) #t
(char-ci=? #\a) #t
procedure: (char- char1 char2)
returns: the integer difference between char1 and char2
libraries: (chezscheme)
char- subtracts the integer value of char2 from the integer value of char1 and returns the difference. The following examples assume that the integer representation is the ASCII code for the character.
(char- #\f #\e) 1
(define digit-value
; returns the digit value of the base-r digit c, or #f if c
; is not a valid digit
(lambda (c r)
(let ([v (cond
[(char<=? #\0 c #\9) (char- c #\0)]
[(char<=? #\A c #\Z) (char- c #\7)]
[(char<=? #\a c #\z) (char- c #\W)]
[else 36])])
(and (fx< v r) v))))
(digit-value #\8 10) 8
(digit-value #\z 10) #f
(digit-value #\z 36) 35
char- might be defined as follows.
(define char-
(lambda (c1 c2)
(- (char->integer c1) (char->integer c2))))
Chez Scheme extends the standard string syntax with two character escapes: \', which produces the single quote character, and \nnn, i.e., backslash followed by 3 octal digits, which produces the character equivalent of the octal value of the 3 digits. These extensions are disabled in an input stream after #!r6rs has been seen by the reader, unless #!chezscheme has been seen more recently.
The length and indices of a string in Chez Scheme are always fixnums.
procedure: (string=? string1 string2 string3 ...)
procedure: (string<? string1 string2 string3 ...)
procedure: (string>? string1 string2 string3 ...)
procedure: (string<=? string1 string2 string3 ...)
procedure: (string>=? string1 string2 string3 ...)
procedure: (string-ci=? string1 string2 string3 ...)
procedure: (string-ci<? string1 string2 string3 ...)
procedure: (string-ci>? string1 string2 string3 ...)
procedure: (string-ci<=? string1 string2 string3 ...)
procedure: (string-ci>=? string1 string2 string3 ...)
returns: #t if the relation holds, #f otherwise
libraries: (chezscheme)
These predicates are identical to the Revised6 Report counterparts, except they are extended to accept one or more rather than two or more arguments. When passed one argument, each of these predicates returns #t.
(string>? "a") #t
(string<? "a") #t
(string-ci=? "a") #t
procedure: (string-copy! src src-start dst dst-start n)
returns: unspecified
libraries: (chezscheme)
src and dst must be strings. src-start, dst-start, and n must be exact nonnegative integers. The sum of src-start and n must not exceed the length of src, and the sum of dst-start and n must not exceed the length of dst.
string-copy! overwrites the n bytes of dst starting at dst-start with the n bytes of dst starting at src-start. This works even if dst is the same string as src and the source and destination locations overlap. That is, the destination is filled with the characters that appeared at the source before the operation began.
(define s1 "to boldly go")
(define s2 (make-string 10 #\-))
(string-copy! s1 3 s2 1 3)
s2 "-bol------"
(string-copy! s1 7 s2 4 2)
s2 "-bolly----"
(string-copy! s2 2 s2 5 4)
s2 "-bollolly-"
procedure: (substring-fill! string start end char)
returns: unspecified
libraries: (chezscheme)
The characters of string from start (inclusive) to end (exclusive) are set to char. start and end must be nonnegative integers; start must be strictly less than the length of string, while end may be less than or equal to the length of string. If end ≤ start, the string is left unchanged.
(let ([str (string-copy "a tpyo typo")])
(substring-fill! str 2 6 #\X)
str) "a XXXX typo"
procedure: (string-truncate! string n)
returns: string or the empty string
libraries: (chezscheme)
n must be an exact nonnegative fixnum not greater than the length of string. If n is zero, string-truncate! returns the empty string. Otherwise, string-truncate! destructively truncates string to its first n characters and returns string.
(define s (make-string 7 #\$))
(string-truncate! s 0) ""
s "$$$$$$$"
(string-truncate! s 3) "$$$"
s "$$$"
Chez Scheme extends the syntax of vectors to allow the length of the vector to be specified between the # and open parenthesis, e.g., #3(a b c). If fewer elements are supplied in the syntax than the specified length, each element after the last printed element is the same as the last printed element. This extension is disabled in an input stream after #!r6rs has been seen by the reader, unless #!chezscheme has been seen more recently.
The length and indices of a vector in Chez Scheme are always fixnums.
procedure: (vector-copy vector)
returns: a copy of vector
libraries: (chezscheme)
vector-copy creates a new vector of the same length and contents as vector. The elements themselves are not copied.
(vector-copy '#(a b c)) #(a b c)
(let ([v '#(a b c)])
(eq? v (vector-copy v))) #f
procedure: (vector-set-fixnum! vector n fixnum)
returns: unspecified
libraries: (chezscheme)
vector-set-fixnum! changes the nth element of vector to fixnum. n must be an exact nonnegative integer strictly less than the length of vector.
It is faster to store a fixnum than an arbitrary value, since for arbitrary values, the system has to record potential assignments from older to younger objects to support generational garbage collection. Care must be taken to ensure that the argument is indeed a fixnum, however; otherwise, the collector may not properly track the assignment. The primitive performs a fixnum check on the argument except at optimization level 3.
See also the description of fixnum-only vectors (fxvectors) below.
(let ([v (vector 1 2 3 4 5)])
(vector-set-fixnum! v 2 73)
v) #(1 2 73 4 5)
Fixnum-only vectors, or "fxvectors," are like vectors but contain only fixnums. Fxvectors are written with the #vfx prefix in place of the # prefix for vectors, e.g., #vfx(1 2 3) or #10vfx(2). The fxvector syntax is disabled in an input stream after #!r6rs has been seen by the reader, unless #!chezscheme has been seen more recently.
The length and indices of an fxvector are always fixnums.
Updating an fxvector is generally less expensive than updating a vector, since for vectors, the system records potential assignments from older to younger objects to support generational garbage collection. The storage management system also takes advantage of the fact that fxvectors contain no pointers to place them in an area of memory that does not have to be traced during collection.
See also vector-set-fixnum! above.
procedure: (fxvector? obj)
returns: #t if obj is an fxvector, #f otherwise
libraries: (chezscheme)
(fxvector? #vfx()) #t
(fxvector? #vfx(1 2 3)) #t
(fxvector? (fxvector 1 2 3)) #t
(fxvector? '#(a b c)) #f
(fxvector? '(a b c)) #f
(fxvector? "abc") #f
procedure: (fxvector fixnum ...)
returns: an fxvector of the fixnums fixnum ...
libraries: (chezscheme)
(fxvector) #vfx()
(fxvector 1 3 5) #vfx(1 3 5)
procedure: (make-fxvector n)
procedure: (make-fxvector n fixnum)
returns: an fxvector of length n
libraries: (chezscheme)
n must be a fixnum. If fixnum is supplied, each element of the fxvector is initialized to fixnum; otherwise, the elements are unspecified.
(make-fxvector 0) #vfx()
(make-fxvector 0 7) #vfx()
(make-fxvector 5 7) #vfx(7 7 7 7 7)
procedure: (fxvector-length fxvector)
returns: the number of elements in fxvector
libraries: (chezscheme)
(fxvector-length #vfx()) 0
(fxvector-length #vfx(1 2 3)) 3
(fxvector-length #10vfx(1 2 3)) 10
(fxvector-length (fxvector 1 2 3 4)) 4
(fxvector-length (make-fxvector 300)) 300
procedure: (fxvector-ref fxvector n)
returns: the nth element (zero-based) of fxvector
libraries: (chezscheme)
n must be a nonnegative fixnum strictly less than the length of fxvector.
(fxvector-ref #vfx(-1 2 4 7) 0) -1
(fxvector-ref #vfx(-1 2 4 7) 1) 2
(fxvector-ref #vfx(-1 2 4 7) 3) 7
procedure: (fxvector-set! fxvector n fixnum)
returns: unspecified
libraries: (chezscheme)
n must be a nonnegative fixnum strictly less than the length of fxvector. fxvector-set! changes the nth element of fxvector to fixnum.
(let ([v (fxvector 1 2 3 4 5)])
(fxvector-set! v 2 (fx- (fxvector-ref v 2)))
v) #vfx(1 2 -3 4 5)
procedure: (fxvector-fill! fxvector fixnum)
returns: unspecified
libraries: (chezscheme)
fxvector-fill! replaces each element of fxvector with fixnum.
(let ([v (fxvector 1 2 3)])
(fxvector-fill! v 0)
v) #vfx(0 0 0)
procedure: (fxvector->list fxvector)
returns: a list of the elements of fxvector
libraries: (chezscheme)
(fxvector->list (fxvector)) ()
(fxvector->list #vfx(7 5 2)) (7 5 2)
(let ([v #vfx(1 2 3 4 5)])
(apply fx* (fxvector->list v))) 120
procedure: (list->fxvector list)
returns: an fxvector of the elements of list
libraries: (chezscheme)
list must consist entirely of fixnums.
(list->fxvector '()) #vfx()
(list->fxvector '(3 5 7)) #vfx(3 5 7)
(let ([v #vfx(1 2 3 4 5)])
(let ([ls (fxvector->list v)])
(list->fxvector (map fx* ls ls)))) #vfx(1 4 9 16 25)
procedure: (fxvector-copy fxvector)
returns: a copy of fxvector
libraries: (chezscheme)
fxvector-copy creates a new fxvector with the same length and contents as fxvector.
(fxvector-copy #vfx(3 4 5)) #vfx(3 4 5)
(let ([v #vfx(3 4 5)])
(eq? v (fxvector-copy v))) #f
As with vectors, Chez Scheme extends the syntax of bytevectors to allow the length of the vector to be specified between the # and open parenthesis, e.g., #3vu8(1 105 73). If fewer elements are supplied in the syntax than the specified length, each element after the last printed element is the same as the last printed element. This extension is disabled in an input stream after #!r6rs has been seen by the reader, unless #!chezscheme has been seen more recently.
Chez Scheme also extends the set of bytevector primitives, including primitives for loading and storing 3, 5, 6, and 7-byte quantities.
The length and indices of a bytevector in Chez Scheme are always fixnums.
procedure: (bytevector fill ...)
returns: a new bytevector containing fill ...
libraries: (chezscheme)
Each fill value must be an exact integer representing a signed or unsigned 8-bit value, i.e., a value in the range -128 to 255 inclusive. A negative fill value is treated as its two's complement equivalent.
(bytevector) #vu8()
(bytevector 1 3 5) #vu8(1 3 5)
(bytevector -1 -3 -5) #vu8(255 253 251)
procedure: (bytevector->s8-list bytevector)
returns: a new list of the 8-bit signed elements of bytevector
libraries: (chezscheme)
The values in the returned list are exact eight-bit signed integers, i.e., values in the range -128 to 127 inclusive. bytevector->s8-list is similar to the Revised6 Report bytevector->u8-list except the values in the returned list are signed rather than unsigned.
(bytevector->s8-list (make-bytevector 0)) ()
(bytevector->s8-list #vu8(1 127 128 255)) (1 127 -128 -1)
(let ([v #vu8(1 2 3 255)])
(apply * (bytevector->s8-list v))) -6
procedure: (s8-list->bytevector list)
returns: a new bytevector of the elements of list
libraries: (chezscheme)
list must consist entirely of exact eight-bit signed integers, i.e., values in the range -128 to 127 inclusive. s8-list->bytevector is similar to the Revised6 Report procedure u8-list->bytevector, except the elements of the input list are signed rather than unsigned.
(s8-list->bytevector '()) #vu8()
(s8-list->bytevector '(1 127 -128 -1)) #vu8(1 127 128 255)
(let ([v #vu8(1 2 3 4 5)])
(let ([ls (bytevector->s8-list v)])
(s8-list->bytevector (map - ls)))) #vu8(255 254 253 252 251)
procedure: (bytevector-truncate! bytevector n)
returns: bytevector or the empty bytevector
libraries: (chezscheme)
n must be an exact nonnegative fixnum not greater than the length of bytevector. If n is zero, bytevector-truncate! returns the empty bytevector. Otherwise, bytevector-truncate! destructively truncates bytevector to its first n bytes and returns bytevector.
(define bv (make-bytevector 7 19))
(bytevector-truncate! bv 0) #vu8()
bv #vu8(19 19 19 19 19 19 19)
(bytevector-truncate! bv 3) #vu8(19 19 19)
bv #vu8(19 19 19)
procedure: (bytevector-u24-ref bytevector n eness)
returns: the 24-bit unsigned integer at index n (zero-based) of bytevector
procedure: (bytevector-s24-ref bytevector n eness)
returns: the 24-bit signed integer at index n (zero-based) of bytevector
procedure: (bytevector-u40-ref bytevector n eness)
returns: the 40-bit unsigned integer at index n (zero-based) of bytevector
procedure: (bytevector-s40-ref bytevector n eness)
returns: the 40-bit signed integer at index n (zero-based) of bytevector
procedure: (bytevector-u48-ref bytevector n eness)
returns: the 48-bit unsigned integer at index n (zero-based) of bytevector
procedure: (bytevector-s48-ref bytevector n eness)
returns: the 48-bit signed integer at index n (zero-based) of bytevector
procedure: (bytevector-u56-ref bytevector n eness)
returns: the 56-bit unsigned integer at index n (zero-based) of bytevector
procedure: (bytevector-s56-ref bytevector n eness)
returns: the 56-bit signed integer at index n (zero-based) of bytevector
libraries: (chezscheme)
n must be an exact nonnegative integer and indexes the starting byte of the value. The sum of n and the number of bytes occupied by the value (3 for 24-bit values, 5 for 40-bit values, 6 for 48-bit values, and 7 for 56-bit values) must not exceed the length of bytevector. eness must be a valid endianness symbol naming the endianness.
The return value is an exact integer in the appropriate range for the number of bytes occupied by the value. Signed values are the equivalent of the stored value treated as a two's complement value.
procedure: (bytevector-u24-set! bytevector n u24 eness)
procedure: (bytevector-s24-set! bytevector n s24 eness)
procedure: (bytevector-u40-set! bytevector n u40 eness)
procedure: (bytevector-s40-set! bytevector n s40 eness)
procedure: (bytevector-u48-set! bytevector n u48 eness)
procedure: (bytevector-s48-set! bytevector n s48 eness)
procedure: (bytevector-u56-set! bytevector n u56 eness)
procedure: (bytevector-s56-set! bytevector n s56 eness)
returns: unspecified
libraries: (chezscheme)
n must be an exact nonnegative integer and indexes the starting byte of the value. The sum of n and the number of bytes occupied by the value must not exceed the length of bytevector. u24 must be a 24-bit unsigned value, i.e., a value in the range 0 to 224 - 1 inclusive; s24 must be a 24-bit signed value, i.e., a value in the range -223 to 223 - 1 inclusive; u40 must be a 40-bit unsigned value, i.e., a value in the range 0 to 240 - 1 inclusive; s40 must be a 40-bit signed value, i.e., a value in the range -239 to 239 - 1 inclusive; u48 must be a 48-bit unsigned value, i.e., a value in the range 0 to 248 - 1 inclusive; s48 must be a 48-bit signed value, i.e., a value in the range -247 to 247 - 1 inclusive; u56 must be a 56-bit unsigned value, i.e., a value in the range 0 to 256 - 1 inclusive; and s56 must be a 56-bit signed value, i.e., a value in the range -255 to 255 - 1 inclusive. eness must be a valid endianness symbol naming the endianness.
These procedures store the given value in the 3, 5, 6, or 7 bytes starting at index n (zero-based) of bytevector. Negative values are stored as their two's complement equivalent.
Boxes are single-cell objects that are primarily useful for providing an "extra level of indirection." This extra level of indirection is typically used to allow more than one body of code or data structure to share a reference, or pointer, to an object. For example, boxes may be used to implement call-by-reference semantics in an interpreter for a language employing this parameter passing discipline.
Boxes are written with the prefix #& (pronounced "hash-ampersand"). For example, #&(a b c) is a box holding the list (a b c). The box syntax is disabled in an input stream after #!r6rs has been seen by the reader, unless #!chezscheme has been seen more recently.
procedure: (box? obj)
returns: #t if obj is a box, #f otherwise
libraries: (chezscheme)
(box? '#&a) #t
(box? 'a) #f
(box? (box 3)) #t
procedure: (box obj)
returns: a new box containing obj
libraries: (chezscheme)
(box 'a) #&a
(box (box '(a b c))) #&#&(a b c)
procedure: (unbox box)
returns: contents of box
libraries: (chezscheme)
(unbox #&a) a
(unbox #&#&(a b c)) #&(a b c)
(let ([b (box "hi")])
(unbox b)) "hi"
procedure: (set-box! box obj)
returns: unspecified
libraries: (chezscheme)
set-box! sets the contents of box to obj.
(let ([b (box 'x)])
(set-box! b 'y)
b) #&y
(let ([incr!
(lambda (x)
(set-box! x (+ (unbox x) 1)))])
(let ([b (box 3)])
(incr! b)
(unbox b))) 4
Chez Scheme extends the standard symbol syntax in several ways:
The printer always prints symbols using the standard R6RS syntax, so that, e.g., @abc prints as \x40;abc and 1- prints as \x31;-. '
Gensyms are printed #{ and } brackets that enclose both the "pretty" and "unique" names, e.g., #{g1426 e5g1c94g642dssw-a}. They may also be printed using the pretty name only with the prefix #:, e.g., #:g1426.
These extensions are disabled in an input stream after #!r6rs has been seen by the reader, unless #!chezscheme has been seen more recently.
procedure: (gensym)
procedure: (gensym pretty-name)
procedure: (gensym pretty-name unique-name)
returns: a unique generated symbol
libraries: (chezscheme)
Each call to gensym returns a unique generated symbol, or gensym. Each generated symbol has two names: a "pretty" name and a "unique" name.
In the first form above, the pretty name is formed (lazily---see below) by combining an internal prefix with the value of an internal counter. After each name is formed, the internal counter is incremented. The parameters gensym-prefix and gensym-count, described below, may be used to access and set the internal prefix and counter. By default, the prefix is the single-character string "g". In the second and third forms, the pretty name of the new gensym is pretty-name, which must be a string. The pretty name of a gensym is returned by the procedure symbol->string.
In both the first and second forms, the unique name is an automatically generated globally unique name. Globally unique names are constructed (lazily---see below) from some combination of a unique machine identifier (such as the network address), the current process identifier (PID), and the time at which the Scheme session began, along with an internal counter. In the third form of gensym, the unique name of the new gensym is unique-name, which must be a string. The unique name of a gensym may be obtained via the procedure gensym->unique-string.
The unique name allows gensyms to be written in such a way that they can be read back and reliably commonized on input. The syntax for gensyms includes both the pretty name and the unique name, as shown in the example below:
(gensym) #{g0 bcsfg5eq4e9b3h9o-a}
When the parameter print-gensym is set to pretty, the printer prints the pretty name only, with a #: syntax, so
(parameterize ([print-gensym 'pretty])
(write (gensym)))
prints #:g0.
When the reader sees the #: syntax, it produces a gensym with the given pretty name, but the original unique name is lost.
When the parameter is set to #f, the printer prints just the pretty name, so
(parameterize ([print-gensym #f])
(write (gensym)))
prints g0. This is useful only when gensyms do not need to be read back in as gensyms.
In order to reduce construction and (when threaded) synchronization overhead when gensyms are frequently created but rarely printed or stored in an object file, generated pretty and unique names are created lazily, i.e., not until first requested, either by the printer, fasl writer, or explicitly by one of the procedures symbol->string or gensym->unique-string. In addition, a gensym is not placed into the system's internal symbol table (the oblist; see page 150) until the unique name is requested. This allows a gensym to be reclaimed by the storage manager if no references to the gensym exist and no unique name exists by which to access it, even if it has a top-level binding or a nonempty property list.
(define x (gensym))
x #{g2 bcsfg5eq4e9b3h9o-c}
(symbol->string x) "g2"
(gensym->unique-string x) "bcsfg5eq4e9b3h9o-c"
Gensyms subsume the notion of uninterned symbols supported by earlier versions of Chez Scheme. Similarly, the predicate uninterned-symbol? has been replaced by gensym?.
thread parameter: gensym-prefix
thread parameter: gensym-count
libraries: (chezscheme)
The parameters gensym-prefix and gensym-count are used to access and set the internal prefix and counter from which the pretty name of a gensym is generated when gensym is not given an explicit string argument. gensym-prefix defaults to the string "g" and may be set to any object. gensym-count starts at 0 and may be set to any nonnegative integer.
As described above, Chez Scheme delays the creation of the pretty name until the name is first requested by the printer or by an explicit call to symbol->string. These parameters are not consulted until that time; setting them when gensym is called thus has no effect on the generated name.
(let ([x (parameterize ([gensym-prefix "genny"]
[gensym-count 17]
[print-gensym 'pretty])
(gensym))])
(format "~s" x)) "#{g4 bcsfg5eq4e9b3h9o-e}"
(let ([x (gensym)])
(parameterize ([gensym-prefix "genny"]
[gensym-count 17]
[print-gensym #f])
(format "~s" (gensym)))) "genny17"
procedure: (gensym->unique-string gensym)
returns: the unique name of gensym
libraries: (chezscheme)
(gensym->unique-string (gensym)) "bd3kufa7ypjcuvut-g"
procedure: (gensym? obj)
returns: #t if obj is gensym, #f otherwise
libraries: (chezscheme)
(gensym? (string->symbol "z")) #f
(gensym? (gensym "z")) #t
(gensym? 'a) #f
(gensym? 3) #f
(gensym? (gensym)) #t
(gensym? '#{g2 bcsfg5eq4e9b3h9o-c}) #t
procedure: (putprop symbol key value)
returns: unspecified
libraries: (chezscheme)
Chez Scheme associates a property list with each symbol, allowing multiple key-value pairs to be stored directly with the symbol. New key-value pairs may be placed in the property list or retrieved in a manner analogous to the use of association lists, using the procedures putprop and getprop. Property lists are often used to store information related to the symbol itself. For example, a natural language program might use symbols to represent words, using their property lists to store information about use and meaning.
putprop associates value with key on the property list of symbol. key and value may be any types of object, although key is typically a symbol.
putprop may be used to establish a new property or to change an existing property.
See the examples under getprop below.
procedure: (getprop symbol key)
procedure: (getprop symbol key default)
returns: the value associated with key on the property list of symbol
libraries: (chezscheme)
getprop searches the property list of symbol for a key identical to key (in the sense of eq?), and returns the value associated with this key, if any. If no value is associated with key on the property list of symbol, getprop returns default, or #f if the default argument is not supplied.
(putprop 'fred 'species 'snurd)
(putprop 'fred 'age 4)
(putprop 'fred 'colors '(black white))
(getprop 'fred 'species) snurd
(getprop 'fred 'colors) (black white)
(getprop 'fred 'nonkey) #f
(getprop 'fred 'nonkey 'unknown) unknown
(putprop 'fred 'species #f)
(getprop 'fred 'species 'unknown) #f
procedure: (remprop symbol key)
returns: unspecified
libraries: (chezscheme)
remprop removes the property with key key from the property list of symbol, if such a property exists.
(putprop 'fred 'species 'snurd)
(getprop 'fred 'species) snurd
(remprop 'fred 'species)
(getprop 'fred 'species 'unknown) unknown
procedure: (property-list symbol)
returns: a copy of the internal property list for symbol
libraries: (chezscheme)
A property list is a list of alternating keys and values, i.e., (key value ...).
(putprop 'fred 'species 'snurd)
(putprop 'fred 'colors '(black white))
(property-list 'fred) (colors (black white) species snurd)
procedure: (oblist)
returns: a list of interned symbols
libraries: (chezscheme)
The system maintains an internal symbol table used to insure that any two occurrences of the same symbol name resolve to the same symbol object. The oblist procedure returns a list of the symbols currently in this symbol table.
The list of interned symbols grows when a new symbol is introduced into the system or when the unique name of a gensym (see page 147) is requested. It shrinks when the garbage collector determines that it is safe to discard a symbol. It is safe to discard a symbol only if the symbol is not accessible except through the oblist, has no top-level binding, and has no properties on its property list.
(if (memq 'tiger (oblist)) 'yes 'no) yes
(equal? (oblist) (oblist)) #t
(= (length (oblist)) (length (oblist))) #t or #f
The first example above follows from the property that all interned symbols are in the oblist from the time they are read, which happens prior to evaluation. The second example follows from the fact that no symbols can be removed from the oblist while references to those symbols exist, in this case, within the list returned by the first call to oblist (whichever call is performed first). The expression in the third example can return #f only if a garbage collection occurs sometime between the two calls to oblist, and only if one or more symbols are removed from the oblist by that collection.
Many Scheme operations return an unspecified result. Chez Scheme typically returns a special void object when the value returned by an operation is unspecified. The Chez Scheme void object is not meant to be used as a datum, and consequently does not have a reader syntax. As for other objects without a reader syntax, such as procedures and ports, Chez Scheme output procedures print the void object using a nonreadable representation, i.e., #<void>. Since the void object should be returned only by operations that do not have "interesting" values, the default waiter printer (see waiter-write) suppresses the printing of the void object. set!, set-car!, load, and write are examples of Chez Scheme operations that return the void object.
procedure: (void)
returns: the void object
libraries: (chezscheme)
void is a procedure of no arguments that returns the void object. It can be used to force expressions that are used for effect or whose values are otherwise unspecified to evaluate to a consistent, trivial value. Since most Chez Scheme operations that are used for effect return the void object, however, it is rarely necessary to explicitly invoke the void procedure.
Since the void object is used explicitly as an "unspecified" value, it is a bad idea to use it for any other purpose or to count on any given expression evaluating to the void object.
The default waiter printer suppresses the void object; that is, nothing is printed for expressions that evaluate to the void object.
(eq? (void) #f) #f
(eq? (void) #t) #f
(eq? (void) '()) #f
procedure: (sort predicate list)
procedure: (sort! predicate list)
returns: a list containing the elements of list sorted according to predicate
libraries: (chezscheme)
sort is identical to the Revised6 Report list-sort, and sort! is a destructive version of sort, i.e., it reuses pairs from the input list to form the output list.
(sort < '(3 4 2 1 2 5)) (1 2 2 3 4 5)
(sort! < '(3 4 2 1 2 5)) (1 2 2 3 4 5)
procedure: (merge predicate list1 list2)
procedure: (merge! predicate list1 list2)
returns: list1 merged with list2 in the order specified by predicate
libraries: (chezscheme)
predicate should be a procedure that expects two arguments and returns #t if its first argument must precede its second in the merged list. It should not have any side effects. That is, if predicate is applied to two objects x and y, where x is taken from the second list and y is taken from the first list, it should return true only if x should appear before y in the output list. If this constraint is met, merge and merge! are stable, in that items from list1 are placed in front of equivalent items from list2 in the output list. Duplicate elements are included in the merged list.
merge! combines the lists destructively, using pairs from the input lists to form the output list.
(merge char<?
'(#\a #\c)
'(#\b #\c #\d)) (#\a #\b #\c #\c #\d)
(merge <
'(1/2 2/3 3/4)
'(0.5 0.6 0.7)) (1/2 0.5 0.6 2/3 0.7 3/4)
Chez Scheme provides several extensions to the hashtable mechanism, including a mechanism for directly accessing a key, value pair in a hashtable, support for weak eq and eqv hashtables, and a set of procedures specialized to eq and symbol hashtables.
procedure: (hashtable-cell hashtable key default)
returns: a pair (see below)
libraries: (chezscheme)
hashtable must be a hashtable. key and default may be any Scheme values.
If no value is associated with key in hashtable, hashtable-cell modifies hashtable to associate key with default. It returns a pair whose car is key and whose cdr is the associated value. Changing the cdr of this pair effectively updates the table to associate key with a new value. The key in the car field should not be changed. The advantage of this procedure over the Revised6 Report procedures for manipulating hashtable entries is that the value associated with a key may be read or written many times with only a single hashtable lookup.
(define ht (make-eq-hashtable))
(define v (vector 'a 'b 'c))
(define cell (hashtable-cell ht v 3))
cell (#(a b c) . 3)
(hashtable-ref ht v 0) 3
(set-cdr! cell 4)
(hashtable-ref ht v 0) 4
procedure: (hashtable-values hashtable)
returns: a vector containing the values in hashtable
libraries: (chezscheme)
Each value is the value of one of the keys in hashtable. Duplicate values are not removed. The values may appear in any order in the returned vector.
(define ht (make-eq-hashtable))
(define p1 (cons 'a 'b))
(define p2 (cons 'a 'b))
(hashtable-set! ht p1 "one")
(hashtable-set! ht p2 "two")
(hashtable-set! ht 'q "two")
(hashtable-values ht) #("one" "two" "two")
This procedure is equivalent to:
(lambda (ht)
(let-values ([(keys values) (hashtable-entries ht)])
values))
but more efficient since the separate vector of keys need not be created.
procedure: (make-weak-eq-hashtable)
procedure: (make-weak-eq-hashtable size)
procedure: (make-weak-eqv-hashtable)
procedure: (make-weak-eqv-hashtable size)
returns: a new weak eq hashtable
libraries: (chezscheme)
These procedures are like the Revised6 Report procedures make-eq-hashtable and make-eqv-hashtable except the keys of the hashtable are held weakly, i.e., they are not protected from the garbage collector. Keys reclaimed by the garbage collector are removed from the table, and their associated values are dropped the next time the table is modified, if not sooner.
A copy of a weak eq or eqv hashtable created by hashtable-copy is also weak. If the copy is immutable, inaccessible keys may still be dropped from the hashtable, even though the contents of the table is otherwise unchanging. The effect of this can be observed via hashtable-keys and hashtable-entries.
(define ht1 (make-weak-eq-hashtable))
(define ht2 (make-weak-eq-hashtable 32))
procedure: (hashtable-weak? obj)
returns: #t if obj is a weak eq or eqv hashtable, #f otherwise
libraries: (chezscheme)
(define ht1 (make-weak-eq-hashtable))
(define ht2 (hashtable-copy ht1))
(hashtable-weak? ht2) #t
procedure: (eq-hashtable? obj)
returns: #t if obj is an eq hashtable, #f otherwise
libraries: (chezscheme)
(eq-hashtable? (make-eq-hashtable)) #t
(eq-hashtable? '(not a hash table)) #f
procedure: (eq-hashtable-weak? hashtable)
returns: #t if hashtable is weak, #f otherwise
libraries: (chezscheme)
hashtable must be an eq hashtable.
(eq-hashtable-weak? (make-eq-hashtable)) #f
(eq-hashtable-weak? (make-weak-eq-hashtable)) #t
procedure: (eq-hashtable-set! hashtable key value)
returns: unspecified
libraries: (chezscheme)
hashtable must be a mutable eq hashtable. key and value may be any Scheme values.
eq-hashtable-set! associates the value value with the key key in hashtable.
(define ht (make-eq-hashtable))
(eq-hashtable-set! ht 'a 73)
procedure: (eq-hashtable-ref hashtable key default)
returns: see below
libraries: (chezscheme)
hashtable must be an eq hashtable. key and default may be any Scheme values.
eq-hashtable-ref returns the value associated with key in hashtable. If no value is associated with key in hashtable, eq-hashtable-ref returns default.
(define ht (make-eq-hashtable))
(define p1 (cons 'a 'b))
(define p2 (cons 'a 'b))
(eq-hashtable-set! ht p1 73)
(eq-hashtable-ref ht p1 55) 73
(eq-hashtable-ref ht p2 55) 55
procedure: (eq-hashtable-contains? hashtable key)
returns: #t if an association for key exists in hashtable, #f otherwise
libraries: (chezscheme)
hashtable must be an eq hashtable. key may be any Scheme value.
(define ht (make-eq-hashtable))
(define p1 (cons 'a 'b))
(define p2 (cons 'a 'b))
(eq-hashtable-set! ht p1 73)
(eq-hashtable-contains? ht p1) #t
(eq-hashtable-contains? ht p2) #f
procedure: (eq-hashtable-update! hashtable key procedure default)
returns: unspecified
libraries: (chezscheme)
hashtable must be a mutable eq hashtable. key and default may be any Scheme values. procedure should accept one argument, should return one value, and should not modify hashtable.
eq-hashtable-update! applies procedure to the value associated with key in hashtable, or to default if no value is associated with key in hashtable. If procedure returns, eq-hashtable-update! associates key with the value returned by procedure, replacing the old association, if any.
A version of eq-hashtable-update! that does not verify that it receives arguments of the proper type might be defined as follows.
(define eq-hashtable-update!
(lambda (ht key proc value)
(eq-hashtable-set! ht key
(proc (eq-hashtable-ref ht key value)))))
An implementation may, however, be able to implement eq-hashtable-update! more efficiently by avoiding multiple hash computations and hashtable lookups.
(define ht (make-eq-hashtable))
(eq-hashtable-update! ht 'a
(lambda (x) (* x 2))
55)
(eq-hashtable-ref ht 'a 0) 110
(eq-hashtable-update! ht 'a
(lambda (x) (* x 2))
0)
(eq-hashtable-ref ht 'a 0) 220
procedure: (eq-hashtable-cell hashtable key default)
returns: a pair (see below)
libraries: (chezscheme)
hashtable must be an eq hashtable. key and default may be any Scheme values.
If no value is associated with key in hashtable, eq-hashtable-cell modifies hashtable to associate key with default. It returns a pair whose car is key and whose cdr is the associated value. Changing the cdr of this pair effectively updates the table to associate key with a new value. The key should not be changed.
(define ht (make-eq-hashtable))
(define v (vector 'a 'b 'c))
(define cell (eq-hashtable-cell ht v 3))
cell (#(a b c) . 3)
(eq-hashtable-ref ht v 0) 3
(set-cdr! cell 4)
(eq-hashtable-ref ht v 0) 4
procedure: (eq-hashtable-delete! hashtable key)
returns: unspecified
libraries: (chezscheme)
hashtable must be a mutable eq hashtable. key may be any Scheme value.
eq-hashtable-delete! drops any association for key from hashtable.
(define ht (make-eq-hashtable))
(define p1 (cons 'a 'b))
(define p2 (cons 'a 'b))
(eq-hashtable-set! ht p1 73)
(eq-hashtable-contains? ht p1) #t
(eq-hashtable-delete! ht p1)
(eq-hashtable-contains? ht p1) #f
(eq-hashtable-contains? ht p2) #f
(eq-hashtable-delete! ht p2)
procedure: (symbol-hashtable? obj)
returns: #t if obj is an eq hashtable, #f otherwise
libraries: (chezscheme)
(symbol-hashtable? (make-hashtable symbol-hash eq?)) #t
(symbol-hashtable? (make-eq-hashtable)) #f
procedure: (symbol-hashtable-set! hashtable key value)
returns: unspecified
libraries: (chezscheme)
hashtable must be a mutable symbol hashtable. (A symbol hashtable is a hashtable created with hash function symbol-hash and equivalence function eq?, eqv?, equal?, or symbol=?.) key must be a symbol, and value may be any Scheme value.
symbol-hashtable-set! associates the value value with the key key in hashtable.
(define ht (make-hashtable symbol-hash eq?))
(symbol-hashtable-ref ht 'a #f) #f
(symbol-hashtable-set! ht 'a 73)
(symbol-hashtable-ref ht 'a #f) 73
procedure: (symbol-hashtable-ref hashtable key default)
returns: see below
libraries: (chezscheme)
hashtable must be a symbol hashtable. (A symbol hashtable is a hashtable created with hash function symbol-hash and equivalence function eq?, eqv?, equal?, or symbol=?.) key must be a symbol, and default may be any Scheme value.
symbol-hashtable-ref returns the value associated with key in hashtable. If no value is associated with key in hashtable, symbol-hashtable-ref returns default.
(define ht (make-hashtable symbol-hash eq?))
(define k1 'abcd)
(define k2 'not-abcd)
(symbol-hashtable-set! ht k1 "hi")
(symbol-hashtable-ref ht k1 "bye") "hi"
(symbol-hashtable-ref ht k2 "bye") "bye"
procedure: (symbol-hashtable-contains? hashtable key)
returns: #t if an association for key exists in hashtable, #f otherwise
libraries: (chezscheme)
hashtable must be a symbol hashtable. (A symbol hashtable is a hashtable created with hash function symbol-hash and equivalence function eq?, eqv?, equal?, or symbol=?.) key must be a symbol.
(define ht (make-hashtable symbol-hash eq?))
(define k1 'abcd)
(define k2 'not-abcd)
(symbol-hashtable-set! ht k1 "hi")
(symbol-hashtable-contains? ht k1) #t
(symbol-hashtable-contains? ht k2 ) #f
procedure: (symbol-hashtable-update! hashtable key procedure default)
returns: unspecified
libraries: (chezscheme)
hashtable must be a mutable symbol hashtable. (A symbol hashtable is a hashtable created with hash function symbol-hash and equivalence function eq?, eqv?, equal?, or symbol=?.) key must be a symbol, and default may be any Scheme value. procedure should accept one argument, should return one value, and should not modify hashtable.
symbol-hashtable-update! applies procedure to the value associated with key in hashtable, or to default if no value is associated with key in hashtable. If procedure returns, symbol-hashtable-update! associates key with the value returned by procedure, replacing the old association, if any.
A version of symbol-hashtable-update! that does not verify that it receives arguments of the proper type might be defined as follows.
(define symbol-hashtable-update!
(lambda (ht key proc value)
(symbol-hashtable-set! ht key
(proc (symbol-hashtable-ref ht key value)))))
An implementation may, however, be able to implement symbol-hashtable-update! more efficiently by avoiding multiple hash computations and hashtable lookups.
(define ht (make-hashtable symbol-hash eq?))
(symbol-hashtable-update! ht 'a
(lambda (x) (* x 2))
55)
(symbol-hashtable-ref ht 'a 0) 110
(symbol-hashtable-update! ht 'a
(lambda (x) (* x 2))
0)
(symbol-hashtable-ref ht 'a 0) 220
procedure: (symbol-hashtable-cell hashtable key default)
returns: a pair (see below)
libraries: (chezscheme)
hashtable must be a mutable symbol hashtable. (A symbol hashtable is a hashtable created with hash function symbol-hash and equivalence function eq?, eqv?, equal?, or symbol=?.) key must be a symbol, and default may be any Scheme value.
If no value is associated with key in hashtable, symbol-hashtable-cell modifies hashtable to associate key with default. It returns a pair whose car is key and whose cdr is the associated value. Changing the cdr of this pair effectively updates the table to associate key with a new value. The key should not be changed.
(define ht (make-hashtable symbol-hash eq?))
(define k 'a-key)
(define cell (symbol-hashtable-cell ht k 3))
cell (a-key . 3)
(symbol-hashtable-ref ht k 0) 3
(set-cdr! cell 4)
(symbol-hashtable-ref ht k 0) 4
procedure: (symbol-hashtable-delete! hashtable key)
returns: unspecified
libraries: (chezscheme)
hashtable must be a mutable symbol hashtable. (A symbol hashtable is a hashtable created with hash function symbol-hash and equivalence function eq?, eqv?, equal?, or symbol=?.) key must be a symbol.
symbol-hashtable-delete! drops any association for key from hashtable.
(define ht (make-hashtable symbol-hash eq?))
(define k1 (gensym))
(define k2 (gensym))
(symbol-hashtable-set! ht k1 73)
(symbol-hashtable-contains? ht k1) #t
(symbol-hashtable-delete! ht k1)
(symbol-hashtable-contains? ht k1) #f
(symbol-hashtable-contains? ht k2) #f
(symbol-hashtable-delete! ht k2)
Chez Scheme extends the Revised6 Report's define-record-type syntax in one way, which is that it allows a generative record type to be declared explicitly as such (in a double-negative sort of way) by including a nongenerative clause with #f as the uid, i.e.:
(nongenerative #f)
This can be used in conjunction with the parameter require-nongenerative-clause to catch the accidental use of generative record types while avoiding spurious errors for record types that must be generative. Generative record types are rarely needed and are generally less efficient since a run-time representation of the type is created each time the define-record-clause is evaluated, rather than once at compile (expansion) time.
thread parameter: require-nongenerative-clause
libraries: (chezscheme)
This parameter holds a boolean value that determines whether define-record-type requires a nongenerative clause. The default value is #f. The lead-in above describes why one might want to set this to #t.
In addition to the Revised6 Report record-type creation and definition mechanisms, which are described in Chapter 9 of The Scheme Programming Language, 4th Edition, Chez Scheme continues to support pre-R6RS mechanisms for creating new data types, or record types, with fixed sets of named fields. Many of the procedures described in this section are available only when imported from the (chezscheme csv7) library.
Code intended to be portable should use the R6RS mechanism instead.
Records may be defined via the define-record syntactic form or via the make-record-type procedure. The underlying representation of records and record-type descriptors is the same for the Revised6 Report mechanism and the alternative mechanism. Record types created by one can be used as parent record types for the other via the procedural mechanisms, though not via the syntactic mechanisms.
The syntactic (define-record) interface is the most commonly used interface. Each define-record form defines a constructor procedure for records of the new type, a type predicate that returns true only for records of the new type, an access procedure for each field, and an assignment procedure for each mutable field. For example,
(define-record point (x y))
creates a new point record type with two fields, x and y, and defines the following procedures:
| (make-point x y) | constructor |
| (point? obj) | predicate |
| (point-x p) | accessor for field x |
| (point-y p) | accessor for field y |
| (set-point-x! p obj) | mutator for field x |
| (set-point-y! p obj) | mutator for field y |
The names of these procedures follow a regular naming convention by default, but the programmer can override the defaults if desired. define-record allows the programmer to control which fields are arguments to the generated constructor procedure and which are explicitly initialized by the constructor procedure. Fields are mutable by default, but may be declared immutable. Fields can generally contain any Scheme value, but the internal representation of each field may be specified, which places implicit constraints on the type of value that may be stored there. These customization options are covered in the formal description of define-record later in this section.
The procedural (make-record-type) interface may be used to implement interpreters that must handle define-record forms. Each call to make-record-type returns a record-type descriptor representing the record type. Using this record-type descriptor, programs may generate constructors, type predicates, field accessors, and field mutators dynamically. The following code demonstrates how the procedural interface might be used to create a similar point record type and associated definitions.
(define point (make-record-type "point" '(x y)))
(define make-point (record-constructor point))
(define point? (record-predicate point))
(define point-x (record-field-accessor point 'x))
(define point-y (record-field-accessor point 'y))
(define set-point-x! (record-field-mutator point 'x))
(define set-point-y! (record-field-mutator point 'y))
The procedural interface is more flexible than the syntactic interface, but this flexibility can lead to less readable programs and compromises the compiler's ability to generate efficient code. Programmers should use the syntactic interface whenever it suffices.
A record-type descriptor may also be extracted from an instance of a record type, whether the record type was produced by define-record or make-record-type, and the extracted descriptor may also be used to produce constructors, predicates, accessors, and mutators, with a few limitations noted in the description of record-type-descriptor below. This is a powerful feature that permits the coding of portable printers and object inspectors. For example, the printer employs this feature in its default record printer, and the inspector uses it to allow inspection and mutation of system- and user-defined records during debugging.
A parent record may be specified in the define-record syntax or as an optional argument to make-record-type. A new record inherits the parent record's fields, and each instance of the new record type is considered to be an instance of the parent type as well, so that accessors and mutators for the parent type may be used on instances of the new type.
Record type definitions may be classified as either generative or nongenerative. A new type results for each generative record definition, while only one type results for all occurrences of a given nongenerative record definition. This distinction is important semantically since record accessors and setters are applicable only to objects with the same type.
Syntactic (define-record) record definitions are expand-time generative by default, which means that a new record is created when the code is expanded. Expansion happens once for each form prior to compilation or interpretation, as when it is entered interactively, loaded from source, or compiled by compile-file. As a result, multiple evaluations of a single define-record form, e.g., in the body of a procedure called multiple times, always produce the same record type.
Separate define-record forms usually produce different types, even if the forms are textually identical. The only exception occurs when the name of a record is specified as a generated symbol, or gensym (page 147). Multiple copies of a record definition whose name is given by a gensym always produce the same record type; i.e., such definitions are nongenerative. Each copy of the record definition must contain the same fields and field modifiers in the same order; an exception is raised with condition-type &assertion when two differing record types with the same generated name are loaded into the same Scheme process.
Procedural (make-record-type) record definitions are run-time generative by default. That is, each call to make-record-type usually produces a new record type. As with the syntactic interface, the only exception occurs when the name of the record is specified as a gensym, in which case the record type is fully nongenerative.
By default, a record is printed with the syntax
#[type-name field ...]
where field ... are the printed representations of the contents of the fields of the record, and type-name is a generated symbol, or gensym (page 147), that uniquely identifies the record type. For nongenerative records, type-name is the gensym provided by the program. Otherwise, it is a gensym whose "pretty" name (page 147) is the name given to the record by define-record or make-record-type.
The default printing of records of a given type may be overridden with record-writer.
The default syntax may be used as input to the reader as well, as long as the corresponding record type has already been defined in the Scheme session in which the read occurs. The parameter record-reader may be used to specify a different name to be recognized by the reader in place of the generated name. Specifying a different name in this manner also changes the name used when the record is printed. This reader extension is disabled in an input stream after #!r6rs has been seen by the reader, unless #!chezscheme has been seen more recently.
The mark (#n=) and reference (#n#) syntaxes may be used within the record syntax, with the result of creating shared or cyclic structure as desired. All cycles must be resolvable, however, without mutation of an immutable record field. That is, any cycle must contain at least one pointer through a mutable field, whether it is a mutable record field or a mutable field of a built-in object type such as a pair or vector.
When the parameter print-record is set to #f, records are printed using the simpler syntax
#<record of type name>
where name is the "pretty" name of the record (not the full gensym) or the reader name first assigned to the record type.
syntax: (define-record name (fld1 ...) ((fld2 init) ...) (opt ...))
syntax: (define-record name parent (fld1 ...) ((fld2 init) ...) (opt ...))
returns: unspecified
libraries: (chezscheme)
A define-record form is a definition and may appear anywhere and only where other definitions may appear.
define-record creates a new record type containing a specified set of named fields and defines a set of procedures for creating and manipulating instances of the record type.
name must be an identifier. If name is a generated symbol (gensym), the record definition is nongenerative, otherwise it is expand-time generative. (See the discussion of generativity earlier in this section.)
Each fld must be an identifier field-name, or it must take the form
(class type field-name)
where class and type are optional and field-name is an identifier. class, if present, must be the keyword immutable or the keyword mutable. If the immutable class specifier is present, the field is immutable; otherwise, the field is mutable. type, if present, specifies how the field is represented, as described below.
If a type is specified, the field can contain objects only of the specified type. If no type is specified, the field is of type ptr, meaning that it can contain any Scheme object.
The field identifiers name the fields of the record. The values of the n fields described by fld1 ... are specified by the n arguments to the generated constructor procedure. The values of the remaining fields, fld2 ..., are given by the corresponding expressions, init .... Each init is evaluated within the scope of the set of field names given by fld1 ... and each field in fld2 ... that precedes it, as if within a let* expression. Each of these field names is bound to the value of the corresponding field during initialization.
If parent is present, the record type named by parent is the parent of the record. The new record type inherits each of the parent record's fields, and records of the new type are considered records of the parent type. If parent is not present, the parent record type is a base record type with no fields.
The following procedures are defined by define-record:
If no parent record type is specified, the constructor behaves as if defined as
(define make-name
(lambda (id1 ...)
(let* ([id2 init] ...)
body)))
where id1 ... are the names of the fields defined by fld1 ..., id2 ... are the names of the fields defined by fld2 ..., and body builds the record from the values of the identifiers id1 ... and id2 ....
If a parent record type is specified, the parent arguments appear first, and the parent fields are inserted into the record before the child fields.
The options opt ... control the selection of names of the generated constructor, predicate, accessors, and mutators.
(constructor id)
(predicate id)
(prefix string)
The option (constructor id) causes the generated constructor's name to be id rather than make-name. The option (predicate id) likewise causes the generated predicate's name to be id rather than name?. The option (prefix string) determines the prefix to be used in the generated accessor and mutator names in place of name-.
If no options are needed, the third subexpression, (opt ...), may be omitted. If no options and no fields other than those initialized by the arguments to the constructor procedure are needed, both the second and third subexpressions may be omitted. If options are specified, the second subexpression must be present, even if it contains no field specifiers.
Here is a simple example with no inheritance and no options.
(define-record marble (color quality))
(define x (make-marble 'blue 'medium))
(marble? x) #t
(pair? x) #f
(vector? x) #f
(marble-color x) blue
(marble-quality x) medium
(set-marble-quality! x 'low)
(marble-quality x) low
(define-record marble ((immutable color) (mutable quality))
(((mutable shape) (if (eq? quality 'high) 'round 'unknown))))
(marble-shape (make-marble 'blue 'high)) round
(marble-shape (make-marble 'blue 'low)) unknown
(define x (make-marble 'blue 'high))
(set-marble-quality! x 'low)
(marble-shape x) round
(set-marble-shape! x 'half-round)
(marble-shape x) half-round
The following example illustrates inheritance.
(define-record shape (x y))
(define-record point shape ())
(define-record circle shape (radius))
(define a (make-point 7 -3))
(shape? a) #t
(point? a) #t
(circle? a) #f
(shape-x a) 7
(set-shape-y! a (- (shape-y a) 1))
(shape-y a) -4
(define b (make-circle 7 -3 1))
(shape? b) #t
(point? b) #f
(circle? b) #t
(circle-radius b) 1
(circle-radius a) exception: not of type circle
(define c (make-shape 0 0))
(shape? c) #t
(point? c) #f
(circle? c) #f
This example demonstrates the use of options:
(define-record pair (car cdr)
()
((constructor cons)
(prefix "")))
(define x (cons 'a 'b))
(car x) a
(cdr x) b
(pair? x) #t
(pair? '(a b c)) #f
x #[#{pair bdhavk1bwafxyss1-a} a b]
This example illustrates the use a specified reader name, immutable fields, and the graph mark and reference syntax.
(define-record triple ((immutable x1) (mutable x2) (immutable x3)))
(record-reader 'triple (type-descriptor triple))
(let ([t '#[triple #1=(1 2) (3 4) #1#]])
(eq? (triple-x1 t) (triple-x3 t))) #t
(let ([x '(#1=(1 2) . #[triple #1# b c])])
(eq? (car x) (triple-x1 (cdr x)))) #t
(let ([t #[triple #1# (3 4) #1=(1 2)]])
(eq? (triple-x1 t) (triple-x3 t))) #t
(let ([t '#1=#[triple a #1# c]])
(eq? t (triple-x2 t))) #t
(let ([t '#1=(#[triple #1# b #1#])])
(and (eq? t (triple-x1 (car t)))
(eq? t (triple-x1 (car t))))) #t
Cycles established with the mark and reference syntax can be resolved only if a mutable record field or mutable location of some other object is involved the cycle, as in the last two examples above. An exception is raised with condition type &lexical if only immutable fields are involved.
'#1=#[triple #1# (3 4) #1#] exception
The following example demonstrates the use of nongenerative record definitions.
(module A (point-disp)
(define-record #{point bdhavk1bwafxyss1-b} (x y))
(define square (lambda (x) (* x x)))
(define point-disp
(lambda (p1 p2)
(sqrt (+ (square (- (point-x p1) (point-x p2)))
(square (- (point-y p1) (point-y p2))))))))
(module B (base-disp)
(define-record #{point bdhavk1bwafxyss1-b} (x y))
(import A)
(define base-disp
(lambda (p)
(point-disp (make-point 0 0) p))))
(let ()
(import B)
(define-record #{point bdhavk1bwafxyss1-b} (x y))
(base-disp (make-point 3 4))) 5
This works even if the different program components are loaded from different source files or are compiled separately and loaded from different object files.
syntax: predicate
syntax: prefix
syntax: constructor
libraries: (chezscheme)
These identifiers are auxiliary keywords for define-record. It is a syntax violation to reference these identifiers except in contexts where they are recognized as auxiliary keywords. mutable and immutable are also auxiliary keywords for define-record, shared with the Revised6 Report define-record-type.
syntax: (type-descriptor name)
returns: the record-type descriptor associated with name
libraries: (chezscheme)
name must name a record type defined by define-record of define-record-type.
This form is equivalent to the Revised6 Report record-type-descriptor form.
The record-type descriptor is useful for overriding the default read and write syntax using record-reader and record-writer and may also be used with the procedural interface routines described later in this section.
(define-record frob ())
(type-descriptor frob) #<record type frob>
procedure: (record-reader name)
returns: the record-type descriptor associated with name
procedure: (record-reader rtd)
returns: the first name associated with rtd
procedure: (record-reader name rtd)
returns: unspecified
procedure: (record-reader name #f)
returns: unspecified
procedure: (record-reader rtd #f)
returns: unspecified
libraries: (chezscheme)
name must be a symbol, and rtd must be a record-type descriptor.
With one argument, record-reader is used to retrieve the record type associated with a name or name associated with a record type. If no association has been created, record-reader returns #f
With arguments name and rtd, record-reader registers rtd as the record-type descriptor to be used whenever the read procedure encounters a record named by name and printed in the default record syntax.
With arguments name and #f, record-reader removes any association for name to a record-type descriptor. Similarly, with arguments rtd and #f, record-reader removes any association for rtd to a name.
(define-record marble (color quality))
(define m (make-marble 'blue 'perfect))
m #[#{marble bdhavk1bwafxyss1-c} blue perfect]
(record-reader (type-descriptor marble)) #f
(record-reader 'marble) #f
(record-reader 'marble (type-descriptor marble))
(marble-color '#[marble red miserable]) red
(record-reader (type-descriptor marble)) marble
(record-reader 'marble) #<record type marble>
(record-reader (type-descriptor marble) #f)
(record-reader (type-descriptor marble)) #f
(record-reader 'marble) #f
(record-reader 'marble (type-descriptor marble))
(record-reader 'marble #f)
(record-reader (type-descriptor marble)) #f
(record-reader 'marble) #f
The introduction of a record reader also changes the default printing of records. The printer always chooses the reader name first assigned to the record, if any, in place of the unique record name, as this continuation of the example above demonstrates.
(record-reader 'marble (type-descriptor marble))
(make-marble 'pink 'splendid) #[marble pink splendid]
procedure: (record-writer rtd)
returns: the record writer associated with rtd
procedure: (record-writer rtd procedure)
returns: unspecified
libraries: (chezscheme)
rtd must be a record-type descriptor, and procedure should accept three arguments, as described below.
When passed only one argument, record-writer returns the record writer associated with rtd, which is initially the default record writer for all records. The default print method prints all records in a uniform syntax that includes the generated name for the record and the values of each of the fields, as described in the introduction to this section.
When passed two arguments, record-writer establishes a new association between rtd and procedure so that procedure will be used by the printer in place of the default printer for records of the given type. The printer passes procedure three arguments: the record r, a port p, and a procedure wr that should be used to write out the values of arbitrary Scheme objects that the print method chooses to include in the printed representation of the record, e.g., values of the record's fields.
(define-record marble (color quality))
(define m (make-marble 'blue 'medium))
m #[#{marble bdhavk1bwafxyss1-d} blue medium]
(record-writer (type-descriptor marble)
(lambda (r p wr)
(display "#<" p)
(wr (marble-quality r) p)
(display " quality " p)
(wr (marble-color r) p)
(display " marble>" p)))
m #<medium quality blue marble>
The record writer is used only when print-record is true (the default). When the parameter print-record is set to #f, records are printed using a compressed syntax that identifies only the type of record.
(parameterize ([print-record #f])
(format "~s" m)) "#<record of type marble>"
A print method may be called more than once during the printing of a single record to support cycle detection and graph printing (see print-graph), so print methods that perform side effects other than printing to the given port are discouraged. Whenever a print method is called more than once during the printing of a single record, in all but one call, a generic "bit sink" port is used to suppress output automatically so that only one copy of the object appears on the actual port. In order to avoid confusing the cycle detection and graph printing algorithms, a print method should always produce the same printed representation for each object. Furthermore, a print method should normally use the supplied procedure wr to print subobjects, though atomic values, such as strings or numbers, may be printed by direct calls to display or write or by other means.
(let ()
(define-record ref () ((contents 'nothing)))
(record-writer (type-descriptor ref)
(lambda (r p wr)
(display "<" p)
(wr (ref-contents r) p)
(display ">" p)))
(let ([ref-lexive (make-ref)])
(set-ref-contents! ref-lexive ref-lexive)
ref-lexive)) #0=<#0#>
Print methods need not be concerned with handling nonfalse values of the parameters print-level. The printer handles print-level automatically even when user-defined print procedures are used. Since records typically contain a small, fixed number of fields, it is usually possible to ignore nonfalse values of print-length as well.
(print-level 3)
(let ()
(define-record ref () ((contents 'nothing)))
(record-writer (type-descriptor ref)
(lambda (r p wr)
(display "<" p)
(wr (ref-contents r) p)
(display ">" p)))
(let ([ref-lexive (make-ref)])
(set-ref-contents! ref-lexive ref-lexive)
ref-lexive)) <<<<#[...]>>>>
thread parameter: print-record
libraries: (chezscheme)
This parameter controls the printing of records. If set to true (the default) the record writer associated with a record type is used to print records of that type. If set to false, all records are printed with the syntax #<record of type name>, where name is the name of the record type as returned by record-type-name.
procedure: (make-record-type type-name fields)
procedure: (make-record-type parent-rtd type-name fields)
returns: a record-type descriptor for a new record type
libraries: (chezscheme)
make-record-type creates a new data type and returns a record-type descriptor, a value representing the new data type. The new type is disjoint from all others.
If present, parent-rtd must be a record-type descriptor.
type-name must be a string or gensym. If type-name is a string, a new record type is generated. If type-name is a gensym, a new record type is generated only if one with the same gensym has not already been defined. If one has already been defined, the parent and fields must be identical to those of the existing record type, and the existing record type is used. If the parent and fields are not identical, an exception is raised with condition-type &assertion.
fields must be a list of field descriptors, each of which describes one field of instances of the new record type. A field descriptor is either a symbol or a list in the following form:
(class type field-name)
where class and type are optional. field-name must be a symbol. class, if present, must be the symbol immutable or the symbol mutable. If the immutable class-specifier is present, the field is immutable; otherwise, the field is mutable. type, if present, specifies how the field is represented. The types are the same as those given in the description of define-record on page 163.
If a type is specified, the field can contain objects only of the specified type. If no type is specified, the field is of type ptr, meaning that it can contain any Scheme object.
The behavior of a program that modifies the string type-name or the list fields or any of its sublists is unspecified.
The record-type descriptor may be passed as an argument to any of the Revised6 Report procedures
or to the Chez Scheme variants
to obtain procedures for creating and manipulating records of the new type.
(define marble
(make-record-type "marble"
'(color quality)
(lambda (r p wr)
(display "#<" p)
(wr (marble-quality r) p)
(display " quality " p)
(wr (marble-color r) p)
(display " marble>" p))))
(define make-marble
(record-constructor marble))
(define marble?
(record-predicate marble))
(define marble-color
(record-field-accessor marble 'color))
(define marble-quality
(record-field-accessor marble 'quality))
(define set-marble-quality!
(record-field-mutator marble 'quality))
(define x (make-marble 'blue 'high))
(marble? x) #t
(marble-quality x) high
(set-marble-quality! x 'low)
(marble-quality x) low
x #<low quality blue marble>
The order in which the fields appear in fields is important. While field names are generally distinct, it is permissible for one field name to be the same as another in the list of fields or the same as an inherited name. In this case, field ordinals must be used to select fields in calls to record-field-accessor and record-field-mutator. Ordinals range from zero through one less than the number of fields. Parent fields come first, if any, followed by the fields in fields, in the order given.
(define r1 (make-record-type "r1" '(t t)))
(define r2 (make-record-type r1 "r2" '(t)))
(define r3 (make-record-type r2 "r3" '(t t t)))
(define x ((record-constructor r3) 'a 'b 'c 'd 'e 'f))
((record-field-accessor r3 0) x) a
((record-field-accessor r3 2) x) c
((record-field-accessor r3 4) x) e
((record-field-accessor r3 't) x) unspecified
procedure: (record-constructor rcd)
procedure: (record-constructor rtd)
returns: a constructor for records of the type represented by rtd
libraries: (chezscheme)
Like the Revised6 Report version of this procedure, this procedure may be passed a record-constructor descriptor, rcd, which determines the behavior of the constructor. It may also be passed a record-type descriptor, rtd, in which case the constructor accepts as many arguments as there are fields in the record; these arguments are the initial values of the fields in the order given when the record-type descriptor was created.
procedure: (record-field-accessor rtd field-id)
returns: an accessor for the identified field
libraries: (chezscheme csv7)
rtd must be a record-type descriptor, field-id must be a symbol or field ordinal, i.e., a nonnegative exact integer less than the number of fields of the given record type. The specified field must be accessible.
The generated accessor expects one argument, which must be a record of the type represented by rtd. It returns the contents of the specified field of the record.
procedure: (record-field-accessible? rtd field-id)
returns: #t if the specified field is accessible, otherwise #f
libraries: (chezscheme csv7)
rtd must be a record-type descriptor, field-id must be a symbol or field ordinal, i.e., a nonnegative exact integer less than the number of fields of the given record type.
The compiler is free to eliminate a record field if it can prove that the field is not accessed. In making this determination, the compiler is free to ignore the possibility that an accessor might be created from a record-type descriptor obtained by calling record-type-descriptor on an instance of the record type.
procedure: (record-field-mutator rtd field-id)
returns: a mutator for the identified field
libraries: (chezscheme csv7)
rtd must be a record-type descriptor, field-id must be a symbol or field ordinal, i.e., a nonnegative exact integer less than the number of fields of the given record type. The specified field must be mutable.
The mutator expects two arguments, r and obj. r must be a record of the type represented by rtd. obj must be a value that is compatible with the type declared for the specified field when the record-type descriptor was created. obj is stored in the specified field of the record.
procedure: (record-field-mutable? rtd field-id)
returns: #t if the specified field is mutable, otherwise #f
libraries: (chezscheme csv7)
rtd must be a record-type descriptor, field-id must be a symbol or field ordinal, i.e., a nonnegative exact integer less than the number of fields of the given record type.
Any field declared immutable is immutable. In addition, the compiler is free to treat a field as immutable if it can prove that the field is never assigned. In making this determination, the compiler is free to ignore the possibility that a mutator might be created from a record-type descriptor obtained by calling record-type-descriptor on an instance of the record type.
procedure: (record-type-name rtd)
returns: the name of the record-type represented by rtd
libraries: (chezscheme csv7)
rtd must be a record-type descriptor.
The name is a always a string. If a gensym is provided as the record-type name in a define-record form or make-record-type call, the result is the "pretty" name of the gensym (see 7.9).
(record-type-name (make-record-type "empty" '())) "empty"
(define-record #{point bdhavk1bwafxyss1-b} (x y))
(define p (type-descriptor #{point bdhavk1bwafxyss1-b}))
(record-type-name p) "point"
procedure: (record-type-symbol rtd)
returns: the generated symbol associated with rtd
libraries: (chezscheme csv7)
rtd must be a record-type descriptor.
(define e (make-record-type "empty" '()))
(record-type-symbol e) #{empty bdhavk1bwafxyss1-e}
(define-record #{point bdhavk1bwafxyss1-b} (x y))
(define p (type-descriptor #{point bdhavk1bwafxyss1-b}))
(record-type-symbol p) #{point bdhavk1bwafxyss1-b}
procedure: (record-type-field-names rtd)
returns: a list of field names of the type represented by rtd
libraries: (chezscheme csv7)
rtd must be a record-type descriptor. The field names are symbols.
(define-record triple ((immutable x1) (mutable x2) (immutable x3)))
(record-type-field-names (type-descriptor triple)) (x1 x2 x3)
procedure: (record-type-field-decls rtd)
returns: a list of field declarations of the type represented by rtd
libraries: (chezscheme csv7)
rtd must be a record-type descriptor. Each field declaration has the following form:
(class type field-name)
where class, type, and field-name are as described under make-record-type.
(define-record shape (x y))
(define-record circle shape (radius))
(record-type-field-decls
(type-descriptor circle)) ((mutable ptr x)
(mutable ptr y)
(mutable ptr radius))
procedure: (record? obj)
returns: #t if obj is a record, otherwise #f
procedure: (record? obj rtd)
returns: #t if obj is a record of the given type, otherwise #f
libraries: (chezscheme)
If present, rtd must be a record-type descriptor.
A record is "of the given type" if it is an instance of the record type or one of its ancestors. The predicate generated by record-predicate for a record-type descriptor rtd is equivalent to the following.
(lambda (x) (record? x rtd))
procedure: (record-type-descriptor rec)
returns: the record-type descriptor of rec
libraries: (chezscheme csv7)
rec must be a record. This procedure is intended for use in the definition of portable printers and debuggers. For records created with make-record-type, it may not be the same as the descriptor returned by make-record-type. See the comments about field accessibility and mutability under record-field-accessible? and record-field-mutable? above.
This procedure is equivalent to the Revised6 Report record-rtd procedure.
(define rtd (make-record-type "frob" '(blit blat)))
rtd #<record type frob>
(define x ((record-constructor rtd) 1 2))
(record-type-descriptor x) #<record type frob>
(eq? (record-type-descriptor x) rtd) unspecified
Chez Scheme Version 9 User's Guide
Copyright © 2016 Cisco Systems, Inc.
Licensed under the Apache License Version 2.0
(full copyright notice.).
Revised June 2016 for Chez Scheme Version 9.4
about this book


Test document
D Evans
Feb 2019
?Command:tableofcontents?
Abstract
?Command:noindent?Mauris augue nunc congue mattis pretium, egestas condimentum leo torquent mattis arcu nascetur, dictum fames eu dictumst sed, ligula hac ante. Nibh libero dictum tellus, vitae vulputate aliquam massa felis nisl pretium, curabitur nullam sollicitudin sodales quisque potenti.
1 Introduction
This is a test file for latextree.latex2html.2 Sections and headings
Bibendum nonummy mus ad suspendisse est quam, mattis ipsum porta imperdiet ultrices libero id, turpis per volutpat luctus, placerat congue. Ipsum facilisis urna libero felis nisl eleifend, tellus nullam cubilia vivamus varius egestas, dictum penatibus nec. Elementum nisl enim faucibus, dictumst interdum dis eleifend nullam, nibh rhoncus vitae tortor eget, congue pellentesque montes dictum senectus. Aliquet litora suscipit facilisis fames libero.
2.1 A fancy title: $\alpha+\beta$
Lacinia sociosqu proin risus dolor enim tincidunt, lobortis mi justo metus vel, eleifend tortor mattis consequat facilisi, aliquam sem. Ad consectetuer magnis fermentum nullam ut, erat habitant consequat ipsum, class.
 Dis phasellus conubia convallis tellus, vel arcu sagittis ultrices cras risus, sit inceptos et aenean tempor, urna id turpis. Dignissim nunc pede dictumst dictum aenean hendrerit.
A subsection-level heading
Ligula erat iaculis sociis et, duis ultrices ridiculus hymenaeos purus, pulvinar rhoncus dis a aliquam, pede facilisis nisi. Pellentesque porttitor potenti nulla, penatibus cubilia diam id iaculis cum nibh, non sociis dignissim dui platea, molestie maecenas eros natoque ornare. Pellentesque interdum nunc malesuada nam et tellus, nisl nisi purus metus, litora aliquam euismod magnis dictumst nonummy, augue nibh. Urna praesent inceptos taciti sem placerat, sodales varius sodales nascetur, facilisis integer placerat sociosqu in vehicula.
3 Lists
An unordered list:- Apples
- Oranges
- Lemons
An ordered list:
- Cars
- Buses
- Bikes
4 Theorems
5 Boxes
Here is a center environment:
A minipage environment (these are inline environments):
A minipage environment with a centering declaration:
A minipage environment with a raggedleft declaration:
6 Mathematics
An inline equation: $\sum_{n=1}^{\infty} a_n = 1$.

An align environment:
An equation containing three pmatrix environments:
7 Text, Text, Text and Text
7.1 Spacing problems
Here is a sum $1+1=2$. Watch the comma $\sum x_n^2$, is there a space? Seems to be fixed!Non-breaking spaces
Tildes don't appear in mathmode. Here is an fbox containing lots of them:?contents?
This is useful to protect mathmode against VLE rewriters.
7.2 Accents
Delimited- Not spaced: é è ŵ ö .
- Spaced: é è ŵ ö .
Undelimited
- Not spaced: é è ŵ ö .
- Spaced: é è ŵ ö .
Some words ...
- Cramé r-Rao.
- Y mô r coch.
7.3 Escaped characters
- Not spaced: &x %x $x .
- Spaced: & x % x $ x .
We need to be careful with $ x characters!
7.4 Font styles
Here are some font styles:- bold
- italic
- teletype
- small caps
- oblique
8 Declarations
8.1 Font style
TeX-style teletype: LatexTree .
LaTeX-style teletype: LatexTree.
- No spaces: pre--inside--post
- No spaces with TeX-style bold: pre--bold- -post
Remark: unlike Latex the browser compounds font styles:
- first second third fourth fifth sixth seventh
8.2 Font size
- tiny
- scriptsize
- footnotesize
- small
- normalsize
- large
- Large
- LARGE
- huge
- Huge
8.3 Language declarations
pre--normal bold italic normal- -post
pre--common cymraeg english common--post
9.2 Links
Here is a labelled theorem containing a labelled equation.
9.1 Cross-references
- Here is a ref - - to the introduction.
- Here is a ref - - to the current section.
- Here is a ref - - to the current subsection.
- Here is a ref - - to the above theorem.
- Here is an eqref - - to the equation in the above theorem.
9.2 Citations
- A citation - [] - to the first bibtex entry.
- A citation - [] - to the second bibtex entry.
- A citation - [] - to the first two bibtex entries.
9.3 The hyperref package
- Here is a url: - http://www.bbc.co.uk/-.
- Here is some - hyperlinked text-.
- Here is a -named cross-reference- to the introduction.
- here is an autoref -- to the introduction.
- Here is a nameref -Introduction- to the introduction.
Document-level labels
For a viewable links to the document-level label we need to use the hyperref command as follows: -back-to-top-. There is no number or title associated with the document-level so other xref commands don't know what to display. Document-level labels might be useful to organise documents within and across modules.References
- Geoffrey R. Grimmett and David R. Stirzaker. ?Command:newblock? Probability and Random Processes . ?Command:newblock? Oxford University Press, third edition, 2001.
- Robert V. Hogg, Joseph W. McKean and Allen T. Craig. ?Command:newblock? Introduction to Mathematical Statistics . ?Command:newblock? Prentice Hall, sixth edition, 2005.
10.2 Counters
- ?counter?
- ?counter?
- ?counter?
11.2 Verbatim
pre12.2 Videos
Embedding videos in PDFs is difficult, and it's better to include hyperlinks to YouTube videos using the url and href commands.url commands
Please watch this video: https://www.youtube.com/watch?v=oCDXhvXye9E.href commands
Please watch this video.12.1 video environments
We define a new float called video which uses the custom includevideo command. This command is intended to mirror the way that includegraphics is used within figure floats. In the PDF version this is again rendered as a hyperlink, but LatexTree embeds the video into the webpage.Why does it need to be a float instead of a simple environment?
-- For PDF it's simply a centred/displayed URL in Latex (one line).
-- For HTML there's no need to float it!
However it gives displayed videos the look and feel of figures and tables in terms of boxed, captions, etc. and we can have lov too.
Note To get an embed code for a YouTube video, click on Share->Embed under the video and it will generate an entire iframe tag from which the URL can be easily recovered.
?Command:appendix?
13.2 Jobs List
- MC/MA as forms
- Table of contents
- Images and videos
- Numerals
14.2 Figures
We parse the optional argument to includegraphics. The Image class has an attribute width expressed as a percentage. This is computed from the (optional) scale or width parameters passed to includegraphics.
- is the original (scale = 0.25).
- is the big one (scale = 0.5).
- is the small one (scale = 0.1).
- shows a figure layout using subfigure.
- shows a figure layout using tabular.
?Command:cleardoublepage? ?Command:newpage?
15.2 Testbed
Multiple captions:


Bases: object
add host
if groupname is none, create a new host if group name is not none, add host to group
class version history
2: (v2.1.1) added ceilometer 1: (v2.0.1) initial release
create json inventory file using filter ({})
The inventory will be placed in a directory in /tmp, with the directory name of form kolla_uuid.py, where uuid is a unique deployment id.
return path to filtered json generator file
generate json inventory for ansible
The hosts and groups added to the json output for ansible will be filtered by the hostnames and groupnames in the deploy filters. This allows a more targeted deploy to a specific set of hosts or groups.
typical ansible json format: { ‘group’: {
- ‘hosts’: [
- ‘<IP_ADDRESS>’, ‘<IP_ADDRESS>’
], ‘vars’: {
‘ansible_ssh_user’: ‘johndoe’, ‘ansible_ssh_private_key_file’: ‘~/.ssh/mykey’, ‘example_variable’: ‘value’} ‘children’: [ ‘marietta’, ‘5points’ ]
}, ‘_meta’: {
- ‘hostvars’: {
- ‘<IP_ADDRESS>’: {
- ‘host_specific_var’: ‘bar’
}, ‘<IP_ADDRESS>’: {
‘host_specific_var’: ‘foo’}
}
}
}
return all groups containing host
if hosts is none, return all groups in inventory
remove host
if groupname is none, delete host if group name is not none, remove host from group
setup multiple hosts
hosts_info is a dict of format: {‘hostname1’: {
‘password’: password ‘uname’: user_name }
} The uname entry is optional.
clear a password
if the password exists, it will be removed from the passwords file
Bases: object
Object which represents an exclusive resource lock
flock usage is the default behavior but a separate pidfile mechanism is also available. flock doesn’t have the same orphaned lock issue that pidfile usage does. both need to be tests on NFS. if flock works then it seems better / less complicated for our needs.
change password in passwords.yml file
file_path: path to passwords file pname: name of password pvalue: value of password when not ssh key public_key: public ssh key private_key: private ssh key clear: flag to remove password
If clear, and password exists, remove it from the password file. If clear, and password doesn’t exists, nothing is done. If not clear, and key is not found, the new password will be added. If not clear, and key is found, edit password in place.
The passwords file contains both key-value pairs and key-dictionary pairs.
change property with a file
file_path: path to property file property_dict: dictionary of property names and values clear: flag to remove property
If clear, and property exists, remove it from the property file. If clear, and property doesn’t exists, nothing is done. If not clear, and key is not found, the new property will be appended. If not clear, and key is found, edit property in place.
convert lists to strings
Because of the way cliff processes strings for tables, if a list has non-ascii chars in it, they would display as unicode bytes (u0414u0435u043au0430u0442). By converting the list to string here, the proper non-ascii chars are displayed.
This will only change the lists when the output is to a user visible medium. It cannot be changed if the display output is json, yaml, etc.
convert string to unicode.
This is used to fixup extended ascii chars in strings. these chars cause errors in json pickle/unpickle.
get a python2 ansible command
Ansible cannot run yet with python3. If the current default python is py3, prefix the ansible command with a py2 interpreter.
Return boolean True if string represents a true value (None is False)
run a system command
return: - err_msg: empty string=command succeeded
not None=command failed
Convert bytes or strings to unicode string
Converts strings, lists, or dictionaries to unicode.


|
ELECTRICAL AND COMPUTER ENGINEERING |
|
FALL Quarter 2011
COURSE LIST |
|
| 9/27/2011 |
|
|
|
|
|
| COURSE |
TITLE |
CR |
FACULTY |
DAYS/TIMES |
ROOM |
| EE 204 |
CIRCUIT ANALYSIS |
4 |
Liu |
TR 130-310PM |
ETA227 |
| EE 210 |
ELECT MEAS LAB |
1 |
Khwaja |
M 1240-330PM |
ETC249 |
| EE 211 |
ELECT CIR LAB |
1 |
Alvarenga |
R 1240-330PM |
ETC249 |
| EE 244 |
DIG ENGINEERING |
4 |
Warter-Perez |
TR 420-6PM |
ETB10 |
| EE 290-1 |
ELECT ENG COMP |
3 |
Brandt |
MW 950-1040AM |
ETC255D |
| EE 290-2 |
LAB |
0 |
Brandt |
MW 1050AM-1220PM |
ETC255D |
| EE 304 |
ELECT MACHINES |
4 |
Rad |
TR 420-6PM |
ETA227 |
| EE 314 |
ELECT ENER CONV LAB |
1 |
Rysin |
M 610-9PM |
ETA209 |
EE 330 |
WRITING FOR ELEC ENG |
1 |
|
R 110-4PM |
ETC255D |
| EE 332 |
SYSTEMS ANALYSIS |
4 |
Tabrizi |
MW 1140AM-120PM |
SHC264 |
| EE 334 |
PROB AND RANDOM PROC |
4 |
Tabrizi |
MW 950-1130AM |
SHC137 |
| EE 345 |
MICROCOMPUTER PROG |
4 |
Warter-Perez |
TR 950-1130AM |
ETA226 |
| EE 421 |
CODING FOR COMM |
4 |
Tabrizi |
TR 1140AM-120PM |
SHC264 |
| EE 426 |
DIGITAL IMAGE PROC |
4 |
Kheiri |
TR 8-940PM |
ETC255G |
| EE 428 |
DIG SIG PROC LAB |
1 |
Flores |
W 610-9PM |
ETC252 |
| EE 431 |
ELEC POWER DIST |
4 |
Rysin |
R 8-940PM |
ETA227 |
|
|
|
|
F 420-6PM |
ETA227 |
| EE 432 |
POWER TRANSM LINES |
4 |
Habibi-Ashrafi |
MW 610-750PM |
ETA226 |
EE 436 |
ANALOG INTEG CIR |
4 |
|
MW 8-940PM |
ETA332 |
| EE 442 |
MULTIMEDIA NETWRKNG |
4 |
Dong |
MW 420-6PM |
ETC255E |
| EE 449 |
COMPUTER ORG |
4 |
Warter-Perez |
MW 950-1130AM |
ETA332 |
| EE 454 |
INTRO TO BIOMED INST. |
4 |
Won |
TR 1140AM-120PM |
ETB10 |
| EE 462 |
STATE SPACE CNTRL SYS |
4 |
Alwar |
TR 420-6PM |
ETC160 |
| EE 465 |
SYSTEMS ENG |
4 |
Karimlou |
TR 610-750PM |
ETA332 |
| EE 483 |
POWER ELECTRONICS |
4 |
Rad |
MW 420-6PM |
ETA332 |
| EE 496A-1 |
SENIOR DESIGN I |
2 |
Injeyan |
T 130-310PM |
ETA331 |
EE 496A-2 |
SENIOR DESIGN I |
2 |
|
T 130-310PM |
ETA332 |
| EE 498 |
COOPERATIVE ED |
1 |
Tabrizi |
TBA |
no room |
| EE 520 |
ADV DIG COMM I |
4 |
Daneshgaran |
TR 610-750PM |
ETC154 |
| EE 533 |
COMP METHOD PWR SYS |
4 |
Castaneda |
F 610-10PM |
ETA209 |
| EE 544 |
COMP NTWRKS AND INTRNTS |
4 |
Liu |
TR 420-6PM |
ETA406 |
| EE 561 |
STOCH SYS AND EST |
4 |
Kheiri |
MW 610-750PM |
ETA406 |
| EE 566 |
SYS ANALYSIS & DES |
4 |
Karimlou |
MW 8-940PM |
ETA226 |
| ENGR 301 |
ETHICS & PROF IN ENG |
1 |
Espinosa-Villegas |
M 8-850PM |
ETA227 |
| ENGR 383 |
ANCHIENT & MOD TEC |
4 |
Azarbayjani |
TR 8-940PM |
ETC256 |
|
|
|
|
|
|
| NOTE:
INFO IN BOLD TYPE INDICATES A CHANGE; |
|
| A
STRIKE THROUGH INDICATES A CANCELLED COURSE |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|


This file provides an API for key wrapping (KW) and key wrapping with padding (KWP) as defined in NIST SP 800-38F. https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38F.pdf.
More...
#include "config.h"
#include "cipher.h"
Go to the source code of this file.
|
| void | mbedtls_nist_kw_init (mbedtls_nist_kw_context *ctx) |
| | This function initializes the specified key wrapping context to make references valid and prepare the context for mbedtls_nist_kw_setkey() or mbedtls_nist_kw_free(). More...
|
| |
| int | mbedtls_nist_kw_setkey (mbedtls_nist_kw_context *ctx, mbedtls_cipher_id_t cipher, const unsigned char *key, unsigned int keybits, const int is_wrap) |
| | This function initializes the key wrapping context set in the ctx parameter and sets the encryption key. More...
|
| |
| void | mbedtls_nist_kw_free (mbedtls_nist_kw_context *ctx) |
| | This function releases and clears the specified key wrapping context and underlying cipher sub-context. More...
|
| |
| int | mbedtls_nist_kw_wrap (mbedtls_nist_kw_context *ctx, mbedtls_nist_kw_mode_t mode, const unsigned char *input, size_t in_len, unsigned char *output, size_t *out_len, size_t out_size) |
| | This function encrypts a buffer using key wrapping. More...
|
| |
| int | mbedtls_nist_kw_unwrap (mbedtls_nist_kw_context *ctx, mbedtls_nist_kw_mode_t mode, const unsigned char *input, size_t in_len, unsigned char *output, size_t *out_len, size_t out_size) |
| | This function decrypts a buffer using key wrapping. More...
|
| |
| int | mbedtls_nist_kw_self_test (int verbose) |
| | The key wrapping checkup routine. More...
|
| |
This file provides an API for key wrapping (KW) and key wrapping with padding (KWP) as defined in NIST SP 800-38F. https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38F.pdf.
Key wrapping specifies a deterministic authenticated-encryption mode of operation, according to NIST SP 800-38F: Recommendation for Block Cipher Modes of Operation: Methods for Key Wrapping. Its purpose is to protect cryptographic keys.
Its equivalent is RFC 3394 for KW, and RFC 5649 for KWP. https://tools.ietf.org/html/rfc3394 https://tools.ietf.org/html/rfc5649
Definition in file nist_kw.h.
◆ mbedtls_nist_kw_mode_t
| Enumerator |
|---|
| MBEDTLS_KW_MODE_KW | |
| MBEDTLS_KW_MODE_KWP | |
Definition at line 77 of file nist_kw.h.
◆ mbedtls_nist_kw_free()
This function releases and clears the specified key wrapping context and underlying cipher sub-context.
- Parameters
-
| ctx | The key wrapping context to clear. |
◆ mbedtls_nist_kw_init()
◆ mbedtls_nist_kw_self_test()
| int mbedtls_nist_kw_self_test |
( |
int |
verbose | ) |
|
The key wrapping checkup routine.
- Returns
0
on success.
-
1
on failure.
◆ mbedtls_nist_kw_setkey()
This function initializes the key wrapping context set in the ctx
parameter and sets the encryption key.
- Parameters
-
| ctx | The key wrapping context. |
| cipher | The 128-bit block cipher to use. Only AES is supported. |
| key | The Key Encryption Key (KEK). |
| keybits | The KEK size in bits. This must be acceptable by the cipher. |
| is_wrap | Specify whether the operation within the context is wrapping or unwrapping |
- Returns
0
on success.
-
MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA
for any invalid input.
-
MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE
for 128-bit block ciphers which are not supported.
-
cipher-specific error code on failure of the underlying cipher.
◆ mbedtls_nist_kw_unwrap()
This function decrypts a buffer using key wrapping.
- Parameters
-
| ctx | The key wrapping context to use for decryption. |
| mode | The key wrapping mode to use (MBEDTLS_KW_MODE_KW or MBEDTLS_KW_MODE_KWP) |
| input | The buffer holding the input data. |
| in_len | The length of the input data in Bytes. The input uses units of 8 Bytes called semiblocks. The input must be a multiple of semiblocks.
-
For KW mode: a multiple of 8 bytes between 24 and 2^57 inclusive.
-
For KWP mode: a multiple of 8 bytes between 16 and 2^32 inclusive.
|
| [out] | output | The buffer holding the output data. The output buffer's minimal length is 8 bytes shorter than in_len . |
| [out] | out_len | The number of bytes written to the output buffer. 0 on failure. For KWP mode, the length could be up to 15 bytes shorter than in_len , depending on how much padding was added to the data. |
| [in] | out_size | The capacity of the output buffer. |
- Returns
0
on success.
-
MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA
for invalid input length.
-
MBEDTLS_ERR_CIPHER_AUTH_FAILED
for verification failure of the ciphertext.
-
cipher-specific error code on failure of the underlying cipher.
◆ mbedtls_nist_kw_wrap()
This function encrypts a buffer using key wrapping.
- Parameters
-
| ctx | The key wrapping context to use for encryption. |
| mode | The key wrapping mode to use (MBEDTLS_KW_MODE_KW or MBEDTLS_KW_MODE_KWP) |
| input | The buffer holding the input data. |
| in_len | The length of the input data in Bytes. The input uses units of 8 Bytes called semiblocks.
-
For KW mode: a multiple of 8 bytes between 16 and 2^57-8 inclusive.
-
For KWP mode: any length between 1 and 2^32-1 inclusive.
|
| [out] | output | The buffer holding the output data.
-
For KW mode: Must be at least 8 bytes larger than
in_len .
-
For KWP mode: Must be at least 8 bytes larger rounded up to a multiple of 8 bytes for KWP (15 bytes at most).
|
| [out] | out_len | The number of bytes written to the output buffer. 0 on failure. |
| [in] | out_size | The capacity of the output buffer. |
- Returns
0
on success.
-
MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA
for invalid input length.
-
cipher-specific error code on failure of the underlying cipher.


Checkout
Ordering by:
Name:
Email
Ordering of:
Thank you for buying!
Please check your email for confirmation of purchase.
Checkout