Crate unixstring

unixstring

UnixString is an FFI-friendly null-terminated byte string that may be constructed from a String, a CString, a PathBuf, an OsString or a collection of bytes.

An UnixString can then be converted into a slice of CStr, Path or OsStr in infallible and zero-cost operations.

Why?

UnixString aims to be useful in any scenario where you’d like to use FFI (specially with C) on Unix systems. If you have a PathBuf, for example, you can send that data to a libc function, such as stat, but you’d have to first allocate a CString (or something analogous) to do so.

The same is true with OsString and String because these three types are allowed to have internal zero bytes and are not null-terminated.

A UnixString is very close to what a CString is but with increased flexibility and usability. A CString cannot be changed or increased after instantited, while UnixString is growable through its push and push_bytes methods, somewhat similar to OsString.

A CString also does not have direct reference conversions to anything but &[u8] or &CStr, while UnixString has those and more (described below).

Obtaining references from an UnixString

Into	Function	Notes
&CStr	UnixString::as_c_str	Available through AsRef as well
&Path	UnixString::as_path	Available through AsRef as well
&str	UnixString::as_str	Fails if the bytes of the UnixString aren’t valid UTF-8
&[u8]	UnixString::as_bytes	Returns the bytes of the UnixString without the null terminator
&[u8]	UnixString::as_bytes_with_nul	Returns the bytes of the UnixString with the null terminator
&OsStr	UnixString::as_os_str	Available through AsRef as well
* const c_char	UnixString::as_ptr

Creating an UnixString

From	Potential failure	Trait impl	Function
CString	Infallible	From	UnixString::from_cstring
PathBuf	Fails if contains an interior zero byte	TryFrom	UnixString::from_pathbuf
String	Fails if contains an interior zero byte	TryFrom	UnixString::from_string
Vec<u8>	Fails if contains an interior zero byte	TryFrom	UnixString::from_bytes
OsString	Fails if contains an interior zero byte	TryFrom	UnixString::from_os_string
* const c_char	Unsafe, see the docs for more info	None	UnixString::from_ptr

Converting from an UnixString

Into	Function	Notes
CString	UnixString::into_cstring
PathBuf	UnixString::into_pathbuf
OsString	UnixString::into_os_string
String	UnixString::into_string	Fails if the UnixString’s bytes are not valid UTF-8
String	UnixString::into_string_lossy
String	UnixString::to_string_lossy	Non-moving version of UnixString::into_string_lossy
String	UnixString::into_string_unchecked	Unsafe: creates a String without checking if the bytes are valid UTF-8
Vec<u8>	UnixString::into_bytes	Returns the bytes of the UnixString without the null terminator
Vec<u8>	UnixString::into_bytes_with_nul	Returns the bytes of the UnixString with the null terminator

All of the above are also available through .into().

Structs

UnixString

An FFI-friendly null-terminated byte string.

Enums

Error

An error enum that encapsulates all possible errors in this crate.

Type Definitions

Result

A Result type alias for this crate’s Error type.