Struct rosy::String

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

An instance of Ruby's String class.

Methods

impl String

pub fn new() -> Self

Creates a new empty string with a capacity of 0.

pub fn with_capacity(capacity: usize) -> Self

Creates a new string with capacity.

pub unsafe fn with_encoding(s: impl AsRef<[u8]>, enc: Encoding) -> Self

Returns a new instance from s encoded as enc.

Safety

Care must be taken to ensure that the bytes are actually encoded this way. Otherwise, Ruby may make incorrect assumptions about the underlying data.

pub fn duplicate(self) -> Self

Duplicates the contents of self into a new instance.

pub fn encoding(self) -> Encoding

Returns how the bytes of self are encoded.

Examples

let string = rosy::String::from("¡Hola!");
assert!(string.encoding().is_utf8());

pub unsafe fn force_encoding(self, encoding: Encoding)

Associates the bytes of self with encoding without checking whether self is actually encoded that way.

pub fn encoding_is_ascii_8bit(self) -> bool

A fast shortcut to self.encoding().is_ascii_8bit().

Examples

let bytes: &[u8] = &[0, 1, 255, 42];
let string = rosy::String::from(bytes);
assert!(string.encoding_is_ascii_8bit());

pub fn encoding_is_utf8(self) -> bool

A fast shortcut to self.encoding().is_utf8().

Examples

let string = rosy::String::from("hellooo");
assert!(string.encoding_is_utf8());

pub fn encoding_is_us_ascii(self) -> bool

A fast shortcut to self.encoding().is_us_ascii().

Examples

use rosy::{Object, String};

let string = String::from("hellooo");
unsafe {
    string.call_with("encode!", &[String::from("US-ASCII")]);
}

assert!(string.encoding_is_us_ascii());

pub unsafe fn as_bytes(&self) -> &[u8]

Returns a reference to the underlying bytes in self.

Safety

Care must be taken to ensure that the length of self and the bytes pointed to by self are not changed through the VM or otherwise.

Examples

let rs = "Hey, I just met you, and this is crazy;
          but here's my number, so call me maybe.";
let rb = rosy::String::from(rs);

unsafe { assert_eq!(rs.as_bytes(), rb.as_bytes()) };

pub fn to_bytes(self) -> Vec<u8>

Returns a buffer of the underlying bytes in self.

pub fn bytes_all<F>(self, f: F) -> bool where
    F: FnMut(u8) -> bool, 

Returns whether all bytes in self satisfy f.

pub fn bytes_any<F>(self, f: F) -> bool where
    F: FnMut(u8) -> bool, 

Returns whether any bytes in self satisfy f.

pub unsafe fn to_str(&self) -> Result<&str, Utf8Error>

Returns a reference to the underlying UTF-8 encoded string in self.

Safety

Care must be taken to ensure that the length of self and the characters pointed to by self are not changed through the VM or otherwise.

If Ruby believes that the underlying encoding is indeed UTF-8, then we return the bytes directly without any further checking. However, if the method force_encoding has been called on self, then we are susceptible to getting invalid UTF-8 in a str instance, which is UB. To force a check, one should call str::from_utf8 on the result of as_bytes.

Examples

let rs = "Somebody once told me the world is gonna roll me...";
let rb = rosy::String::from(rs);

unsafe { assert_eq!(rb.to_str().unwrap(), rs) };

pub unsafe fn to_str_lossy(&self) -> Cow<str>

Returns the underlying string lossy-encoded as UTF-8. See String::from_utf8_lossy for more details.

Safety

Care must be taken to ensure that, if the returned value is a reference to self, the length of self and the characters pointed to by self are not changed through the VM or otherwise.

If Ruby believes that the underlying encoding is indeed UTF-8, then we return the bytes directly without any further checking. However, if the method force_encoding has been called on self, then we are susceptible to getting invalid UTF-8 in a str instance, which is UB. To force a check, one should call str::from_utf8 on the result of as_bytes.

pub unsafe fn to_str_unchecked(&self) -> &str

Returns a reference to the underlying bytes of self as if they were UTF-8 encoded.

Safety

Same reasons as to_str as well as that no UTF-8 checking is performed.

pub fn to_string(self) -> Result<String, Utf8Error>

Returns a buffer of the underlying UTF-8 encoded string of self.

pub fn len(self) -> usize

Returns the number of bytes in self.

Examples

let s1 = "Í'm in Rüby!";
let s2 = "I'm in Ruby!";
let s3 = rosy::String::from(s1);

assert_eq!(s3.len(), s1.len());
assert_ne!(s3.len(), s2.len());

pub fn char_len(self) -> usize

Returns the number of characters in self.

Examples

This is a Unicode-aware method:

let s1 = "Í'm in Rüby!";
let s2 = "I'm in Ruby!";
let s3 = rosy::String::from(s1);

assert_eq!(s3.char_len(), s1.chars().count());
assert_eq!(s3.char_len(), s2.chars().count());

pub fn is_empty(self) -> bool

Returns whether self has no characters.

pub fn is_whitespace(self) -> bool

Returns whether self only contains whitespace.

Examples

When self is encoded as UTF-8, it checks against all unicode characters with the property "WSpace=Y":

use rosy::String;

let space = String::from("\u{0009}\u{000A}\u{000B}\u{000C}\u{000D}\
                          \u{0020}\u{0085}\u{00A0}\u{1680}\u{2000}\
                          \u{2001}\u{2002}\u{2003}\u{2004}\u{2005}\
                          \u{2006}\u{2007}\u{2008}\u{2009}\u{200A}\
                          \u{2028}\u{202F}\u{2029}\u{205F}\u{3000}");

assert!(space.is_whitespace());

pub fn is_ascii_whitespace(self) -> bool

Returns whether self only contains ASCII whitespace.

pub unsafe fn push(self, c: char)

Concatenates c to self.

Safety

The caller must ensure that self is not frozen or else a FrozenError exception will be raised.

pub unsafe fn push_str(self, s: &str)

Concatenates s to self.

Safety

The caller must ensure that self is not frozen or else a FrozenError exception will be raised.

pub fn ellipsized(self, len: usize) -> Self

Returns the contents of self with an ellipsis (three dots) if it's longer than len characters.

Examples

let s1 = rosy::String::from("Hello, there!");
let s2 = s1.ellipsized(8);

assert_eq!(s2, "Hello...");

pub fn is_locked(self) -> bool

Returns whether the string is locked by the VM.

#[must_use]

pub fn with_lock<F, O>(self, f: F) -> Option<O> where
    F: FnOnce(Self) -> O, 

Attempts to call f if a lock on self can be acquired, returning its output on success.

Examples

let s = rosy::String::from("Hello!");
let result = s.with_lock(|s| s.is_locked());

assert_eq!(result, Some(true));

pub unsafe fn raw_lock(self)

Locks the string, preventing others from writing to it.

Safety

The exception raised by the VM must be handled if the string is already locked.

pub unsafe fn raw_unlock(self)

Unlocks the string, allowing others to write to it.

Safety

The exception raised by the VM must be handled if the string is already unlocked.

Trait Implementations

impl GcInfoKey for String

fn stat_gc(self) -> Result<usize>

Returns the status information for self with respect to the garbage collector, or an exception if one is raised.

unsafe fn stat_gc_unchecked(self) -> usize

Returns the status information for self with respect to the garbage collector.

fn latest_gc_info(self) -> Result<AnyObject>

Returns the latest information regarding self with respect to the garbage collector.

unsafe fn latest_gc_info_unchecked(self) -> AnyObject

Returns the latest information regarding self with respect to the garbage collector.

impl Classify for String

fn class() -> Class<Self>

Returns the typed class that can be used to get an instance of self.

impl Object for String

fn unique_id() -> Option<u128>

Returns a unique identifier for an object type to facilitate casting.

fn cast<A: Object>(obj: A) -> Option<Self>

Attempts to create an instance by casting obj.

fn ty(self) -> Ty

Returns the virtual type of self.

fn is_ty(self, ty: Ty) -> bool

Returns whether the virtual type of self is ty.

unsafe fn from_raw(raw: usize) -> Self

Creates a new object from raw without checking.

unsafe fn cast_unchecked(obj: impl Object) -> Self

Casts obj to Self without checking its type.

fn into_any_object(self) -> AnyObject

Returns self as an AnyObject.

fn as_any_object(&self) -> &AnyObject

Returns a reference to self as an AnyObject.

fn as_any_slice(&self) -> &[AnyObject]

Returns self as a reference to a single-element slice.

fn raw(self) -> usize

Returns the raw object pointer.

unsafe fn as_unchecked<O: Object>(&self) -> &O

Casts self to O without checking whether it is one.

unsafe fn into_unchecked<O: Object>(self) -> O

Converts self to O without checking whether it is one.

fn id(self) -> u64

Returns the object's identifier.

fn class(self) -> Class<Self>

Returns the Class for self.

fn singleton_class(self) -> Class<Self>

Returns the singleton Class of self, creating one if it doesn't exist already.

fn mark(self)

Marks self for Ruby to avoid garbage collecting it.

unsafe fn force_recycle(self)

Forces the garbage collector to free the contents of self.

fn def_singleton_method<N, F>(self, name: N, f: F) -> Result where
    N: Into<SymbolId>,
    F: MethodFn<Self>, 

Defines a method for name on the singleton class of self that calls f when invoked.

unsafe fn def_singleton_method_unchecked<N, F>(self, name: N, f: F) where
    N: Into<SymbolId>,
    F: MethodFn<Self>, 

Defines a method for name on the singleton class of self that calls f when invoked.

unsafe fn call(self, method: impl Into<SymbolId>) -> AnyObject

Calls method on self and returns its output.

unsafe fn call_protected(self, method: impl Into<SymbolId>) -> Result<AnyObject>

Calls method on self and returns its output, or an exception if one is raised.

unsafe fn call_with(
    self,
    method: impl Into<SymbolId>,
    args: &[impl Object]
) -> AnyObject

Calls method on self with args and returns its output.

unsafe fn call_with_protected(
    self,
    method: impl Into<SymbolId>,
    args: &[impl Object]
) -> Result<AnyObject>

Calls method on self with args and returns its output, or an exception if one is raised.

unsafe fn call_public(self, method: impl Into<SymbolId>) -> AnyObject

Calls the public method on self and returns its output.

unsafe fn call_public_protected(
    self,
    method: impl Into<SymbolId>
) -> Result<AnyObject>

Calls the public method on self and returns its output, or an exception if one is raised.

unsafe fn call_public_with(
    self,
    method: impl Into<SymbolId>,
    args: &[impl Object]
) -> AnyObject

Calls the public method on self with args and returns its output.

unsafe fn call_public_with_protected(
    self,
    method: impl Into<SymbolId>,
    args: &[impl Object]
) -> Result<AnyObject>

Calls the public method on self with args and returns its output, or an exception if one is raised.

fn inspect(self) -> String

Returns a printable string representation of self.

fn to_s(self) -> String

Returns the result of calling the to_s method on self.

fn is_frozen(self) -> bool

Returns whether modifications can be made to self.

fn freeze(self)

Freezes self, preventing any further mutations.

fn is_eql<O: Object>(self, other: &O) -> bool

Returns whether self is equal to other in terms of the eql? method.

fn get_attr<N: Into<SymbolId>>(self, name: N) -> AnyObject

Returns the value for the attribute of self associated with name.

unsafe fn eval(self, args: impl EvalArgs) -> AnyObject

Evaluates args in the context of self.

unsafe fn eval_protected(self, args: impl EvalArgs) -> Result<AnyObject>

Evaluates args in the context of self, returning any raised exceptions.

impl EvalArgs for String

The script argument without any extra information.

unsafe fn eval_in_object_protected(
    self,
    object: impl Into<AnyObject>
) -> Result<AnyObject>

Evaluates self in the context of object, returning any raised exceptions.

unsafe fn eval_in_object(self, object: impl Into<AnyObject>) -> AnyObject

Evaluates self in the context of object.

unsafe fn eval_in_mixin_protected(self, mixin: impl Mixin) -> Result<AnyObject>

Evaluates self in the context of mixin, returning any raised exceptions.

unsafe fn eval_in_mixin(self, mixin: impl Mixin) -> AnyObject

Evaluates self in the context of mixin.

impl Eq for String

impl Ord for String

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

🔬 This is a nightly-only experimental API. (clamp)

Restrict a value to a certain interval.

impl<O: Object> PartialEq<O> for String

fn eq(&self, obj: &O) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl PartialEq<[u8]> for String

fn eq(&self, other: &[u8]) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'_> PartialEq<&'_ [u8]> for String

fn eq(&self, other: &&[u8]) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl PartialEq<String> for [u8]

fn eq(&self, other: &String) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'_> PartialEq<String> for &'_ [u8]

fn eq(&self, other: &String) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl PartialEq<Vec<u8>> for String

fn eq(&self, other: &Vec<u8>) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'_> PartialEq<&'_ Vec<u8>> for String

fn eq(&self, other: &&Vec<u8>) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl PartialEq<String> for Vec<u8>

fn eq(&self, other: &String) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'_> PartialEq<String> for &'_ Vec<u8>

fn eq(&self, other: &String) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl PartialEq<str> for String

fn eq(&self, other: &str) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'_> PartialEq<&'_ str> for String

fn eq(&self, other: &&str) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl PartialEq<String> for str

fn eq(&self, other: &String) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'_> PartialEq<String> for &'_ str

fn eq(&self, other: &String) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl PartialEq<String> for String

fn eq(&self, other: &String) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'_> PartialEq<&'_ String> for String

fn eq(&self, other: &&String) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl PartialEq<String> for String

fn eq(&self, other: &String) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'_> PartialEq<String> for &'_ String

fn eq(&self, other: &String) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl PartialEq<CStr> for String

fn eq(&self, other: &CStr) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'_> PartialEq<&'_ CStr> for String

fn eq(&self, other: &&CStr) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl PartialEq<String> for CStr

fn eq(&self, other: &String) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'_> PartialEq<String> for &'_ CStr

fn eq(&self, other: &String) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl PartialEq<CString> for String

fn eq(&self, other: &CString) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'_> PartialEq<&'_ CString> for String

fn eq(&self, other: &&CString) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl PartialEq<String> for CString

fn eq(&self, other: &String) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'_> PartialEq<String> for &'_ CString

fn eq(&self, other: &String) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<S: ?Sized + Clone, '_> PartialEq<Cow<'_, S>> for String where
    String: PartialEq<S>, 

fn eq(&self, other: &Cow<S>) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl Copy for String

impl Clone for String

fn clone(&self) -> String

Returns a copy of the value.

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

Performs copy-assignment from source.

impl PartialOrd<String> for String

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

#[must_use]

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use]

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

#[must_use]

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl AsRef<AnyObject> for String

fn as_ref(&self) -> &AnyObject

Performs the conversion.

impl From<String> for AnyObject

fn from(object: String) -> AnyObject

Performs the conversion.

impl<'_> From<&'_ str> for String

fn from(s: &str) -> String

Performs the conversion.

impl<'_> From<&'_ String> for String

fn from(s: &String) -> String

Performs the conversion.

impl<'_> From<&'_ CStr> for String

fn from(s: &CStr) -> String

Performs the conversion.

impl<'_> From<&'_ CString> for String

fn from(s: &CString) -> String

Performs the conversion.

impl<'_> From<&'_ [u8]> for String

fn from(bytes: &[u8]) -> String

Performs the conversion.

impl<'_> From<&'_ Vec<u8>> for String

fn from(bytes: &Vec<u8>) -> String

Performs the conversion.

impl From<String> for Symbol

fn from(s: String) -> Symbol

Performs the conversion.

impl From<String> for SymbolId

fn from(s: String) -> SymbolId

Performs the conversion.

impl Debug for String

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

Formats the value using the given formatter.

impl Display for String

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

Formats the value using the given formatter.

impl FromIterator<char> for String

fn from_iter<I: IntoIterator<Item = char>>(iter: I) -> Self

Creates a value from an iterator.

impl<'a> FromIterator<&'a char> for String

fn from_iter<I: IntoIterator<Item = &'a char>>(iter: I) -> Self

Creates a value from an iterator.

impl<'a> FromIterator<&'a str> for String

fn from_iter<I: IntoIterator<Item = &'a str>>(iter: I) -> Self

Creates a value from an iterator.

impl<'a> FromIterator<&'a String> for String

fn from_iter<I>(iter: I) -> Self where
    I: IntoIterator<Item = &'a String>, 

Creates a value from an iterator.

impl TryFrom<String> for String

type Error = Utf8Error

The type returned in the event of a conversion error.

fn try_from(s: String) -> Result<Self, Self::Error>

Performs the conversion.