Struct NSString

#[repr(C)]
pub struct NSString<'data>(/* private fields */);

A static, plain-text Unicode string object.

See documentation.

Implementations

impl NSString<'_>

Getting available encodings.

pub fn available_encodings_slice() -> &'static [NSStringEncoding]

Returns a slice containing all supported encodings.

The first time this is called, one pass is done to determine the length of the slice. The slice is then cached for subsequent calls.

pub fn available_encodings_iter() -> impl Iterator<Item = NSStringEncoding>

Returns an iterator over all supported encodings.

Unlike available_encodings_slice, this is implemented lazily and does not perform caching.

pub fn available_encodings_ptr() -> *const NSStringEncoding

Returns a pointer to a buffer containing all supported encodings.

See documentation.

pub fn available_encodings_count() -> usize

Returns the number of supported encodings.

The first time this is called, one pass is done to determine the number of encodings. The count is then cached for subsequent calls. This shares the same cache as available_encodings_slice.

impl<'data> NSString<'data>

pub fn from_str(s: &str) -> Arc<Self>

Creates an immutable string object from copying a slice.

pub fn from_str_no_copy(s: &'data str) -> Arc<Self>

Creates an immutable string object without copying a slice.

Safety

The returned string object or its clones must not outlive the referenced string slice.

pub fn from_nsrange(range: NSRange) -> Arc<Self>

Returns a string representation of range.

See documentation.

pub fn copy(&self) -> Arc<Self>

Returns a copy of this object using NSCopying.

See documentation.

pub fn mutable_copy(&self) -> Arc<NSMutableString<'data>>

Returns a copy of this object using NSMutableCopying.

See documentation.

impl NSString<'_>

Getting contents as UTF-8.

pub fn as_utf8_ptr(&self) -> *const c_char

Returns a null-terminated UTF-8 representation of self, or null if the internal storage of self does not allow this to be returned efficiently.

Unlike to_utf8_ptr, this does not allocate and construct a new UTF-8 C string if self does not represent one.

This is retrieved using CFStringGetCStringPtr and kCFStringEncodingUTF8.

pub fn to_utf8_ptr(&self) -> *const c_char

Returns a null-terminated UTF-8 representation of self.

This C string is a pointer to a structure inside self, which may have a lifetime shorter than the string object and will certainly not have a longer lifetime. Therefore, you should copy the C string if it needs to be stored outside of the memory context in which you use this property.

This is retrieved using -[NSString UTF8String].

pub fn utf8_length(&self) -> usize

Returns the number of bytes required to encode this string as UTF-8.

pub unsafe fn as_str(&self) -> Option<&str>

Returns the contents of self as a native UTF-8 string slice, or None if the internal storage of self does not allow this to be returned efficiently.

Unlike to_str, this does not allocate and construct a new UTF-8 C string if self does not represent one.

Safety

You must ensure that self is not mutated during the lifetime of the returned string slice.

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

Returns the contents of self as a native UTF-8 string slice.

This internally uses to_utf8_ptr. See its documentation for details.

Safety

The lifetime of the returned string slice may be shorter than this object. Therefore, long use cases should copy the bytes of the returned string slice or use to_string.

pub unsafe fn as_str_with_nul(&self) -> Option<&str>

Returns the contents of self as a native UTF-8 string slice ending with a 0 byte, or None if the internal storage of self does not allow this to be returned efficiently.

Unlike to_str_with_nul, this does not allocate and construct a new UTF-8 C string if self does not represent one.

Safety

You must ensure that self is not mutated during the lifetime of the returned string slice.

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

Returns the contents of self as a native UTF-8 string slice ending with a 0 byte.

This internally uses to_utf8_ptr. See its documentation for details.

Safety

The lifetime of the returned string slice may be shorter than this object. Therefore, long use cases should copy the bytes of the returned string slice or use to_string_with_nul.

pub fn to_string(&self) -> String

Returns the contents of self as a native UTF-8 string buffer.

This internally uses to_utf8_ptr. See its documentation for details.

Performance Considerations

Because of how -[NSString UTF8String] works, this method will likely allocate twice as much memory needed for the length of the resulting buffer. If your use case is short-lived enough, consider using to_str to save memory and time.

pub fn to_string_with_nul(&self) -> String

Returns the contents of self as a native UTF-8 string buffer ending with a 0 byte.

This internally uses to_utf8_ptr. See its documentation for details.

Performance Considerations

Because of how -[NSString UTF8String] works, this method will likely allocate twice as much memory needed for the length of the resulting buffer. If your use case is short-lived enough, consider using to_str_with_nul to save memory and time.

impl NSString<'_>

Getting contents as UTF-16.

pub fn as_utf16_ptr(&self) -> *const u16

Returns a pointer to the UTF-16 representation of self, or null if the internal storage of self does not allow this to be returned efficiently.

This is retrieved using CFStringGetCharactersPtr

See as_utf8_ptr for the UTF-8 equivalent.

pub unsafe fn as_utf16(&self) -> Option<&[u16]>

Returns the contents of self as a UTF-16 string slice, or None if the internal storage of self does not allow this to be returned efficiently.

See as_str for the UTF-8 equivalent.

Safety

You must ensure that self is not mutated during the lifetime of the returned slice.

impl NSString<'_>

pub fn length(&self) -> NSUInteger

Returns the number of UTF-16 code units in self.

See documentation.

pub fn length_of_bytes_using_encoding( &self, encoding: NSStringEncoding, ) -> NSUInteger

Returns the number of bytes required to store self in a given encoding.

The length does not include space for a terminating null character. Returns 0 if the specified encoding cannot be used to convert self or if the amount of memory required for storing the results of the encoding conversion would exceed NSIntegerMax.

The result is exact and is returned in O(n) time.

See documentation.

pub fn to_selector(&self) -> Option<Sel>

Returns a selector with self as its name.

If self cannot be converted to UTF-8 (this should be only due to insufficient memory), this returns None.

See documentation.

pub fn compare(&self, other: &NSString<'_>) -> NSComparisonResult

Compares the string and a given string using no options.

See documentation.

pub fn localized_compare(&self, other: &NSString<'_>) -> NSComparisonResult

Compares the string and a given string using a localized comparison.

See documentation.

pub fn case_insensitive_compare( &self, other: &NSString<'_>, ) -> NSComparisonResult

Compares the string with a given string using NSCaseInsensitiveSearch.

See documentation.

pub fn localized_case_insensitive_compare( &self, other: &NSString<'_>, ) -> NSComparisonResult

Compares the string with a given string using a case-insensitive, localized, comparison.

See documentation.

pub fn localized_standard_compare( &self, other: &NSString<'_>, ) -> NSComparisonResult

Compares strings as sorted by the Finder.

This method should be used whenever file names or other strings are presented in lists and tables where Finder-like sorting is appropriate. The exact sorting behavior of this method is different under different locales and may be changed in future releases. This method uses the current locale.

See documentation.

pub fn has_prefix(&self, prefix: &NSString<'_>) -> bool

Returns true if the given string matches the beginning characters of self.

See documentation.

pub fn has_suffix(&self, suffix: &NSString<'_>) -> bool

Returns true if the given string matches the ending characters of this string.

See documentation.

Methods from Deref<Target = NSObject<'data>>

pub fn retain_count(&self) -> usize

Returns this object’s reference count.

This method is only useful for debugging certain objects.

See documentation.

pub fn responds_to_selector(&self, selector: Sel) -> bool

Returns true if this object implements or inherits a method that can respond to a specified message.

See documentation.

pub fn is_kind_of_class(&self, class: &Class) -> bool

Returns true if this object is an instance or subclass of class.

See documentation

pub fn is_member_of_class(&self, class: &Class) -> bool

Returns true if this object is an instance of class.

See documentation

pub fn hash(&self) -> NSUInteger

Returns an integer that can be used as a table address in a hash table structure.

See documentation.

pub fn copy(&self) -> Arc<Self>

Returns a copy of this object using NSCopying.

See documentation.

pub fn mutable_copy(&self) -> Arc<Self>

Returns a copy of this object using NSMutableCopying.

See documentation.

pub fn description(&self) -> Arc<NSString<'static>>

Returns a string that describes the contents of this object.

See documentation

pub fn debug_description(&self) -> Arc<NSString<'static>>

Returns a string that describes the contents of the receiver for presentation in the debugger.

See documentation

Trait Implementations

impl AsMut<NSErrorDomain> for NSString<'static>

fn as_mut(&mut self) -> &mut NSErrorDomain

Converts this type into a mutable reference of the (usually inferred) input type.

impl AsMut<NSErrorUserInfoKey> for NSString<'static>

fn as_mut(&mut self) -> &mut NSErrorUserInfoKey

Converts this type into a mutable reference of the (usually inferred) input type.

impl AsMut<NSExceptionName> for NSString<'static>

fn as_mut(&mut self) -> &mut NSExceptionName

Converts this type into a mutable reference of the (usually inferred) input type.

impl<'data> AsMut<NSString<'data>> for NSString<'data>

fn as_mut(&mut self) -> &mut Self

Converts this type into a mutable reference of the (usually inferred) input type.

impl<'data, T> AsMut<T> for NSString<'data>

where NSObject<'data>: AsMut<T>,

fn as_mut(&mut self) -> &mut T

Converts this type into a mutable reference of the (usually inferred) input type.

impl AsRef<NSErrorDomain> for NSString<'static>

fn as_ref(&self) -> &NSErrorDomain

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<NSErrorUserInfoKey> for NSString<'static>

fn as_ref(&self) -> &NSErrorUserInfoKey

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<NSExceptionName> for NSString<'static>

fn as_ref(&self) -> &NSExceptionName

Converts this type into a shared reference of the (usually inferred) input type.

impl<'data> AsRef<NSString<'data>> for NSString<'data>

fn as_ref(&self) -> &Self

Converts this type into a shared reference of the (usually inferred) input type.

impl<'data, T> AsRef<T> for NSString<'data>

where NSObject<'data>: AsRef<T>,

fn as_ref(&self) -> &T

Converts this type into a shared reference of the (usually inferred) input type.

impl<'data> ClassType<'data> for NSString<'data>

fn class() -> &'static Class

Returns the Objective-C class that can be used to instantiate a new instance of Self.

impl Debug for NSString<'_>

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

Formats the value using the given formatter.

impl Default for &NSString<'_>

fn default() -> Self

Returns the “default value” for a type.

impl<'data> Deref for NSString<'data>

type Target = NSObject<'data>

The resulting type after dereferencing.

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

Dereferences the value.

impl Display for NSString<'_>

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

Formats the value using the given formatter.

impl<'data> ObjectType<'data> for NSString<'data>

fn as_objc_object(&self) -> &ObjCObject<'data>

Casts self into a type-erased Objective-C object.

fn class<'s>(&'s self) -> &'s Class

where 'data: 's,

Returns the class that this object is an instance of.

impl<'data> ObjectType for NSString<'data>

fn retain(obj: &Self) -> Arc<Self>

Increments the object’s retain count and returns a smart pointer that automatically calls release on Drop.

unsafe fn release(obj: NonNull<Self>)

Decrements the object’s retain count.

impl Ord for NSString<'_>

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

This method returns an Ordering between self and other.

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

where Self: Sized,

Compares and returns the maximum of two values.

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

where Self: Sized,

Compares and returns the minimum of two values.

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

where Self: Sized,

Restrict a value to a certain interval.

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

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<NSErrorDomain> for NSString<'static>

where NSString<'static>: PartialEq,

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<NSErrorUserInfoKey> for NSString<'static>

where NSString<'static>: PartialEq,

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<NSExceptionName> for NSString<'static>

where NSString<'static>: PartialEq,

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<NSMutableString<'_>> for NSString<'_>

fn eq(&self, other: &NSMutableString<'_>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

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

fn eq(&self, other: &NSString<'_>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<NSString<'_>> for NSMutableString<'_>

fn eq(&self, other: &NSString<'_>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<NSString<'_>> for str

fn eq(&self, other: &NSString<'_>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<NSString<'static>> for NSErrorDomain

where NSString<'static>: PartialEq,

fn eq(&self, other: &NSString<'static>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<NSString<'static>> for NSErrorUserInfoKey

where NSString<'static>: PartialEq,

fn eq(&self, other: &NSString<'static>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<NSString<'static>> for NSExceptionName

where NSString<'static>: PartialEq,

fn eq(&self, other: &NSString<'static>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<str> for NSString<'_>

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq for NSString<'_>

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd<&str> for NSString<'_>

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

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

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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

impl PartialOrd<NSMutableString<'_>> for NSString<'_>

fn partial_cmp(&self, other: &NSMutableString<'_>) -> Option<Ordering>

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

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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

impl PartialOrd<NSString<'_>> for &str

fn partial_cmp(&self, other: &NSString<'_>) -> Option<Ordering>

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

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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

impl PartialOrd<NSString<'_>> for NSMutableString<'_>

fn partial_cmp(&self, other: &NSString<'_>) -> Option<Ordering>

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

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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

impl PartialOrd<NSString<'_>> for str

fn partial_cmp(&self, other: &NSString<'_>) -> Option<Ordering>

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

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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

impl PartialOrd<str> for NSString<'_>

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

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

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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

impl PartialOrd for NSString<'_>

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

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

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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

impl Eq for NSString<'_>