According the R-ints the only current uses of the `truelength` meta datum is
for environment hash tables. Jim Hester just made me aware that R3.4.0
introduces a new use case: growable vectors.
I attach a patch to the R-ints manual that reflects this change. The wording
is obviously just a suggestion. Additionally, it may be worth moving the
footnote into the main body of the document now that there are more use cases.
Best,
Brodie.
Index: doc/manual/R-ints.texi
===================================================================
--- doc/manual/R-ints.texi (revision 76152)
+++ doc/manual/R-ints.texi (working copy)
@@ -366,6 +366,9 @@
Bit 4 is turned on to mark S4 objects.
+Bit 5 for vectors is used to indicate that the vector is overallocated
+and thus may be growable without a new allocation.
+
Bits 1, 2, 3, 5 and 6 are used for a @code{CHARSXP} to denote its
encoding. Bit 1 indicates that the @code{CHARSXP} should be treated as
a set of bytes, not necessarily representing a character in any known
@@ -406,16 +409,19 @@
types are a @code{VECTOR_SEXPREC}, which again consists of the header
and the same three pointers, but followed by two integers giving the
length and `true length'@footnote{This is almost unused. The only
-current use is for hash tables of environments (@code{VECSXP}s), where
+current uses are for hash tables of environments (@code{VECSXP}s), where
@code{length} is the size of the table and @code{truelength} is the
-number of primary slots in use, and for the reference hash tables in
+number of primary slots in use, for the reference hash tables in
serialization (@code{VECSXP}s), where @code{truelength} is the number of
-slots in use.} of the vector, and then followed by the data (aligned as
-required: on most 32-bit systems with a 24-byte @code{VECTOR_SEXPREC}
-node the data can follow immediately after the node). The data are a
-block of memory of the appropriate length to store `true length'
-elements (rounded up to a multiple of 8 bytes, with the 8-byte blocks
-being the `Vcells' referred in the documentation for @code{gc()}).
+slots in use, and for vectors that are over-allocated due to assignment
+past the original length, where @code{length} is the in-use length and
+@code{truelength} is the allocated length.} of the vector, and then
+followed by the data (aligned as required: on most 32-bit systems with a
+24-byte @code{VECTOR_SEXPREC} node the data can follow immediately after
+the node). The data are a block of memory of the appropriate length to
+store `true length' elements (rounded up to a multiple of 8 bytes, with
+the 8-byte blocks being the `Vcells' referred in the documentation for
+@code{gc()}).
The `data' for the various types are given in the table below. A lot of
this is interpretation, i.e.@: the types are not checked.
______________________________________________
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
