▼ |  | The Racket Reference

1 | Language Model
2 | Notation for Documentation
3 | Syntactic Forms
4 | Datatypes
5 | Structures
6 | Classes and Objects
7 | Units
8 | Contracts
9 | Pattern Matching
10 | Control Flow
11 | Concurrency and Parallelism
12 | Macros
13 | Input and Output
14 | Reflection and Security
15 | Operating System
16 | Memory Management
17 | Unsafe Operations
18 | Running Racket
| Bibliography
| Index

► | 17 | Unsafe Operations

17.1 | Unsafe Numeric Operations
17.2 | Unsafe Character Operations
17.3 | Unsafe Data Extraction
17.4 | Unsafe Extflonum Operations
17.5 | Unsafe Impersonators and Chaperones
17.6 | Unsafe Undefined

On this page:

17.1`` Unsafe Numeric Operations
unsafe-fx+
unsafe-fx-
unsafe-fx*
unsafe-fxquotient
unsafe-fxremainder
unsafe-fxmodulo
unsafe-fxabs
unsafe-fxand
unsafe-fxior
unsafe-fxxor
unsafe-fxnot
unsafe-fxlshift
unsafe-fxrshift
unsafe-fx=
unsafe-fx<
unsafe-fx>
unsafe-fx<=
unsafe-fx>=
unsafe-fxmin
unsafe-fxmax
unsafe-fl+
unsafe-fl-
unsafe-fl*
unsafe-fl/
unsafe-flabs
unsafe-fl=
unsafe-fl<
unsafe-fl>
unsafe-fl<=
unsafe-fl>=
unsafe-flmin
unsafe-flmax
unsafe-flround
unsafe-flfloor
unsafe-flceiling
unsafe-fltruncate
unsafe-flsin
unsafe-flcos
unsafe-fltan
unsafe-flasin
unsafe-flacos
unsafe-flatan
unsafe-fllog
unsafe-flexp
unsafe-flsqrt
unsafe-flexpt
unsafe-make-flrectangular
unsafe-flreal-part
unsafe-flimag-part
unsafe-fx->fl
unsafe-fl->fx
unsafe-flrandom
17.2`` Unsafe Character Operations
unsafe-char=?
unsafe-char<?
unsafe-char>?
unsafe-char<=?
unsafe-char>=?
unsafe-char->integer
17.3`` Unsafe Data Extraction
unsafe-car
unsafe-cdr
unsafe-mcar
unsafe-mcdr
unsafe-set-mcar!
unsafe-set-mcdr!
unsafe-cons-list
unsafe-list-ref
unsafe-list-tail
unsafe-unbox
unsafe-set-box!
unsafe-unbox*
unsafe-set-box*!
unsafe-box*-cas!
unsafe-vector-length
unsafe-vector-ref
unsafe-vector-set!
unsafe-vector*-length
unsafe-vector*-ref
unsafe-vector*-set!
unsafe-vector*-cas!
unsafe-string-length
unsafe-string-ref
unsafe-string-set!
unsafe-bytes-length
unsafe-bytes-ref
unsafe-bytes-set!
unsafe-fxvector-length
unsafe-fxvector-ref
unsafe-fxvector-set!
unsafe-flvector-length
unsafe-flvector-ref
unsafe-flvector-set!
unsafe-f64vector-ref
unsafe-f64vector-set!
unsafe-s16vector-ref
unsafe-s16vector-set!
unsafe-u16vector-ref
unsafe-u16vector-set!
unsafe-struct-ref
unsafe-struct-set!
unsafe-struct*-ref
unsafe-struct*-set!
unsafe-struct*-cas!
unsafe-mutable-hash-iterate-first
unsafe-mutable-hash-iterate-next
unsafe-mutable-hash-iterate-key
unsafe-mutable-hash-iterate-value
unsafe-mutable-hash-iterate-key+ value
unsafe-mutable-hash-iterate-pair
unsafe-immutable-hash-iterate-first
unsafe-immutable-hash-iterate-next
unsafe-immutable-hash-iterate-key
unsafe-immutable-hash-iterate-value
unsafe-immutable-hash-iterate-key+ value
unsafe-immutable-hash-iterate-pair
unsafe-weak-hash-iterate-first
unsafe-weak-hash-iterate-next
unsafe-weak-hash-iterate-key
unsafe-weak-hash-iterate-value
unsafe-weak-hash-iterate-key+ value
unsafe-weak-hash-iterate-pair
17.4`` Unsafe Extflonum Operations
unsafe-extfl+
unsafe-extfl-
unsafe-extfl*
unsafe-extfl/
unsafe-extflabs
unsafe-extfl=
unsafe-extfl<
unsafe-extfl>
unsafe-extfl<=
unsafe-extfl>=
unsafe-extflmin
unsafe-extflmax
unsafe-extflround
unsafe-extflfloor
unsafe-extflceiling
unsafe-extfltruncate
unsafe-extflsin
unsafe-extflcos
unsafe-extfltan
unsafe-extflasin
unsafe-extflacos
unsafe-extflatan
unsafe-extfllog
unsafe-extflexp
unsafe-extflsqrt
unsafe-extflexpt
unsafe-fx->extfl
unsafe-extfl->fx
unsafe-extflvector-length
unsafe-extflvector-ref
unsafe-extflvector-set!
17.5`` Unsafe Impersonators and Chaperones
unsafe-impersonate-procedure
unsafe-chaperone-procedure
unsafe-impersonate-vector
unsafe-chaperone-vector
17.6`` Unsafe Undefined
unsafe-undefined
check-not-unsafe-undefined
check-not-unsafe-undefined/ assign
chaperone-struct-unsafe-undefined
prop: chaperone-unsafe-undefined

top ← prev up next →

### 17`` Unsafe Operations

(require racket/unsafe/ops) | package: base

All functions and forms provided by racket/base and racket check their arguments to ensure that the arguments conform to contracts and other constraints. For example, vector-ref checks its arguments to ensure that the first argument is a vector, that the second argument is an exact integer, and that the second argument is between 0 and one less than the vector’s length, inclusive.

Functions provided by racket/unsafe/ops are unsafe. They have certain constraints, but the constraints are not checked, which allows the system to generate and execute faster code. If arguments violate an unsafe function’s constraints, the function’s behavior and result is unpredictable, and the entire system can crash or become corrupted.

All of the exported bindings of racket/unsafe/ops are protected in the sense of protect-out, so access to unsafe operations can be prevented by adjusting the code inspector (see Code Inspectors).

#### 17.1`` Unsafe Numeric Operations

> procedure (unsafe-fx+ a ...) → fixnum?
> a : fixnum?
> procedure (unsafe-fx- a b ...) → fixnum?
> a : fixnum?
> b : fixnum?
> procedure (unsafe-fx* a ...) → fixnum?
> a : fixnum?
> procedure (unsafe-fxquotient a b) → fixnum?
> a : fixnum?
> b : fixnum?
> procedure (unsafe-fxremainder a b) → fixnum?
> a : fixnum?
> b : fixnum?
> procedure (unsafe-fxmodulo a b) → fixnum?
> a : fixnum?
> b : fixnum?
> procedure (unsafe-fxabs a) → fixnum?
> a : fixnum?

For fixnums: Like +, -, *, quotient, remainder, modulo, and abs, but constrained to consume fixnums and produce a fixnum result. The mathematical operation on a and b must be representable as a fixnum. In the case of unsafe-fxquotient, unsafe-fxremainder, and unsafe-fxmodulo, b must not be 0.

Changed in version 7.0.0.13 of package base: Allow zero or more arguments for unsafe-fx+ and unsafe-fx* and allow one or more arguments for unsafe-fx-.

> procedure (unsafe-fxand a ...) → fixnum?
> a : fixnum?
> procedure (unsafe-fxior a ...) → fixnum?
> a : fixnum?
> procedure (unsafe-fxxor a ...) → fixnum?
> a : fixnum?
> procedure (unsafe-fxnot a) → fixnum?
> a : fixnum?
> procedure (unsafe-fxlshift a b) → fixnum?
> a : fixnum?
> b : fixnum?
> procedure (unsafe-fxrshift a b) → fixnum?
> a : fixnum?
> b : fixnum?

For fixnums: Like bitwise-and, bitwise-ior, bitwise-xor, bitwise-not, and arithmetic-shift, but constrained to consume fixnums; the result is always a fixnum. The unsafe-fxlshift and unsafe-fxrshift operations correspond to arithmetic-shift, but require non-negative arguments; unsafe-fxlshift is a positive (i.e., left) shift, and unsafe-fxrshift is a negative (i.e., right) shift, where the number of bits to shift must be no more than the number of bits used to represent a fixnum. In the case of unsafe-fxlshift, bits in the result beyond the number of bits used to represent a fixnum are effectively replaced with a copy of the high bit.

Changed in version 7.0.0.13 of package base: Allow zero or more arguments for unsafe-fxand, unsafe-fxior, and unsafe-fxxor.

> procedure (unsafe-fx= a b ...) → boolean?
> a : fixnum?
> b : fixnum?
> procedure (unsafe-fx< a b ...) → boolean?
> a : fixnum?
> b : fixnum?
> procedure (unsafe-fx> a b ...) → boolean?
> a : fixnum?
> b : fixnum?
> procedure (unsafe-fx<= a b ...) → boolean?
> a : fixnum?
> b : fixnum?
> procedure (unsafe-fx>= a b ...) → boolean?
> a : fixnum?
> b : fixnum?
> procedure (unsafe-fxmin a b ...) → fixnum?
> a : fixnum?
> b : fixnum?
> procedure (unsafe-fxmax a b ...) → fixnum?
> a : fixnum?
> b : fixnum?

For fixnums: Like =, <, >, <=, >=, min, and max, but constrained to consume fixnums.

Changed in version 7.0.0.13 of package base: Allow one or more argument, instead of allowing just two.

> procedure (unsafe-fl+ a ...) → flonum?
> a : flonum?
> procedure (unsafe-fl- a b ...) → flonum?
> a : flonum?
> b : flonum?
> procedure (unsafe-fl* a ...) → flonum?
> a : flonum?
> procedure (unsafe-fl/ a b ...) → flonum?
> a : flonum?
> b : flonum?
> procedure (unsafe-flabs a) → flonum?
> a : flonum?

For flonums: Unchecked versions of fl+, fl-, fl*, fl/, and flabs.

Changed in version 7.0.0.13 of package base: Allow zero or more arguments for unsafe-fl+ and unsafe-fl* and one or more arguments for unsafe-fl- and unsafe-fl/.

> procedure (unsafe-fl= a b ...) → boolean?
> a : flonum?
> b : flonum?
> procedure (unsafe-fl< a b ...) → boolean?
> a : flonum?
> b : flonum?
> procedure (unsafe-fl> a b ...) → boolean?
> a : flonum?
> b : flonum?
> procedure (unsafe-fl<= a b ...) → boolean?
> a : flonum?
> b : flonum?
> procedure (unsafe-fl>= a b ...) → boolean?
> a : flonum?
> b : flonum?
> procedure (unsafe-flmin a b ...) → flonum?
> a : flonum?
> b : flonum?
> procedure (unsafe-flmax a b ...) → flonum?
> a : flonum?
> b : flonum?

For flonums: Unchecked versions of fl=, fl<, fl>, fl<=, fl>=, flmin, and flmax.

Changed in version 7.0.0.13 of package base: Allow one or more argument, instead of allowing just two.

> procedure (unsafe-flround a) → flonum?
> a : flonum?
> procedure (unsafe-flfloor a) → flonum?
> a : flonum?
> procedure (unsafe-flceiling a) → flonum?
> a : flonum?
> procedure (unsafe-fltruncate a) → flonum?
> a : flonum?

For flonums: Unchecked (potentially) versions of flround, flfloor, flceiling, and fltruncate. Currently, these bindings are simply aliases for the corresponding safe bindings.

> procedure (unsafe-flsin a) → flonum?
> a : flonum?
> procedure (unsafe-flcos a) → flonum?
> a : flonum?
> procedure (unsafe-fltan a) → flonum?
> a : flonum?
> procedure (unsafe-flasin a) → flonum?
> a : flonum?
> procedure (unsafe-flacos a) → flonum?
> a : flonum?
> procedure (unsafe-flatan a) → flonum?
> a : flonum?
> procedure (unsafe-fllog a) → flonum?
> a : flonum?
> procedure (unsafe-flexp a) → flonum?
> a : flonum?
> procedure (unsafe-flsqrt a) → flonum?
> a : flonum?
> procedure (unsafe-flexpt a b) → flonum?
> a : flonum?
> b : flonum?

For flonums: Unchecked (potentially) versions of flsin, flcos, fltan, flasin, flacos, flatan, fllog, flexp, flsqrt, and flexpt. Currently, some of these bindings are simply aliases for the corresponding safe bindings.

> procedure (unsafe-make-flrectangular a b)
> | → |  |
> (and/c complex?
> (lambda (c) (flonum? (real-part c)))
> (lambda (c) (flonum? (imag-part c))))
> a : flonum?
> b : flonum?
> procedure (unsafe-flreal-part a) → flonum?
> | a |  | : |  |
> (and/c complex?
> (lambda (c) (flonum? (real-part c)))
> (lambda (c) (flonum? (imag-part c))))
> procedure (unsafe-flimag-part a) → flonum?
> | a |  | : |  |
> (and/c complex?
> (lambda (c) (flonum? (real-part c)))
> (lambda (c) (flonum? (imag-part c))))

For flonums: Unchecked versions of make-flrectangular, flreal-part, and flimag-part.

> procedure (unsafe-fx->fl a) → flonum?
> a : fixnum?
> procedure (unsafe-fl->fx a) → fixnum?
> a : flonum?

Unchecked conversion of a fixnum to an integer flonum and vice versa. These are similar to the safe bindings ->fl and fl->exact-integer, but further constrained to consume or produce a fixnum.

> procedure (unsafe-flrandom rand-gen) → (and flonum? (>/c 0) (</c 1))
> rand-gen : pseudo-random-generator?

Unchecked version of flrandom.

#### 17.2`` Unsafe Character Operations

> procedure (unsafe-char=? a b ...) → boolean?
> a : char?
> b : char?
> procedure (unsafe-char<? a b ...) → boolean?
> a : char?
> b : char?
> procedure (unsafe-char>? a b ...) → boolean?
> a : char?
> b : char?
> procedure (unsafe-char<=? a b ...) → boolean?
> a : char?
> b : char?
> procedure (unsafe-char>=? a b ...) → boolean?
> a : char?
> b : char?
> procedure (unsafe-char->integer a) → fixnum?
> a : char?

Unchecked versions of char=?, char<?, char>?, char<=?, char>=?, and char->integer.

Added in version 7.0.0.14 of package base.

#### 17.3`` Unsafe Data Extraction

> procedure (unsafe-car p) → any/c
> p : pair?
> procedure (unsafe-cdr p) → any/c
> p : pair?
> procedure (unsafe-mcar p) → any/c
> p : mpair?
> procedure (unsafe-mcdr p) → any/c
> p : mpair?
> procedure (unsafe-set-mcar! p v) → void?
> p : mpair?
> v : any/c
> procedure (unsafe-set-mcdr! p v) → void?
> p : mpair?
> v : any/c

Unsafe variants of car, cdr, mcar, mcdr, set-mcar!, and set-mcdr!.

> procedure (unsafe-cons-list v rest) → (and/c pair? list?)
> v : any/c
> rest : list?

Unsafe variant of cons that produces a pair that claims to be a list—without checking whether rest is a list.

> procedure (unsafe-list-ref lst pos) → any/c
> lst : pair?
> pos : (and/c exact-nonnegative-integer? fixnum?)
> procedure (unsafe-list-tail lst pos) → any/c
> lst : any/c
> pos : (and/c exact-nonnegative-integer? fixnum?)

Unsafe variants of list-ref and list-tail, where pos must be a fixnum, and lst must start with at least (add1 pos) (for unsafe-list-ref) or pos (for unsafe-list-tail) pairs.

> procedure (unsafe-unbox b) → fixnum?
> b : box?
> procedure (unsafe-set-box! b k) → void?
> b : box?
> k : fixnum?
> procedure (unsafe-unbox* v) → any/c
> v : (and/c box? (not/c impersonator?))
> procedure (unsafe-set-box*! v val) → void?
> v : (and/c box? (not/c impersonator?))
> val : any/c

Unsafe versions of unbox and set-box!, where the box* variants can be faster but do not work on impersonators.

> procedure (unsafe-box*-cas! loc old new) → boolean?
> loc : box?
> old : any/c
> new : any/c

Unsafe version of box-cas!. Like unsafe-set-box*!, it does not work on impersonators.

> procedure (unsafe-vector-length v) → fixnum?
> v : vector?
> procedure (unsafe-vector-ref v k) → any/c
> v : vector?
> k : fixnum?
> procedure (unsafe-vector-set! v k val) → void?
> v : vector?
> k : fixnum?
> val : any/c
> procedure (unsafe-vector*-length v) → fixnum?
> v : (and/c vector? (not/c impersonator?))
> procedure (unsafe-vector*-ref v k) → any/c
> v : (and/c vector? (not/c impersonator?))
> k : fixnum?
> procedure (unsafe-vector*-set! v k val) → void?
> v : (and/c vector? (not/c impersonator?))
> k : fixnum?
> val : any/c
> procedure (unsafe-vector*-cas! v k old-val new-val) → boolean?
> v : (and/c vector? (not/c impersonator?))
> k : fixnum?
> old-val : any/c
> new-val : any/c

Unsafe versions of vector-length, vector-ref, vector-set!, and vector-cas!, where the vector* variants can be faster but do not work on impersonators.

A vector’s size can never be larger than a fixnum, so even vector-length always returns a fixnum.

Changed in version 6.11.0.2 of package base: Added unsafe-vector*-cas!.

> procedure (unsafe-string-length str) → fixnum?
> str : string?
> procedure (unsafe-string-ref str k)
> → (and/c char? (lambda (ch) (<= 0 (char->integer ch) 255)))
> str : string?
> k : fixnum?
> procedure (unsafe-string-set! str k ch) → void?
> str : (and/c string? (not/c immutable?))
> k : fixnum?
> ch : char?

Unsafe versions of string-length, string-ref, and string-set!. The unsafe-string-ref procedure can be used only when the result will be a Latin-1 character. A string’s size can never be larger than a fixnum (so even string-length always returns a fixnum).

> procedure (unsafe-bytes-length bstr) → fixnum?
> bstr : bytes?
> procedure (unsafe-bytes-ref bstr k) → byte?
> bstr : bytes?
> k : fixnum?
> procedure (unsafe-bytes-set! bstr k b) → void?
> bstr : (and/c bytes? (not/c immutable?))
> k : fixnum?
> b : byte?

Unsafe versions of bytes-length, bytes-ref, and bytes-set!. A bytes’s size can never be larger than a fixnum (so even bytes-length always returns a fixnum).

> procedure (unsafe-fxvector-length v) → fixnum?
> v : fxvector?
> procedure (unsafe-fxvector-ref v k) → fixnum?
> v : fxvector?
> k : fixnum?
> procedure (unsafe-fxvector-set! v k x) → void?
> v : fxvector?
> k : fixnum?
> x : fixnum?

Unsafe versions of fxvector-length, fxvector-ref, and fxvector-set!. A fxvector’s size can never be larger than a fixnum (so even fxvector-length always returns a fixnum).

> procedure (unsafe-flvector-length v) → fixnum?
> v : flvector?
> procedure (unsafe-flvector-ref v k) → flonum?
> v : flvector?
> k : fixnum?
> procedure (unsafe-flvector-set! v k x) → void?
> v : flvector?
> k : fixnum?
> x : flonum?

Unsafe versions of flvector-length, flvector-ref, and flvector-set!. A flvector’s size can never be larger than a fixnum (so even flvector-length always returns a fixnum).

> procedure (unsafe-f64vector-ref vec k) → flonum?
> vec : f64vector?
> k : fixnum?
> procedure (unsafe-f64vector-set! vec k n) → void?
> vec : f64vector?
> k : fixnum?
> n : flonum?

Unsafe versions of f64vector-ref and f64vector-set!.

> procedure (unsafe-s16vector-ref vec k) → (integer-in -32768 32767)
> vec : s16vector?
> k : fixnum?
> procedure (unsafe-s16vector-set! vec k n) → void?
> vec : s16vector?
> k : fixnum?
> n : (integer-in -32768 32767)

Unsafe versions of s16vector-ref and s16vector-set!.

> procedure (unsafe-u16vector-ref vec k) → (integer-in 0 65535)
> vec : u16vector?
> k : fixnum?
> procedure (unsafe-u16vector-set! vec k n) → void?
> vec : u16vector?
> k : fixnum?
> n : (integer-in 0 65535)

Unsafe versions of u16vector-ref and u16vector-set!.

> procedure (unsafe-struct-ref v k) → any/c
> v : any/c
> k : fixnum?
> procedure (unsafe-struct-set! v k val) → void?
> v : any/c
> k : fixnum?
> val : any/c
> procedure (unsafe-struct*-ref v k) → any/c
> v : (not/c impersonator?)
> k : fixnum?
> procedure (unsafe-struct*-set! v k val) → void?
> v : (not/c impersonator?)
> k : fixnum?
> val : any/c
> procedure (unsafe-struct*-cas! v k old-val new-val) → boolean?
> v : (not/c impersonator?)
> k : fixnum?
> old-val : any/c
> new-val : any/c

Unsafe field access and update for an instance of a structure type, where the struct* variants can be faster but do not work on impersonators. The index k must be between 0 (inclusive) and the number of fields in the structure (exclusive). In the case of unsafe-struct-set!, unsafe-struct*-set!, and unsafe-struct*-cas!, the field must be mutable. The unsafe-struct*-cas! operation is analogous to box-cas! to perform an atomic compare-and-set.

Changed in version 6.11.0.2 of package base: Added unsafe-struct*-cas!.

> procedure (unsafe-mutable-hash-iterate-first hash) → (or/c #f any/c)
> hash : (and/c hash? (not/c immutable?) (not/c hash-weak?))
> procedure (unsafe-mutable-hash-iterate-next hash pos) → (or/c #f any/c)
> hash : (and/c hash? (not/c immutable?) (not/c hash-weak?))
> pos : any/c
> procedure (unsafe-mutable-hash-iterate-key hash pos) → any/c
> hash : (and/c hash? (not/c immutable?) (not/c hash-weak?))
> pos : any/c
> > procedure
> > (unsafe-mutable-hash-iterate-key |  | hash |  |  |  |
> > |  | pos |  |  |  |
> > |  | bad-index-v) |  | → |  | any/c
> hash : (and/c hash? (not/c immutable?) (not/c hash-weak?))
> pos : any/c
> bad-index-v : any/c
> > procedure
> > (unsafe-mutable-hash-iterate-value |  | hash |  |  |  |
> > |  | pos) |  | → |  | any/c
> hash : (and/c hash? (not/c immutable?) (not/c hash-weak?))
> pos : any/c
> > procedure
> > (unsafe-mutable-hash-iterate-value |  | hash |  |  |  |
> > |  | pos |  |  |  |
> > |  | bad-index-v) |  | → |  | any/c
> hash : (and/c hash? (not/c immutable?) (not/c hash-weak?))
> pos : any/c
> bad-index-v : any/c
> > procedure
> > (unsafe-mutable-hash-iterate-key+value |  | hash |  |  |  |
> > |  | pos) |  | → |  |
> > any/c |  | any/c
> hash : (and/c hash? (not/c immutable?) (not/c hash-weak?))
> pos : any/c
> > procedure
> > (unsafe-mutable-hash-iterate-key+value |  | hash |
> > |  | pos |
> > |  | bad-index-v) |
> | → |  |
> any/c |  | any/c
> hash : (and/c hash? (not/c immutable?) (not/c hash-weak?))
> pos : any/c
> bad-index-v : any/c
> procedure (unsafe-mutable-hash-iterate-pair hash pos) → pair?
> hash : (and/c hash? (not/c immutable?) (not/c hash-weak?))
> pos : any/c
> > procedure
> > (unsafe-mutable-hash-iterate-pair |  | hash |  |  |  |
> > |  | pos |  |  |  |
> > |  | bad-index-v) |  | → |  | pair?
> hash : (and/c hash? (not/c immutable?) (not/c hash-weak?))
> pos : any/c
> bad-index-v : any/c
> procedure (unsafe-immutable-hash-iterate-first hash) → (or/c #f any/c)
> hash : (and/c hash? immutable?)
> > procedure
> > (unsafe-immutable-hash-iterate-next |  | hash |  |  |  |
> > |  | pos) |  | → |  | (or/c #f any/c)
> hash : (and/c hash? immutable?)
> pos : any/c
> > procedure
> > (unsafe-immutable-hash-iterate-key |  | hash |  |  |  |
> > |  | pos) |  | → |  | any/c
> hash : (and/c hash? immutable?)
> pos : any/c
> > procedure
> > (unsafe-immutable-hash-iterate-key |  | hash |  |  |  |
> > |  | pos |  |  |  |
> > |  | bad-index-v) |  | → |  | any/c
> hash : (and/c hash? immutable?)
> pos : any/c
> bad-index-v : any/c
> > procedure
> > (unsafe-immutable-hash-iterate-value |  | hash |  |  |  |
> > |  | pos) |  | → |  | any/c
> hash : (and/c hash? immutable?)
> pos : any/c
> > procedure
> > (unsafe-immutable-hash-iterate-value |  | hash |  |  |  |
> > |  | pos |  |  |  |
> > |  | bad-index-v) |  | → |  | any/c
> hash : (and/c hash? immutable?)
> pos : any/c
> bad-index-v : any/c
> > procedure
> > (unsafe-immutable-hash-iterate-key+value |  | hash |  |  |  |
> > |  | pos) |  | → |  |
> > any/c |  | any/c
> hash : (and/c hash? immutable?)
> pos : any/c
> > procedure
> > (unsafe-immutable-hash-iterate-key+value |  | hash |
> > |  | pos |
> > |  | bad-index-v) |
> | → |  |
> any/c |  | any/c
> hash : (and/c hash? immutable?)
> pos : any/c
> bad-index-v : any/c
> > procedure
> > (unsafe-immutable-hash-iterate-pair |  | hash |  |  |  |
> > |  | pos) |  | → |  | pair?
> hash : (and/c hash? immutable?)
> pos : any/c
> > procedure
> > (unsafe-immutable-hash-iterate-pair |  | hash |  |  |  |
> > |  | pos |  |  |  |
> > |  | bad-index-v) |  | → |  | pair?
> hash : (and/c hash? immutable?)
> pos : any/c
> bad-index-v : any/c
> procedure (unsafe-weak-hash-iterate-first hash) → (or/c #f any/c)
> hash : (and/c hash? hash-weak?)
> procedure (unsafe-weak-hash-iterate-next hash pos) → (or/c #f any/c)
> hash : (and/c hash? hash-weak?)
> pos : any/c
> procedure (unsafe-weak-hash-iterate-key hash pos) → any/c
> hash : (and/c hash? hash-weak?)
> pos : any/c
> > procedure
> > (unsafe-weak-hash-iterate-key |  | hash |  |  |  |
> > |  | pos |  |  |  |
> > |  | bad-index-v) |  | → |  | any/c
> hash : (and/c hash? hash-weak?)
> pos : any/c
> bad-index-v : any/c
> procedure (unsafe-weak-hash-iterate-value hash pos) → any/c
> hash : (and/c hash? hash-weak?)
> pos : any/c
> > procedure
> > (unsafe-weak-hash-iterate-value |  | hash |  |  |  |
> > |  | pos |  |  |  |
> > |  | bad-index-v) |  | → |  | any/c
> hash : (and/c hash? hash-weak?)
> pos : any/c
> bad-index-v : any/c
> > procedure
> > (unsafe-weak-hash-iterate-key+value |  | hash |  |  |  |
> > |  | pos) |  | → |  |
> > any/c |  | any/c
> hash : (and/c hash? hash-weak?)
> pos : any/c
> > procedure
> > (unsafe-weak-hash-iterate-key+value |  | hash |  |  |  |
> > |  | pos |  |  |  |
> > |  | bad-index-v) |  | → |  |
> > any/c |  | any/c
> hash : (and/c hash? hash-weak?)
> pos : any/c
> bad-index-v : any/c
> procedure (unsafe-weak-hash-iterate-pair hash pos) → pair?
> hash : (and/c hash? hash-weak?)
> pos : any/c
> > procedure
> > (unsafe-weak-hash-iterate-pair |  | hash |  |  |  |
> > |  | pos |  |  |  |
> > |  | bad-index-v) |  | → |  | pair?
> hash : (and/c hash? hash-weak?)
> pos : any/c
> bad-index-v : any/c

Unsafe versions of hash-iterate-key and similar procedures. These operations support chaperones and impersonators.

Each unsafe ...-first and ...-next procedure may return, instead of a number index, an internal representation of a view into the hash structure, enabling faster iteration. The result of these ...-first and ...-next functions should be given as pos to the corresponding unsafe accessor functions.

If the pos provided to an accessor function for a mutable hash was formerly a valid hash index but is no longer a valid hash index for hash, and if bad-index-v is not provided, then the exn:fail:contract exception is raised. No behavior is specified for a pos that was never a valid hash index for hash. Note that bad-index-v argument is technically not useful for the unsafe-immutable-hash-iterate- functions, since an index cannot become invalid for an immutable hash.

Added in version 6.4.0.6 of package base.
Changed in version 7.0.0.10: Added the optional bad-index-v argument.

#### 17.4`` Unsafe Extflonum Operations

> procedure (unsafe-extfl+ a b) → extflonum?
> a : extflonum?
> b : extflonum?
> procedure (unsafe-extfl- a b) → extflonum?
> a : extflonum?
> b : extflonum?
> procedure (unsafe-extfl* a b) → extflonum?
> a : extflonum?
> b : extflonum?
> procedure (unsafe-extfl/ a b) → extflonum?
> a : extflonum?
> b : extflonum?
> procedure (unsafe-extflabs a) → extflonum?
> a : extflonum?

Unchecked versions of extfl+, extfl-, extfl*, extfl/, and extflabs.

> procedure (unsafe-extfl= a b) → boolean?
> a : extflonum?
> b : extflonum?
> procedure (unsafe-extfl< a b) → boolean?
> a : extflonum?
> b : extflonum?
> procedure (unsafe-extfl> a b) → boolean?
> a : extflonum?
> b : extflonum?
> procedure (unsafe-extfl<= a b) → boolean?
> a : extflonum?
> b : extflonum?
> procedure (unsafe-extfl>= a b) → boolean?
> a : extflonum?
> b : extflonum?
> procedure (unsafe-extflmin a b) → extflonum?
> a : extflonum?
> b : extflonum?
> procedure (unsafe-extflmax a b) → extflonum?
> a : extflonum?
> b : extflonum?

Unchecked versions of extfl=, extfl<, extfl>, extfl<=, extfl>=, extflmin, and extflmax.

> procedure (unsafe-extflround a) → extflonum?
> a : extflonum?
> procedure (unsafe-extflfloor a) → extflonum?
> a : extflonum?
> procedure (unsafe-extflceiling a) → extflonum?
> a : extflonum?
> procedure (unsafe-extfltruncate a) → extflonum?
> a : extflonum?

Unchecked (potentially) versions of extflround, extflfloor, extflceiling, and extfltruncate. Currently, these bindings are simply aliases for the corresponding safe bindings.

> procedure (unsafe-extflsin a) → extflonum?
> a : extflonum?
> procedure (unsafe-extflcos a) → extflonum?
> a : extflonum?
> procedure (unsafe-extfltan a) → extflonum?
> a : extflonum?
> procedure (unsafe-extflasin a) → extflonum?
> a : extflonum?
> procedure (unsafe-extflacos a) → extflonum?
> a : extflonum?
> procedure (unsafe-extflatan a) → extflonum?
> a : extflonum?
> procedure (unsafe-extfllog a) → extflonum?
> a : extflonum?
> procedure (unsafe-extflexp a) → extflonum?
> a : extflonum?
> procedure (unsafe-extflsqrt a) → extflonum?
> a : extflonum?
> procedure (unsafe-extflexpt a b) → extflonum?
> a : extflonum?
> b : extflonum?

Unchecked (potentially) versions of extflsin, extflcos, extfltan, extflasin, extflacos, extflatan, extfllog, extflexp, extflsqrt, and extflexpt. Currently, some of these bindings are simply aliases for the corresponding safe bindings.

> procedure (unsafe-fx->extfl a) → extflonum?
> a : fixnum?
> procedure (unsafe-extfl->fx a) → fixnum?
> a : extflonum?

Unchecked conversion of a fixnum to an integer extflonum and vice versa. These are similar to the safe bindings ->extfl and extfl->exact-integer, but further constrained to consume or produce a fixnum.

> procedure (unsafe-extflvector-length v) → fixnum?
> v : extflvector?
> procedure (unsafe-extflvector-ref v k) → extflonum?
> v : extflvector?
> k : fixnum?
> procedure (unsafe-extflvector-set! v k x) → void?
> v : extflvector?
> k : fixnum?
> x : extflonum?

Unchecked versions of extflvector-length, extflvector-ref, and extflvector-set!. A extflvector’s size can never be larger than a fixnum (so even extflvector-length always returns a fixnum).

#### 17.5`` Unsafe Impersonators and Chaperones

> > procedure
> > (unsafe-impersonate-procedure |  | proc |
> > |  | replacement-proc |
> > |  | prop |
> > |  | prop-val ... |
> > |  | ...) |
> → (and/c procedure? impersonator?)
> proc : procedure?
> replacement-proc : procedure?
> prop : impersonator-property?
> prop-val : any

Like impersonate-procedure, but assumes that replacement-proc calls proc itself. When the result of unsafe-impersonate-procedure is applied to arguments, the arguments are passed on to replacement-proc directly, ignoring proc. At the same time, impersonator-of? reports #t when given the result of unsafe-impersonate-procedure and proc.

If proc is itself an impersonator that is derived from impersonate-procedure* or chaperone-procedure*, beware that replacement-proc will not be able to call it correctly. Specifically, the impersonator produced by unsafe-impersonate-procedure will not get passed to a wrapper procedure that was supplied to impersonate-procedure* or chaperone-procedure* to generate proc.

Finally, unlike impersonate-procedure, unsafe-impersonate-procedure does not specially handle impersonator-prop:application-mark as a prop.

The unsafety of unsafe-impersonate-procedure is limited to the above differences from impersonate-procedure. The contracts on the arguments of unsafe-impersonate-procedure are checked when the arguments are supplied.

As an example, assuming that f accepts a single argument and is not derived from impersonate-procedure* or chaperone-procedure*, then

> (λ (f)
> (unsafe-impersonate-procedure
> f
> (λ (x)
> (if (number? x)
> (error 'no-numbers!)
> (f x)))))

is equivalent to

> (λ (f)
> (impersonate-procedure
> f
> (λ (x)
> (if (number? x)
> (error 'no-numbers!)
> x))))

Similarly, with the same assumptions about f, the following two procedures wrap-f1 and wrap-f2 are almost equivalent; they differ only in the error message produced when their arguments are functions that return multiple values (and that they update different global variables). The version using unsafe-impersonate-procedure will signal an error in the let expression about multiple return values, whereas the one using impersonate-procedure signals an error from impersonate-procedure about multiple return values.

> (define log1-args '())
> (define log1-results '())
> (define wrap-f1
> (λ (f)
> (impersonate-procedure
> f
> (λ (arg)
> (set! log1-args (cons arg log1-args))
> (values (λ (res)
> (set! log1-results (cons res log1-results))
> res)
> arg)))))
> (define log2-args '())
> (define log2-results '())
> (define wrap-f2
> (λ (f)
> (unsafe-impersonate-procedure
> f
> (λ (arg)
> (set! log2-args (cons arg log2-args))
> (let ([res (f arg)])
> (set! log2-results (cons res log2-results))
> res)))))

Added in version 6.4.0.4 of package base.

> > procedure
> > (unsafe-chaperone-procedure |  | proc |
> > |  | wrapper-proc |
> > |  | prop |
> > |  | prop-val ... |
> > |  | ...) |
> → (and/c procedure? chaperone?)
> proc : procedure?
> wrapper-proc : procedure?
> prop : impersonator-property?
> prop-val : any

Like unsafe-impersonate-procedure, but creates a chaperone. Since wrapper-proc will be called in lieu of proc, wrapper-proc is assumed to return a chaperone of the value that proc would return.

Added in version 6.4.0.4 of package base.

> > procedure
> > (unsafe-impersonate-vector |  | vec |
> > |  | replacement-vec |
> > |  | prop |
> > |  | prop-val ... |
> > |  | ...) |
> → (and/c vector? impersonator?)
> vec : vector?
> replacement-vec : (and/c vector? (not/c impersonator?))
> prop : impersonator-property?
> prop-val : any/c

Like impersonate-vector, but instead of going through interposition procedures, all accesses to the impersonator are dispatched to replacement-vec.

The result of unsafe-impersonate-vector is an impersonator of vec.

Added in version 6.9.0.2 of package base.

> > procedure
> > (unsafe-chaperone-vector |  | vec |
> > |  | replacement-vec |
> > |  | prop |
> > |  | prop-val ... |
> > |  | ...) |
> → (and/c vector? chaperone?)
> vec : vector?
> replacement-vec : (and/c vector? (not/c impersonator?))
> prop : impersonator-property?
> prop-val : any/c

Like unsafe-impersonate-vector, but the result of unsafe-chaperone-vector is a chaperone of vec.

Added in version 6.9.0.2 of package base.

#### 17.6`` Unsafe Undefined

(require racket/unsafe/undefined) | package: base

The bindings documented in this section are provided by the racket/unsafe/undefined library, not racket/base or racket.

The constant unsafe-undefined is used internally as a placeholder value. For example, it is used by letrec as a value for a variable that has not yet been assigned a value. Unlike the undefined value exported by racket/undefined, however, the unsafe-undefined value should not leak as the result of a safe expression, and it should not be passed as an optional argument to a procedure (because it may count as “no value provided”). Expression results that potentially produce unsafe-undefined can be guarded by check-not-unsafe-undefined, so that an exception can be raised instead of producing an undefined value.

The unsafe-undefined value is always eq? to itself.

Added in version 6.0.1.2 of package base.
Changed in version 6.90.0.29: Procedures with optional arguments sometimes use the unsafe-undefined value internally to mean “no argument supplied.”

> value unsafe-undefined : any/c

The unsafe “undefined” constant.

See above for important constraints on the use of unsafe-undefined.

> procedure (check-not-unsafe-undefined v sym)
> → (and/c any/c (not/c (one-of/c unsafe-undefined)))
> v : any/c
> sym : symbol?

Checks whether v is unsafe-undefined, and raises exn:fail:contract:variable in that case with an error message along the lines of “sym: undefined; use before initialization.” If v is not unsafe-undefined, then v is returned.

> procedure (check-not-unsafe-undefined/assign v sym)
> → (and/c any/c (not/c (one-of/c unsafe-undefined)))
> v : any/c
> sym : symbol?

The same as check-not-unsafe-undefined, except that the error message (if any) is along the lines of “sym: undefined; assignment before initialization.”

> procedure (chaperone-struct-unsafe-undefined v) → any/c
> v : any/c

Chaperones v if it is a structure (as viewed through some inspector). Every access of a field in the structure is checked to prevent returning unsafe-undefined. Similarly, every assignment to a field in the structure is checked (unless the check disabled as described below) to prevent assignment of a field whose current value is unsafe-undefined.

When a field access would otherwise produce unsafe-undefined or when a field assignment would replace unsafe-undefined, the exn:fail:contract exception is raised.

The chaperone’s field-assignment check is disabled whenever (continuation-mark-set-first #f prop:chaperone-unsafe-undefined) returns unsafe-undefined. Thus, a field-initializing assignment—one that is intended to replace the unsafe-undefined value of a field—should be wrapped with (with-continuation-mark prop:chaperone-unsafe-undefined unsafe-undefined ....).

> value prop:chaperone-unsafe-undefined : struct-type-property?

A structure type property that causes a structure type’s constructor to produce a chaperone of an instance in the same way as chaperone-struct-unsafe-undefined.

The property value should be a list of symbols used as field names, but the list should be in reverse order of the structure’s fields. When a field access or assignment would produce or replace unsafe-undefined, the exn:fail:contract:variable exception is raised if a field name is provided by the structure property’s value, otherwise the exn:fail:contract exception is raised.

top ← prev up next →