Struct UnixString

pub struct UnixString { /* private fields */ }

A type that can represent owned, mutable Unix strings, but is cheaply inter-convertible with Rust strings.

The need for this type arises from the fact that:

• On Unix systems, strings are often arbitrary sequences of non-zero bytes, in many cases interpreted as UTF-8.

• In Rust, strings are always valid UTF-8, which may contain zeros.

UnixString and UnixStr bridge this gap by simultaneously representing Rust and platform-native string values, and in particular allowing a Rust string to be converted into a “Unix” string with no cost if possible. A consequence of this is that UnixString instances are not NULL terminated; in order to pass to e.g., Unix system call, you should create a CStr.

UnixString is to &UnixStr as String is to &str: the former in each pair are owned strings; the latter are borrowed references.

Note, UnixString and UnixStr internally do not hold in the form native to the platform: UnixStrings are stored as a sequence of 8-bit values.

Creating an UnixString

From a Rust string: UnixString implements From<String>, so you can use my_string.from to create an UnixString from a normal Rust string.

From slices: Just like you can start with an empty Rust String and then [push_str][String.push_str] &str sub-string slices into it, you can create an empty UnixString with the new method and then push string slices into it with the push method.

Extracting a borrowed reference to the whole OS string

You can use the as_unix_str method to get a &UnixStr from a UnixString; this is effectively a borrowed reference to the whole string.

Conversions

See the module’s toplevel documentation about conversions for a discussion on the traits which UnixString implements for conversions from/to native representations.

Implementations

impl UnixString

pub fn new() -> Self

Constructs a new empty UnixString.

Examples

use unix_str::UnixString;

let unix_string = UnixString::new();

pub fn as_unix_str(&self) -> &UnixStr

Converts to an UnixStr slice.

Examples

use unix_str::{UnixString, UnixStr};

let unix_string = UnixString::from("foo");
let unix_str = UnixStr::new("foo");
assert_eq!(unix_string.as_unix_str(), unix_str);

pub fn into_string(self) -> Result<String, UnixString>

Converts the UnixString into a String if it contains valid Unicode data.

On failure, ownership of the original UnixString is returned.

Examples

use unix_str::UnixString;

let unix_string = UnixString::from("foo");
let string = unix_string.into_string();
assert_eq!(string, Ok(String::from("foo")));

pub fn push<T: AsRef<UnixStr>>(&mut self, s: T)

Extends the string with the given &UnixStr slice.

Examples

use unix_str::UnixString;

let mut unix_string = UnixString::from("foo");
unix_string.push("bar");
assert_eq!(&unix_string, "foobar");

pub fn with_capacity(capacity: usize) -> Self

Creates a new UnixString with the given capacity.

The string will be able to hold exactly capacity length units of other OS strings without reallocating. If capacity is 0, the string will not allocate.

See main UnixString documentation information about encoding.

Examples

use unix_str::UnixString;

let mut unix_string = UnixString::with_capacity(10);
let capacity = unix_string.capacity();

// This push is done without reallocating
unix_string.push("foo");

assert_eq!(capacity, unix_string.capacity());

pub fn clear(&mut self)

Truncates the UnixString to zero length.

Examples

use unix_str::UnixString;

let mut unix_string = UnixString::from("foo");
assert_eq!(&unix_string, "foo");

unix_string.clear();
assert_eq!(&unix_string, "");

pub fn capacity(&self) -> usize

Returns the capacity this UnixString can hold without reallocating.

See UnixString introduction for information about encoding.

Examples

use unix_str::UnixString;

let unix_string = UnixString::with_capacity(10);
assert!(unix_string.capacity() >= 10);

pub fn reserve(&mut self, additional: usize)

Reserves capacity for at least additional more capacity to be inserted in the given UnixString.

The collection may reserve more space to avoid frequent reallocations.

Examples

use unix_str::UnixString;

let mut s = UnixString::new();
s.reserve(10);
assert!(s.capacity() >= 10);

pub fn reserve_exact(&mut self, additional: usize)

Reserves the minimum capacity for exactly additional more capacity to be inserted in the given UnixString. Does nothing if the capacity is already sufficient.

Note that the allocator may give the collection more space than it requests. Therefore, capacity can not be relied upon to be precisely minimal. Prefer reserve if future insertions are expected.

Examples

use unix_str::UnixString;

let mut s = UnixString::new();
s.reserve_exact(10);
assert!(s.capacity() >= 10);

pub fn shrink_to_fit(&mut self)

Shrinks the capacity of the UnixString to match its length.

Examples

use unix_str::UnixString;

let mut s = UnixString::from("foo");

s.reserve(100);
assert!(s.capacity() >= 100);

s.shrink_to_fit();
assert_eq!(3, s.capacity());

pub fn into_boxed_unix_str(self) -> Box<UnixStr>

Converts this UnixString into a boxed UnixStr.

Examples

use unix_str::{UnixString, UnixStr};

let s = UnixString::from("hello");

let b: Box<UnixStr> = s.into_boxed_unix_str();

pub fn from_vec(vec: Vec<u8>) -> Self

Creates a UnixString from a byte vector.

See the module documentation for an example.

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

Yields the underlying byte vector of this UnixString.

See the module documentation for an example.

Methods from Deref<Target = UnixStr>

pub fn to_str(&self) -> Option<&str>

Yields a &str slice if the UnixStr is valid Unicode.

This conversion may entail doing a check for UTF-8 validity.

Examples

use unix_str::UnixStr;

let unix_str = UnixStr::new("foo");
assert_eq!(unix_str.to_str(), Some("foo"));

pub fn to_string_lossy(&self) -> Cow<'_, str>

Converts an UnixStr to a Cow<str>.

Any non-Unicode sequences are replaced with U+FFFD REPLACEMENT CHARACTER.

Examples

Calling to_string_lossy on an UnixStr with invalid unicode:

use unix_str::UnixStr;

// Here, the values 0x66 and 0x6f correspond to 'f' and 'o'
// respectively. The value 0x80 is a lone continuation byte, invalid
// in a UTF-8 sequence.
let source = [0x66, 0x6f, 0x80, 0x6f];
let unix_str = UnixStr::from_bytes(&source[..]);

assert_eq!(unix_str.to_string_lossy(), "fo�o");

pub fn to_unix_string(&self) -> UnixString

Copies the slice into an owned UnixString.

Examples

use unix_str::{UnixStr, UnixString};

let unix_str = UnixStr::new("foo");
let unix_string = unix_str.to_unix_string();
assert_eq!(unix_string, UnixString::from("foo"));

pub fn is_empty(&self) -> bool

Checks whether the UnixStr is empty.

Examples

use unix_str::UnixStr;

let unix_str = UnixStr::new("");
assert!(unix_str.is_empty());

let unix_str = UnixStr::new("foo");
assert!(!unix_str.is_empty());

pub fn len(&self) -> usize

Returns the length of this UnixStr.

Note that this does not return the number of bytes in the string in OS string form.

The length returned is that of the underlying storage used by UnixStr. As discussed in the UnixString introduction, UnixString and UnixStr store strings in a form best suited for cheap inter-conversion between native-platform and Rust string forms, which may differ significantly from both of them, including in storage size and encoding.

This number is simply useful for passing to other methods, like UnixString::with_capacity to avoid reallocations.

Examples

use unix_str::UnixStr;

let unix_str = UnixStr::new("");
assert_eq!(unix_str.len(), 0);

let unix_str = UnixStr::new("foo");
assert_eq!(unix_str.len(), 3);

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

Gets the underlying byte view of the UnixStr slice.

See the module documentation for an example.

Trait Implementations

impl AsRef<UnixStr> for UnixString

fn as_ref(&self) -> &UnixStr

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

impl Borrow<UnixStr> for UnixString

fn borrow(&self) -> &UnixStr

Immutably borrows from an owned value.

impl Clone for UnixString

fn clone(&self) -> UnixString

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for UnixString

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

Formats the value using the given formatter.

impl Default for UnixString

fn default() -> Self

Constructs an empty UnixString.

impl Deref for UnixString

type Target = UnixStr

The resulting type after dereferencing.

fn deref(&self) -> &UnixStr

Dereferences the value.

impl DerefMut for UnixString

fn deref_mut(&mut self) -> &mut UnixStr

Mutably dereferences the value.

impl<T: ?Sized + AsRef<UnixStr>> From<&T> for UnixString

fn from(s: &T) -> Self

Converts to this type from the input type.

impl<'a> From<&'a UnixString> for Cow<'a, UnixStr>

fn from(s: &'a UnixString) -> Self

Converts to this type from the input type.

impl From<Box<UnixStr>> for UnixString

fn from(boxed: Box<UnixStr>) -> Self

Converts a Box<UnixStr> into a UnixString without copying or allocating.

impl<'a> From<Cow<'a, UnixStr>> for UnixString

fn from(s: Cow<'a, UnixStr>) -> Self

Converts to this type from the input type.

impl From<String> for UnixString

fn from(s: String) -> Self

Converts a String into a UnixString.

The conversion copies the data, and includes an allocation on the heap.

impl From<UnixString> for Arc<UnixStr>

fn from(s: UnixString) -> Self

Converts a UnixString into a Arc<UnixStr> without copying or allocating.

impl From<UnixString> for Box<UnixStr>

fn from(s: UnixString) -> Self

Converts a UnixString into a Box<UnixStr> without copying or allocating.

impl<'a> From<UnixString> for Cow<'a, UnixStr>

fn from(s: UnixString) -> Self

Converts to this type from the input type.

impl From<UnixString> for Rc<UnixStr>

fn from(s: UnixString) -> Self

Converts a UnixString into a Rc<UnixStr> without copying or allocating.

impl FromStr for UnixString

type Err = Infallible

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl Hash for UnixString

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Index<RangeFull> for UnixString

type Output = UnixStr

The returned type after indexing.

fn index(&self, _index: RangeFull) -> &UnixStr

Performs the indexing (container[index]) operation.

impl IndexMut<RangeFull> for UnixString

fn index_mut(&mut self, _index: RangeFull) -> &mut UnixStr

Performs the mutable indexing (container[index]) operation.

impl Ord for UnixString

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<'a, 'b> PartialEq<&'a UnixStr> for UnixString

fn eq(&self, other: &&'a UnixStr) -> 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 UnixString

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<'a, 'b> PartialEq<Cow<'a, UnixStr>> for UnixString

fn eq(&self, other: &Cow<'a, UnixStr>) -> 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<'a, 'b> PartialEq<UnixStr> for UnixString

fn eq(&self, other: &UnixStr) -> 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<'a, 'b> PartialEq<UnixString> for &'a UnixStr

fn eq(&self, other: &UnixString) -> 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<'a> PartialEq<UnixString> for &'a str

fn eq(&self, other: &UnixString) -> 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<'a, 'b> PartialEq<UnixString> for Cow<'a, UnixStr>

fn eq(&self, other: &UnixString) -> 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<'a, 'b> PartialEq<UnixString> for UnixStr

fn eq(&self, other: &UnixString) -> 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<UnixString> for str

fn eq(&self, other: &UnixString) -> 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 UnixString

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 UnixString

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<'a, 'b> PartialOrd<&'a UnixStr> for UnixString

fn partial_cmp(&self, other: &&'a UnixStr) -> 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<'a, 'b> PartialOrd<Cow<'a, UnixStr>> for UnixString

fn partial_cmp(&self, other: &Cow<'a, UnixStr>) -> 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<'a, 'b> PartialOrd<UnixStr> for UnixString

fn partial_cmp(&self, other: &UnixStr) -> 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<'a, 'b> PartialOrd<UnixString> for &'a UnixStr

fn partial_cmp(&self, other: &UnixString) -> 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<'a, 'b> PartialOrd<UnixString> for Cow<'a, UnixStr>

fn partial_cmp(&self, other: &UnixString) -> 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<'a, 'b> PartialOrd<UnixString> for UnixStr

fn partial_cmp(&self, other: &UnixString) -> 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 UnixString

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 UnixString

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: &Self) -> bool

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

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

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

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

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

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

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

impl Eq for UnixString