xstring 0.1.1

An immutable owned string that could be cheaply cloned and passed through FFI.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91

/// Represents str-like types that could be cast to valid byte patterns and back.
///
/// # Safety
///
/// It is the implementor's responsibility to ensure that the bytes returned by `as_bytes` could be safely passed to `from_bytes_unchecked`.
pub unsafe trait Str {
    /// Casts the given bytes to a reference to `Self`.
    ///
    /// # Safety
    ///
    /// The bytes must be valid byte patterns for `Self`.
    unsafe fn from_bytes_unchecked(bytes: &[u8]) -> &Self;

    /// Casts the given reference to `Self` to a slice of bytes.
    fn as_bytes(&self) -> &[u8];

    /// Indicates whether the bytes returned by `as_bytes` contain a NUL byte.
    const CONTAINS_NUL: bool;
}

unsafe impl Str for str {
    #[inline(always)]
    unsafe fn from_bytes_unchecked(bytes: &[u8]) -> &Self {
        unsafe { core::str::from_utf8_unchecked(bytes) }
    }

    #[inline(always)]
    fn as_bytes(&self) -> &[u8] {
        self.as_bytes()
    }

    const CONTAINS_NUL: bool = false;
}

unsafe impl Str for [u8] {
    #[inline(always)]
    unsafe fn from_bytes_unchecked(bytes: &[u8]) -> &Self {
        bytes
    }

    #[inline(always)]
    fn as_bytes(&self) -> &[u8] {
        self
    }

    const CONTAINS_NUL: bool = false;
}

unsafe impl Str for core::ffi::CStr {
    #[inline(always)]
    unsafe fn from_bytes_unchecked(bytes: &[u8]) -> &Self {
        unsafe { core::ffi::CStr::from_bytes_with_nul_unchecked(bytes) }
    }

    #[inline(always)]
    fn as_bytes(&self) -> &[u8] {
        self.to_bytes_with_nul()
    }

    const CONTAINS_NUL: bool = true;
}

#[cfg(feature = "std")]
unsafe impl Str for std::ffi::OsStr {
    #[inline(always)]
    unsafe fn from_bytes_unchecked(bytes: &[u8]) -> &Self {
        unsafe { std::ffi::OsStr::from_encoded_bytes_unchecked(bytes) }
    }

    #[inline(always)]
    fn as_bytes(&self) -> &[u8] {
        self.as_encoded_bytes()
    }

    const CONTAINS_NUL: bool = false;
}

#[cfg(feature = "std")]
unsafe impl Str for std::path::Path {
    #[inline(always)]
    unsafe fn from_bytes_unchecked(bytes: &[u8]) -> &Self {
        unsafe { Self::new(std::ffi::OsStr::from_bytes_unchecked(bytes)) }
    }

    #[inline(always)]
    fn as_bytes(&self) -> &[u8] {
        self.as_os_str().as_encoded_bytes()
    }

    const CONTAINS_NUL: bool = false;
}