Skip to content

Commit

Permalink
doc example tweaks
Browse files Browse the repository at this point in the history
  • Loading branch information
@matsadler
matsadler committed May 8, 2023
1 parent 7cd2067 commit 69edc69
Show file tree
Hide file tree
Showing 5 changed files with 87 additions and 44 deletions.
2 changes: 1 addition & 1 deletion src/binding.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -142,7 +142,7 @@ impl Binding {
/// ```
#[deprecated(
since = "0.6.0",
note = "Please use `value.funcall(\"local_variable_set\", (name,))` instead."
note = "Please use `value.funcall(\"local_variable_set\", (name, val))` instead."
)]
pub fn local_variable_set<N, T>(self, name: N, val: T)
where
Expand Down
22 changes: 22 additions & 0 deletions src/r_typed_data.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,28 @@ pub struct RTypedData(NonZeroValue);

impl RTypedData {
/// Return `Some(RTypedData)` if `val` is a `RTypedData`, `None` otherwise.
///
/// # Examples
///
/// ```
/// use magnus::{class, define_class, eval, function, prelude::*, RTypedData};
/// # let _cleanup = unsafe { magnus::embed::init() };
///
/// #[magnus::wrap(class = "Point")]
/// struct Point {
/// x: isize,
/// y: isize,
/// }
///
/// let point_class = define_class("Point", class::object()).unwrap();
/// point_class
/// .define_singleton_method("new", function!(|x, y| Point { x, y }, 2))
/// .unwrap();
///
/// assert!(RTypedData::from_value(eval(r#"Point.new(1, 2)"#).unwrap()).is_some());
/// assert!(RTypedData::from_value(eval(r#"Object.new"#).unwrap()).is_none());
/// # let _ = Point { x: 1, y: 2 }.x + Point { x: 3, y: 4 }.y;
/// ```
#[inline]
pub fn from_value(val: Value) -> Option<Self> {
unsafe {
Expand Down
30 changes: 14 additions & 16 deletions src/range.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -83,21 +83,19 @@ impl Range {
/// # Examples
///
/// ```
/// use magnus::eval;
/// use magnus::rb_assert;
/// # let _cleanup = unsafe { magnus::embed::init() };
///
/// let range = magnus::Range::new(2, 7, false).unwrap();
/// let res: bool = eval!("range == (2..7)", range).unwrap();
/// assert!(res);
/// rb_assert!("range == (2..7)", range);
/// ```
///
/// ```
/// use magnus::eval;
/// use magnus::rb_assert;
/// # let _cleanup = unsafe { magnus::embed::init() };
///
/// let range = magnus::Range::new(2, 7, true).unwrap();
/// let res: bool = eval!("range == (2...7)", range).unwrap();
/// assert!(res);
/// rb_assert!("range == (2...7)", range);
/// ```
#[cfg(feature = "friendly-api")]
#[inline]
Expand All @@ -120,7 +118,7 @@ impl Range {
/// use magnus::eval;
/// # let _cleanup = unsafe { magnus::embed::init() };
///
/// let range = eval::<magnus::Range>("2..7").unwrap();
/// let range: magnus::Range = eval("2..7").unwrap();
/// assert_eq!(range.beg::<i64>().unwrap(), 2);
/// ```
pub fn beg<T>(self) -> Result<T, Error>
Expand All @@ -141,7 +139,7 @@ impl Range {
/// use magnus::eval;
/// # let _cleanup = unsafe { magnus::embed::init() };
///
/// let range = eval::<magnus::Range>("2..7").unwrap();
/// let range: magnus::Range = eval("2..7").unwrap();
/// assert_eq!(range.end::<i64>().unwrap(), 7);
/// ```
pub fn end<T>(self) -> Result<T, Error>
Expand All @@ -160,7 +158,7 @@ impl Range {
/// use magnus::eval;
/// # let _cleanup = unsafe { magnus::embed::init() };
///
/// let range = eval::<magnus::Range>("2..7").unwrap();
/// let range: magnus::Range = eval("2..7").unwrap();
/// assert_eq!(range.excl(), false);
/// ```
pub fn excl(self) -> bool {
Expand All @@ -179,7 +177,7 @@ impl Range {
/// use magnus::eval;
/// # let _cleanup = unsafe { magnus::embed::init() };
///
/// let range = eval::<magnus::Range>("2..").unwrap();
/// let range: magnus::Range = eval("2..").unwrap();
/// assert_eq!(range.beg_len(10).unwrap(), (2, 8));
/// ```
///
Expand All @@ -188,7 +186,7 @@ impl Range {
/// # let _cleanup = unsafe { magnus::embed::init() };
///
/// # #[cfg(ruby_gte_2_7)]
/// let range = eval::<magnus::Range>("..7").unwrap();
/// let range: magnus::Range = eval("..7").unwrap();
/// # #[cfg(ruby_gte_2_7)]
/// assert_eq!(range.beg_len(10).unwrap(), (0, 8));
/// ```
Expand All @@ -197,7 +195,7 @@ impl Range {
/// use magnus::eval;
/// # let _cleanup = unsafe { magnus::embed::init() };
///
/// let range = eval::<magnus::Range>("-3..-1").unwrap();
/// let range: magnus::Range = eval("-3..-1").unwrap();
/// assert_eq!(range.beg_len(10).unwrap(), (7, 3));
/// ```
pub fn beg_len(self, length: usize) -> Result<(usize, usize), Error> {
Expand Down Expand Up @@ -231,7 +229,7 @@ impl Range {
/// # let _cleanup = unsafe { magnus::embed::init() };
///
/// // Ruby's .. range is inclusive
/// let range = eval::<magnus::Range>("2..7").unwrap();
/// let range: magnus::Range = eval("2..7").unwrap();
/// // Rust's .. range in exclusive
/// assert_eq!(range.to_range_with_len(10).unwrap(), 2..8);
/// ```
Expand All @@ -240,7 +238,7 @@ impl Range {
/// use magnus::eval;
/// # let _cleanup = unsafe { magnus::embed::init() };
///
/// let range = eval::<magnus::Range>("2..").unwrap();
/// let range: magnus::Range = eval("2..").unwrap();
/// assert_eq!(range.to_range_with_len(10).unwrap(), 2..10);
/// ```
///
Expand All @@ -249,7 +247,7 @@ impl Range {
/// # let _cleanup = unsafe { magnus::embed::init() };
///
/// # #[cfg(ruby_gte_2_7)]
/// let range = eval::<magnus::Range>("..7").unwrap();
/// let range: magnus::Range = eval("..7").unwrap();
/// # #[cfg(ruby_gte_2_7)]
/// assert_eq!(range.to_range_with_len(10).unwrap(), 0..8);
/// ```
Expand All @@ -258,7 +256,7 @@ impl Range {
/// use magnus::eval;
/// # let _cleanup = unsafe { magnus::embed::init() };
///
/// let range = eval::<magnus::Range>("-3..-1").unwrap();
/// let range: magnus::Range = eval("-3..-1").unwrap();
/// assert_eq!(range.to_range_with_len(10).unwrap(), 7..10);
/// ```
pub fn to_range_with_len(self, length: usize) -> Result<StdRange<usize>, Error> {
Expand Down
42 changes: 36 additions & 6 deletions src/symbol.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -79,12 +79,11 @@ impl Symbol {
/// # Examples
///
/// ```
/// use magnus::{eval, Symbol};
/// use magnus::{rb_assert, Symbol};
/// # let _cleanup = unsafe { magnus::embed::init() };
///
/// let sym = Symbol::new("example");
/// let result: bool = eval!(":example == sym", sym).unwrap();
/// assert!(result);
/// rb_assert!(":example == sym", sym);
/// ```
#[cfg(feature = "friendly-api")]
#[inline]
Expand Down Expand Up @@ -170,13 +169,12 @@ impl Symbol {
/// # Examples
///
/// ```
/// use magnus::{eval, Symbol};
/// use magnus::{rb_assert, Symbol};
/// # let _cleanup = unsafe { magnus::embed::init() };
///
/// let sym = Symbol::new("example");
/// let static_sym = sym.to_static();
/// let res: bool = eval!("sym == static_sym", sym, static_sym).unwrap();
/// assert!(res);
/// rb_assert!("sym == static_sym", sym, static_sym);
/// ```
pub fn to_static(self) -> StaticSymbol {
if let Some(sym) = StaticSymbol::from_value(self.as_value()) {
Expand Down Expand Up @@ -211,6 +209,16 @@ pub trait IntoSymbol: Sized {
///
/// Panics if called from a non-Ruby thread. See
/// [`IntoSymbol::into_symbol_with`] for the non-panicking version.
///
/// # Examples
///
/// ```
/// use magnus::{rb_assert, symbol::IntoSymbol};
/// # let _cleanup = unsafe { magnus::embed::init() };
///
/// let sym = "example".into_symbol();
/// rb_assert!("sym == :example", sym);
/// ```
#[cfg(feature = "friendly-api")]
#[inline]
fn into_symbol(self) -> Symbol {
Expand All @@ -222,11 +230,33 @@ pub trait IntoSymbol: Sized {
/// # Safety
///
/// This method should only be called from a Ruby thread.
///
/// # Examples
///
/// ```
/// use magnus::{rb_assert, symbol::IntoSymbol};
/// # let _cleanup = unsafe { magnus::embed::init() };
///
/// // only safe when called from a Ruby thread
/// let sym = unsafe { "example".into_symbol_unchecked() };
/// rb_assert!("sym == :example", sym);
/// ```
unsafe fn into_symbol_unchecked(self) -> Symbol {
self.into_symbol_with(&Ruby::get_unchecked())
}

/// Convert `self` into [`Symbol`].
///
/// # Examples
///
/// ```
/// use magnus::{rb_assert, symbol::IntoSymbol, Ruby};
/// # let _cleanup = unsafe { magnus::embed::init() };
///
/// let ruby = Ruby::get().unwrap();
/// let sym = "example".into_symbol_with(&ruby);
/// rb_assert!(ruby, "sym == :example", sym);
/// ```
fn into_symbol_with(self, handle: &Ruby) -> Symbol;
}

Expand Down
35 changes: 14 additions & 21 deletions src/typed_data.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -683,10 +683,10 @@ where
///
/// let value: Value = eval(
/// r#"
/// class SubPoint < Point
/// end
/// SubPoint.new(4, 2)
/// "#,
/// class SubPoint < Point
/// end
/// SubPoint.new(4, 2)
/// "#,
/// )
/// .unwrap();
///
Expand Down Expand Up @@ -1044,7 +1044,7 @@ where
/// use std::cmp::Ordering;
///
/// use magnus::{
/// class, define_class, eval, function, gc, method, module, prelude::*, typed_data,
/// class, define_class, function, gc, method, module, prelude::*, rb_assert, typed_data,
/// value::Opaque, DataTypeFunctions, IntoValue, Module, TypedData, Value,
/// };
///
Expand Down Expand Up @@ -1110,18 +1110,15 @@ where
///
/// let a = Pair::new("foo".into_value(), 1.into_value());
/// let b = Pair::new("foo".into_value(), 2.into_value());
/// let res: bool = eval!("a < b", a, b).unwrap();
/// assert!(res);
/// rb_assert!("a < b", a, b);
///
/// let b = Pair::new("foo".into_value(), 2.into_value());
/// let c = Pair::new("bar".into_value(), 3.into_value());
/// let res: bool = eval!("b > c", b, c).unwrap();
/// assert!(res);
/// rb_assert!("b > c", b, c);
///
/// let a = Pair::new("foo".into_value(), 1.into_value());
/// let b = Pair::new("foo".into_value(), 2.into_value());
/// let res: i64 = eval!("a <=> b", a, b).unwrap();
/// assert_eq!(res, -1);
/// rb_assert!("(a <=> b) == -1", a, b);
/// ```
pub trait Cmp {
// Docs at trait level.
Expand Down Expand Up @@ -1155,8 +1152,8 @@ where
/// use std::fmt;
///
/// use magnus::{
/// class, define_class, eval, function, gc, method, prelude::*, typed_data, value::Opaque,
/// DataTypeFunctions, IntoValue, TypedData, Value,
/// class, define_class, function, gc, method, prelude::*, rb_assert, typed_data,
/// value::Opaque, DataTypeFunctions, IntoValue, TypedData, Value,
/// };
///
/// #[derive(TypedData)]
Expand Down Expand Up @@ -1207,8 +1204,7 @@ where
/// .unwrap();
///
/// let pair = Pair::new("foo".into_value(), 1.into_value());
/// let res: bool = eval!(r#"pair.inspect == "Pair { a: \"foo\", b: 1 }""#, pair).unwrap();
/// assert!(res);
/// rb_assert!(r#"pair.inspect == "Pair { a: \"foo\", b: 1 }""#, pair);
/// ```
pub trait Inspect {
// Docs at trait level.
Expand Down Expand Up @@ -1236,16 +1232,14 @@ where
///
/// ```
/// use magnus::{
/// class, define_class, eval, function, gc, method, prelude::*, typed_data, value::Opaque,
/// DataTypeFunctions, IntoValue, TypedData, Value,
/// class, define_class, function, gc, method, prelude::*, rb_assert, typed_data,
/// value::Opaque, DataTypeFunctions, IntoValue, TypedData, Value,
/// };
///
/// #[derive(TypedData, Clone)]
/// #[magnus(class = "Pair", free_immediately, mark)]
/// struct Pair {
/// #[magnus(opaque_attr_reader)]
/// a: Opaque<Value>,
/// #[magnus(opaque_attr_reader)]
/// b: Opaque<Value>,
/// }
///
Expand Down Expand Up @@ -1279,8 +1273,7 @@ where
/// .unwrap();
///
/// let a = Pair::new("foo".into_value(), 1.into_value());
/// let res: bool = eval!("b = a.dup; a.object_id != b.object_id", a).unwrap();
/// assert!(res);
/// rb_assert!("b = a.dup; a.object_id != b.object_id", a);
/// ```
pub trait Dup: Sized {
// Docs at trait level.
Expand Down

0 comments on commit 69edc69

Please sign in to comment.