Struct ExternalPtr 

#[repr(C)]
pub struct ExternalPtr<T: TypedExternal> {
    sexp: SEXP,
    cached_ptr: NonNull<RefCell<T>>,
    root: Option<ProtectKey>,
    _marker: PhantomData<T>,
}

An owned pointer stored in R’s external pointer SEXP.

This is conceptually similar to Box<T>, but with the following differences:

• Memory is freed by R’s GC via a registered finalizer (non-deterministic)
• The underlying SEXP is Copy, so aliasing must be manually prevented
• Type checking happens at runtime via Any::downcast (Rust TypeId)

Thread Safety

ExternalPtr is Send to allow returning from worker thread functions. However, concurrent access is not allowed - R’s runtime is single-threaded. All R API calls are serialized through the main thread via with_r_thread.

Reading the value

A handle has no Deref: borrow / borrow_mut read the value, checking its RefCell (see “Reentrant calls” in the module docs). A #[miniextendr] function that needs only the value takes &T / &mut T instead, and the generated wrapper borrows it for the call.

Safety

The ExternalPtr assumes exclusive ownership of the underlying data. Cloning the raw SEXP without proper handling will lead to double-free.

Examples

use miniextendr_api::externalptr::{ExternalPtr, TypedExternal};

struct MyData { value: f64 }
impl TypedExternal for MyData {
    const TYPE_NAME: &'static str = "MyData";
    const TYPE_NAME_CSTR: &'static [u8] = b"MyData\0";
    const TYPE_ID_CSTR: &'static [u8] = b"my_crate::MyData\0";
}

let ptr = ExternalPtr::new(MyData { value: 3.14 });
assert_eq!(ptr.borrow().value, 3.14);

Fields

sexp: SEXP

cached_ptr: NonNull<RefCell<T>>

Cached address of the value’s RefCell, set once at construction time.

This avoids the R_ExternalPtrAddr FFI call on every borrow()/borrow_mut(). The pointer remains valid for the lifetime of the ExternalPtr because:

• R’s finalizer only runs after R garbage-collects the SEXP (which cannot happen while a Rust ExternalPtr value exists).
• R_ClearExternalPtr is only called in methods that consume or finalize (into_raw, into_inner, release_any).

root: Option<ProtectKey>

The ProtectPool key rooting this handle’s EXTPTRSXP, or None for borrowed views.

Some(key) for owning handles built from a fresh value (new / new_unchecked / from_raw / Clone / Default): the constructor roots the EXTPTRSXP in the main-thread pool so it stays alive for the whole Rust lifetime of the handle — including while it sits in a Vec across other R allocations before being handed to R (#836). Drop / into_raw / into_inner release the root via the key.

None for borrowed views of an SEXP R already owns (wrap_sexp* / from_sexp* / same_object): no root is taken, so none is released. The aliased object is kept alive by whatever R-side reference handed it to us (a .Call argument frame, an owning sibling handle, …).

_marker: PhantomData<T>

Implementations

impl<T: TypedExternal> ExternalPtr<T>

fn from_owned_parts( sexp: SEXP, cached_ptr: NonNull<RefCell<T>>, root: ProtectKey, ) -> Self

Build an owning handle rooted at root.

Pairs with the ProtectPool root that create_extptr_sexp / create_extptr_sexp_unchecked take on the SEXP (and return as the key). The root is released by Drop / into_raw / into_inner. Only the four fresh-value constructors (new / new_unchecked / from_raw / from_raw_unchecked) build through here.

fn from_borrowed_parts(sexp: SEXP, cached_ptr: NonNull<RefCell<T>>) -> Self

Build a borrowed view (root = None) of an SEXP R already owns.

No GC root is taken and none is released — the aliased object is kept alive by the R-side reference that handed it to us. Used by every wrap_sexp* / from_sexp* / same_object path.

pub(crate) unsafe fn rooted(self) -> Self

Root this handle’s EXTPTRSXP for as long as the handle lives, as the fresh-value constructors do: for a pointer converted from a class handle, whose .ptr reference R code can drop while Rust still holds the pointer (a callback the call makes, or a handle Rust keeps).

Safety

On R’s main thread, with no root taken yet.

fn release_root_if_owned(&self)

Release the pool root iff this handle owns one.

Routed through with_r_thread because an owning ExternalPtr is Send and may be dropped on the worker thread, while the pool lives on R’s main thread. with_r_thread runs the closure inline when already on the main thread (the common case), so this is a direct pool release there and a thread hand-off only from the worker. ProtectKey is Copy

• Send (two u32s), so it crosses the boundary by value.

fn erase(x: T) -> (NonNull<RefCell<T>>, *mut Box<dyn Any>)

Box x in its RefCell and erase that to the Box<Box<dyn Any>> R stores, returning the cell’s address for cached_ptr as well.

pub fn new(x: T) -> Self

Allocates memory on the heap and places x into it.

Internally stores a Box<Box<dyn Any>> — a thin pointer (fits in R’s R_ExternalPtrAddr) pointing to a fat pointer (carries the Any vtable for runtime type checking via downcast) to a RefCell<T>.

This function can be called from the two supported R contexts:

• If called from R’s main thread, creates the ExternalPtr directly
• If called from the worker thread (during run_on_worker), automatically sends the R API calls to the main thread via with_r_thread

Panics

Panics if called from a non-main thread outside of a run_on_worker context.

Equivalent to Box::new.

pub unsafe fn new_unchecked(x: T) -> Self

Allocates memory on the heap and places x into it, without thread checks.

Safety

Must be called from R’s main thread. Calling from another thread is undefined behavior (R APIs are not thread-safe).

unsafe fn create_extptr_sexp(any_raw: *mut Box<dyn Any>) -> (SEXP, ProtectKey)

Create an EXTPTRSXP from a *mut Box<dyn Any>. Must be called from main thread.

The any_raw is a thin pointer to a heap-allocated fat pointer (Box<dyn Any>). R stores the thin pointer in R_ExternalPtrAddr. Returns the SEXP and the ProtectPool key that roots it for the owning handle’s lifetime.

unsafe fn create_extptr_sexp_unchecked( any_raw: *mut Box<dyn Any>, ) -> (SEXP, ProtectKey)

Create an EXTPTRSXP from a *mut Box<dyn Any> without thread safety checks.

Safety

Must be called from R’s main thread. No debug assertions for thread safety.

Returns the SEXP and the ProtectPool key that roots it.

pub fn collect_into_r_list<I>(items: I) -> SEXP

where I: IntoIterator<Item = T>,

Collect an iterator of values into a protected R list (VECSXP) holding one fresh external pointer per item, rooting each via the destination list instead of the ProtectPool.

This is the GC-safe, allocation-lean way to hand many Rust values to R at once — e.g. converting a Vec<T> into an R list() of external pointers. Each EXTPTRSXP is created and immediately stored into the already-protected result list, so the list roots it the instant it exists: there is no unprotected window between element allocations, and no per-element pool traffic.

Contrast the naive items.map(ExternalPtr::new).collect::<Vec<_>>(), which roots every handle in the process-wide pool (keeping the Vec GC-safe while held — #836) only to release every root again when the Vec drops, then still needs a second pass to copy the handles into a list. Here the list is the root, so both the pool round-trip and the copy pass are skipped. The whole batch also crosses to R’s main thread in a single with_r_thread hop rather than one per element.

The returned VECSXP is not protected: the caller must protect it or return it to R immediately, exactly like any other freshly built SEXP (e.g. an IntoR result).

unsafe fn build_extptr_list(allocations: Vec<Box<dyn Any>>) -> SEXP

Build a protected VECSXP of external pointers from already-erased boxes.

Allocates the result list, protects it, then creates one EXTPTRSXP per entry directly into its slot — rooted by the protected list, no pool. The type symbols are interned once and reused (they are never GC’d, so they stay valid across the allocating loop). Returns the list unprotected.

Safety

Must run on R’s main thread; each allocation must wrap a RefCell<T>.

unsafe fn make_extptr_into_slot( any_raw: *mut Box<dyn Any>, type_sym: SEXP, type_id_sym: SEXP, dest: SEXP, idx: R_xlen_t, )

Create an EXTPTRSXP for any_raw and store it into dest[idx].

Mirrors create_extptr_sexp_unchecked but roots the new pointer via dest (which the caller keeps protected) instead of the pool — the element is live the instant it lands in the protected list, so a bulk build pays no pool insert/release per element.

Safety

Must run on R’s main thread; any_raw must own a T; dest must be a protected VECSXP with idx in bounds; type_sym / type_id_sym must be the interned symbols for T.

pub fn new_uninit() -> ExternalPtr<MaybeUninit<T>>

where MaybeUninit<T>: TypedExternal,

Constructs a new ExternalPtr with uninitialized contents.

Equivalent to Box::new_uninit.

pub fn new_zeroed() -> ExternalPtr<MaybeUninit<T>>

where MaybeUninit<T>: TypedExternal,

Constructs a new ExternalPtr with zeroed contents.

Equivalent to Box::new_zeroed.

pub unsafe fn from_raw(raw: *mut T) -> Self

Constructs an ExternalPtr from a raw pointer.

Moves the value out of the Box<T> allocation into the pointer’s own RefCell<T> storage and frees that allocation, so the value’s address changes: from_raw(into_raw(p)) round-trips the value, not the address.

Safety

• raw must have been allocated via Box::into_raw or equivalent
• raw must not be null
• Caller transfers ownership to the ExternalPtr
• Must be called from R’s main thread

Like Box::from_raw, except for the address.

pub unsafe fn from_raw_unchecked(raw: *mut T) -> Self

Constructs an ExternalPtr from a raw pointer, without thread checks.

Safety

• raw must have been allocated via Box::into_raw or equivalent
• raw must not be null
• Caller transfers ownership to the ExternalPtr
• Must be called from R’s main thread (no debug assertions)

pub fn into_raw(this: Self) -> *mut T

Consumes the ExternalPtr, returning a raw pointer.

The caller is responsible for the memory, and the finalizer is effectively orphaned (will do nothing since we clear the pointer). The R object is emptied: address, tag and protection list (each Sidecar<T> slot is read back into its field as a pending value first, so the values travel with the struct), so its accessors report a null external pointer, not an object restored from a saved session.

The value moves out of the pointer’s RefCell<T> storage into a new Box<T>, so its address changes. Like into_inner, this raises the miniextendr_borrow_conflict error while a running call holds the value.

Like Box::into_raw, except for the address.

pub fn into_non_null(this: Self) -> NonNull<T>

Consumes the ExternalPtr, returning a NonNull pointer.

Equivalent to Box::into_non_null.

pub fn leak<'a>(this: Self) -> &'a mut T

where T: 'a,

Consumes and leaks the ExternalPtr, returning a mutable reference.

The memory will never be freed (from Rust’s perspective; R’s GC finalizer is neutralized).

Equivalent to Box::leak.

pub fn into_inner(this: Self) -> T

Consumes the ExternalPtr, returning the wrapped value.

Uses Box<dyn Any>::downcast to recover the concrete Box<RefCell<T>>, then moves the value out. The R object is emptied like by into_raw: its accessors report a null external pointer afterwards, and each Sidecar<T> slot is read back into its field as a pending value, so wrapping the value again keeps the values.

Panics

With the miniextendr_borrow_conflict R error while a running call (a generated method of the same object, further up the stack) holds the value: the call’s borrow points into the storage this frees.

Equivalent to *boxed (deref move) or Box::into_inner.

fn cell(&self) -> &RefCell<T>

The value’s RefCell.

fn value_ptr(&self) -> *mut T

The value’s address, through its RefCell.

pub fn borrow(&self) -> ExternalPtrRef<'_, T>

Borrows the value, as the generated wrapper does for a &T argument: until the returned view drops, a method of the same object that needs it mutably, a &mut T argument holding it, or borrow_mut through another handle raises the error below instead. The view also carries the R object, for the sidecar accessors.

Panics

With the R error of class miniextendr_borrow_conflict while the value is borrowed mutably, and for a type-erased ExternalPtr<()>, which has no value of its own to borrow (downcast it first).

pub fn borrow_mut(&mut self) -> ExternalPtrMut<'_, T>

Borrows the value mutably, as the generated wrapper does for a &mut T argument: until the returned view drops, any other borrow of the value raises the error below.

Panics

With the R error of class miniextendr_borrow_conflict while the value is borrowed (by a running call holding it, or another handle’s borrow), and for a type-erased ExternalPtr<()>.

#[doc(hidden)]

pub unsafe fn as_ref_unchecked(&self) -> &T

The value, with no RefCell borrow: only the ALTREP data1 paths, whose per-element callbacks read without one until #2103 measures the checked read.

Safety

Nothing may hold the value mutably while the reference lives.

#[doc(hidden)]

pub unsafe fn as_mut_unchecked(&mut self) -> &mut T

The value mutably, with no RefCell borrow, like as_ref_unchecked.

Safety

Nothing else may hold the value while the reference lives.

fn value_cell(&self) -> &RefCell<T>

The value’s RefCell, which a type-erased handle doesn’t point at.

pub fn as_ptr(&self) -> *const T

Returns the raw pointer without consuming the ExternalPtr.

pub fn as_mut_ptr(&mut self) -> *mut T

Returns the raw mutable pointer without consuming the ExternalPtr.

pub fn ptr_eq(this: &Self, other: &Self) -> bool

Checks whether two ExternalPtrs refer to the same allocation (pointer identity).

This ignores the pointee values. Use this when you need alias detection; prefer PartialEq/PartialOrd for value comparisons.

pub fn as_sexp(&self) -> SEXP

Returns the underlying SEXP.

Warning

The returned SEXP must not be duplicated or the finalizer will double-free.

pub fn same_object(&self) -> Self

A second handle to the same R object: no value is copied and no R object is allocated, and the handle takes no borrow until it is read. Returning it from a #[miniextendr] function returns the same R object, so R sees the identity it passed in.

#[miniextendr]
pub fn first_of(objs: Vec<ExternalPtr<MyType>>) -> ExternalPtr<MyType> {
    objs[0].same_object()
}

The new handle takes no GC root of its own: something else (the handle it was made from, or R) must keep the R object reachable while it is used.

pub fn tag(&self) -> SEXP

Returns the tag SEXP (type identifier symbol).

pub unsafe fn tag_unchecked(&self) -> SEXP

Returns the tag SEXP (unchecked version).

Skips thread safety checks for performance-critical paths.

Safety

Must be called from the R main thread. Only use in ALTREP callbacks or other contexts where you’re certain you’re on the main thread.

pub fn protected(&self) -> SEXP

Returns the protected SEXP slot (user-protected objects).

This returns the user-protected object stored in the prot VECSXP, not the VECSXP itself.

pub unsafe fn protected_unchecked(&self) -> SEXP

Returns the protected SEXP slot (unchecked version).

Skips thread safety checks for performance-critical paths.

Safety

Must be called from the R main thread. Only use in ALTREP callbacks or other contexts where you’re certain you’re on the main thread.

pub unsafe fn set_protected(&self, user_prot: SEXP) -> bool

Sets the user-protected SEXP slot.

Use this to prevent R objects from being GC’d while this ExternalPtr exists. The type ID stored in prot slot 0 is preserved.

Returns false if the prot structure is malformed (should not happen for ExternalPtrs created by this library).

Safety

• user_prot must be a valid SEXP or R_NilValue
• Must be called from the R main thread

pub fn prot_raw(&self) -> SEXP

Returns the raw prot VECSXP (contains both type ID and user protected).

Prefer using protected() for user data and stored_type_id() for type info.

pub fn is_null(&self) -> bool

Checks if the internal pointer is null (already finalized or cleared).

pub unsafe fn wrap_sexp(sexp: SEXP) -> Option<Self>

Attempt to wrap a SEXP as an ExternalPtr with type checking.

Uses Any::downcast_ref for authoritative type checking (Rust TypeId). Type-erased ExternalPtr<()> deliberately skips the concrete downcast.

Returns None if:

• The internal pointer is null
• The metadata does not identify ordinary miniextendr storage
• The stored Box<dyn Any> does not contain a RefCell<T>

Safety

• sexp must be a valid EXTPTRSXP; foreign pointers must not carry forged miniextendr metadata
• The caller must ensure no other ExternalPtr owns this SEXP

pub unsafe fn wrap_sexp_unchecked(sexp: SEXP) -> Option<Self>

Attempt to wrap a SEXP as an ExternalPtr (unchecked version).

Skips thread safety checks for performance-critical paths like ALTREP callbacks.

Safety

• sexp must be a valid EXTPTRSXP; foreign pointers must not carry forged miniextendr metadata
• The caller must ensure exclusive ownership
• Must be called from the R main thread (guaranteed in ALTREP callbacks)

pub unsafe fn wrap_sexp_with_error( sexp: SEXP, ) -> Result<Self, TypeMismatchError>

Attempt to wrap a SEXP as an ExternalPtr, returning an error with type info on mismatch.

This is used by the TryFromSexp trait implementation.

Safety

Same as wrap_sexp.

pub unsafe fn from_sexp_unchecked(sexp: SEXP) -> Self

Create an ExternalPtr from an SEXP without type checking.

Safety

• sexp must be a valid EXTPTRSXP containing a *mut Box<dyn Any> wrapping a RefCell<T>
• The caller must ensure exclusive ownership

pub fn type_name() -> &'static str

Returns the type name for type T.

pub fn stored_type_name(&self) -> Option<&'static str>

Returns the type name stored in this ExternalPtr’s prot slot.

Returns None if the prot slot doesn’t contain a valid type symbol.

impl ExternalPtr<()>

pub unsafe fn from_sexp(sexp: SEXP) -> Self

Create a type-erased ExternalPtr from an EXTPTRSXP without checking the stored type.

Safety

• sexp must be a valid EXTPTRSXP
• Caller must ensure exclusive ownership semantics are upheld

pub fn is<T: TypedExternal>(&self) -> bool

Check whether the stored Box<dyn Any> contains a T.

Uses Any::is for authoritative runtime type checking.

#[doc(hidden)]

pub fn downcast_cell<T: TypedExternal>(&self) -> Option<&RefCell<T>>

The RefCell holding the stored value if it is a T.

Uses Any::downcast_ref for authoritative runtime type checking. This is where every generated method receiver (inherent and trait-impl) gets the struct: it borrows the cell for the call.

pub fn downcast_ref<T: TypedExternal>(&self) -> Option<ExternalPtrRef<'_, T>>

Borrow the stored value if it is a T, like ExternalPtr::borrow.

Uses Any::downcast_ref for authoritative runtime type checking.

Panics

With the R error of class miniextendr_borrow_conflict while the value is borrowed mutably.

pub fn downcast_mut<T: TypedExternal>( &mut self, ) -> Option<ExternalPtrMut<'_, T>>

Borrow the stored value mutably if it is a T, like ExternalPtr::borrow_mut.

Panics

With the R error of class miniextendr_borrow_conflict while the value is borrowed.

impl ExternalPtr<()>

pub fn is_consumed(&self) -> bool

Whether the slot holds the ConsumedSlot marker.

pub fn has_null_address(&self) -> bool

Whether the pointer has no address: restored from a saved session (readRDS() / unserialize()), cleared by into_inner, or never given one (R’s new("externalptr")).

pub fn take_for_consuming<T: TypedExternal>(&mut self) -> Option<T>

Move the stored T out of the handle, leaving ConsumedSlot behind.

Returns None when the slot does not hold a T (wrong type, null, or already consumed); the slot is untouched in that case. The outer Box<Box<dyn Any>> cell stays allocated, so the finaliser and every other accessor keep working on the marker. The value’s Sidecar<T> slots stay in the pointer’s prot list across the method: a self -> Self result that keeps the fields (Self { n, ..self }) keeps the values, one built afresh (Self::new(..)) replaces them at the write-back. Runs on R’s main thread (the generated receiver prelude). Raises the miniextendr_borrow_conflict error while a running call holds the value.

pub fn restore_after_consuming<T: TypedExternal>(&mut self, value: T)

Put a value back into a slot emptied by Self::take_for_consuming (the write-back half of self -> Self). Replaces whatever the slot holds; the TypedExternal tag in the prot slot is unchanged because the type is the same. The pending values of the value’s Sidecar<T> fields (what the method set with Sidecar::new) are flushed into prot, on R’s main thread (a worker method’s write-back runs on the worker, so the flush is routed through with_r_thread); the other slots keep their values. Raises the miniextendr_borrow_conflict error while a running call holds the value the slot holds.

impl<T: TypedExternal> ExternalPtr<MaybeUninit<T>>

where MaybeUninit<T>: TypedExternal,

pub fn assume_init(self) -> ExternalPtr<T>

Converts to ExternalPtr<T>.

Safety

The value must have been initialized.

Implementation Note

This method creates a new SEXP with T’s type information, leaving the original MaybeUninit<T> SEXP as an orphaned empty shell in R’s heap. This is necessary because the type ID stored in the prot slot must match the actual type. The orphaned SEXP will be cleaned up by R’s GC eventually.

If you need to avoid this overhead, consider using ExternalPtr<T>::new directly and initializing in place via as_mut.

Equivalent to Box::assume_init.

pub fn write(self, value: T) -> ExternalPtr<T>

Writes a value and converts to initialized.

Creates a new SEXP with T’s type information (the original MaybeUninit<T> SEXP becomes an orphaned shell, cleaned up by GC).

Trait Implementations

impl<T: TypedExternal + Clone> Clone for ExternalPtr<T>

fn clone(&self) -> Self

Deep clones the inner value into a new ExternalPtr.

This creates a completely independent ExternalPtr with its own heap allocation and finalizer. The Sidecar<T> slots are copied as R objects (after flushing the source’s pending values), so the two pointers share those values until one side writes a field: every write replaces the slot, and R copies a shared value before modifying it in place. For a type with Sidecar fields this runs on R’s main thread only.

Panics

With the R error of class miniextendr_borrow_conflict while the value is borrowed mutably, like borrow.

fn clone_from(&mut self, source: &Self)

Clones source’s value into this pointer’s value in place. The Sidecar<T> slots are copied as R objects like in clone, replacing this pointer’s slot values and its pending values.

Panics

With the R error of class miniextendr_borrow_conflict while source’s value is borrowed mutably or this one’s is borrowed, which includes cloning a pointer into itself.

impl<T: TypedExternal + Debug> Debug for ExternalPtr<T>

Like RefCell’s: a value borrowed mutably prints as <borrowed> instead of raising, and so does a type-erased ExternalPtr<()>, which has no value of its own.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: TypedExternal + Default> Default for ExternalPtr<T>

fn default() -> Self

Creates an ExternalPtr containing the default value of T.

impl<T: TypedExternal + Display> Display for ExternalPtr<T>

Borrows the value, like ExternalPtr::borrow.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: TypedExternal + DoubleEndedIterator> DoubleEndedIterator for ExternalPtr<T>

fn next_back(&mut self) -> Option<Self::Item>

Removes and returns an element from the end of the iterator.

fn nth_back(&mut self, n: usize) -> Option<Self::Item>

Returns the nth element from the end of the iterator.

fn next_chunk_back<const N: usize>( &mut self, ) -> Result<[Self::Item; N], IntoIter<Self::Item, N>>

where Self: Sized,

🔬This is a nightly-only experimental API. (iter_next_chunk)

Advances from the back of the iterator and returns an array containing the next N values in sequence.

fn advance_back_by(&mut self, n: usize) -> Result<(), NonZero<usize>>

🔬This is a nightly-only experimental API. (iter_advance_by)

Advances the iterator from the back by n elements.

fn try_rfold<B, F, R>(&mut self, init: B, f: F) -> R

where Self: Sized, F: FnMut(B, Self::Item) -> R, R: Try<Output = B>,

This is the reverse version of Iterator::try_fold(): it takes elements starting from the back of the iterator.

fn rfold<B, F>(self, init: B, f: F) -> B

where Self: Sized, F: FnMut(B, Self::Item) -> B,

An iterator method that reduces the iterator’s elements to a single, final value, starting from the back.

fn rfind<P>(&mut self, predicate: P) -> Option<Self::Item>

where Self: Sized, P: FnMut(&Self::Item) -> bool,

Searches for an element of an iterator from the back that satisfies a predicate.

impl<T: TypedExternal> Drop for ExternalPtr<T>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl<T: TypedExternal + Eq> Eq for ExternalPtr<T>

#[doc(hidden)]

fn assert_receiver_is_total_eq(&self)

👎Deprecated since 1.95.0:

implementation detail of #[derive(Eq)]

#[doc(hidden)]

fn assert_fields_are_eq(&self)

🔬This is a nightly-only experimental API. (derive_eq_internals)

impl<T: TypedExternal + ExactSizeIterator> ExactSizeIterator for ExternalPtr<T>

fn len(&self) -> usize

Returns the exact remaining length of the iterator.

fn is_empty(&self) -> bool

🔬This is a nightly-only experimental API. (exact_size_is_empty)

Returns true if the iterator is empty.

impl<T: TypedExternal> From<Box<T>> for ExternalPtr<T>

fn from(boxed: Box<T>) -> Self

Converts to this type from the input type.

impl<T: TypedExternal> From<T> for ExternalPtr<T>

fn from(t: T) -> Self

Converts to this type from the input type.

impl<T: TypedExternal + FusedIterator> FusedIterator for ExternalPtr<T>

impl<T: TypedExternal + Hash> Hash for ExternalPtr<T>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<T: TypedExternal> IntoR for ExternalPtr<T>

type Error = !

The error type for fallible conversions.

fn try_into_sexp(self) -> Result<SEXP, Self::Error>

Try to convert this value to an R SEXP.

unsafe fn try_into_sexp_unchecked(self) -> Result<SEXP, Self::Error>

Try to convert to SEXP without thread safety checks.

fn into_sexp(self) -> SEXP

Convert this value to an R SEXP, panicking on error.

unsafe fn into_sexp_unchecked(self) -> SEXP

where Self: Sized,

Convert to SEXP without thread safety checks, panicking on error.

impl<T: TypedExternal + Iterator> Iterator for ExternalPtr<T>

Each step borrows the value mutably, like ExternalPtr::borrow_mut.

type Item = <T as Iterator>::Item

The type of the elements being iterated over.

fn next(&mut self) -> Option<Self::Item>

Advances the iterator and returns the next value.

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the iterator.

fn nth(&mut self, n: usize) -> Option<Self::Item>

Returns the nth element of the iterator.

fn next_chunk<const N: usize>( &mut self, ) -> Result<[Self::Item; N], IntoIter<Self::Item, N>>

where Self: Sized,

🔬This is a nightly-only experimental API. (iter_next_chunk)

Advances the iterator and returns an array containing the next N values.

fn count(self) -> usize

where Self: Sized,

Consumes the iterator, counting the number of iterations and returning it.

fn last(self) -> Option<Self::Item>

where Self: Sized,

Consumes the iterator, returning the last element.

fn advance_by(&mut self, n: usize) -> Result<(), NonZero<usize>>

🔬This is a nightly-only experimental API. (iter_advance_by)

Advances the iterator by n elements.

fn step_by(self, step: usize) -> StepBy<Self>

where Self: Sized,

Creates an iterator starting at the same point, but stepping by the given amount at each iteration.

fn chain<U>(self, other: U) -> Chain<Self, <U as IntoIterator>::IntoIter>

where Self: Sized, U: IntoIterator<Item = Self::Item>,

Takes two iterators and creates a new iterator over both in sequence.

fn zip<U>(self, other: U) -> Zip<Self, <U as IntoIterator>::IntoIter>

where Self: Sized, U: IntoIterator,

‘Zips up’ two iterators into a single iterator of pairs.

fn intersperse(self, separator: Self::Item) -> Intersperse<Self>

where Self: Sized, Self::Item: Clone,

🔬This is a nightly-only experimental API. (iter_intersperse)

Creates a new iterator which places a copy of separator between items of the original iterator.

fn intersperse_with<G>(self, separator: G) -> IntersperseWith<Self, G>

where Self: Sized, G: FnMut() -> Self::Item,

🔬This is a nightly-only experimental API. (iter_intersperse)

Creates a new iterator which places an item generated by separator between items of the original iterator.

fn map<B, F>(self, f: F) -> Map<Self, F>

where Self: Sized, F: FnMut(Self::Item) -> B,

Takes a closure and creates an iterator which calls that closure on each element.

fn for_each<F>(self, f: F)

where Self: Sized, F: FnMut(Self::Item),

Calls a closure on each element of an iterator.

fn filter<P>(self, predicate: P) -> Filter<Self, P>

where Self: Sized, P: FnMut(&Self::Item) -> bool,

Creates an iterator which uses a closure to determine if an element should be yielded.

fn filter_map<B, F>(self, f: F) -> FilterMap<Self, F>

where Self: Sized, F: FnMut(Self::Item) -> Option<B>,

Creates an iterator that both filters and maps.

fn enumerate(self) -> Enumerate<Self>

where Self: Sized,

Creates an iterator which gives the current iteration count as well as the next value.

fn peekable(self) -> Peekable<Self>

where Self: Sized,

Creates an iterator which can use the peek and peek_mut methods to look at the next element of the iterator without consuming it. See their documentation for more information.

fn skip_while<P>(self, predicate: P) -> SkipWhile<Self, P>

where Self: Sized, P: FnMut(&Self::Item) -> bool,

Creates an iterator that skips elements based on a predicate.

fn take_while<P>(self, predicate: P) -> TakeWhile<Self, P>

where Self: Sized, P: FnMut(&Self::Item) -> bool,

Creates an iterator that yields elements based on a predicate.

fn map_while<B, P>(self, predicate: P) -> MapWhile<Self, P>

where Self: Sized, P: FnMut(Self::Item) -> Option<B>,

Creates an iterator that both yields elements based on a predicate and maps.

fn skip(self, n: usize) -> Skip<Self>

where Self: Sized,

Creates an iterator that skips the first n elements.

fn take(self, n: usize) -> Take<Self>

where Self: Sized,

Creates an iterator that yields the first n elements, or fewer if the underlying iterator ends sooner.

fn scan<St, B, F>(self, initial_state: St, f: F) -> Scan<Self, St, F>

where Self: Sized, F: FnMut(&mut St, Self::Item) -> Option<B>,

An iterator adapter which, like fold, holds internal state, but unlike fold, produces a new iterator.

fn flat_map<U, F>(self, f: F) -> FlatMap<Self, U, F>

where Self: Sized, U: IntoIterator, F: FnMut(Self::Item) -> U,

Creates an iterator that works like map, but flattens nested structure.

fn flatten(self) -> Flatten<Self>

where Self: Sized, Self::Item: IntoIterator,

Creates an iterator that flattens nested structure.

fn map_windows<F, R, const N: usize>(self, f: F) -> MapWindows<Self, F, N>

where Self: Sized, F: FnMut(&[Self::Item; N]) -> R,

🔬This is a nightly-only experimental API. (iter_map_windows)

Calls the given function f for each contiguous window of size N over self and returns an iterator over the outputs of f. Like slice::windows(), the windows during mapping overlap as well.

fn fuse(self) -> Fuse<Self>

where Self: Sized,

Creates an iterator which ends after the first None.

fn inspect<F>(self, f: F) -> Inspect<Self, F>

where Self: Sized, F: FnMut(&Self::Item),

Does something with each element of an iterator, passing the value on.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Iterator.

fn collect<B>(self) -> B

where B: FromIterator<Self::Item>, Self: Sized,

Transforms an iterator into a collection.

fn try_collect<B>( &mut self, ) -> <<Self::Item as Try>::Residual as Residual<B>>::TryType

where Self: Sized, Self::Item: Try, <Self::Item as Try>::Residual: Residual<B>, B: FromIterator<<Self::Item as Try>::Output>,

🔬This is a nightly-only experimental API. (iterator_try_collect)

Fallibly transforms an iterator into a collection, short circuiting if a failure is encountered.

fn collect_into<E>(self, collection: &mut E) -> &mut E

where E: Extend<Self::Item>, Self: Sized,

🔬This is a nightly-only experimental API. (iter_collect_into)

Collects all the items from an iterator into a collection.

fn partition<B, F>(self, f: F) -> (B, B)

where Self: Sized, B: Default + Extend<Self::Item>, F: FnMut(&Self::Item) -> bool,

Consumes an iterator, creating two collections from it.

fn partition_in_place<'a, T, P>(self, predicate: P) -> usize

where T: 'a, Self: Sized + DoubleEndedIterator<Item = &'a mut T>, P: FnMut(&T) -> bool,

🔬This is a nightly-only experimental API. (iter_partition_in_place)

Reorders the elements of this iterator in-place according to the given predicate, such that all those that return true precede all those that return false. Returns the number of true elements found.

fn is_partitioned<P>(self, predicate: P) -> bool

where Self: Sized, P: FnMut(Self::Item) -> bool,

🔬This is a nightly-only experimental API. (iter_is_partitioned)

Checks if the elements of this iterator are partitioned according to the given predicate, such that all those that return true precede all those that return false.

fn try_fold<B, F, R>(&mut self, init: B, f: F) -> R

where Self: Sized, F: FnMut(B, Self::Item) -> R, R: Try<Output = B>,

An iterator method that applies a function as long as it returns successfully, producing a single, final value.

fn try_for_each<F, R>(&mut self, f: F) -> R

where Self: Sized, F: FnMut(Self::Item) -> R, R: Try<Output = ()>,

An iterator method that applies a fallible function to each item in the iterator, stopping at the first error and returning that error.

fn fold<B, F>(self, init: B, f: F) -> B

where Self: Sized, F: FnMut(B, Self::Item) -> B,

Folds every element into an accumulator by applying an operation, returning the final result.

fn reduce<F>(self, f: F) -> Option<Self::Item>

where Self: Sized, F: FnMut(Self::Item, Self::Item) -> Self::Item,

Reduces the elements to a single one, by repeatedly applying a reducing operation.

fn try_reduce<R>( &mut self, f: impl FnMut(Self::Item, Self::Item) -> R, ) -> <<R as Try>::Residual as Residual<Option<<R as Try>::Output>>>::TryType

where Self: Sized, R: Try<Output = Self::Item>, <R as Try>::Residual: Residual<Option<Self::Item>>,

🔬This is a nightly-only experimental API. (iterator_try_reduce)

Reduces the elements to a single one by repeatedly applying a reducing operation. If the closure returns a failure, the failure is propagated back to the caller immediately.

fn all<F>(&mut self, f: F) -> bool

where Self: Sized, F: FnMut(Self::Item) -> bool,

Tests if every element of the iterator matches a predicate.

fn any<F>(&mut self, f: F) -> bool

where Self: Sized, F: FnMut(Self::Item) -> bool,

Tests if any element of the iterator matches a predicate.

fn find<P>(&mut self, predicate: P) -> Option<Self::Item>

where Self: Sized, P: FnMut(&Self::Item) -> bool,

Searches for an element of an iterator that satisfies a predicate.

fn find_map<B, F>(&mut self, f: F) -> Option<B>

where Self: Sized, F: FnMut(Self::Item) -> Option<B>,

Applies function to the elements of iterator and returns the first non-none result.

fn try_find<R>( &mut self, f: impl FnMut(&Self::Item) -> R, ) -> <<R as Try>::Residual as Residual<Option<Self::Item>>>::TryType

where Self: Sized, R: Try<Output = bool>, <R as Try>::Residual: Residual<Option<Self::Item>>,

🔬This is a nightly-only experimental API. (try_find)

Applies function to the elements of iterator and returns the first true result or the first error.

fn position<P>(&mut self, predicate: P) -> Option<usize>

where Self: Sized, P: FnMut(Self::Item) -> bool,

Searches for an element in an iterator, returning its index.

fn rposition<P>(&mut self, predicate: P) -> Option<usize>

where P: FnMut(Self::Item) -> bool, Self: Sized + ExactSizeIterator + DoubleEndedIterator,

Searches for an element in an iterator from the right, returning its index.

fn max(self) -> Option<Self::Item>

where Self: Sized, Self::Item: Ord,

Returns the maximum element of an iterator.

fn min(self) -> Option<Self::Item>

where Self: Sized, Self::Item: Ord,

Returns the minimum element of an iterator.

fn max_by_key<B, F>(self, f: F) -> Option<Self::Item>

where B: Ord, Self: Sized, F: FnMut(&Self::Item) -> B,

Returns the element that gives the maximum value from the specified function.

fn max_by<F>(self, compare: F) -> Option<Self::Item>

where Self: Sized, F: FnMut(&Self::Item, &Self::Item) -> Ordering,

Returns the element that gives the maximum value with respect to the specified comparison function.

fn min_by_key<B, F>(self, f: F) -> Option<Self::Item>

where B: Ord, Self: Sized, F: FnMut(&Self::Item) -> B,

Returns the element that gives the minimum value from the specified function.

fn min_by<F>(self, compare: F) -> Option<Self::Item>

where Self: Sized, F: FnMut(&Self::Item, &Self::Item) -> Ordering,

Returns the element that gives the minimum value with respect to the specified comparison function.

fn rev(self) -> Rev<Self>

where Self: Sized + DoubleEndedIterator,

Reverses an iterator’s direction.

fn unzip<A, B, FromA, FromB>(self) -> (FromA, FromB)

where FromA: Default + Extend<A>, FromB: Default + Extend<B>, Self: Sized + Iterator<Item = (A, B)>,

Converts an iterator of pairs into a pair of containers.

fn copied<'a, T>(self) -> Copied<Self>

where T: Copy + 'a, Self: Sized + Iterator<Item = &'a T>,

Creates an iterator which copies all of its elements.

fn cloned<'a, T>(self) -> Cloned<Self>

where T: Clone + 'a, Self: Sized + Iterator<Item = &'a T>,

Creates an iterator which clones all of its elements.

fn cycle(self) -> Cycle<Self>

where Self: Sized + Clone,

Repeats an iterator endlessly.

fn array_chunks<const N: usize>(self) -> ArrayChunks<Self, N>

where Self: Sized,

🔬This is a nightly-only experimental API. (iter_array_chunks)

Returns an iterator over N elements of the iterator at a time.

fn sum<S>(self) -> S

where Self: Sized, S: Sum<Self::Item>,

Sums the elements of an iterator.

fn product<P>(self) -> P

where Self: Sized, P: Product<Self::Item>,

Iterates over the entire iterator, multiplying all the elements.

fn cmp<I>(self, other: I) -> Ordering

where I: IntoIterator<Item = Self::Item>, Self::Item: Ord, Self: Sized,

Lexicographically compares the elements of this Iterator with those of another.

fn cmp_by<I, F>(self, other: I, cmp: F) -> Ordering

where Self: Sized, I: IntoIterator, F: FnMut(Self::Item, <I as IntoIterator>::Item) -> Ordering,

🔬This is a nightly-only experimental API. (iter_order_by)

Lexicographically compares the elements of this Iterator with those of another with respect to the specified comparison function.

fn partial_cmp<I>(self, other: I) -> Option<Ordering>

where I: IntoIterator, Self::Item: PartialOrd<<I as IntoIterator>::Item>, Self: Sized,

Lexicographically compares the PartialOrd elements of this Iterator with those of another. The comparison works like short-circuit evaluation, returning a result without comparing the remaining elements. As soon as an order can be determined, the evaluation stops and a result is returned.

fn partial_cmp_by<I, F>(self, other: I, partial_cmp: F) -> Option<Ordering>

where Self: Sized, I: IntoIterator, F: FnMut(Self::Item, <I as IntoIterator>::Item) -> Option<Ordering>,

🔬This is a nightly-only experimental API. (iter_order_by)

Lexicographically compares the elements of this Iterator with those of another with respect to the specified comparison function.

fn eq<I>(self, other: I) -> bool

where I: IntoIterator, Self::Item: PartialEq<<I as IntoIterator>::Item>, Self: Sized,

Determines if the elements of this Iterator are equal to those of another.

fn eq_by<I, F>(self, other: I, eq: F) -> bool

where Self: Sized, I: IntoIterator, F: FnMut(Self::Item, <I as IntoIterator>::Item) -> bool,

🔬This is a nightly-only experimental API. (iter_order_by)

Determines if the elements of this Iterator are equal to those of another with respect to the specified equality function.

fn ne<I>(self, other: I) -> bool

where I: IntoIterator, Self::Item: PartialEq<<I as IntoIterator>::Item>, Self: Sized,

Determines if the elements of this Iterator are not equal to those of another.

fn lt<I>(self, other: I) -> bool

where I: IntoIterator, Self::Item: PartialOrd<<I as IntoIterator>::Item>, Self: Sized,

Determines if the elements of this Iterator are lexicographically less than those of another.

fn le<I>(self, other: I) -> bool

where I: IntoIterator, Self::Item: PartialOrd<<I as IntoIterator>::Item>, Self: Sized,

Determines if the elements of this Iterator are lexicographically less or equal to those of another.

fn gt<I>(self, other: I) -> bool

where I: IntoIterator, Self::Item: PartialOrd<<I as IntoIterator>::Item>, Self: Sized,

Determines if the elements of this Iterator are lexicographically greater than those of another.

fn ge<I>(self, other: I) -> bool

where I: IntoIterator, Self::Item: PartialOrd<<I as IntoIterator>::Item>, Self: Sized,

Determines if the elements of this Iterator are lexicographically greater than or equal to those of another.

fn is_sorted(self) -> bool

where Self: Sized, Self::Item: PartialOrd,

Checks if the elements of this iterator are sorted.

fn is_sorted_by<F>(self, compare: F) -> bool

where Self: Sized, F: FnMut(&Self::Item, &Self::Item) -> bool,

Checks if the elements of this iterator are sorted using the given comparator function.

fn is_sorted_by_key<F, K>(self, f: F) -> bool

where Self: Sized, F: FnMut(Self::Item) -> K, K: PartialOrd,

Checks if the elements of this iterator are sorted using the given key extraction function.

impl<T: TypedExternal + Ord> Ord for ExternalPtr<T>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

fn clamp_to<R>(self, range: R) -> Self

where Self: Sized, R: ClampBounds<Self>,

🔬This is a nightly-only experimental API. (clamp_to)

Restrict a value to a certain range.

impl<T: TypedExternal> Owner for ExternalPtr<T>

impl<T: TypedExternal + PartialEq> PartialEq for ExternalPtr<T>

Compares the values, borrowing both, like ExternalPtr::borrow.

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<T: TypedExternal + PartialOrd> PartialOrd for ExternalPtr<T>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

#[doc(hidden)]

fn __chaining_lt(&self, other: &Rhs) -> ControlFlow<bool>

🔬This is a nightly-only experimental API. (partial_ord_chaining_methods)

If self == other, returns ControlFlow::Continue(()). Otherwise, returns ControlFlow::Break(self < other).

#[doc(hidden)]

fn __chaining_le(&self, other: &Rhs) -> ControlFlow<bool>

🔬This is a nightly-only experimental API. (partial_ord_chaining_methods)

Same as __chaining_lt, but for <= instead of <.

#[doc(hidden)]

fn __chaining_gt(&self, other: &Rhs) -> ControlFlow<bool>

🔬This is a nightly-only experimental API. (partial_ord_chaining_methods)

Same as __chaining_lt, but for > instead of <.

#[doc(hidden)]

fn __chaining_ge(&self, other: &Rhs) -> ControlFlow<bool>

🔬This is a nightly-only experimental API. (partial_ord_chaining_methods)

Same as __chaining_lt, but for >= instead of <.

impl<T: TypedExternal> Pointer for ExternalPtr<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: TypedExternal + Send> Send for ExternalPtr<T>

impl<T: TypedExternal> SidecarOwner<T> for ExternalPtr<T>

fn __mx_read(&self) -> SidecarRead<'_, T>

The value, borrowed shared, with its R object; or, for a Saved handle, the restored pointer alone.

impl<T: TypedExternal> SidecarOwnerMut<T> for ExternalPtr<T>

fn __mx_write(&mut self) -> ExternalPtrMut<'_, T>

The value, borrowed exclusively, with its R object.

impl<T: TypedExternal + Send> TryFromSexp for ExternalPtr<T>

Convert R EXTPTRSXP to ExternalPtr<T>.

This enables using ExternalPtr<T> as parameter types in #[miniextendr] functions, for a body that keeps or consumes the handle; a body that only reads the value takes &T.

Example

#[derive(ExternalPtr)]
struct MyData { value: i32 }

#[miniextendr]
fn process(data: ExternalPtr<MyData>) -> i32 {
    data.borrow().value
}

type Error = SexpError

The error type returned when conversion fails.

fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error>

Attempt to convert an R SEXP to this Rust type.

unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error>

Convert from SEXP without thread safety checks.

const NATIVE_BORROW: Option<NativeBorrow> = None

Native vector storage retained by this conversion, if any.

const CHARACTER_ONLY: bool = false

Whether this conversion accepts only character input: every value it converts, other than NULL, is a character vector or a factor.

#[doc(hidden)]

const __MX_EXPECTATION: Option<&'static str> = None

What an argument of this type must be, in R terms, when #[miniextendr] cannot tell from the type as written: the <expected> of a failed conversion’s '<p>' must be <expected>: ....

#[doc(hidden)]

unsafe fn __mx_try_from_rooted(root: Root<'_>) -> Result<Self, Self::Error>

Convert with a scope able to retain uncached ALTREP elements. Custom reference converters keep their existing behavior by default.

#[doc(hidden)]

fn __mx_has_na(&self) -> bool

Whether the converted argument holds a value #[miniextendr(no_na)] refuses after the conversion.

#[doc(hidden)]

fn __mx_input_has_na(&self, input: SEXP) -> bool

Whether #[miniextendr(no_na)] refuses this converted argument, read from input (the R value it converted from), when no R guard ran.

#[doc(hidden)]

fn __mx_try_from_sexp_with_check( sexp: SEXP, check: &ElementCheck<'_>, ) -> Result<Self, SexpError>

where Self::Error: Into<SexpError>,

Convert, running check, an element type’s TryFromSexpElement::check_sexp, on the R value that carries an element’s class (#1837).

#[doc(hidden)]

unsafe fn __mx_try_from_sexp_unchecked_with_check( sexp: SEXP, check: &ElementCheck<'_>, ) -> Result<Self, SexpError>

where Self::Error: Into<SexpError>,

__mx_try_from_sexp_with_check through try_from_sexp_unchecked. Not public API.

Layout

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 32 bytes