Struct magnus::Range

source ·

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

Expand description

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

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

Implementations§

source §

impl Range

source

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

Return Some(Range) if val is an Range, None otherwise.

Examples

use magnus::eval;

assert!(magnus::Range::from_value(eval("2..7").unwrap()).is_some());
assert!(magnus::Range::from_value(eval("1").unwrap()).is_none());

source

pub fn new<T, U>(beg: T, end: U, excl: bool) -> Result<Self, Error>where
T: Into<Value>,
U: Into<Value>,

Create a new Range.

Returns Err if beg and end are not comparable.

Examples

use magnus::eval;

let range = magnus::Range::new(2, 7, false).unwrap();
let res: bool = eval!("range == (2..7)", range).unwrap();
assert!(res);

use magnus::eval;

let range = magnus::Range::new(2, 7, true).unwrap();
let res: bool = eval!("range == (2...7)", range).unwrap();
assert!(res);

source

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

Return the value that defines the beginning of the range, converting it to a T.

Errors if the conversion fails.

Examples

use magnus::eval;

let range = eval::<magnus::Range>("2..7").unwrap();
assert_eq!(range.beg::<i64>().unwrap(), 2);

source

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

Return the value that defines the end of the range, converting it to a T.

Errors if the conversion fails.

Examples

use magnus::eval;

let range = eval::<magnus::Range>("2..7").unwrap();
assert_eq!(range.end::<i64>().unwrap(), 7);

source

pub fn excl(self) -> bool

Returns true if the range excludes its end value, false if the end value is included.

Examples

use magnus::eval;

let range = eval::<magnus::Range>("2..7").unwrap();
assert_eq!(range.excl(), false);

source

pub fn beg_len(self, length: usize) -> Result<(usize, usize), Error>

Given a total length, returns a beginning index and length of the range within that total length.

Returns Err if self is a non-numerical range, or the range is out of range for length.

Examples

use magnus::eval;

let range = eval::<magnus::Range>("2..").unwrap();
assert_eq!(range.beg_len(10).unwrap(), (2, 8));

use magnus::eval;

let range = eval::<magnus::Range>("..7").unwrap();
assert_eq!(range.beg_len(10).unwrap(), (0, 8));

use magnus::eval;

let range = eval::<magnus::Range>("-3..-1").unwrap();
assert_eq!(range.beg_len(10).unwrap(), (7, 3));

source

pub fn to_range_with_len(self, length: usize) -> Result<StdRange<usize>, Error>

Given a total length, converts the Ruby Range to a Rust std::ops::Range.

length is required to account for Ruby conventions such as a range from -2..-1 returning the end of a collection.

Returns Err if self is a non-numerical range, or the range is out of range for length.

Examples

use magnus::eval;

// Ruby's .. range is inclusive
let range = eval::<magnus::Range>("2..7").unwrap();
// Rust's .. range in exclusive
assert_eq!(range.to_range_with_len(10).unwrap(), 2..8);

use magnus::eval;

let range = eval::<magnus::Range>("2..").unwrap();
assert_eq!(range.to_range_with_len(10).unwrap(), 2..10);

use magnus::eval;

let range = eval::<magnus::Range>("..7").unwrap();
assert_eq!(range.to_range_with_len(10).unwrap(), 0..8);

use magnus::eval;

let range = eval::<magnus::Range>("-3..-1").unwrap();
assert_eq!(range.to_range_with_len(10).unwrap(), 7..10);

Methods from Deref<Target = Value>§

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