Struct unixstring::UnixString

#[non_exhaustive]
pub struct UnixString { /* fields omitted */ }

An FFI-friendly null-terminated byte string.

Implementations

impl UnixString

pub fn new() -> Self

Constructs a new, “empty” UnixString.

This function allocates a byte in order to store its nul terminator.

If you are creating a UnixString with the intention of writing stuff to it, you may be interested in UnixString::with_capacity.

pub fn push(&mut self, value: impl AsRef<OsStr>) -> Result<()>

Extends the UnixString with anything that implements AsRef<OsStr>.

This method fails if the given data has a zero byte anywhere but at its end.

use std::path::Path;

use unixstring::UnixString;
let mut unix_string = UnixString::new();
unix_string.push("/home/")?;
let username = Path::new("user");
unix_string.push(username)?;

assert_eq!(unix_string.as_str()?, "/home/user");

pub fn push_bytes(&mut self, bytes: &[u8]) -> Result<()>

Extends the UnixString with the given bytes.

This method fails if the bytes contain an interior zero byte (a zero byte not at the buffer’s final position)

use std::path::Path;

use unixstring::UnixString;
let mut unix_string = UnixString::new();

let abc = b"abc".to_vec();
unix_string.push_bytes(&abc)?;

assert_eq!(unix_string.into_bytes(), abc);

pub fn from_bytes(bytes: Vec<u8>) -> Result<Self>

Creates a UnixString given a Vec of bytes.

This method will return an error if the given bytes have a zero byte, except if the zero byte is the last element of the Vec.

use unixstring::UnixString;

let bytes_without_zero = b"abc".to_vec();
let bytes_with_nul_terminator = b"abc\0".to_vec();
let bytes_with_interior_nul = b"a\0bc".to_vec();

// Valid: no zero bytes were given
assert!(UnixString::from_bytes(bytes_without_zero).is_ok());

// Still valid: the zero byte is being used as the terminator
assert!(UnixString::from_bytes(bytes_with_nul_terminator).is_ok());

// Invalid: an interior nul byte was found
assert!(UnixString::from_bytes(bytes_with_interior_nul).is_err());

pub fn with_capacity(capacity: usize) -> Self

Constructs a new, empty UnixString with the specified capacity.

The UnixString’s inner vector will be able to hold exactly capacity elements without reallocating.

This function will always allocate enough to fit the null terminator byte, even if the given capacity is 0.

Panics

Panics if the new capacity exceeds isize::MAX - 1 bytes.

pub unsafe fn from_ptr(ptr: *const c_char) -> Self

Clones a raw C string into an UnixString.

The total size of the raw C string must be smaller than isize::MAX bytes in memory due to calling the slice::from_raw_parts function.

Safety

This method is unsafe for a number of reasons:

• There is no guarantee to the validity of ptr.
• There is no guarantee that the memory pointed to by ptr contains a valid nul terminator byte at the end of the string.
• It is not guaranteed that the memory pointed by ptr won’t change before the UnixString has been constructed.

See CStr::from_ptr for more info.

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

Returns an inner pointer to the data this UnixString contains.

The returned pointer will be valid for as long as the given UnixString is, and points to a null-terminated contiguous region of memory.

Note: The returned pointer is read-only and writing to it in any way causes undefined behavior.

You must ensure that the underlying memory is not freed too early. If the UnixString is deallocated then the pointer becomes dangling.

See CStr::as_ptr for more info.

pub fn as_os_str(&self) -> &OsStr

Converts the UnixString to an OsStr slice. This always succeeds and is zero cost. The terminating nul byte will not be included in the OsStr slice.

use std::{convert::TryFrom, path::PathBuf};
use unixstring::UnixString;

let logs = PathBuf::from("/var/log/journal");
let unix_string = UnixString::try_from(logs.clone()).unwrap();

assert_eq!(
    logs.as_os_str(),
    unix_string.as_os_str()
)

pub fn as_path(&self) -> &Path

Converts the UnixString to a Path slice. This always succeeds and is zero cost. The terminating nul byte will not be included in the Path slice.

use std::{convert::TryFrom, path::PathBuf};

use unixstring::UnixString;

let home_dir = PathBuf::from("/home/user");
let unix_string = UnixString::try_from(home_dir.clone()).unwrap();

assert_eq!(&home_dir, unix_string.as_path())

pub fn as_c_str(&self) -> &CStr

Converts the UnixString to a CStr slice. This always succeeds and is zero cost.

pub fn as_str(&self) -> Result<&str>

Tries to convert this UnixString into a &str.

The terminating nul byte will not be included in the &str.

If this byte string is not valid UTF-8, then an error is returned indicating the first invalid byte found and the length of the error. If instead you wish for a lossy conversion to &str, then use to_str_lossy.

pub unsafe fn extend_from_ptr(&mut self, ptr: *const c_char) -> Result<()>

Extends a UnixString by copying from a raw C string

Safety

This method is unsafe for a number of reasons:

• The total size of the raw C string must be smaller than isize::MAX bytes in memory.
• There is no guarantee to the validity of ptr.
• There is no guarantee that the memory pointed to by ptr contains a valid nul terminator byte at the end of the string.
• It is not guaranteed that the memory pointed by ptr won’t change while this operation occurs.

This function uses CStr::from_ptr internally, so check it out for more information.

pub fn into_string_lossy(self) -> String

This function will check if the inner bytes of this UnixString (without its null terminator) consists of valid UTF-8, and if so, returns a String reusing the UnixString’s buffer.

If the inner bytes contain invalid UTF-8, then a new String will be allocated with the invalid bytes replaced with the Unicode replacement codepoint.

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

Converts a UnixString into a String if the bytes of the UnixString are valid UTF-8.

If you are sure that the byte slice is valid UTF-8 and you don’t want to incur the overhead of the validity check, there is an unsafe version of this function, UnixString::into_string_unchecked, which has the same behavior but skips the check.

If the validity check passes, the resulting String will reuse the allocation of the UnixString’s inner buffer and no copy will be done.

If you need a &str instead of a String, consider UnixString::as_str.

pub unsafe fn into_string_unchecked(self) -> String

Converts a UnixString into a String without checking that the string contains valid UTF-8.

See the safe version, UnixString::into_string, for more details.

Safety

This function is unsafe because it does not check that the bytes passed to it are valid UTF-8. If this constraint is violated, it may cause memory unsafety issues with future users of the String, as the rest of the standard library assumes that Strings are valid UTF-8.

Examples

use unixstring::UnixString;

let baby = UnixString::from_bytes(vec![0xF0, 0x9F, 0x91, 0xB6]).unwrap();

let baby = unsafe {
    baby.into_string_unchecked()
};

assert_eq!("👶", baby);

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

This function will check if the inner bytes of this UnixString (without its null terminator) consists of valid UTF-8, and if so, returns a string slice without copying.

If the inner bytes contain invalid UTF-8, then a new String will be allocated with the invalid bytes replaced with the Unicode replacement codepoint.

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

Gets the underlying byte view of this UnixString without the nul terminator.

use unixstring::UnixString;

let bytes = b"abc\0".to_vec();
let unix_string = UnixString::from_bytes(bytes).unwrap();

assert_eq!(
    unix_string.as_bytes(),
    &[b'a', b'b', b'c']
);

pub fn into_os_string(self) -> OsString

Converts a UnixString into an OsString.

This operation is zero-cost.

If you need a &OsStr instead of an OsString, consider UnixString::as_os_str.

pub fn into_pathbuf(self) -> PathBuf

Converts a UnixString into a PathBuf.

This operation is zero-cost.

If you need a &Path instead of a PathBuf, consider UnixString::as_path.

pub fn into_cstring(self) -> CString

Converts a UnixString into a PathBuf.

This operation is zero-cost.

If you need a &CStr instead of a CString, consider UnixString::as_c_str.

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

Gets the underlying byte view of this UnixString including the nul terminator.

use unixstring::UnixString;

let bytes = b"abc\0".to_vec();
let unix_string = UnixString::from_bytes(bytes).unwrap();

assert_eq!(
    unix_string.as_bytes_with_nul(),
    &[b'a', b'b', b'c', 0]
);

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

Returns the inner representation of a UnixString.

The UnixString’s nul terminator byte will be included.

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

Returns the inner representation of a UnixString with its nul-terminator removed.

pub fn from_cstring(cstring: CString) -> Self

Converts a CString into an UnixString.

This operation is zero-cost and does not fail.

This operation fails if the CString has any interior zero byte but a zero byte at the last position is acceptable.

pub fn from_pathbuf(pathbuf: PathBuf) -> Result<Self>

Converts a PathBuf into an UnixString.

A validation will be done to ensure that the PathBuf has no interior zero bytes. Other than that, this operation is zero-cost.

This operation fails if the PathBuf has any interior zero byte but a zero byte at the last position is acceptable.

pub fn from_string(string: String) -> Result<Self>

Converts a String into an UnixString.

A validation will be done to ensure that the String has no interior zero bytes. Other than that, this operation is zero-cost.

This operation fails if the String has any interior zero byte but a zero byte at the last position is acceptable.

pub fn from_os_string(os_string: OsString) -> Result<Self>

Converts an OsString into an UnixString.

A validation will be done to ensure that the OsString has no interior zero bytes. Other than that, this operation is zero-cost.

This operation fails if the OsString has any interior zero byte but a zero byte at the last position is acceptable.

Trait Implementations

impl AsRef<CStr> for UnixString

fn as_ref(&self) -> &CStr

Performs the conversion.

impl AsRef<OsStr> for UnixString

fn as_ref(&self) -> &OsStr

Performs the conversion.

impl AsRef<Path> for UnixString

fn as_ref(&self) -> &Path

Performs the conversion.

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, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for UnixString

fn default() -> Self

Returns the “default value” for a type.

impl From<CString> for UnixString

fn from(value: CString) -> Self

Performs the conversion.

impl From<UnixString> for CString

fn from(unx: UnixString) -> Self

Performs the conversion.

impl From<UnixString> for OsString

fn from(unx: UnixString) -> Self

Performs the conversion.

impl From<UnixString> for PathBuf

fn from(unx: UnixString) -> Self

Performs the conversion.

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, 

Feeds a slice of this type into the given Hasher.

impl Ord for UnixString

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

Restrict a value to a certain interval.

impl PartialEq<UnixString> for UnixString

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

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

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

This method tests for !=.

impl PartialOrd<UnixString> for UnixString

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

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

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

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

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

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

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 TryFrom<OsString> for UnixString

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: OsString) -> Result<Self>

Performs the conversion.

impl TryFrom<PathBuf> for UnixString

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: PathBuf) -> Result<Self>

Performs the conversion.

impl TryFrom<String> for UnixString

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: String) -> Result<Self>

Performs the conversion.

impl TryFrom<Vec<u8, Global>> for UnixString

type Error = Error

The type returned in the event of a conversion error.

fn try_from(bytes: Vec<u8>) -> Result<Self>

Performs the conversion.

impl Eq for UnixString

impl StructuralEq for UnixString

impl StructuralPartialEq for UnixString