5.2 Creating Structure Types (original) (raw)
5.2 Creating Structure Types🔗ℹ
Creates a new structure type, unless inspector is'prefab, in which case make-struct-type accesses aprefab structure type. The name argument is used as the type name. If super-type is not #f, the resulting type is a subtype of the corresponding structure type.
The resulting structure type hasinit-field-cnt+auto-field-cnt fields (in addition to any fields from super-type), but onlyinit-field-cnt constructor arguments (in addition to any constructor arguments from super-type). The remaining fields are initialized with auto-v. The total field count (includingsuper-type fields) must be no more than 32768.
The props argument is a list of pairs, where the carof each pair is a structure type property descriptor, and thecdr is an arbitrary value. A property can be specified multiple times in props (including properties that are automatically added by properties that are directly included inprops) only if the associated values are eq?, otherwise the exn:fail:contract exception is raised. See Structure Type Propertiesfor more information about properties. When inspector is'prefab, then props must be null.
The inspector argument normally controls access to reflective information about the structure type and its instances; seeStructure Inspectors for more information. If inspector is'prefab, then the resulting prefab structure type and its instances are always transparent. If inspector is#f, then the structure type’s instances are transparent.
If proc-spec is an integer or procedure, instances of the structure type act as procedures. See prop:procedure for further information. Providing a non-#f value forproc-spec is the same as pairing the value withprop:procedure at the end of props, plus includingproc-spec in immutables when proc-spec is an integer.
The immutables argument provides a list of field positions. Each element in the list must be unique, otherwiseexn:fail:contract exception is raised. Each element must also fall in the range0 (inclusive) to init-field-cnt (exclusive), otherwiseexn:fail:contract exception is raised.
The guard argument is either a procedure of n+1arguments or #f, where n is the number of arguments for the new structure type’s constructor (i.e.,init-field-cnt plus constructor arguments implied bysuper-type, if any). If guard is a procedure, then the procedure is called whenever an instance of the type is constructed, or whenever an instance of a subtype is created. The arguments to guard are the values provided for the structure’s first n fields, followed by the name of the instantiated structure type (which is name, unless a subtype is instantiated). The guard result must be n values, which become the actual values for the structure’s fields. Theguard can raise an exception to prevent creation of a structure with the given field values. If a structure subtype has its own guard, the subtype guard is applied first, and the first nvalues produced by the subtype’s guard procedure become the firstn arguments to guard. When inspector is'prefab, then guard must be #f.
If constructor-name is not #f, it is used as the name of the generated constructor procedure as returned byobject-name or in the printed form of the constructor value.
The result of make-struct-type is five values:
- a structure type descriptor,
- a constructor procedure,
- a predicate procedure,
- an accessor procedure, which consumes a structure and a field index between 0 (inclusive) andinit-field-cnt+auto-field-cnt (exclusive), and
- a mutator procedure, which consumes a structure, a field index, and a field value.
Examples:
(define-values (struct:a make-a a? a-ref a-set!) (make-struct-type 'a #f 2 1 'uninitialized))(define an-a (make-a 'x 'y)) > (a-ref an-a 1) 'y > (a-ref an-a 2) 'uninitialized > (define a-first (make-struct-field-accessor a-ref 0)) > (a-first an-a) 'x (define-values (struct:b make-b b? b-ref b-set!) (make-struct-type 'b struct:a 1 2 'b-uninitialized))(define a-b (make-b 'x 'y 'z)) > (a-ref a-b 1) 'y > (a-ref a-b 2) 'uninitialized > (b-ref a-b 0) 'z > (b-ref a-b 1) 'b-uninitialized > (b-ref a-b 2) 'b-uninitialized > (make-c 'x 'y 'z) make-c: second field must be a number > (define a-c (make-c 'x 2 'z)) > (a-ref a-c 1) 2.0 > (p? p1) #t > (p-ref p1 0) 'a > (make-p 'x 'y 'z) '#s(p x y z)
Returns a field accessor that is equivalent to (lambda (s) (accessor-proc s field-pos)). The accessor-proc must be an accessor returned by make-struct-type.
The field/proc-name argument determines the name of the resulting procedure for error reporting and debugging purposes. Iffield/proc-name is a symbol and arg-contract-str is not#f, then field/proc-name is used as the procedure name. If field/proc-name is a symbol andarg-contract-str is #f, then field/proc-name is combined with the name of accessor-proc’s structure type to form the procedure name. If field/proc-name is #f, then 'accessor is used as the procedure name.
The arg-contract-str argument determines how the accessor procedure reports an error when it is applied to a value that is not an instance of the accessor-proc’s structure type. If it is a string or symbol, the text of the string or symbol is used as a contract for error reporting. Otherwise, contract text is synthesized from the name of accessor-proc’s structure type.
The realm argument is also used for error reporting. It specifies a realm that an error-message adjuster may use to determine how to adjust an error message. The realm argument also determines the result of procedure-realm for the accessor procedure.
For examples, see make-struct-type.
Changed in version 8.4.0.2 of package base: Added the arg-contract-str and realm arguments.
Returns a field mutator that is equivalent to (lambda (s v) (mutator-proc s field-pos v)). The mutator-proc must be a mutator returned by make-struct-type.
The field-name, arg-contract-str, and realmarguments are used for error and debugging purposes analogous to the same arguments to make-struct-field-accessor.
For examples, see make-struct-type.
Changed in version 8.4.0.2 of package base: Added the arg-contract-str and realm arguments.
A structure type property that declares a structure type assealed. The value associated with the property is ignored; the presence of the property itself makes the structure type sealed.
A sealed structure type cannot be used as the supertype of another structure type. Declaring a structure type as sealed is typically just a performance hint, since checking for an instance of a sealed structure type can be slightly faster than checking for an instance of a structure type that might have subtypes.
Added in version 8.0.0.7 of package base.