Struct magnus::typed_data::Obj

pub struct Obj<T> { /* private fields */ }

A Ruby Object wrapping a Rust type T.

This is a Value pointer to a RTypedData struct, Ruby’s internal representation of objects that wrap foreign types. Unlike RTypedData it tracks the Rust type it should contains and errors early in TryConvert if types don’t match, rather than on Obj::get.

See the ReprValue and Object traits for additional methods available on this type. See Ruby for methods to create a typed_data::Obj.

Implementations

impl<T> Obj<T>

where T: TypedData,

pub fn wrap(data: T) -> Self

Wrap the Rust type T in a Ruby object.

Panics

Panics if called from a non-Ruby thread. See Ruby::obj_wrap for the non-panicking version.

Examples

use magnus::{class, define_class, prelude::*, typed_data};

#[magnus::wrap(class = "Point")]
struct Point {
    x: isize,
    y: isize,
}

let point_class = define_class("Point", class::object()).unwrap();

let value = typed_data::Obj::wrap(Point { x: 4, y: 2 });
assert!(value.is_kind_of(point_class));

pub fn wrap_as(data: T, class: RClass) -> Self

Wrap the Rust type T in a Ruby object that is an instance of the given class.

See also TypedData::class_for.

Panics

Panics if class is not a subclass of <T as TypedData>::class(), or if called from a non-Ruby thread. See Ruby::obj_wrap_as for a version that can not be called from a non-Ruby thread, so will not panic for that reason.

Examples

use magnus::{class, define_class, prelude::*, typed_data};

#[magnus::wrap(class = "Point")]
struct Point {
    x: isize,
    y: isize,
}

let point_class = define_class("Point", class::object()).unwrap();
let point_sub_class = define_class("SubPoint", point_class).unwrap();

let value = typed_data::Obj::wrap_as(Point { x: 4, y: 2 }, point_sub_class);
assert!(value.is_kind_of(point_sub_class));
assert!(value.is_kind_of(point_class));

Allowing a wrapped type to be subclassed from Ruby:

(note, in this example Point does not have and does not call the initialize method, subclasses would need to override the class new method rather than initialize)

use magnus::{
    class, define_class, eval, function, method, prelude::*, typed_data, RClass, Value,
};

#[magnus::wrap(class = "Point")]
struct Point {
    x: isize,
    y: isize,
}

impl Point {
    fn new(class: RClass, x: isize, y: isize) -> typed_data::Obj<Self> {
        typed_data::Obj::wrap_as(Self { x, y }, class)
    }
}
let point_class = define_class("Point", class::object()).unwrap();
point_class
    .define_singleton_method("new", method!(Point::new, 2))
    .unwrap();
point_class
    .define_singleton_method("inherited", function!(RClass::undef_default_alloc_func, 1))
    .unwrap();

let value: Value = eval(
    r#"
      class SubPoint < Point
      end
      SubPoint.new(4, 2)
    "#,
)
.unwrap();

assert!(value.is_kind_of(class::object().const_get::<_, RClass>("SubPoint").unwrap()));
assert!(value.is_kind_of(point_class));

Trait Implementations

impl<T> Clone for Obj<T>

where T: TypedData,

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T> Debug for Obj<T>

where T: TypedData,

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

Formats the value using the given formatter.

impl<T> Deref for Obj<T>

where T: TypedData,

fn deref(&self) -> &Self::Target

Dereference to the Rust type wrapped in the Ruby object self.

Examples

use magnus::{class, define_class, typed_data};

#[magnus::wrap(class = "Point")]
#[derive(Debug, PartialEq, Eq)]
struct Point {
    x: isize,
    y: isize,
}

define_class("Point", class::object()).unwrap();
let value = typed_data::Obj::wrap(Point { x: 4, y: 2 });

assert_eq!(&*value, &Point { x: 4, y: 2 });

type Target = T

The resulting type after dereferencing.

impl<T> Display for Obj<T>

where T: TypedData,

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

Formats the value using the given formatter.

impl<T> From<Obj<T>> for RTypedData

where T: TypedData,

fn from(val: Obj<T>) -> Self

Converts to this type from the input type.

impl<T> IntoValue for Obj<T>

where T: TypedData,

fn into_value_with(self, handle: &Ruby) -> Value

Convert self into Value.

fn into_value(self) -> Value

Convert self into Value.

unsafe fn into_value_unchecked(self) -> Value

Convert self into Value.

impl<T> Object for Obj<T>

where T: TypedData,

fn define_singleton_method<M>(self, name: &str, func: M) -> Result<(), Error>

where M: Method,

Define a singleton method in self’s scope.

fn ivar_get<T, U>(self, name: T) -> Result<U, Error>

where T: IntoId, U: TryConvert,

Get the value for the instance variable name within self’s scope.

fn ivar_set<T, U>(self, name: T, value: U) -> Result<(), Error>

where T: IntoId, U: IntoValue,

Set the value for the instance variable name within self’s scope.

fn singleton_class(self) -> Result<RClass, Error>

Finds or creates the singleton class of self.

fn extend_object(self, module: RModule) -> Result<(), Error>

Extend self with module.

impl<T> ReprValue for Obj<T>

where T: TypedData,

fn as_value(self) -> Value

Return self as a Value.

fn is_nil(self) -> bool

Returns whether self is Ruby’s nil value.

fn equal<T>(self, other: T) -> Result<bool, Error>

where T: ReprValue,

Checks for equality, delegating to the Ruby method #==.

fn eql<T>(self, other: T) -> Result<bool, Error>

where T: ReprValue,

Checks for equality, delegating to the Ruby method #eql?.

fn hash(self) -> Result<Integer, Error>

Returns an integer non-uniquely identifying self.

fn class(self) -> RClass

Returns the class that self is an instance of.

fn is_frozen(self) -> bool

Returns whether self is ‘frozen’.

fn check_frozen(self) -> Result<(), Error>

Returns an error if self is ‘frozen’.

fn freeze(self)

Mark self as frozen.

fn to_bool(self) -> bool

Convert self to a bool, following Ruby’s rules of false and nil as boolean false and everything else boolean true.

fn funcall<M, A, T>(self, method: M, args: A) -> Result<T, Error>

where M: IntoId, A: ArgList, T: TryConvert,

Call the method named method on self with args.

fn funcall_public<M, A, T>(self, method: M, args: A) -> Result<T, Error>

where M: IntoId, A: ArgList, T: TryConvert,

Call the public method named method on self with args.

fn check_funcall<M, A, T>(self, method: M, args: A) -> Option<Result<T, Error>>

where M: IntoId, A: ArgList, T: TryConvert,

If self responds to the method named method, call it with args.

fn funcall_with_block<M, A, T>( self, method: M, args: A, block: Proc ) -> Result<T, Error>

where M: IntoId, A: ArgList, T: TryConvert,

Call the method named method on self with args and block.

fn block_call<M, A, R, T>( self, method: M, args: A, block: fn(_: &[Value], _: Option<Proc>) -> R ) -> Result<T, Error>

where M: IntoId, A: ArgList, R: BlockReturn, T: TryConvert,

Call the method named method on self with args and block.

fn respond_to<M>(self, method: M, include_private: bool) -> Result<bool, Error>

where M: IntoId,

Check if self responds to the given Ruby method.

fn to_r_string(self) -> Result<RString, Error>

Convert self to a Ruby String.

unsafe fn to_s(&self) -> Result<Cow<'_, str>, Error>

Convert self to a Rust string.

fn inspect(self) -> String

Convert self to its Ruby debug representation.

unsafe fn classname(&self) -> Cow<'_, str>

Return the name of self’s class.

fn is_kind_of<T>(self, class: T) -> bool

where T: ReprValue + Module,

Returns whether or not self is an instance of class.

fn enumeratorize<M, A>(self, method: M, args: A) -> Enumerator

where M: IntoSymbol, A: ArgList,

Generate an Enumerator from method on self, passing args to method.

impl<T> TryConvert for Obj<T>

where T: TypedData,

fn try_convert(val: Value) -> Result<Self, Error>

Convert val into Self.

impl<T> Copy for Obj<T>

where T: TypedData,