Trait StableApiDefinition 

pub trait StableApiDefinition {
    const VERSION_MAJOR: u32;
    const VERSION_MINOR: u32;

    // Required methods
    unsafe fn rstring_len(&self, obj: VALUE) -> c_long;
    unsafe fn rstring_ptr(&self, obj: VALUE) -> *const c_char;
    unsafe fn rarray_len(&self, obj: VALUE) -> c_long;
    unsafe fn rarray_const_ptr(&self, obj: VALUE) -> *const VALUE;
    unsafe fn rarray_aref(&self, obj: VALUE, idx: isize) -> VALUE;
    unsafe fn rarray_aset(&self, obj: VALUE, idx: isize, val: VALUE);
    unsafe fn rbasic_class(&self, obj: VALUE) -> Option<NonNull<VALUE>>;
    unsafe fn frozen_p(&self, obj: VALUE) -> bool;
    unsafe fn bignum_positive_p(&self, obj: VALUE) -> bool;
    fn special_const_p(&self, value: VALUE) -> bool;
    unsafe fn builtin_type(&self, obj: VALUE) -> ruby_value_type;
    unsafe fn type_p(&self, obj: VALUE, ty: ruby_value_type) -> bool;
    fn nil_p(&self, obj: VALUE) -> bool;
    fn fixnum_p(&self, obj: VALUE) -> bool;
    unsafe fn dynamic_sym_p(&self, obj: VALUE) -> bool;
    fn static_sym_p(&self, obj: VALUE) -> bool;
    unsafe fn symbol_p(&self, obj: VALUE) -> bool;
    unsafe fn float_type_p(&self, obj: VALUE) -> bool;
    unsafe fn integer_type_p(&self, obj: VALUE) -> bool;
    fn flonum_p(&self, obj: VALUE) -> bool;
    fn immediate_p(&self, obj: VALUE) -> bool;
    fn rb_test(&self, ob: VALUE) -> bool;
    unsafe fn rb_type(&self, obj: VALUE) -> ruby_value_type;
    unsafe fn rstring_interned_p(&self, obj: VALUE) -> bool;
    fn thread_sleep(&self, duration: Duration);
    unsafe fn rtypeddata_p(&self, obj: VALUE) -> bool;
    unsafe fn rtypeddata_type(&self, obj: VALUE) -> *const rb_data_type_t;
    unsafe fn rtypeddata_get_data(&self, obj: VALUE) -> *mut c_void;
    unsafe fn rstring_end(&self, obj: VALUE) -> *const c_char;
    unsafe fn rdata_ptr(&self, obj: VALUE) -> *mut c_void;
    unsafe fn rb_obj_freeze(&self, obj: VALUE);
    unsafe fn rb_obj_promoted(&self, obj: VALUE) -> bool;
    unsafe fn rb_obj_promoted_raw(&self, obj: VALUE) -> bool;
    unsafe fn num2dbl(&self, obj: VALUE) -> c_double;
    fn dbl2num(&self, val: c_double) -> VALUE;
    unsafe fn rhash_size(&self, obj: VALUE) -> usize;
    unsafe fn rhash_empty_p(&self, obj: VALUE) -> bool;
    unsafe fn encoding_get(&self, obj: VALUE) -> c_int;
    fn fl_able(&self, obj: VALUE) -> bool;
    fn fix2long(&self, obj: VALUE) -> c_long;
    fn fix2ulong(&self, obj: VALUE) -> c_ulong;
    fn long2fix(&self, val: c_long) -> VALUE;
    fn fixable(&self, val: c_long) -> bool;
    fn posfixable(&self, val: c_ulong) -> bool;
    unsafe fn num2long(&self, obj: VALUE) -> c_long;
    unsafe fn num2ulong(&self, obj: VALUE) -> c_ulong;
    fn long2num(&self, val: c_long) -> VALUE;
    fn ulong2num(&self, val: c_ulong) -> VALUE;
    fn id2sym(&self, id: ID) -> VALUE;
    unsafe fn sym2id(&self, obj: VALUE) -> ID;
    unsafe fn rb_obj_write(
        &self,
        old: VALUE,
        slot: *mut VALUE,
        young: VALUE,
    ) -> VALUE;
    unsafe fn rb_obj_written(
        &self,
        old: VALUE,
        oldv: VALUE,
        young: VALUE,
    ) -> VALUE;

    // Provided methods
    fn version(&self) -> (u32, u32) { ... }
    unsafe fn bignum_negative_p(&self, obj: VALUE) -> bool { ... }
}

Required Associated Constants

const VERSION_MAJOR: u32

const VERSION_MINOR: u32

Required Methods

unsafe fn rstring_len(&self, obj: VALUE) -> c_long

Get the length of a Ruby string (akin to RSTRING_LEN).

Safety

This function is unsafe because it dereferences a raw pointer to get access to underlying Ruby data. The caller must ensure that the pointer is valid.

unsafe fn rstring_ptr(&self, obj: VALUE) -> *const c_char

Get a pointer to the bytes of a Ruby string (akin to RSTRING_PTR).

Safety

This function is unsafe because it dereferences a raw pointer to get access to underlying Ruby data. The caller must ensure that the pointer is valid.

unsafe fn rarray_len(&self, obj: VALUE) -> c_long

Get the length of a Ruby array (akin to RARRAY_LEN).

Safety

This function is unsafe because it dereferences a raw pointer to get access to underlying Ruby data. The caller must ensure that the pointer is valid.

unsafe fn rarray_const_ptr(&self, obj: VALUE) -> *const VALUE

Get a pointer to the elements of a Ruby array (akin to RARRAY_CONST_PTR).

Safety

This function is unsafe because it dereferences a raw pointer to get access to underlying Ruby data. The caller must ensure that the pointer is valid.

unsafe fn rarray_aref(&self, obj: VALUE, idx: isize) -> VALUE

Get element from array by index (akin to RARRAY_AREF).

Safety

This function is unsafe because it dereferences a raw pointer to get access to underlying Ruby data. The caller must ensure that the pointer is valid and that the index is within bounds.

unsafe fn rarray_aset(&self, obj: VALUE, idx: isize, val: VALUE)

Set element in array by index (akin to RARRAY_ASET).

Includes GC write barrier for safety.

Safety

This function is unsafe because it dereferences a raw pointer to get access to underlying Ruby data. The caller must ensure that the pointer is valid and that the index is within bounds.

unsafe fn rbasic_class(&self, obj: VALUE) -> Option<NonNull<VALUE>>

Get the class from a VALUE which contains an RBasic struct.

VALUE is a valid pointer to a non-immediate object.

Safety

This function is unsafe because it dereferences a raw pointer to get access to underlying RBasic struct. The caller must ensure that the VALUE is a valid pointer to an RBasic struct.

unsafe fn frozen_p(&self, obj: VALUE) -> bool

Checks if the given object is frozen.

VALUE is a valid pointer to a non-immediate object.

Safety

This function is unsafe because it may dereference a raw pointer to get access to underlying RBasic struct. The caller must ensure that the VALUE is a valid pointer to an RBasic struct.

unsafe fn bignum_positive_p(&self, obj: VALUE) -> bool

Tests if a bignum is positive.

Safety

This function is unsafe because it dereferences a raw pointer to get access to underlying RBasic struct. The caller must ensure that the VALUE is a valid pointer to a bignum.

fn special_const_p(&self, value: VALUE) -> bool

Tests if the given value is a special constant.

unsafe fn builtin_type(&self, obj: VALUE) -> ruby_value_type

Queries the type of the object.

Note

The input obj must not be a special constant.

Safety

This function is unsafe because it could dereference a raw pointer when attemping to access the underlying [RBasic] struct.

unsafe fn type_p(&self, obj: VALUE, ty: ruby_value_type) -> bool

Tests if the object’s type is the given type.

Safety

This function is unsafe because it could dereference a raw pointer when attemping to access the underlying [RBasic] struct.

fn nil_p(&self, obj: VALUE) -> bool

Checks if the given object is nil.

fn fixnum_p(&self, obj: VALUE) -> bool

Checks if the given object is a so-called Fixnum.

unsafe fn dynamic_sym_p(&self, obj: VALUE) -> bool

Checks if the given object is a dynamic symbol.

Safety

This function is unsafe because it could dereference a raw pointer when attemping to access the underlying [RBasic] struct.

fn static_sym_p(&self, obj: VALUE) -> bool

Checks if the given object is a static symbol.

unsafe fn symbol_p(&self, obj: VALUE) -> bool

Checks if the given object is a symbol.

Safety

This function is unsafe because it could dereference a raw pointer when attemping to access the underlying [RBasic] struct.

unsafe fn float_type_p(&self, obj: VALUE) -> bool

Checks if the given object is a so-called Flonum.

Safety

This function is unsafe because it could dereference a raw pointer when attemping to access the underlying [RBasic] struct.

unsafe fn integer_type_p(&self, obj: VALUE) -> bool

Checks if the given object is an integer type

Safety

This function is unsafe because it could dereference a raw pointer when attemping to access the underlying [RBasic] struct.

fn flonum_p(&self, obj: VALUE) -> bool

Checks if the given object is a so-called Flonum.

fn immediate_p(&self, obj: VALUE) -> bool

Checks if the given object is an immediate i.e. an object which has no corresponding storage inside of the object space.

fn rb_test(&self, ob: VALUE) -> bool

Emulates Ruby’s “if” statement by testing if the given obj is neither Qnil or Qfalse.

Safety

This function is unsafe because it could dereference a raw pointer when attemping to access the underlying [RBasic] struct.

unsafe fn rb_type(&self, obj: VALUE) -> ruby_value_type

Queries the type of the object. Identical to StableApi.builtin_type, except it can also accept special constants.

Safety

This function is unsafe because it could dereference a raw pointer when attemping to access the underlying [RBasic] struct.

unsafe fn rstring_interned_p(&self, obj: VALUE) -> bool

Check if a Ruby string is interned (akin to RSTRING_FSTR).

Safety

This function is unsafe because it dereferences a raw pointer to get access to underlying flags of the RString. The caller must ensure that the VALUE is a valid pointer to an RString.

fn thread_sleep(&self, duration: Duration)

Blocks the current thread until the given duration has passed.

unsafe fn rtypeddata_p(&self, obj: VALUE) -> bool

Checks if the given object is an RTypedData.

Safety

This function is unsafe because it dereferences a raw pointer to get access to underlying Ruby data. The caller must ensure that the pointer is valid and points to a T_DATA object.

unsafe fn rtypeddata_type(&self, obj: VALUE) -> *const rb_data_type_t

Gets the data type from an RTypedData object.

Safety

This function is unsafe because it dereferences a raw pointer to get access to underlying Ruby data. The caller must ensure that the pointer is valid and points to an RTypedData object.

unsafe fn rtypeddata_get_data(&self, obj: VALUE) -> *mut c_void

Gets the data pointer from an RTypedData object.

Safety

This function is unsafe because it dereferences a raw pointer to get access to underlying Ruby data. The caller must ensure that the pointer is valid and points to an RTypedData object.

unsafe fn rstring_end(&self, obj: VALUE) -> *const c_char

Get pointer to end of string contents (akin to RSTRING_END).

Returns a pointer to the byte after the last character of the string.

Safety

• obj must be a valid Ruby String object

unsafe fn rdata_ptr(&self, obj: VALUE) -> *mut c_void

Get data pointer from RData/TypedData object (akin to DATA_PTR).

Returns the user data pointer stored in an RData or TypedData object.

Safety

• obj must be a valid RData or TypedData object

unsafe fn rb_obj_freeze(&self, obj: VALUE)

Freeze an object (akin to RB_OBJ_FREEZE).

Sets the frozen flag on an object, preventing further modification.

Safety

• obj must be a valid heap-allocated Ruby object

unsafe fn rb_obj_promoted(&self, obj: VALUE) -> bool

Check if object is promoted to old GC generation (akin to RB_OBJ_PROMOTED).

Returns true if the object has been promoted to the old generation in Ruby’s generational GC.

Safety

• obj must be a valid VALUE

unsafe fn rb_obj_promoted_raw(&self, obj: VALUE) -> bool

Raw version assuming FL_ABLE (akin to RB_OBJ_PROMOTED_RAW).

Safety

• obj must be a valid heap-allocated Ruby object (FL_ABLE must be true)

unsafe fn num2dbl(&self, obj: VALUE) -> c_double

Convert Ruby numeric to C double (akin to NUM2DBL).

Works for Float (including Flonum), Fixnum, and other numeric types.

Safety

This function is unsafe because it may dereference a raw pointer to get access to underlying Ruby data. The caller must ensure that the pointer is valid.

fn dbl2num(&self, val: c_double) -> VALUE

Convert C double to Ruby Float VALUE (akin to DBL2NUM).

May return a Flonum (tagged pointer) for small values on 64-bit platforms, or a heap-allocated Float object.

unsafe fn rhash_size(&self, obj: VALUE) -> usize

Get hash size (akin to RHASH_SIZE).

Returns the number of entries in the hash.

Safety

This function is unsafe because it dereferences a raw pointer to get access to underlying Ruby data. The caller must ensure that the pointer is valid and points to a Hash object.

unsafe fn rhash_empty_p(&self, obj: VALUE) -> bool

Check if hash is empty (akin to RHASH_EMPTY_P).

Safety

This function is unsafe because it dereferences a raw pointer to get access to underlying Ruby data. The caller must ensure that the pointer is valid and points to a Hash object.

unsafe fn encoding_get(&self, obj: VALUE) -> c_int

Get encoding index from object (akin to ENCODING_GET).

Returns the encoding index stored in the object’s flags.

Safety

This function is unsafe because it dereferences a raw pointer to get access to underlying Ruby data. The caller must ensure that the pointer is valid and points to an object with encoding (String, Regexp, Symbol).

fn fl_able(&self, obj: VALUE) -> bool

Check if an object can have flags (akin to RB_FL_ABLE).

Returns false for immediate values (nil, true, false, Fixnum, Symbol, Flonum) which don’t have flag storage. Returns true for heap-allocated objects.

fn fix2long(&self, obj: VALUE) -> c_long

Convert Fixnum to long (akin to FIX2LONG).

Extracts the integer value from a Fixnum VALUE.

Safety assumptions

• obj must be a valid Fixnum VALUE

fn fix2ulong(&self, obj: VALUE) -> c_ulong

Convert Fixnum to unsigned long (akin to FIX2ULONG).

Extracts the unsigned integer value from a Fixnum VALUE.

Safety assumptions

• obj must be a valid positive Fixnum VALUE

fn long2fix(&self, val: c_long) -> VALUE

Convert long to Fixnum (akin to LONG2FIX).

Creates a Fixnum VALUE from a long integer.

Safety assumptions

• val must be in the valid Fixnum range

fn fixable(&self, val: c_long) -> bool

Check if long value can be represented as Fixnum (akin to FIXABLE).

Returns true if the value fits in a Fixnum.

fn posfixable(&self, val: c_ulong) -> bool

Check if unsigned long value can be represented as positive Fixnum (akin to POSFIXABLE).

Returns true if the value fits in a positive Fixnum.

unsafe fn num2long(&self, obj: VALUE) -> c_long

Convert Ruby Integer to long (akin to NUM2LONG).

Converts any Ruby Integer (Fixnum or Bignum) to a C long. May raise an exception if the value is out of range.

Safety

• obj must be a valid Integer VALUE
• May call into Ruby runtime (for Bignum conversion)

unsafe fn num2ulong(&self, obj: VALUE) -> c_ulong

Convert Ruby Integer to unsigned long (akin to NUM2ULONG).

Converts any Ruby Integer (Fixnum or Bignum) to a C unsigned long. May raise an exception if the value is out of range or negative.

Safety

• obj must be a valid Integer VALUE
• May call into Ruby runtime (for Bignum conversion)

fn long2num(&self, val: c_long) -> VALUE

Convert long to Ruby Integer (akin to LONG2NUM).

Creates a Ruby Integer (Fixnum or Bignum) from a C long. Uses Fixnum if possible, otherwise allocates a Bignum.

fn ulong2num(&self, val: c_ulong) -> VALUE

Convert unsigned long to Ruby Integer (akin to ULONG2NUM).

Creates a Ruby Integer (Fixnum or Bignum) from a C unsigned long. Uses Fixnum if possible, otherwise allocates a Bignum.

fn id2sym(&self, id: ID) -> VALUE

Convert ID to Symbol (akin to RB_ID2SYM).

Converts an internal ID to its corresponding Symbol VALUE. This is a safe operation - just bit manipulation for static symbols.

unsafe fn sym2id(&self, obj: VALUE) -> ID

Convert Symbol to ID (akin to RB_SYM2ID).

Converts a Symbol VALUE to its internal ID representation.

Safety

• obj must be a valid Symbol VALUE
• For dynamic symbols, this may access the heap

unsafe fn rb_obj_write( &self, old: VALUE, slot: *mut VALUE, young: VALUE, ) -> VALUE

Execute GC write barrier when storing a reference (akin to RB_OBJ_WRITE).

Must be called when storing a VALUE reference from one heap object to another. This is critical for GC correctness - without it, the GC may collect objects that are still referenced.

Safety

• old must be a valid heap-allocated Ruby object
• slot must be a valid pointer to a VALUE within old
• young must be a valid VALUE

unsafe fn rb_obj_written(&self, old: VALUE, oldv: VALUE, young: VALUE) -> VALUE

Declare a write barrier without actually writing (akin to RB_OBJ_WRITTEN).

Use this when you’ve already written a reference but need to inform the GC.

Safety

• old must be a valid heap-allocated Ruby object
• oldv is the previous value (can be any VALUE)
• young must be a valid VALUE that was written

Provided Methods

fn version(&self) -> (u32, u32)

unsafe fn bignum_negative_p(&self, obj: VALUE) -> bool

Tests if a bignum is negative.

Safety

This function is unsafe because it dereferences a raw pointer to get access to underlying RBasic struct. The caller must ensure that the VALUE is a valid pointer to a bignum.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors