chromium 0.0.2

Helps add some stability to your metal!
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
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

use core::{fmt::Debug, marker::PhantomData, ops::Deref, slice, str};

use super::StableLayout;

// General Safety Note: The soundness of the `SharedStr` type is centered
// around the fact that the fields are all private, and so *safe rust* must
// construct values of the type from an existing valid slice. However, because
// the type is `repr(C)` it can of course be constructed with unsafe rust, or
// even by foreign code. It is the responsibility of _the other code_ to ensure
// that the actual fields are valid for being turned into a slice.

/// A struct for **shared** `str` views with a stable layout.
///
/// This is a `repr(C)` variant of `&str`. If you want a variant of `&mut str`
/// then you should use [`UniqueStr`](crate::UniqueStr) instead.
///
/// Rationale for using this type is given in the crate level docs.
///
/// ## Unsafety
///
/// Because this type is primarily intended to help _unsafe_ Rust we should
/// discuss the precise guarantees offered:
/// * **Validity Invariants**
///   * The data layout is a `*const u8` and then a `usize`.
/// * **Soundness Invariants**
///   * The `*const u8` must point to the start of a valid `&str`.
///   * The `usize` must be the correct length of that valid `&str`.
///   * For as long as the `SharedStr` exists the memory in question has a
///     shared borrow over it (tracked via `PhantomData`).
///   * The memory must contain value UTF-8 data.
///
/// This type matches up with the following C layout:
/// ```c
/// #include <stdint.h>
/// // Identical layout to `SharedStr<'a>`
/// typedef struct {
///   uint8_t const *ptr;
///   uintptr_t len;
/// } SharedStr;
/// ```
#[repr(C)]
pub struct SharedStr<'a> {
  ptr: *const u8,
  len: usize,
  life: PhantomData<&'a str>,
}

unsafe impl<'a> StableLayout for SharedStr<'a> {}

impl<'a> Debug for SharedStr<'a> {
  /// Debug prints as a slice would.
  fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result {
    Debug::fmt(self.deref(), f)
  }
}

impl<'a> Clone for SharedStr<'a> {
  #[inline(always)]
  fn clone(&self) -> Self {
    *self
  }
}

impl<'a> Copy for SharedStr<'a> {}

impl<'a> Default for SharedStr<'a> {
  /// Defaults to an empty string.
  ///
  /// ```rust
  /// # use chromium::*;
  /// let shared: SharedStr<'static> = SharedStr::default();
  /// assert_eq!(shared.len(), "".len());
  /// ```
  #[inline(always)]
  fn default() -> Self {
    let life = PhantomData;
    let len = 0;
    let ptr = core::ptr::NonNull::dangling().as_ptr();
    Self { ptr, len, life }
  }
}

impl<'a> Deref for SharedStr<'a> {
  type Target = str;
  #[inline(always)]
  fn deref(&self) -> &str {
    // Safety: See note at the top of the module.
    unsafe {
      str::from_utf8_unchecked(slice::from_raw_parts(self.ptr, self.len))
    }
  }
}

impl<'a> From<&'a str> for SharedStr<'a> {
  #[inline(always)]
  fn from(s: &'a str) -> Self {
    let life = PhantomData;
    let len = s.len();
    let ptr = s.as_ptr();
    Self { ptr, len, life }
  }
}

impl<'a> From<SharedStr<'a>> for &'a str {
  #[inline(always)]
  fn from(shared: SharedStr<'a>) -> Self {
    // Safety: See note at the top of the module.
    unsafe {
      str::from_utf8_unchecked(slice::from_raw_parts(shared.ptr, shared.len))
    }
  }
}