5.3 Structure Type Properties

► |  | 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

▼ | 5 | Structures

5.1 | Defining Structure Types: struct
5.2 | Creating Structure Types
5.3 | Structure Type Properties
5.4 | Generic Interfaces
5.5 | Copying and Updating Structures
5.6 | Structure Utilities
5.7 | Structure Type Transformer Binding

On this page:

make-struct-type-property
struct-type-property?
struct-type-property-accessor-procedure?
struct-type-property-predicate-procedure?

top contents ← prev up next →

#### 5.3`` Structure Type Properties🔗ℹ

> > > Generic Interfaces provide a high-level API on top of structure type properties.

A structure type property allows per-type information to be associated with a structure type (as opposed to per-instance information associated with a structure value). A property value is associated with a structure type through the make-struct-type procedure (see Creating Structure Types) or through the #:property option of struct. Subtypes inherit the property values of their parent types, and subtypes can override an inherited property value with a new value.

> > procedure
> > (make-struct-type-property |  | name |
> > | [ | guard |
> > |  | supers |
> > |  | can-impersonate? |
> > |  | accessor-name |
> > |  | contract-str |
> > |  | realm]) |
> | → |  |
> struct-type-property?
> (any/c . -> . boolean?)
> procedure?
> name : symbol?
> guard : (or/c procedure? #f 'can-impersonate) = #f
> | supers |  | : |  |
> (listof (cons/c struct-type-property?
> (any/c . -> . any/c)))
> |  | = |  | null
> can-impersonate? : any/c = #f
> accessor-name : (or/c symbol? #f) = #f
> contract-str : (or/c string? symbol? #f) = #f
> realm : symbol? = 'racket

Creates a new structure type property and returns three values:

- a structure type property descriptor, for use with make-struct-type and struct;

- a property predicate procedure, which takes an arbitrary value and returns #t if the value is a descriptor or instance of a structure type that has a value for the property, #f otherwise;

- a property accessor procedure, which returns the value associated with the structure type given its descriptor or one of its instances; if the structure type does not have a value for the property, or if any other kind of value is provided, the exn:fail:contract exception is raised unless a second argument, failure-result, is supplied to the procedure. In that case, if failure-result is a procedure, it is called (through a tail call) with no arguments to produce the result of the property accessor procedure; otherwise, failure-result is itself returned as the result.

If the optional guard is supplied as a procedure, it is called by make-struct-type before attaching the property to a new structure type. The guard must accept two arguments: a value for the property supplied to make-struct-type, and a list containing information about the new structure type. The list contains the values that struct-type-info would return for the new structure type if it skipped the current-inspector control checks.

The result of calling guard is associated with the property in the target structure type, instead of the value supplied to make-struct-type. To reject a property association (e.g., because the value supplied to make-struct-type is inappropriate for the property), the guard can raise an exception. Such an exception prevents make-struct-type from returning a structure type descriptor.

If guard is 'can-impersonate, then the property’s accessor can be redirected through impersonate-struct. This option is identical to supplying #t as the can-impersonate? argument and is provided for backwards compatibility.

The optional supers argument is a list of properties that are automatically associated with some structure type when the newly created property is associated to the structure type. Each property in supers is paired with a procedure that receives the value supplied for the new property (after it is processed by guard) and returns a value for the associated property (which is then sent to that property’s guard, of any).

The optional can-impersonate? argument determines if the structure type property can be redirected through impersonate-struct. If the argument is #f, then redirection is not allowed. Otherwise, the property accessor may be redirected by a struct impersonator.

The optional accessor-name argument supplies a name (in the sense of object-name) to use for the returned accessor function. If accessor-name is #f, a name is created by adding -accessor to the end of name.

The optional contract-str argument supplies a contract that is included in an error message with the returned accessor is applied to a value that is not an instance of the property (and where a failure-result argument is not supplied to the accessor). If contract-str is #f, a contract is created by adding ? to the end of name.

The optional realm argument supplies a realm (in the sense of procedure-realm) to associate with the returned accessor.

Examples:

> > (define-values (prop:p p? p-ref) (make-struct-type-property 'p))
> > (define-values (struct:a make-a a? a-ref a-set!)
> (make-struct-type 'a #f 2 1 'uninitialized
> (list (cons prop:p 8))))
> > (p? struct:a)
> #t
> > (p? 13)
> #f
> > (define an-a (make-a 'x 'y))
> > (p? an-a)
> #t
> > (p-ref an-a)
> 8
> > (define-values (struct:b make-b b? b-ref b-set!)
> (make-struct-type 'b #f 0 0 #f))
> > (p? struct:b)
> #f
> > (define-values (prop:q q? q-ref) (make-struct-type-property
> 'q (lambda (v si) (add1 v))
> (list (cons prop:p sqrt))))
> > (define-values (struct:c make-c c? c-ref c-set!)
> (make-struct-type 'c #f 0 0 'uninit
> (list (cons prop:q 8))))
> > (q-ref struct:c)
> 9
> > (p-ref struct:c)
> 3

Changed in version 7.0 of package base: The CS implementation of Racket skips the inspector check for exposing an ancestor structure type, if any, in information provided to a guard procedure.
Changed in version 8.4.0.2: Added the accessor-name, contract-str, and realm arguments.
Changed in version 8.5.0.2: Changed the BC implementation of Racket to skip the inspector check, the same as the CS implementation, for ancestor information provided to a guard procedure.

> procedure (struct-type-property? v) → boolean?
> v : any/c

Returns #t if v is a structure type property descriptor value, #f otherwise.

> procedure (struct-type-property-accessor-procedure? v) → boolean?
> v : any/c

Returns #t if v is an accessor procedure produced by make-struct-type-property, #f otherwise.

> > procedure
> > (struct-type-property-predicate-procedure? |  | v |  |  |  |
> > | [ | prop]) |  | → |  | boolean?
> v : any/c
> prop : (or/c struct-type-property? #f) = #f

Returns #t if v is a predicate procedure produced by make-struct-type-property and either prop is #f or it was produced by the same call to make-struct-type-property, #f otherwise.

Added in version 7.5.0.11 of package base.

top contents ← prev up next →