Struct magnus::value::Value

source · [−]

#[repr(transparent)]
pub struct Value(_);

Expand description

Ruby’s VALUE type, which can represent any Ruby object.

Implementations

source

impl Value

source

pub fn is_nil(self) -> bool

Returns whether self is Ruby’s nil value.

Examples

use magnus::{eval, 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

pub fn equal<T>(self, other: T) -> Result<bool, Error> where
T: Deref<Target = Value>,

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::{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, 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

pub fn eql<T>(self, other: T) -> Result<bool, Error> where
T: Deref<Target = Value>,

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 or some built-in types, then calling the #== method will be skipped.

Returns Err if #eql? raises.

Examples

use magnus::{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, 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

pub fn class(self) -> RClass

Returns the class that self is an instance of.

Panics

panics if self is Qundef.

Examples

use magnus::{eval, Value};

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

source

pub fn leak(self)

👎 Deprecated since 0.3.0:

please use gc::register_mark_object instead

Registers self as to never be garbage collected.

Examples

use magnus::{eval, RArray};

let ary = eval::<RArray>("[1, 2, 3]").unwrap();
ary.leak();

source

pub fn is_frozen(self) -> bool

Returns whether self is ‘frozen’.

Ruby prevents modifying frozen objects.

Examples

use magnus::{eval, Value};

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

source

pub 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, 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

pub fn freeze(self)

Mark self as frozen.

Examples

use magnus::{eval, RArray};

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

source

pub 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, 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

pub fn funcall<M, A, T>(self, method: M, args: A) -> Result<T, Error> where
 M: Into<Id>,
 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, RArray};

let values = eval::<RArray>(r#"["foo", 1, :bar]"#).unwrap();
let result: String = values.funcall("join", (" & ",)).unwrap();
assert_eq!(result, "foo & 1 & bar");

source

pub fn check_funcall<M, A, T>(
 self,
 method: M,
 args: A
) -> Option<Result<T, Error>> where
 M: Into<Id>,
 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::{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

pub fn block_call<M, A, F, R, T>(
 self,
 method: M,
 args: A,
 block: F
) -> Result<T, Error> where
 M: Into<Id>,
 A: ArgList,
 F: FnMut(&[Value ], Option<Proc>) -> R,
 R: BlockReturn,
 T: TryConvert,

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

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

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 Into<Value>. Returning Err(Error) will raise the error as a Ruby exception.

Examples

use magnus::{eval, 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

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

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.

Examples

use magnus::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

pub 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::{eval, class, Value};

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

source

pub 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::{eval, QTRUE};

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

source

pub fn inspect(self) -> String

Convert self to its Ruby debug representation.

Examples

use magnus::{eval, Symbol, QNIL};

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

source

pub 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::{eval, RHash};

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

source

pub fn is_kind_of<T>(self, class: T) -> bool where
T: Deref<Target = Value> + Module,

Returns whether or not self is an instance of class.

Examples

use magnus::{class, eval, Value};

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

source

pub fn enumeratorize<M, A>(self, method: M, args: A) -> EnumeratorⓘNotable traits for Enumerator`impl Iterator for Enumerator type Item = Result<Value, Error>;` where
M: Into<Symbol>,
A: ArgList,

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

Examples

use magnus::{class, eval, 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);

source

pub fn try_convert<T>(&self) -> Result<T, Error> where
T: TryConvert,

Convert self to the Rust type T.

See the types that TryConvert is implemented on for what this method can convert to.

Examples

use magnus::{eval, Value};

assert_eq!(eval::<Value>("42").unwrap().try_convert::<i64>().unwrap(), 42);
assert_eq!(eval::<Value>("1.23").unwrap().try_convert::<i64>().unwrap(), 1);
assert_eq!(eval::<Value>("1").unwrap().try_convert::<f64>().unwrap(), 1.0);
assert_eq!(eval::<Value>("nil").unwrap().try_convert::<Option<i64>>().unwrap(), None);
assert_eq!(eval::<Value>("42").unwrap().try_convert::<Option<i64>>().unwrap(), Some(42));

Trait Implementations

source

impl Clone for Value

source

fn clone(&self) -> Value

Returns a copy of the value. Read more

1.0.0 · source

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

Performs copy-assignment from source. Read more

source

impl Debug for Value

source

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

Formats the value using the given formatter. Read more

source

impl Default for Value

source

fn default() -> Self

Returns the “default value” for a type. Read more

source

impl Display for Value

source

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

Formats the value using the given formatter. Read more

source