| Title: | ALTREP String Interoperability |
|---|---|
| Description: | Provides infrastructure for interoperable ALTREP character vectors. Producers of ALTREP string classes can register access methods, allowing consumers to read supported character vectors through a common interface without materializing them as ordinary R strings. Also provides 'charvec', a reference ALTREP string implementation backed by stable memory slices, with support for efficient and multithreaded construction. |
| Authors: | Travers Ching [aut, cre, cph], R Consortium [fnd] (Infrastructure Steering Committee grant: Universal ALTREP Interoperability for Strings) |
| Maintainer: | Travers Ching <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.1 |
| Built: | 2026-09-19 06:06:58 UTC |
| Source: | https://github.com/charbase/charport |
Converts a character vector (or anything [as.character()] accepts) to a 'charvec'. If 'x' is already a 'charvec' it is returned unchanged. Names are preserved; other attributes are dropped.
as_charvec(x)as_charvec(x)
x |
object to convert. |
A 'charvec' (an ALTREP character vector).
as_charvec(letters)as_charvec(letters)
Identifies whether a registered ALTREP class claims 'x'. This is a class-membership question answered without touching the vector's data: it never materializes 'x' and reports a match even when the class reader would decline to serve this particular instance (for example, a materialized 'charvec').
charport_class_of(x)charport_class_of(x)
x |
a character vector. |
'"package::class"' for a registered class match when class metadata is available; otherwise 'NA_character_'.
charport_class_of(charvec("a")) charport_class_of(letters)charport_class_of(charvec("a")) charport_class_of(letters)
Reports on the broker's ALTREP class registry. Registered classes are ALTREP character vector classes whose authors registered a reader with charport (via the 'charport_register_altrep_v1' C entry point, fetched with 'R_GetCCallable'). The reference 'charvec' class is registered when 'charport' loads, so a freshly loaded session normally reports at least that class.
charport_classes()charport_classes()
ALTREP class names require an instance to query (R's 'R_altrep_class_name' takes a vector, not a class descriptor), so this registry view reports the count and capability flags; use [charport_class_of()] on a vector to get its registered class name.
A list with elements 'n' (integer: number of registered classes), 'persistent_views' (logical vector: whether returned byte views remain valid until the reader borrow ends), 'concurrent_access' (logical vector: whether reader access calls may run concurrently), and 'reentrant' (logical vector: whether both capabilities are true).
charport_classes()charport_classes()
Reports non-forcing diagnostics for a possible character vector. This is a preflight/development helper: it does not call 'STRING_ELT()', 'STRING_PTR_RO()', 'DATAPTR()', or any registered reader callback.
charport_info(x)charport_info(x)
x |
object to inspect. |
'is_materialized' means ordinary string pointer storage is available without forcing ('DATAPTR_OR_NULL(x) != NULL'). For base R deferred strings, some elements may have been cached by 'STRING_ELT()' while this still reports 'FALSE'; the field is a full-materialization/direct-pointer diagnostic.
A named list containing 'is_strsxp', 'length', 'is_altrep', 'is_materialized', 'is_registered', reader capability flags, 'stateful_reader', 'reentrant', ALTREP class name/package fields, and 'altrep_class' as '"package::class"' when class metadata is available.
charport_info(charvec("a"))charport_info(charvec("a"))
Forces a 'charvec' to materialize its R-level strings ('CHARSXP's), caching them on the object; the native store is released. Ordinary character vectors are returned unchanged. This is a diagnostic/escape hatch: code that needs guaranteed-plain string storage (for example, before handing a vector to C code that bypasses ALTREP accessors) can call it explicitly.
charport_materialize(x)charport_materialize(x)
x |
a character vector (plain or 'charvec'). |
'x', invisibly, after forcing materialization.
x <- charvec("a", "b") charport_materialize(x)x <- charvec("a", "b") charport_materialize(x)
Builds a ‘charvec', charport’s reference ALTREP character vector class, from the given values. A 'charvec' is an ordinary character vector to R code ('typeof(x)' is '"character"'); its strings live as byte views in stable native memory blocks and are only converted to R's interned 'CHARSXP' strings when something forces materialization.
charvec(...)charvec(...)
... |
values to combine, as in [c()]; non-character values are coerced with [as.character()]. |
Element bytes and encoding marks are preserved verbatim. 'charvec' is a storage/reference class, not an encoding-normalization layer; translation policy belongs in consumers built above charport. 'NA_character_' is preserved.
A 'charvec' (an ALTREP character vector).
x <- charvec("hello", "world", NA) is_charvec(x) x[1]x <- charvec("hello", "world", NA) is_charvec(x) x[1]
Test for a charvec
is_charvec(x)is_charvec(x)
x |
object to test. |
'TRUE' if 'x' is a 'charvec' ALTREP vector, 'FALSE' otherwise. Note a materialized 'charvec' is still a 'charvec'; serialization of a materialized 'charvec' round-trips to a plain character vector.
is_charvec(charvec("a")) is_charvec(letters)is_charvec(charvec("a")) is_charvec(letters)