summaryrefslogtreecommitdiff
path: root/doc/ref/api-data.texi
diff options
context:
space:
mode:
authorAndy Wingo <wingo@pobox.com>2017-09-25 21:33:22 +0200
committerAndy Wingo <wingo@pobox.com>2017-09-25 21:54:36 +0200
commita74d4ee4f6e062ff640f2532c9cfc9977bb68a49 (patch)
treef76bf42f2d76b4304cde6dc909a74c152336e4b0 /doc/ref/api-data.texi
parentf23415589a0e263e34a687b5dad1b1624e949639 (diff)
downloadguile-a74d4ee4f6e062ff640f2532c9cfc9977bb68a49.tar.gz
Add struct-ref/unboxed, struct-set!/unboxed
* NEWS: Add news entry. * doc/ref/api-data.texi (Vtables, Structure Basics): Update documentation. * libguile/struct.c (scm_i_struct_equalp): Avoid using struct-ref on unboxed fields. (scm_struct_ref, scm_struct_set_x_unboxed): Issue deprecation warning when accessing unboxed fields. (scm_struct_ref_unboxed, scm_struct_set_x_unboxed): New functions. * libguile/struct.h (scm_struct_ref_unboxed, scm_struct_set_x_unboxed): New functions. * module/oop/goops.scm (class-add-flags!, class-clear-flags!): (class-has-flags?, <class>, %allocate-instance, <slot>): (compute-get-n-set, unboxed-get, unboxed-set, unboxed-slot?): (allocate-slots, %prep-layout!, make-standard-class, initialize): Adapt to access unboxed nfields and flags fields via the new accessors.
Diffstat (limited to 'doc/ref/api-data.texi')
-rw-r--r--doc/ref/api-data.texi25
1 files changed, 19 insertions, 6 deletions
diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi
index e0f8be324..677454bbe 100644
--- a/doc/ref/api-data.texi
+++ b/doc/ref/api-data.texi
@@ -8781,10 +8781,9 @@ it's protected against garbage collection.
@item
@code{u} -- an arbitrary word of data (an @code{scm_t_bits}). At the
-Scheme level it's read and written as an unsigned integer. ``u''
-stands for ``uninterpreted'' (it's not treated as a Scheme value), or
-``unprotected'' (it's not marked during GC), or ``unsigned long'' (its
-size), or all of these things.
+Scheme level it's read and written as an unsigned integer. ``u'' stands
+for ``unboxed'', as it's stored as a raw value without additional type
+annotations.
@end itemize
The second letter for each field is a permission code,
@@ -8802,7 +8801,7 @@ Here are some examples.
@example
(make-vtable "pw") ;; one writable field
(make-vtable "prpw") ;; one read-only and one writable
-(make-vtable "pwuwuw") ;; one scheme and two uninterpreted
+(make-vtable "pwuwuw") ;; one scheme and two unboxed
@end example
The optional @var{print} argument is a function called by
@@ -8840,7 +8839,7 @@ The optional @var{init}@dots{} arguments are initial values for the
fields of the structure. This is the only way to
put values in read-only fields. If there are fewer @var{init}
arguments than fields then the defaults are @code{#f} for a Scheme
-field (type @code{p}) or 0 for an uninterpreted field (type @code{u}).
+field (type @code{p}) or 0 for an unboxed field (type @code{u}).
The name is a bit strange, we admit. The reason for it is that Guile
used to have a @code{make-struct} that took an additional argument;
@@ -8890,6 +8889,20 @@ An error is thrown if @var{n} is out of range, or if the field cannot
be written because it's @code{r} read-only.
@end deffn
+Unboxed fields (those with type @code{u}) need to be accessed with
+special procedures.
+
+@deffn {Scheme Procedure} struct-ref/unboxed struct n
+@deffnx {Scheme Procedure} struct-set!/unboxed struct n value
+@deffnx {C Function} scm_struct_ref_unboxed (struct, n)
+@deffnx {C Function} scm_struct_set_x_unboxed (struct, n, value)
+Like @code{struct-ref} and @code{struct-set!}, except that these may
+only be used on unboxed fields. @code{struct-ref/unboxed} will always
+return a positive integer. Likewise, @code{struct-set!/unboxed} takes
+an unsigned integer as the @var{value} argument, and will signal an
+error otherwise.
+@end deffn
+
@deffn {Scheme Procedure} struct-vtable struct
@deffnx {C Function} scm_struct_vtable (struct)
Return the vtable that describes @var{struct}.