spinoso_string/
center.rs

1use core::fmt;
2use core::iter::{Cycle, FusedIterator, Take};
3use core::slice;
4
5use crate::chars::Chars;
6
7/// Error returned when failing to construct a [`Center`] iterator.
8///
9/// This error is returned from [`String::center`]. See its documentation for
10/// more detail.
11///
12/// This error corresponds to the [Ruby `ArgumentError` Exception class].
13///
14/// When the **std** feature of `spinoso-string` is enabled, this struct
15/// implements [`std::error::Error`].
16///
17/// [`String::center`]: crate::String::center
18/// [Ruby `ArgumentError` Exception class]: https://ruby-doc.org/core-3.1.2/ArgumentError.html
19/// [`std::error::Error`]: https://doc.rust-lang.org/std/error/trait.Error.html
20#[derive(Debug, Clone, Copy, Hash, PartialEq, Eq, PartialOrd, Ord)]
21pub enum CenterError {
22    /// Error returned when calling [`String::center`] with an empty padding
23    /// byte string.
24    ///
25    /// [`String::center`]: crate::String::center
26    ZeroWidthPadding,
27}
28
29impl CenterError {
30    pub const EXCEPTION_TYPE: &'static str = "ArgumentError";
31
32    /// Create a new zero width padding `CenterError`.
33    ///
34    /// # Examples
35    ///
36    /// ```
37    /// use spinoso_string::CenterError;
38    ///
39    /// const ERR: CenterError = CenterError::zero_width_padding();
40    /// assert_eq!(ERR.message(), "zero width padding");
41    /// ```
42    #[inline]
43    #[must_use]
44    pub const fn zero_width_padding() -> Self {
45        Self::ZeroWidthPadding
46    }
47
48    /// Retrieve the exception message associated with this center error.
49    ///
50    /// # Examples
51    ///
52    /// ```
53    /// # use spinoso_string::CenterError;
54    /// let err = CenterError::zero_width_padding();
55    /// assert_eq!(err.message(), "zero width padding");
56    /// ```
57    #[inline]
58    #[must_use]
59    pub const fn message(self) -> &'static str {
60        "zero width padding"
61    }
62}
63
64impl fmt::Display for CenterError {
65    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
66        let CenterError::ZeroWidthPadding = self;
67        f.write_str(self.message())
68    }
69}
70
71#[cfg(feature = "std")]
72impl std::error::Error for CenterError {}
73
74/// An iterator that yields a byte string centered within a padding byte string.
75///
76/// This struct is created by the [`center`] method on a Spinoso [`String`]. See
77/// its documentation for more.
78///
79/// # Examples
80///
81/// ```
82/// use spinoso_string::String;
83/// # fn example() -> Result<(), spinoso_string::CenterError> {
84/// let s = String::from("hello");
85///
86/// assert_eq!(s.center(4, None)?.collect::<Vec<_>>(), b"hello");
87/// assert_eq!(
88///     s.center(20, None)?.collect::<Vec<_>>(),
89///     b"       hello        "
90/// );
91/// assert_eq!(
92///     s.center(20, Some(&b"123"[..]))?.collect::<Vec<_>>(),
93///     b"1231231hello12312312"
94/// );
95/// # Ok(())
96/// # }
97/// # example().unwrap();
98/// ```
99///
100/// This iterator is [encoding-aware]. [Conventionally UTF-8] strings are
101/// iterated by UTF-8 byte sequences.
102///
103/// ```
104/// use spinoso_string::String;
105/// # fn example() -> Result<(), spinoso_string::CenterError> {
106/// let s = String::from("💎");
107///
108/// assert_eq!(s.center(3, None)?.collect::<Vec<_>>(), " 💎 ".as_bytes());
109/// # Ok(())
110/// # }
111/// # example().unwrap();
112/// ```
113///
114/// [`String`]: crate::String
115/// [`center`]: crate::String::center
116/// [encoding-aware]: crate::Encoding
117/// [Conventionally UTF-8]: crate::Encoding::Utf8
118#[derive(Debug, Clone)]
119pub struct Center<'a, 'b> {
120    left: Take<Cycle<slice::Iter<'b, u8>>>,
121    next: Option<&'a [u8]>,
122    s: Chars<'a>,
123    right: Take<Cycle<slice::Iter<'b, u8>>>,
124}
125
126impl Default for Center<'_, '_> {
127    #[inline]
128    fn default() -> Self {
129        Self::with_chars_width_and_padding(Chars::new(), 0, &[])
130    }
131}
132
133impl<'a, 'b> Center<'a, 'b> {
134    #[inline]
135    #[must_use]
136    pub(crate) fn with_chars_width_and_padding(s: Chars<'a>, padding_width: usize, padding: &'b [u8]) -> Self {
137        let pre_pad = padding_width / 2;
138        let post_pad = (padding_width + 1) / 2;
139        let left = padding.iter().cycle().take(pre_pad);
140        let right = padding.iter().cycle().take(post_pad);
141        Self {
142            left,
143            next: None,
144            s,
145            right,
146        }
147    }
148}
149
150impl Iterator for Center<'_, '_> {
151    type Item = u8;
152
153    #[inline]
154    fn next(&mut self) -> Option<Self::Item> {
155        if let Some(&next) = self.left.next() {
156            return Some(next);
157        }
158        if let Some(next) = self.next.take() {
159            if let Some((&first, tail)) = next.split_first() {
160                self.next = Some(tail);
161                return Some(first);
162            }
163        }
164        if let Some(next) = self.s.next() {
165            if let Some((&first, tail)) = next.split_first() {
166                if !tail.is_empty() {
167                    self.next = Some(tail);
168                }
169                return Some(first);
170            }
171        }
172        self.right.next().copied()
173    }
174}
175
176impl FusedIterator for Center<'_, '_> {}
177
178impl ExactSizeIterator for Center<'_, '_> {}
spinoso_string/center.rs

spinoso_string/
center.rs
