UnixString: a convenient FFI-friendly null-terminated byte string

This post has been de-listed

It is no longer included in search results and normal feeds (front page, hot posts, subreddit posts, etc). It remains visible only via the author's post history.

126

Post Body

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 expanded after instantiated, while UnixString is growable through its push and push_bytes methods, somewhat similar to OsString's usage.

A CString also does not have direct reference conversions to anything but &[u8] or &CStr, while UnixString can be converted to &OsStr, &Path, &CStr, &[u8] and &str (but only if it contains valid UTF-8)

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 function, 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

Thoughts? Suggestions?

Links

On GitHub

On crates.io

On docs.rs

Author

Account Strength

100%

Account Age

10 years

Verified Email

Yes

Verified Flair

Total Karma

24,261

Link Karma

3,790

Comment Karma

20,224

Profile updated: 1 day ago

Posts updated: 1 month ago

VinceMiguel

Subreddit

r/rust

Post Details

We try to extract some basic information from the post title. This is not always successful or accurate, please use your best judgement and compare these values to the post title and body for confirmation.

Posted: 3 years ago
Reddit URL: View post on reddit.com
External URL: reddit.com/r/rust/commen...