Trait magnus::value::ReprValue

source · 
pub trait ReprValue: ReprValue {

Show 22 methods    // Provided methods
    fn as_value(self) -> Value { ... }
    fn is_nil(self) -> bool { ... }
    fn equal<T>(self, other: T) -> Result<bool, Error>
       where T: ReprValue { ... }
    fn eql<T>(self, other: T) -> Result<bool, Error>
       where T: ReprValue { ... }
    fn hash(self) -> Result<Integer, Error> { ... }
    fn class(self) -> RClass { ... }
    fn is_frozen(self) -> bool { ... }
    fn check_frozen(self) -> Result<(), Error> { ... }
    fn freeze(self) { ... }
    fn to_bool(self) -> bool { ... }
    fn funcall<M, A, T>(self, method: M, args: A) -> Result<T, Error>
       where M: IntoId,
             A: ArgList,
             T: TryConvert { ... }
    fn funcall_public<M, A, T>(self, method: M, args: A) -> Result<T, Error>
       where M: IntoId,
             A: ArgList,
             T: TryConvert { ... }
    fn check_funcall<M, A, T>(
        self,
        method: M,
        args: A
    ) -> Option<Result<T, Error>>
       where M: IntoId,
             A: ArgList,
             T: TryConvert { ... }
    fn funcall_with_block<M, A, T>(
        self,
        method: M,
        args: A,
        block: Proc
    ) -> Result<T, Error>
       where M: IntoId,
             A: ArgList,
             T: TryConvert { ... }
    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 { ... }
    fn respond_to<M>(
        self,
        method: M,
        include_private: bool
    ) -> Result<bool, Error>
       where M: IntoId { ... }
    fn to_r_string(self) -> Result<RString, Error> { ... }
    unsafe fn to_s(&self) -> Result<Cow<'_, str>, Error> { ... }
    fn inspect(self) -> String { ... }
    unsafe fn classname(&self) -> Cow<'_, str> { ... }
    fn is_kind_of<T>(self, class: T) -> bool
       where T: ReprValue + Module { ... }
    fn enumeratorize<M, A>(self, method: M, args: A) -> Enumerator ⓘ
       where M: IntoSymbol,
             A: ArgList { ... }

}
Expand description

Marker trait for types that have the same representation as Value.

Types that are ReprValue can be safely transmuted to Value.

Provided Methods§

source

fn as_value(self) -> Value

Return self as a Value.

source

fn is_nil(self) -> bool

Returns whether self is Ruby’s nil value.

Examples
use magnus::{eval, prelude::*, Value};

assert!(eval::<Value>("nil").unwrap().is_nil());
assert!(!eval::<Value>("Object.new").unwrap().is_nil());
assert!(!eval::<Value>("0").unwrap().is_nil());
assert!(!eval::<Value>("[]").unwrap().is_nil());
source

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

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

Ruby optimises this check if self and other are the same object or some built-in types, then calling the #== method will be skipped.

Returns Err if #== raises.

Examples
use magnus::{prelude::*, Integer, RArray};

let a = RArray::from_vec(vec![1, 2, 3]);
let b = RArray::from_vec(vec![1, 2, 3]);
let c = RArray::from_vec(vec![4, 5, 6]);
let d = Integer::from_i64(1);
assert!(a.equal(a).unwrap());
assert!(a.equal(b).unwrap());
assert!(!a.equal(c).unwrap());
assert!(!a.equal(d).unwrap());
use magnus::{eval, prelude::*, Value};

let (a, b): (Value, Value) = eval!(
    "
    class Example
      def ==(other)
        raise
      end
    end
    [Example.new, Example.new]
"
)
.unwrap();

assert!(a.equal(b).is_err());
source

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

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

See Value::equal for the equivalent of the #== method.

Ruby optimises this check if self and other are the same object for some built-in types, then calling the #== method will be skipped.

Returns Err if #eql? raises.

Examples
use magnus::{prelude::*, Integer, RArray};

let a = RArray::from_vec(vec![1, 2, 3]);
let b = RArray::from_vec(vec![1, 2, 3]);
let c = RArray::from_vec(vec![4, 5, 6]);
let d = Integer::from_i64(1);
assert!(a.eql(a).unwrap());
assert!(a.eql(b).unwrap());
assert!(!a.eql(c).unwrap());
assert!(!a.eql(d).unwrap());
use magnus::{eval, prelude::*, Value};

let (a, b): (Value, Value) = eval!(
    "
      class Example
        def eql?(other)
          raise
        end
      end
      [Example.new, Example.new]
    "
)
.unwrap();

assert!(a.eql(b).is_err());
source

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

Returns an integer non-uniquely identifying self.

The return value is not stable between different Ruby processes.

Ruby guarantees the return value will be in the range of a C long, this is usually equivalent to a i64, though will be i32 on Windows.

Ruby built-in classes will not error, but it is possible for badly behaving 3rd party classes (or collections such as Array containing them) to error in this function.

Examples
use magnus::{prelude::*, RString};

assert!(RString::new("test")
    .hash()
    .unwrap()
    .equal(RString::new("test").hash().unwrap())
    .unwrap());
source

fn class(self) -> RClass

Returns the class that self is an instance of.

Panics

panics if self is Qundef.

Examples
use magnus::{eval, prelude::*, Value};

assert_eq!(
    eval::<Value>("true").unwrap().class().inspect(),
    "TrueClass"
);
assert_eq!(eval::<Value>("[1,2,3]").unwrap().class().inspect(), "Array");
source

fn is_frozen(self) -> bool

Returns whether self is ‘frozen’.

Ruby prevents modifying frozen objects.

Examples
use magnus::{eval, prelude::*, Value};

assert!(eval::<Value>(":foo").unwrap().is_frozen());
assert!(eval::<Value>("42").unwrap().is_frozen());
assert!(!eval::<Value>("[]").unwrap().is_frozen());
source

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

Returns an error if self is ‘frozen’.

Useful for checking if an object is frozen in a function that would modify it.

Examples
use magnus::{eval, prelude::*, Error, Value};

fn mutate(val: Value) -> Result<(), Error> {
    val.check_frozen()?;

    // ...
    Ok(())
}

assert!(mutate(eval("Object.new").unwrap()).is_ok());
assert!(mutate(eval(":foo").unwrap()).is_err());
source

fn freeze(self)

Mark self as frozen.

Examples
use magnus::{prelude::*, RArray};

let ary = RArray::new();
assert!(!ary.is_frozen());
ary.freeze();
assert!(ary.is_frozen());
source

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.

Examples
use magnus::{eval, prelude::*, Value};

assert!(!eval::<Value>("false").unwrap().to_bool());
assert!(!eval::<Value>("nil").unwrap().to_bool());

assert!(eval::<Value>("true").unwrap().to_bool());
assert!(eval::<Value>("0").unwrap().to_bool());
assert!(eval::<Value>("[]").unwrap().to_bool());
assert!(eval::<Value>(":foo").unwrap().to_bool());
assert!(eval::<Value>("Object.new").unwrap().to_bool());
source

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.

Returns Ok(T) if the method returns without error and the return value converts to a T, or returns Err if the method raises or the conversion fails.

Examples
use magnus::{eval, prelude::*, RArray};

let values = eval::<RArray>(r#"["foo", 1, :bar]"#).unwrap();
let result: String = values.funcall("join", (" & ",)).unwrap();
assert_eq!(result, "foo & 1 & bar");
use magnus::{eval, kwargs, prelude::*, RObject};

let object: RObject = eval!(
    r#"
    class Adder
      def add(a, b, c:)
        a + b + c
      end
    end

    Adder.new
"#
)
.unwrap();

let result: i32 = object.funcall("add", (1, 2, kwargs!("c" => 3))).unwrap();
assert_eq!(result, 6);
source

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.

Returns Ok(T) if the method returns without error and the return value converts to a T, or returns Err if the method raises or the conversion fails.

Examples
use magnus::{eval, prelude::*, Error, RObject, Symbol};

let object: RObject = eval!(
    r#"
    class Foo
      def bar
        :bar
      end

      private

      def baz
        :baz
      end
    end

    Foo.new
"#
)
.unwrap();

let result: Symbol = object.funcall_public("bar", ()).unwrap();
assert_eq!(result.name().unwrap(), "bar");

let result: Result<Symbol, Error> = object.funcall_public("baz", ());
assert!(result.is_err());
source

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.

Returns Some(Ok(T)) if the method exists and returns without error, None if it does not exist, or Some(Err) if an exception was raised.

Examples
use magnus::{prelude::*, Float, Integer, RString};

let val = Float::from_f64(1.23);
let res: Integer = val.check_funcall("to_int", ()).unwrap().unwrap();
assert_eq!(res.to_i64().unwrap(), 1);

let val = RString::new("1.23");
let res: Option<Result<Integer, _>> = val.check_funcall("to_int", ());
assert!(res.is_none());
source

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.

Similar to funcall, but passes block as a Ruby block to the method.

See also block_call.

Examples
use magnus::{block::Proc, eval, prelude::*, RArray, Value};

let values = eval::<RArray>(r#"["foo", 1, :bar]"#).unwrap();
let block = Proc::new(|args, _block| args.first().unwrap().to_r_string());
let _: Value = values.funcall_with_block("map!", (), block).unwrap();
assert_eq!(values.to_vec::<String>().unwrap(), vec!["foo", "1", "bar"]);
source

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.

Similar to funcall, but passes block as a Ruby block to the method.

As block is a function pointer, only functions and closures that do not capture any variables are permitted. For more flexibility (at the cost of allocating) see Proc::from_fn and funcall_with_block.

The function passed as block will receive values yielded to the block as a slice of Values, plus Some(Proc) if the block itself was called with a block, or None otherwise.

The block function may return any R or Result<R, Error> where R implements IntoValue. Returning Err(Error) will raise the error as a Ruby exception.

Examples
use magnus::{eval, prelude::*, RArray, Value};

let values = eval::<RArray>(r#"["foo", 1, :bar]"#).unwrap();
let _: Value = values
    .block_call("map!", (), |args, _block| {
        args.first().unwrap().to_r_string()
    })
    .unwrap();
assert_eq!(values.to_vec::<String>().unwrap(), vec!["foo", "1", "bar"]);
source

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.

The include_private agument controls whether self’s private methods are checked. If false they are not, if true they are.

See also Value::check_funcall.

Examples
use magnus::{prelude::*, RString};

let s = RString::new("example");
assert!(s.respond_to("to_str", false).unwrap());
assert!(!s.respond_to("puts", false).unwrap());
assert!(s.respond_to("puts", true).unwrap());
assert!(!s.respond_to("non_existant", false).unwrap());
assert!(!s.respond_to("non_existant", true).unwrap());
source

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

Convert self to a Ruby String.

If self is already a String is it wrapped as a RString, otherwise the Ruby to_s method is called.

Examples
use magnus::{class, eval, prelude::*, Value};

let value = eval::<Value>("[]").unwrap();
assert!(value.to_r_string().unwrap().is_kind_of(class::string()));
source

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

Convert self to a Rust string.

Safety

This may return a direct view of memory owned and managed by Ruby. Ruby may modify or free the memory backing the returned str, the caller must ensure this does not happen.

This can be used safely by immediately calling into_owned on the return value.

Examples
use magnus::{prelude::*, IntoValue};

let value = true.into_value();
// safe as we never give Ruby a chance to free the string.
let s = unsafe { value.to_s() }.unwrap().into_owned();
assert_eq!(s, "true");
source

fn inspect(self) -> String

Convert self to its Ruby debug representation.

Examples
use magnus::{prelude::*, IntoValue, Symbol};

assert_eq!(().into_value().inspect(), "nil");
assert_eq!(Symbol::new("foo").inspect(), ":foo");
source

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

Return the name of self’s class.

Safety

Ruby may modify or free the memory backing the returned str, the caller must ensure this does not happen.

This can be used safely by immediately calling into_owned on the return value.

Examples
use magnus::{prelude::*, RHash};

let value = RHash::new();
// safe as we never give Ruby a chance to free the string.
let s = unsafe { value.classname() }.into_owned();
assert_eq!(s, "Hash");
source

fn is_kind_of<T>(self, class: T) -> boolwhere T: ReprValue + Module,

Returns whether or not self is an instance of class.

Examples
use magnus::{class, eval, prelude::*, Value};

let value = eval::<Value>("[]").unwrap();
assert!(value.is_kind_of(class::array()));
source

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.

Examples
use magnus::{class, prelude::*, r_string};

let s = r_string!("foo\\bar\\baz");
let mut i = 0;
for line in s.enumeratorize("each_line", ("\\",)) {
    assert!(line.unwrap().is_kind_of(class::string()));
    i += 1;
}
assert_eq!(i, 3);

Implementors§