▼Unstable
►4 Contracts
On this page:
non-empty-string?
non-empty-list?
non-empty-bytes?
non-empty-vector?
singleton-list?
port-number?
tcp-listen-port?
path-element?
if/ c
failure-result/ c
rename-contract
4.1 Flat Contracts
nat/ c
pos/ c
truth/ c
4.2 Syntax Object Contracts
syntax-datum/ c
syntax-listof/ c
syntax-list/ c
4.3 Higher-Order Contracts
thunk/ c
unary/ c
binary/ c
predicate/ c
predicate-like/ c
comparison/ c
comparison-like/ c
sequence/ c
dict/ c
Version: 5.1
  top← prev  up  next → 

4 Contracts

 (require unstable/contract)

This library is unstable; compatibility will not be maintained. See Unstable for more information.

(non-empty-string? x) → boolean?
  x : any/c
(non-empty-list? x) → boolean?
  x : any/c
(non-empty-bytes? x) → boolean?
  x : any/c
(non-empty-vector? x) → boolean?
  x : any/c
Returns #t if x is of the appropriate data type (string, list, bytes, or vector, respectively) and is not empty; returns #f otherwise.

(singleton-list? x) → boolean?
  x : any/c
Returns #t if x is a list of one element; returns #f otherwise.

port-number? : contract?
Equivalent to (between/c 1 65535).

tcp-listen-port? : contract?
Equivalent to (between/c 0 65535).

path-element? : contract?
Equivalent to (or/c path-string? (symbols 'up 'same)).

The subsequent bindings were added by Ryan Culpepper.

(if/c predicate then-contract else-contract) → contract?
  predicate : (-> any/c any/c)
  then-contract : contract?
  else-contract : contract?
Produces a contract that, when applied to a value, first tests the value with predicate; if predicate returns true, the then-contract is applied; otherwise, the else-contract is applied. The resulting contract is a flat contract if both then-contract and else-contract are flat contracts.

For example, the following contract enforces that if a value is a procedure, it is a thunk; otherwise it can be any (non-procedure) value:
  (if/c procedure? (-> any) any/c)
Note that the following contract is not equivalent:
  (or/c (-> any) any/c) ; wrong!
The last contract is the same as any/c because or/c tries flat contracts before higher-order contracts.

failure-result/c : contract?
A contract that describes the failure result arguments of procedures such as hash-ref.

Equivalent to (if/c procedure? (-> any) any/c).

(rename-contract contract name) → contract?
  contract : contract?
  name : any/c
Produces a contract that acts like contract but with the name name.

The resulting contract is a flat contract if contract is a flat contract.

The subsequent bindings were added by Carl Eastlund <cce@racket-lang.org>.

4.1 Flat Contracts

nat/c : flat-contract?
This contract recognizes natural numbers that satisfy exact-nonnegative-integer?.

pos/c : flat-contract?
This contract recognizes positive integers that satisfy exact-positive-integer?.

truth/c : flat-contract?
This contract recognizes Scheme truth values, i.e., any value, but with a more informative name and description. Use it in negative positions for arguments that accept arbitrary truth values that may not be booleans.

4.2 Syntax Object Contracts

(syntax-datum/c datum/c) → flat-contract?
  datum/c : any/c
Recognizes syntax objects stx such that (syntax->datum stx) satisfies datum/c.

(syntax-listof/c elem/c) → flat-contract?
  elem/c : any/c
Recognizes syntax objects stx such that (syntax->list stx) satisfies (listof elem/c).

(syntax-list/c elem/c ...) → flat-contract?
  elem/c : any/c
Recognizes syntax objects stx such that (syntax->list stx) satisfies (list/c elem/c ...).

4.3 Higher-Order Contracts

thunk/c : contract?
unary/c : contract?
binary/c : contract?
These contracts recognize functions that accept 0, 1, or 2 arguments, respectively, and produce a single result.

predicate/c : contract?
predicate-like/c : contract?
These contracts recognize predicates: functions of a single argument that produce a boolean result.

The first constrains its output to satisfy boolean?. Use predicate/c in positive position for predicates that guarantee a result of #t or #f.

The second constrains its output to satisfy truth/c. Use predicate-like/c in negative position for predicates passed as arguments that may return arbitrary values as truth values.

comparison/c : contract?
comparison-like/c : contract?
These contracts recognize comparisons: functions of two arguments that produce a boolean result.

The first constrains its output to satisfy boolean?. Use comparison/c in positive position for comparisons that guarantee a result of #t or #f.

The second constrains its output to satisfy truth/c. Use comparison-like/c in negative position for comparisons passed as arguments that may return arbitrary values as truth values.

(sequence/c elem/c ...) → contract?
  elem/c : contract?
Wraps a sequence, obligating it to produce as many values as there are elem/c contracts, and obligating each value to satisfy the corresponding elem/c. The result is not guaranteed to be the same kind of sequence as the original value; for instance, a wrapped list is not guaranteed to satisfy list?.

Examples:

  > (define/contract predicates
      (sequence/c (-> any/c boolean?))
      (list integer? string->symbol))
  > (for ([P predicates])
      (printf "~s\n" (P "cat")))

  #f

  self-contract violation: expected <boolean?>, given: 'cat

    contract on predicates from (definition predicates),

  blaming (definition predicates)

    contract:

      (sequence/c (-> any/c boolean?))

    at: eval:3.0

(dict/c key/c value/c) → contract?
  key/c : contract?
  value/c : contract?
Wraps a dictionary, obligating its keys to satisfy key/c and their corresponding values to satisfy value/c. The result is not guaranteed to be the same kind of dictionary as the original value; for instance, a wrapped hash table is not guaranteed to satisfy hash?.

Examples:

  > (define/contract table
      (dict/c symbol? string?)
      (make-immutable-hash (list (cons 'A "A") (cons 'B 2) (cons 3 "C"))))
  > (dict-ref table 'A)

  "A"

  > (dict-ref table 'B)

  self-contract violation: expected <string?>, given: 2

    contract on table from (definition table), blaming

  (definition table)

    contract: (dict/c symbol? string?)

          at: eval:4.0

  > (dict-ref table 3)

  self-contract violation: expected <symbol?>, given: 3

    contract on table from (definition table), blaming

  (definition table)

    contract: (dict/c symbol? string?)

          at: eval:4.0

Warning: Bear in mind that key and value contracts are re-wrapped on every dictionary operation, and dictionaries wrapped in dict/c multiple times will perform the checks as many times for each operation. Especially for immutable dictionaries (which may be passed through a constructor that involves dict/c on each update), contract-wrapped dictionaries may be much less efficient than the original dictionaries.

  top← prev  up  next →