Struct magnus::block::Proc

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

Wrapper type for a Value known to be an instance of Ruby’s Proc class.

All Value methods should be available on this type through Deref, but some may be missed by this documentation.

Implementations

impl Proc

pub fn from_value(val: Value) -> Option<Self>

Return Some(Proc) if val is a Proc, None otherwise.

pub fn new<R>(block: fn(_: &[Value], _: Option<Proc>) -> R) -> Selfwhere
    R: BlockReturn,

Create a new Proc.

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 from_fn.

Examples

use magnus::{block::Proc, eval};

let proc = Proc::new(|args, _block| {
    let acc = args.get(0).unwrap().try_convert::<i64>()?;
    let i = args.get(1).unwrap().try_convert::<i64>()?;
    Ok(acc + i)
});

let res: bool = eval!("proc.call(1, 2) == 3", proc).unwrap();
assert!(res);

let res: bool = eval!("[1, 2, 3, 4, 5].inject(&proc) == 15", proc).unwrap();
assert!(res);

pub fn from_fn<F, R>(block: F) -> Selfwhere
    F: 'static + Send + FnMut(&[Value], Option<Proc>) -> R,
    R: BlockReturn,

Create a new Proc.

See also Proc::new, which is more efficient when block is a function or closure that does not capture any variables.

Examples

use magnus::{block::Proc, eval};

let proc = Proc::from_fn(|args, _block| {
    let acc = args.get(0).unwrap().try_convert::<i64>()?;
    let i = args.get(1).unwrap().try_convert::<i64>()?;
    Ok(acc + i)
});

let res: bool = eval!("proc.call(1, 2) == 3", proc).unwrap();
assert!(res);

let res: bool = eval!("[1, 2, 3, 4, 5].inject(&proc) == 15", proc).unwrap();
assert!(res);

pub fn call<A, T>(self, args: A) -> Result<T, Error>where
    A: RArrayArgList,
    T: TryConvert,

Call the proc with args.

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

pub fn arity(self) -> i64

Returns the number of arguments self takes.

If self takes no arguments, returns 0. If self takes only required arguments, returns the number of required arguments. If self is a lambda and has optional arguments, or is not a lambda and takes a splat argument, returns -n-1, where n is the number of required arguments. If self is not a lambda, and takes a finite number of optional arguments, returns the number of required arguments. Keyword arguments are considered as a single additional argument, that argument being required if any keyword argument is required.

Examples

use magnus::{block::Proc, eval};

let proc = eval::<Proc>("proc {nil}", ).unwrap();
assert_eq!(proc.arity(), 0);

let proc = eval::<Proc>("proc {|a| a + 1}", ).unwrap();
assert_eq!(proc.arity(), 1);

let proc = eval::<Proc>("proc {|a, b| a + b}", ).unwrap();
assert_eq!(proc.arity(), 2);

let proc = eval::<Proc>("proc {|*args| args.sum}", ).unwrap();
assert_eq!(proc.arity(), -1);

pub fn is_lambda(self) -> bool

Returns whether or not self is a lambda.

Examples

use magnus::{block::Proc, eval};

let proc = eval::<Proc>("proc {|a, b| a + b}", ).unwrap();
assert!(!proc.is_lambda());

let proc = eval::<Proc>("lambda {|a, b| a + b}", ).unwrap();
assert!(proc.is_lambda());

Methods from Deref<Target = Value>

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");

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 never give Ruby a chance to free the string.
let s = unsafe { value.classname() }.into_owned();
assert_eq!(s, "Hash");

Trait Implementations

impl Clone for Proc

fn clone(&self) -> Proc

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Proc

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

Formats the value using the given formatter.

impl Deref for Proc

type Target = Value

The resulting type after dereferencing.

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

Dereferences the value.

impl Display for Proc

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

Formats the value using the given formatter.

impl From<Proc> for Value

fn from(val: Proc) -> Self

Converts to this type from the input type.

impl Object for Proc

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: Into<Id>,
    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: Into<Id>,
    U: Into<Value>,

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 TryConvert for Proc

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

Convert val into Self.

impl Copy for Proc

impl ReprValue for Proc