[−][src]Struct unix_str::UnixString

pub struct UnixString { /* fields omitted */ }

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`[src]

`pub fn new() -> Self`[src]

Constructs a new empty UnixString.

Examples

use unix_str::UnixString;

let unix_string = UnixString::new();

`pub fn as_unix_str(&self) -> &UnixStr`[src]

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>`[src]

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)`[src]

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`[src]

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)`[src]

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`[src]

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)`[src]

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)`[src]

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)`[src]

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>`[src]

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`[src]

Creates a UnixString from a byte vector.

See the module documentation for an example.

`pub fn into_vec(self) -> Vec<u8>`[src]

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>`[src]

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>`[src]

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`[src]

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`[src]

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`[src]

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