Struct magnus::Symbol

source ·

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

Expand description

A type wrapping either a StaticSymbol or a Value pointer to a RSymbol struct.

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

Implementations§

source §

impl Symbol

source

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

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

Examples

use magnus::{eval, Symbol};

assert!(Symbol::from_value(eval(":foo").unwrap()).is_some());
assert!(Symbol::from_value(eval(r#""bar".to_sym"#).unwrap()).is_some());
assert!(Symbol::from_value(eval(r#""baz""#).unwrap()).is_none());

source

pub fn new<T: AsRef<str>>(name: T) -> Self

Create a new Symbol from name.

Examples

use magnus::{eval, Symbol};

let sym = Symbol::new("example");
let result: bool = eval!(":example == sym", sym).unwrap();
assert!(result);

source

pub fn is_static(self) -> bool

Returns whether self is static or not.

Static symbols won’t be garbage collected, so should be safe to store on the heap. See StaticSymbol.

Examples

use magnus::{eval, Symbol};

assert!(eval::<Symbol>(":foo").unwrap().is_static());
assert!(!Symbol::new("bar").is_static());
assert!(!eval::<Symbol>(r#""baz".to_sym"#).unwrap().is_static());

source

pub fn name(self) -> Result<Cow<'static, str>, Error>

Return the symbol as a string. If the symbol is static this will be a &str, otherwise an owned String.

May error if the name is not valid utf-8.

Examples

use magnus::Symbol;

let sym = Symbol::new("example");
assert_eq!(sym.name().unwrap(), "example");

source

pub fn as_static(self) -> Option<StaticSymbol>

If self is static, returns self as a StaticSymbol, otherwise returns None.

Examples

use magnus::{eval, Symbol};

assert!(eval::<Symbol>(":foo").unwrap().as_static().is_some());
assert!(Symbol::new("bar").as_static().is_none());
assert!(eval::<Symbol>(r#""baz".to_sym"#).unwrap().as_static().is_none());

source

pub fn to_static(self) -> StaticSymbol

If self is already static simply returns self as a StaticSymbol. If self is not static it will be made so and returned as a StaticSymbol.

Be aware that once static a symbol will never be garbage collected.

Examples

use magnus::{eval, Symbol};

let sym = Symbol::new("example");
let static_sym = sym.to_static();

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