Source code
Revision control
Copy as Markdown
Other Tools
//! Strings that are compatible wuth Unix-like operating systems.
//!
//! * [`UnixString`] and [`UnixStr`] are useful when you need to with Unix strings.
//! Conversions between [`UnixString`], [`UnixStr`] and Rust strings work similarly
//! to those for `CString` and `CStr`.
//!
//! * [`UnixString`] represents an owned string in Unix's preferred
//! representation.
//!
//! * [`UnixStr`] represents a borrowed reference to a string in a format that
//! can be passed to a Unix-lie operating system. It can be converted into
//! a UTF-8 Rust string slice in a similar way to [`UnixString`].
//!
//! # Conversions
//!
//! [`UnixStr`] implements two methods, [`from_bytes`] and [`as_bytes`].
//! These do inexpensive conversions from and to UTF-8 byte slices.
//!
//! Additionally, [`UnixString`] provides [`from_vec`] and [`into_vec`] methods
//! that consume their arguments, and take or produce vectors of [`u8`].
//!
//! [`UnixString`]: struct.UnixString.html
//! [`UnixStr`]: struct.UnixStr.html
//! [`from_vec`]: struct.UnixString.html#method.from_vec
//! [`into_vec`]: struct.UnixString.html#method.into_vec
//! [`from_bytes`]: struct.UnixStrExt.html#method.from_bytes
//! [`as_bytes`]: struct.UnixStrExt.html#method.as_bytes
#![cfg_attr(feature = "shrink_to", feature(shrink_to))]
#![cfg_attr(feature = "toowned_clone_into", feature(toowned_clone_into))]
#![no_std]
#[cfg(feature = "alloc")]
extern crate alloc;
use core::cmp;
use core::fmt;
use core::hash::{Hash, Hasher};
use core::mem;
#[cfg(feature = "alloc")]
use alloc::borrow::{Borrow, Cow, ToOwned};
#[cfg(feature = "alloc")]
use alloc::boxed::Box;
#[cfg(feature = "alloc")]
use alloc::rc::Rc;
#[cfg(feature = "alloc")]
use alloc::string::String;
#[cfg(feature = "alloc")]
use alloc::sync::Arc;
#[cfg(feature = "alloc")]
use alloc::vec::Vec;
#[cfg(feature = "alloc")]
use core::ops;
#[cfg(feature = "alloc")]
use core::str::FromStr;
mod lossy;
mod sys;
#[cfg(feature = "alloc")]
use sys::Buf;
use sys::Slice;
mod sys_common;
use sys_common::AsInner;
#[cfg(feature = "alloc")]
use sys_common::{FromInner, IntoInner};
/// 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: `UnixString`s 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][conversions]
/// for a discussion on the traits which `UnixString` implements for
/// [conversions] from/to native representations.
///
/// [`UnixStr`]: struct.UnixStr.html
/// [`&UnixStr`]: struct.UnixStr.html
/// [`CStr`]: struct.CStr.html
/// [`new`]: #method.new
/// [`push`]: #method.push
/// [`as_unix_str`]: #method.as_unix_str
/// [conversions]: index.html#conversions
#[derive(Clone)]
#[cfg(feature = "alloc")]
pub struct UnixString {
inner: Buf,
}
/// Borrowed reference to a Unix string (see [`UnixString`]).
///
/// This type represents a borrowed reference to a string in Unix's preferred
/// representation.
///
/// `&UnixStr` is to [`UnixString`] as `&str` is to `String`: the former
/// in each pair are borrowed references; the latter are owned strings.
///
/// See the [module's toplevel documentation about conversions][conversions]
/// for a discussion on the traits which `UnixStr` implements for [conversions]
/// from/to native representations.
///
/// [`UnixString`]: struct.UnixString.html
/// [conversions]: index.html#conversions
// FIXME:
// `UnixStr::from_inner` current implementation relies on `UnixStr` being
// layout-compatible with `Slice`. When attribute privacy is implemented,
// `UnixStr` should be annotated as `#[repr(transparent)]`. Anyway, `UnixStr`
// representation and layout are considered implementation detail, are
// not documented and must not be relied upon.
pub struct UnixStr {
inner: Slice,
}
#[cfg(feature = "alloc")]
impl UnixString {
/// Constructs a new empty `UnixString`.
///
/// # Examples
///
/// ```
/// use unix_str::UnixString;
///
/// let unix_string = UnixString::new();
/// ```
pub fn new() -> Self {
Self {
inner: Buf::from_string(String::new()),
}
}
/// Converts to an [`UnixStr`] slice.
///
/// [`UnixStr`]: struct.UnixStr.html
///
/// # 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 as_unix_str(&self) -> &UnixStr {
self
}
/// 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 into_string(self) -> Result<String, UnixString> {
self.inner
.into_string()
.map_err(|buf| UnixString { inner: buf })
}
/// Extends the string with the given [`&UnixStr`] slice.
///
/// [`&UnixStr`]: struct.UnixStr.html
///
/// # Examples
///
/// ```
/// use unix_str::UnixString;
///
/// let mut unix_string = UnixString::from("foo");
/// unix_string.push("bar");
/// assert_eq!(&unix_string, "foobar");
/// ```
pub fn push<T: AsRef<UnixStr>>(&mut self, s: T) {
self.inner.push_slice(&s.as_ref().inner)
}
/// 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 with_capacity(capacity: usize) -> Self {
Self {
inner: Buf::with_capacity(capacity),
}
}
/// 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 clear(&mut self) {
self.inner.clear()
}
/// 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 capacity(&self) -> usize {
self.inner.capacity()
}
/// 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(&mut self, additional: usize) {
self.inner.reserve(additional)
}
/// 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 reserve_exact(&mut self, additional: usize) {
self.inner.reserve_exact(additional)
}
/// 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 shrink_to_fit(&mut self) {
self.inner.shrink_to_fit()
}
/// Shrinks the capacity of the `UnixString` with a lower bound.
///
/// The capacity will remain at least as large as both the length
/// and the supplied value.
///
/// Panics if the current capacity is smaller than the supplied
/// minimum capacity.
///
/// # Examples
///
/// ```
/// #![feature(shrink_to)]
/// use std::ffi::UnixString;
///
/// let mut s = UnixString::from("foo");
///
/// s.reserve(100);
/// assert!(s.capacity() >= 100);
///
/// s.shrink_to(10);
/// assert!(s.capacity() >= 10);
/// s.shrink_to(0);
/// assert!(s.capacity() >= 3);
/// ```
#[inline]
#[cfg(feature = "shrink_to")]
pub fn shrink_to(&mut self, min_capacity: usize) {
self.inner.shrink_to(min_capacity)
}
/// Converts this `UnixString` into a boxed [`UnixStr`].
///
/// [`UnixStr`]: struct.UnixStr.html
///
/// # Examples
///
/// ```
/// use unix_str::{UnixString, UnixStr};
///
/// let s = UnixString::from("hello");
///
/// let b: Box<UnixStr> = s.into_boxed_unix_str();
/// ```
pub fn into_boxed_unix_str(self) -> Box<UnixStr> {
let rw = Box::into_raw(self.inner.into_box()) as *mut UnixStr;
unsafe { Box::from_raw(rw) }
}
/// Creates a `UnixString` from a byte vector.
///
/// See the module documentation for an example.
///
pub fn from_vec(vec: Vec<u8>) -> Self {
FromInner::from_inner(Buf { inner: vec })
}
/// Yields the underlying byte vector of this `UnixString`.
///
/// See the module documentation for an example.
pub fn into_vec(self) -> Vec<u8> {
self.into_inner().inner
}
}
#[cfg(feature = "alloc")]
impl From<String> for UnixString {
/// Converts a `String` into a [`UnixString`].
///
/// The conversion copies the data, and includes an allocation on the heap.
///
/// [`UnixString`]: ../../std/ffi/struct.UnixString.html
fn from(s: String) -> Self {
UnixString {
inner: Buf::from_string(s),
}
}
}
#[cfg(feature = "alloc")]
impl<T: ?Sized + AsRef<UnixStr>> From<&T> for UnixString {
fn from(s: &T) -> Self {
s.as_ref().to_unix_string()
}
}
#[cfg(feature = "alloc")]
impl ops::Index<ops::RangeFull> for UnixString {
type Output = UnixStr;
#[inline]
fn index(&self, _index: ops::RangeFull) -> &UnixStr {
UnixStr::from_inner(self.inner.as_slice())
}
}
#[cfg(feature = "alloc")]
impl ops::IndexMut<ops::RangeFull> for UnixString {
#[inline]
fn index_mut(&mut self, _index: ops::RangeFull) -> &mut UnixStr {
UnixStr::from_inner_mut(self.inner.as_mut_slice())
}
}
#[cfg(feature = "alloc")]
impl ops::Deref for UnixString {
type Target = UnixStr;
#[inline]
fn deref(&self) -> &UnixStr {
&self[..]
}
}
#[cfg(feature = "alloc")]
impl ops::DerefMut for UnixString {
#[inline]
fn deref_mut(&mut self) -> &mut UnixStr {
&mut self[..]
}
}
#[cfg(feature = "alloc")]
impl Default for UnixString {
/// Constructs an empty `UnixString`.
#[inline]
fn default() -> Self {
Self::new()
}
}
#[cfg(feature = "alloc")]
impl fmt::Debug for UnixString {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
fmt::Debug::fmt(&**self, formatter)
}
}
#[cfg(feature = "alloc")]
impl PartialEq for UnixString {
fn eq(&self, other: &Self) -> bool {
&**self == &**other
}
}
#[cfg(feature = "alloc")]
impl PartialEq<str> for UnixString {
fn eq(&self, other: &str) -> bool {
&**self == other
}
}
#[cfg(feature = "alloc")]
impl PartialEq<UnixString> for str {
fn eq(&self, other: &UnixString) -> bool {
&**other == self
}
}
#[cfg(feature = "alloc")]
impl PartialEq<&str> for UnixString {
fn eq(&self, other: &&str) -> bool {
**self == **other
}
}
#[cfg(feature = "alloc")]
impl<'a> PartialEq<UnixString> for &'a str {
fn eq(&self, other: &UnixString) -> bool {
**other == **self
}
}
#[cfg(feature = "alloc")]
impl Eq for UnixString {}
#[cfg(feature = "alloc")]
impl PartialOrd for UnixString {
#[inline]
fn partial_cmp(&self, other: &Self) -> Option<cmp::Ordering> {
(&**self).partial_cmp(&**other)
}
#[inline]
fn lt(&self, other: &Self) -> bool {
&**self < &**other
}
#[inline]
fn le(&self, other: &Self) -> bool {
&**self <= &**other
}
#[inline]
fn gt(&self, other: &Self) -> bool {
&**self > &**other
}
#[inline]
fn ge(&self, other: &Self) -> bool {
&**self >= &**other
}
}
#[cfg(feature = "alloc")]
impl PartialOrd<str> for UnixString {
#[inline]
fn partial_cmp(&self, other: &str) -> Option<cmp::Ordering> {
(&**self).partial_cmp(other)
}
}
#[cfg(feature = "alloc")]
impl Ord for UnixString {
#[inline]
fn cmp(&self, other: &Self) -> cmp::Ordering {
(&**self).cmp(&**other)
}
}
#[cfg(feature = "alloc")]
impl Hash for UnixString {
#[inline]
fn hash<H: Hasher>(&self, state: &mut H) {
(&**self).hash(state)
}
}
impl UnixStr {
/// Coerces into an `UnixStr` slice.
///
/// # Examples
///
/// ```
/// use unix_str::UnixStr;
///
/// let unix_str = UnixStr::new("foo");
/// ```
#[inline]
pub fn new<S: AsRef<UnixStr> + ?Sized>(s: &S) -> &UnixStr {
s.as_ref()
}
#[inline]
fn from_inner(inner: &Slice) -> &UnixStr {
// Safety: UnixStr is just a wrapper of Slice,
// therefore converting &Slice to &UnixStr is safe.
unsafe { &*(inner as *const Slice as *const UnixStr) }
}
#[inline]
#[cfg(feature = "alloc")]
fn from_inner_mut(inner: &mut Slice) -> &mut UnixStr {
// Safety: UnixStr is just a wrapper of Slice,
// therefore converting &mut Slice to &mut UnixStr is safe.
// Any method that mutates UnixStr must be careful not to
// break platform-specific encoding, in particular Wtf8 on Windows.
unsafe { &mut *(inner as *mut Slice as *mut UnixStr) }
}
/// 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_str(&self) -> Option<&str> {
self.inner.to_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");
/// ```
#[cfg(feature = "alloc")]
pub fn to_string_lossy(&self) -> Cow<'_, str> {
self.inner.to_string_lossy()
}
/// Copies the slice into an owned [`UnixString`].
///
/// [`UnixString`]: struct.UnixString.html
///
/// # 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"));
/// ```
#[cfg(feature = "alloc")]
pub fn to_unix_string(&self) -> UnixString {
UnixString {
inner: self.inner.to_owned(),
}
}
/// 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());
/// ```
#[inline]
pub fn is_empty(&self) -> bool {
self.inner.inner.is_empty()
}
/// 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.
///
/// [`UnixString`]: struct.UnixString.html
/// [`UnixString::with_capacity`]: struct.UnixString.html#method.with_capacity
///
/// # 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 len(&self) -> usize {
self.inner.inner.len()
}
/// Converts a `Box<UnixStr>` into an [`UnixString`] without copying
/// allocating.
///
/// [`UnixString`]: struct.UnixString.html
#[cfg(feature = "alloc")]
pub fn into_unix_string(self: Box<UnixStr>) -> UnixString {
let boxed = unsafe { Box::from_raw(Box::into_raw(self) as *mut Slice) };
UnixString {
inner: Buf::from_box(boxed),
}
}
/// Gets the underlying byte representation.
///
/// Note: it is *crucial* that this API is private, to avoid
/// revealing the internal, platform-specific encodings.
#[inline]
fn bytes(&self) -> &[u8] {
unsafe { &*(&self.inner as *const _ as *const [u8]) }
}
/// Converts this string to its ASCII lower case equivalent in-place.
///
/// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z', but non-ASCII letters
/// are unchanged.
///
/// To return a new lowercased value without modifying the existing one, use
/// [`to_ascii_lowercase`].
///
/// [`to_ascii_lowercase`]: #method.to_ascii_lowercase
///
/// # Examples
///
/// ```
/// use unix_str::UnixString;
///
/// let mut s = UnixString::from("GRÜßE, JÜRGEN ❤");
///
/// s.make_ascii_lowercase();
///
/// assert_eq!("grÜße, jÜrgen ❤", s);
/// ```
#[cfg(feature = "unixstring_ascii")]
pub fn make_ascii_lowercase(&mut self) {
self.inner.make_ascii_lowercase()
}
/// Converts this string to its ASCII upper case equivalent in-place.
///
/// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
/// but non-ASCII letters are unchanged.
///
/// To return a new uppercased value without modifying the existing one, use
/// [`to_ascii_uppercase`].
///
/// [`to_ascii_uppercase`]: #method.to_ascii_uppercase
///
/// # Examples
///
/// ```
/// use unix_str::UnixString;
///
/// let mut s = UnixString::from("Grüße, Jürgen ❤");
///
/// s.make_ascii_uppercase();
///
/// assert_eq!("GRüßE, JüRGEN ❤", s);
/// ```
#[cfg(feature = "unixstring_ascii")]
pub fn make_ascii_uppercase(&mut self) {
self.inner.make_ascii_uppercase()
}
/// Returns a copy of this string where each character is mapped to its
/// ASCII lower case equivalent.
///
/// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
/// but non-ASCII letters are unchanged.
///
/// To lowercase the value in-place, use [`make_ascii_lowercase`].
///
/// [`make_ascii_lowercase`]: #method.make_ascii_lowercase
///
/// # Examples
///
/// ```
/// use unix_str::UnixString;
/// let s = UnixString::from("Grüße, Jürgen ❤");
///
/// assert_eq!("grüße, jürgen ❤", s.to_ascii_lowercase());
/// ```
#[cfg(all(feature = "alloc", feature = "unixstring_ascii"))]
pub fn to_ascii_lowercase(&self) -> UnixString {
UnixString::from_inner(self.inner.to_ascii_lowercase())
}
/// Returns a copy of this string where each character is mapped to its
/// ASCII upper case equivalent.
///
/// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
/// but non-ASCII letters are unchanged.
///
/// To uppercase the value in-place, use [`make_ascii_uppercase`].
///
/// [`make_ascii_uppercase`]: #method.make_ascii_uppercase
///
/// # Examples
///
/// ```
/// use unix_str::UnixString;
/// let s = UnixString::from("Grüße, Jürgen ❤");
///
/// assert_eq!("GRüßE, JüRGEN ❤", s.to_ascii_uppercase());
/// ```
#[cfg(all(feature = "alloc", feature = "unixstring_ascii"))]
pub fn to_ascii_uppercase(&self) -> UnixString {
UnixString::from_inner(self.inner.to_ascii_uppercase())
}
/// Checks if all characters in this string are within the ASCII range.
///
/// # Examples
///
/// ```
/// use unix_str::UnixString;
///
/// let ascii = UnixString::from("hello!\n");
/// let non_ascii = UnixString::from("Grüße, Jürgen ❤");
///
/// assert!(ascii.is_ascii());
/// assert!(!non_ascii.is_ascii());
/// ```
#[cfg(feature = "unixstring_ascii")]
pub fn is_ascii(&self) -> bool {
self.inner.is_ascii()
}
/// Checks that two strings are an ASCII case-insensitive match.
///
/// Same as `to_ascii_lowercase(a) == to_ascii_lowercase(b)`,
/// but without allocating and copying temporaries.
///
/// # Examples
///
/// ```
/// use unix_str::UnixString;
///
/// assert!(UnixString::from("Ferris").eq_ignore_ascii_case("FERRIS"));
/// assert!(UnixString::from("Ferrös").eq_ignore_ascii_case("FERRöS"));
/// assert!(!UnixString::from("Ferrös").eq_ignore_ascii_case("FERRÖS"));
/// ```
#[cfg(feature = "unixstring_ascii")]
pub fn eq_ignore_ascii_case<S: ?Sized + AsRef<UnixStr>>(&self, other: &S) -> bool {
self.inner.eq_ignore_ascii_case(&other.as_ref().inner)
}
/// Creates a `UnixStr` from a byte slice.
///
/// See the module documentation for an example.
pub fn from_bytes(slice: &[u8]) -> &Self {
unsafe { mem::transmute(slice) }
}
/// Gets the underlying byte view of the `UnixStr` slice.
///
/// See the module documentation for an example.
pub fn as_bytes(&self) -> &[u8] {
&self.as_inner().inner
}
}
#[cfg(feature = "alloc")]
impl From<&UnixStr> for Box<UnixStr> {
fn from(s: &UnixStr) -> Self {
let rw = Box::into_raw(s.inner.into_box()) as *mut UnixStr;
unsafe { Box::from_raw(rw) }
}
}
#[cfg(feature = "alloc")]
impl From<Cow<'_, UnixStr>> for Box<UnixStr> {
#[inline]
fn from(cow: Cow<'_, UnixStr>) -> Self {
match cow {
Cow::Borrowed(s) => Box::from(s),
Cow::Owned(s) => Box::from(s),
}
}
}
#[cfg(feature = "alloc")]
impl From<Box<UnixStr>> for UnixString {
/// Converts a `Box<UnixStr>` into a `UnixString` without copying or
/// allocating.
///
/// [`UnixStr`]: ../ffi/struct.UnixStr.html
fn from(boxed: Box<UnixStr>) -> Self {
boxed.into_unix_string()
}
}
#[cfg(feature = "alloc")]
impl From<UnixString> for Box<UnixStr> {
/// Converts a [`UnixString`] into a `Box<UnixStr>` without copying or
/// allocating.
///
/// [`UnixString`]: ../ffi/struct.UnixString.html
fn from(s: UnixString) -> Self {
s.into_boxed_unix_str()
}
}
#[cfg(feature = "alloc")]
impl Clone for Box<UnixStr> {
#[inline]
fn clone(&self) -> Self {
self.to_unix_string().into_boxed_unix_str()
}
}
#[cfg(feature = "alloc")]
impl From<UnixString> for Arc<UnixStr> {
/// Converts a [`UnixString`] into a `Arc<UnixStr>` without copying or
/// allocating.
///
/// [`UnixString`]: ../ffi/struct.UnixString.html
#[inline]
fn from(s: UnixString) -> Self {
let arc = s.inner.into_arc();
unsafe { Arc::from_raw(Arc::into_raw(arc) as *const UnixStr) }
}
}
#[cfg(feature = "alloc")]
impl From<&UnixStr> for Arc<UnixStr> {
#[inline]
fn from(s: &UnixStr) -> Self {
let arc = s.inner.into_arc();
unsafe { Arc::from_raw(Arc::into_raw(arc) as *const UnixStr) }
}
}
#[cfg(feature = "alloc")]
impl From<UnixString> for Rc<UnixStr> {
/// Converts a [`UnixString`] into a `Rc<UnixStr>` without copying or
/// allocating.
///
/// [`UnixString`]: ../ffi/struct.UnixString.html
#[inline]
fn from(s: UnixString) -> Self {
let rc = s.inner.into_rc();
unsafe { Rc::from_raw(Rc::into_raw(rc) as *const UnixStr) }
}
}
#[cfg(feature = "alloc")]
impl From<&UnixStr> for Rc<UnixStr> {
#[inline]
fn from(s: &UnixStr) -> Self {
let rc = s.inner.into_rc();
unsafe { Rc::from_raw(Rc::into_raw(rc) as *const UnixStr) }
}
}
#[cfg(feature = "alloc")]
impl<'a> From<UnixString> for Cow<'a, UnixStr> {
#[inline]
fn from(s: UnixString) -> Self {
Cow::Owned(s)
}
}
#[cfg(feature = "alloc")]
impl<'a> From<&'a UnixStr> for Cow<'a, UnixStr> {
#[inline]
fn from(s: &'a UnixStr) -> Self {
Cow::Borrowed(s)
}
}
#[cfg(feature = "alloc")]
impl<'a> From<&'a UnixString> for Cow<'a, UnixStr> {
#[inline]
fn from(s: &'a UnixString) -> Self {
Cow::Borrowed(s.as_unix_str())
}
}
#[cfg(feature = "alloc")]
impl<'a> From<Cow<'a, UnixStr>> for UnixString {
#[inline]
fn from(s: Cow<'a, UnixStr>) -> Self {
s.into_owned()
}
}
#[cfg(feature = "alloc")]
impl Default for Box<UnixStr> {
fn default() -> Self {
let rw = Box::into_raw(Slice::empty_box()) as *mut UnixStr;
unsafe { Box::from_raw(rw) }
}
}
impl Default for &UnixStr {
/// Creates an empty `UnixStr`.
#[inline]
fn default() -> Self {
UnixStr::new("")
}
}
impl PartialEq for UnixStr {
#[inline]
fn eq(&self, other: &UnixStr) -> bool {
self.bytes().eq(other.bytes())
}
}
impl PartialEq<str> for UnixStr {
#[inline]
fn eq(&self, other: &str) -> bool {
*self == *UnixStr::new(other)
}
}
impl PartialEq<UnixStr> for str {
#[inline]
fn eq(&self, other: &UnixStr) -> bool {
*other == *UnixStr::new(self)
}
}
impl Eq for UnixStr {}
impl PartialOrd for UnixStr {
#[inline]
fn partial_cmp(&self, other: &Self) -> Option<cmp::Ordering> {
self.bytes().partial_cmp(other.bytes())
}
#[inline]
fn lt(&self, other: &Self) -> bool {
self.bytes().lt(other.bytes())
}
#[inline]
fn le(&self, other: &Self) -> bool {
self.bytes().le(other.bytes())
}
#[inline]
fn gt(&self, other: &Self) -> bool {
self.bytes().gt(other.bytes())
}
#[inline]
fn ge(&self, other: &Self) -> bool {
self.bytes().ge(other.bytes())
}
}
impl PartialOrd<str> for UnixStr {
#[inline]
fn partial_cmp(&self, other: &str) -> Option<cmp::Ordering> {
self.partial_cmp(Self::new(other))
}
}
// FIXME (#19470): cannot provide PartialOrd<UnixStr> for str until we
// have more flexible coherence rules.
impl Ord for UnixStr {
#[inline]
fn cmp(&self, other: &Self) -> cmp::Ordering {
self.bytes().cmp(other.bytes())
}
}
#[cfg(feature = "alloc")]
macro_rules! impl_cmp {
($lhs:ty, $rhs: ty) => {
impl<'a, 'b> PartialEq<$rhs> for $lhs {
#[inline]
fn eq(&self, other: &$rhs) -> bool {
<UnixStr as PartialEq>::eq(self, other)
}
}
impl<'a, 'b> PartialEq<$lhs> for $rhs {
#[inline]
fn eq(&self, other: &$lhs) -> bool {
<UnixStr as PartialEq>::eq(self, other)
}
}
impl<'a, 'b> PartialOrd<$rhs> for $lhs {
#[inline]
fn partial_cmp(&self, other: &$rhs) -> Option<cmp::Ordering> {
<UnixStr as PartialOrd>::partial_cmp(self, other)
}
}
impl<'a, 'b> PartialOrd<$lhs> for $rhs {
#[inline]
fn partial_cmp(&self, other: &$lhs) -> Option<cmp::Ordering> {
<UnixStr as PartialOrd>::partial_cmp(self, other)
}
}
};
}
#[cfg(feature = "alloc")]
impl_cmp!(UnixString, UnixStr);
#[cfg(feature = "alloc")]
impl_cmp!(UnixString, &'a UnixStr);
#[cfg(feature = "alloc")]
impl_cmp!(Cow<'a, UnixStr>, UnixStr);
#[cfg(feature = "alloc")]
impl_cmp!(Cow<'a, UnixStr>, &'b UnixStr);
#[cfg(feature = "alloc")]
impl_cmp!(Cow<'a, UnixStr>, UnixString);
impl Hash for UnixStr {
#[inline]
fn hash<H: Hasher>(&self, state: &mut H) {
self.bytes().hash(state)
}
}
impl fmt::Debug for UnixStr {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
fmt::Debug::fmt(&self.inner, formatter)
}
}
#[cfg(feature = "alloc")]
impl Borrow<UnixStr> for UnixString {
fn borrow(&self) -> &UnixStr {
&self[..]
}
}
#[cfg(feature = "alloc")]
impl ToOwned for UnixStr {
type Owned = UnixString;
fn to_owned(&self) -> Self::Owned {
self.to_unix_string()
}
#[cfg(feature = "toowned_clone_into")]
fn clone_into(&self, target: &mut Self::Owned) {
self.inner.clone_into(&mut target.inner)
}
}
impl AsRef<UnixStr> for UnixStr {
fn as_ref(&self) -> &UnixStr {
self
}
}
#[cfg(feature = "alloc")]
impl AsRef<UnixStr> for UnixString {
#[inline]
fn as_ref(&self) -> &UnixStr {
self
}
}
impl AsRef<UnixStr> for str {
#[inline]
fn as_ref(&self) -> &UnixStr {
UnixStr::from_inner(Slice::from_str(self))
}
}
#[cfg(feature = "alloc")]
impl AsRef<UnixStr> for String {
#[inline]
fn as_ref(&self) -> &UnixStr {
(&**self).as_ref()
}
}
#[cfg(feature = "alloc")]
impl FromInner<Buf> for UnixString {
fn from_inner(buf: Buf) -> UnixString {
UnixString { inner: buf }
}
}
#[cfg(feature = "alloc")]
impl IntoInner<Buf> for UnixString {
fn into_inner(self) -> Buf {
self.inner
}
}
impl AsInner<Slice> for UnixStr {
#[inline]
fn as_inner(&self) -> &Slice {
&self.inner
}
}
#[cfg(feature = "alloc")]
impl FromStr for UnixString {
type Err = core::convert::Infallible;
fn from_str(s: &str) -> Result<Self, Self::Err> {
Ok(UnixString::from(s))
}
}
#[cfg(test)]
mod tests {
use super::*;
use sys_common::{AsInner, IntoInner};
use alloc::rc::Rc;
use alloc::sync::Arc;
#[test]
fn test_unix_string_with_capacity() {
let unix_string = UnixString::with_capacity(0);
assert_eq!(0, unix_string.inner.into_inner().capacity());
let unix_string = UnixString::with_capacity(10);
assert_eq!(10, unix_string.inner.into_inner().capacity());
let mut unix_string = UnixString::with_capacity(0);
unix_string.push("abc");
assert!(unix_string.inner.into_inner().capacity() >= 3);
}
#[test]
fn test_unix_string_clear() {
let mut unix_string = UnixString::from("abc");
assert_eq!(3, unix_string.inner.as_inner().len());
unix_string.clear();
assert_eq!(&unix_string, "");
assert_eq!(0, unix_string.inner.as_inner().len());
}
#[test]
fn test_unix_string_capacity() {
let unix_string = UnixString::with_capacity(0);
assert_eq!(0, unix_string.capacity());
let unix_string = UnixString::with_capacity(10);
assert_eq!(10, unix_string.capacity());
let mut unix_string = UnixString::with_capacity(0);
unix_string.push("abc");
assert!(unix_string.capacity() >= 3);
}
#[test]
fn test_unix_string_reserve() {
let mut unix_string = UnixString::new();
assert_eq!(unix_string.capacity(), 0);
unix_string.reserve(2);
assert!(unix_string.capacity() >= 2);
for _ in 0..16 {
unix_string.push("a");
}
assert!(unix_string.capacity() >= 16);
unix_string.reserve(16);
assert!(unix_string.capacity() >= 32);
unix_string.push("a");
unix_string.reserve(16);
assert!(unix_string.capacity() >= 33)
}
#[test]
fn test_unix_string_reserve_exact() {
let mut unix_string = UnixString::new();
assert_eq!(unix_string.capacity(), 0);
unix_string.reserve_exact(2);
assert!(unix_string.capacity() >= 2);
for _ in 0..16 {
unix_string.push("a");
}
assert!(unix_string.capacity() >= 16);
unix_string.reserve_exact(16);
assert!(unix_string.capacity() >= 32);
unix_string.push("a");
unix_string.reserve_exact(16);
assert!(unix_string.capacity() >= 33)
}
#[test]
fn test_unix_string_default() {
let unix_string: UnixString = Default::default();
assert_eq!("", &unix_string);
}
#[test]
fn test_unix_str_is_empty() {
let mut unix_string = UnixString::new();
assert!(unix_string.is_empty());
unix_string.push("abc");
assert!(!unix_string.is_empty());
unix_string.clear();
assert!(unix_string.is_empty());
}
#[test]
fn test_unix_str_len() {
let mut unix_string = UnixString::new();
assert_eq!(0, unix_string.len());
unix_string.push("abc");
assert_eq!(3, unix_string.len());
unix_string.clear();
assert_eq!(0, unix_string.len());
}
#[test]
fn test_unix_str_default() {
let unix_str: &UnixStr = Default::default();
assert_eq!("", unix_str);
}
#[test]
fn into_boxed() {
let orig = "Hello, world!";
let unix_str = UnixStr::new(orig);
let boxed: Box<UnixStr> = Box::from(unix_str);
let unix_string = unix_str.to_owned().into_boxed_unix_str().into_unix_string();
assert_eq!(unix_str, &*boxed);
assert_eq!(&*boxed, &*unix_string);
assert_eq!(&*unix_string, unix_str);
}
#[test]
fn boxed_default() {
let boxed = <Box<UnixStr>>::default();
assert!(boxed.is_empty());
}
#[test]
#[cfg(feature = "toowned_clone_into")]
fn test_unix_str_clone_into() {
let mut unix_string = UnixString::with_capacity(123);
unix_string.push("hello");
let unix_str = UnixStr::new("bonjour");
unix_str.clone_into(&mut unix_string);
assert_eq!(unix_str, unix_string);
assert!(unix_string.capacity() >= 123);
}
#[test]
fn into_rc() {
let orig = "Hello, world!";
let unix_str = UnixStr::new(orig);
let rc: Rc<UnixStr> = Rc::from(unix_str);
let arc: Arc<UnixStr> = Arc::from(unix_str);
assert_eq!(&*rc, unix_str);
assert_eq!(&*arc, unix_str);
let rc2: Rc<UnixStr> = Rc::from(unix_str.to_owned());
let arc2: Arc<UnixStr> = Arc::from(unix_str.to_owned());
assert_eq!(&*rc2, unix_str);
assert_eq!(&*arc2, unix_str);
}
}