►The Racket Reference
▼5 Structures
►5.6 Structure Utilities
On this page:
struct->vector
struct?
struct-type?
struct-constructor-procedure?
struct-predicate-procedure?
struct-accessor-procedure?
struct-mutator-procedure?
prefab-struct-key
make-prefab-struct
prefab-key->struct-type
prefab-key?
5.6.1 Additional Structure Utilities
make-constructor-style-printer
struct->list
  top  ← prev  up  next → 

5.6 Structure Utilities

procedure

(struct->vector v [opaque-v]) → vector?

  v : any/c
  opaque-v : any/c = '...
Creates a vector representing v. The first slot of the result vector contains a symbol whose printed name has the form struct:id. Each remaining slot contains either the value of a field in v, if it is accessible via the current inspector, or opaque-v for a field that is not accessible. A single opaque-v value is used in the vector for contiguous inaccessible fields. (Consequently, the size of the vector does not match the size of the struct if more than one field is inaccessible.)

procedure

(struct? v) → any

  v : any/c
Returns #t if struct-info exposes any structure types of v with the current inspector, #f otherwise.

Typically, when (struct? v) is true, then (struct->vector v) exposes at least one field value. It is possible, however, for the only visible types of v to contribute zero fields.

procedure

(struct-type? v) → boolean?

  v : any/c
Returns #t if v is a structure type descriptor value, #f otherwise.

procedure

(struct-constructor-procedure? v) → boolean?

  v : any/c
Returns #t if v is a constructor procedure generated by struct or make-struct-type, #f otherwise.

procedure

(struct-predicate-procedure? v) → boolean?

  v : any/c
Returns #t if v is a predicate procedure generated by struct or make-struct-type, #f otherwise.

procedure

(struct-accessor-procedure? v) → boolean?

  v : any/c
Returns #t if v is an accessor procedure generated by struct, make-struct-type, or make-struct-field-accessor, #f otherwise.

procedure

(struct-mutator-procedure? v) → boolean?

  v : any/c
Returns #t if v is a mutator procedure generated by struct, make-struct-type, or make-struct-field-mutator, #f otherwise.

procedure

(prefab-struct-key v) → (or/c #f symbol? list?)

  v : any/c
Returns #f if v is not an instance of a prefab structure type. Otherwise, the result is the shorted key that could be used with make-prefab-struct to create an instance of the structure type.

Examples:
> (prefab-struct-key #s(cat "Garfield"))

'cat

> (struct cat (name) #:prefab)
> (struct cute-cat cat (shipping-dest) #:prefab)
> (cute-cat "Nermel" "Abu Dhabi")

'#s((cute-cat cat 1) "Nermel" "Abu Dhabi")

> (prefab-struct-key (cute-cat "Nermel" "Abu Dhabi"))

'(cute-cat cat 1)

procedure

(make-prefab-struct key v ...) → struct?

  key : prefab-key?
  v : any/c
Creates an instance of a prefab structure type, using the vs as field values. The key and the number of vs determine the prefab structure type.

A key identifies a structure type based on a list with the following items:

An empty vector and an auto-field list that starts with 0 can be omitted. Furthermore, the first integer (which indicates the number of non-automatic fields) can be omitted, since it can be inferred from the number of supplied vs. Finally, a single symbol can be used instead of a list that contains only a symbol (in the case that the structure type has no supertype, no automatic fields, and no mutable fields).

The total field count must be no more than 32768. If the number of fields indicated by key is inconsistent with the number of supplied vs, the exn:fail:contract exception is raised.

Examples:
> (make-prefab-struct 'clown "Binky" "pie")

'#s(clown "Binky" "pie")

> (make-prefab-struct '(clown 2) "Binky" "pie")

'#s(clown "Binky" "pie")

> (make-prefab-struct '(clown 2 (0 #f) #()) "Binky" "pie")

'#s(clown "Binky" "pie")

> (make-prefab-struct '(clown 1 (1 #f) #()) "Binky" "pie")

'#s((clown (1 #f)) "Binky" "pie")

> (make-prefab-struct '(clown 1 (1 #f) #(0)) "Binky" "pie")

'#s((clown (1 #f) #(0)) "Binky" "pie")

procedure

(prefab-key->struct-type key field-count) → struct-type?

  key : prefab-key?
  field-count : (integer-in 0 32768)
Returns a structure type descriptor for the prefab structure type specified by the combination of key and field-count.

If the number of fields indicated by key is inconsistent with field-count, the exn:fail:contract exception is raised.

procedure

(prefab-key? v) → boolean?

  v : any/c
Return #t if v can be a prefab structure type key, #f otherwise.

See make-prefab-struct for a description of valid key shapes.

5.6.1 Additional Structure Utilities

 (require racket/struct) package: base
The bindings documented in this section are provided by the racket/struct library, not racket/base or racket.

procedure

(make-constructor-style-printer get-constructor 
  get-contents) 
 → (-> any/c output-port? (or/c #t #f 0 1) void?)
  get-constructor : (-> any/c (or/c symbol? string?))
  get-contents : (-> any/c sequence?)
Produces a function suitable as a value for gen:custom-write or prop:custom-write. The function prints values in “constructor style.” When the value is printed as an expression, it is shown as an application of the constructor (as returned by get-constructor) to the contents (as returned by get-contents). When given to write, it is shown as an unreadable value with the constructor separated from the contents by a colon.

Examples:
> (struct point (x y)
    #:methods gen:custom-write
    [(define write-proc
       (make-constructor-style-printer
        (lambda (obj) 'point)
        (lambda (obj) (list (point-x obj) (point-y obj)))))])
> (print (point 1 2))

(point 1 2)

> (write (point 1 2))

#<point: 1 2>

The function also cooperates with pretty-print:

> (parameterize ((pretty-print-columns 10))
    (pretty-print (point 3000000 4000000)))

(point

 3000000

 4000000)

> (parameterize ((pretty-print-columns 10))
    (pretty-write (point 3000000 4000000)))

#<point:

 3000000

 4000000>

Note that the printer uses a separate property, prop:custom-print-quotable, to determine whether a struct instance is quotable. If so, the printer may print it in write mode it in certain contexts, such as within a list. For example:
> (print (list (point 1 2) (point 3 4)))

'(#<point: 1 2> #<point: 3 4>)

Use #:property prop:custom-print-quotable 'never to prevent a struct instance from being considered quotable. For example:
> (struct point2 (x y)
    #:property prop:custom-print-quotable 'never
    #:methods gen:custom-write
    [(define write-proc
       (make-constructor-style-printer
        (lambda (obj) 'point)
        (lambda (obj) (list (point2-x obj) (point2-y obj)))))])
> (print (list (point2 1 2) (point2 3 4)))

(list (point 1 2) (point 3 4))

Keyword arguments can be simulated with unquoted-printing-string:

; Private implementation
> (struct kwpoint-impl (x y)
    #:methods gen:custom-write
    [(define write-proc
       (make-constructor-style-printer
        (lambda (obj) 'kwpoint)
        (lambda (obj)
          (list (unquoted-printing-string "#:x")
                (kwpoint-impl-x obj)
                (unquoted-printing-string "#:y")
                (kwpoint-impl-y obj)))))])
; Public ``constructor''
> (define (kwpoint #:x x #:y y)
    (kwpoint-impl x y))
; Example use
> (print (kwpoint #:x 1 #:y 2))

(kwpoint #:x 1 #:y 2)

> (write (kwpoint #:x 3 #:y 4))

#<kwpoint: #:x 3 #:y 4>

Added in version 6.3 of package base.

procedure

(struct->list v [#:on-opaque on-opaque]) → (or/c list? #f)

  v : any/c
  on-opaque : (or/c 'error 'return-false 'skip) = 'error
Returns a list containing the struct instance v’s fields. Unlike struct->vector, the struct name itself is not included.

If any fields of v are inaccessible via the current inspector the behavior of struct->list is determined by on-opaque. If on-opaque is 'error (the default), an error is raised. If it is 'return-false, struct->list returns #f. If it is 'skip, the inaccessible fields are omitted from the list.

Examples:
> (struct open (u v) #:transparent)
> (struct->list (open 'a 'b))

'(a b)

> (struct->list #s(pre 1 2 3))

'(1 2 3)

> (struct secret open (x y))
> (struct->list (secret 0 1 17 22))

struct->list: expected argument of type <non-opaque struct>;

given: (secret 0 1 ...)

> (struct->list (secret 0 1 17 22) #:on-opaque 'return-false)

#f

> (struct->list (secret 0 1 17 22) #:on-opaque 'skip)

'(0 1)

> (struct->list 'not-a-struct #:on-opaque 'return-false)

#f

> (struct->list 'not-a-struct #:on-opaque 'skip)

'()

Added in version 6.3 of package base.

  top  ← prev  up  next →