barf 1.0.0

Turn any input into "barf"-ed output.
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
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

#![doc = include_str!("../README.md")]
#![cfg_attr(not(feature = "std"), no_std)]

#[cfg(feature = "std")]
extern crate std;

#[cfg(feature = "alloc")]
extern crate alloc;
#[cfg(feature = "alloc")]
use alloc::string::String;
#[cfg(feature = "alloc")]
use alloc::vec::Vec;

use core::clone::Clone;
use core::iter::IntoIterator;
use core::result::Result;

mod stack_buffer;
pub use stack_buffer::*;

mod ext;
pub use ext::*;

/// A [`Barfer`] is a trait that wraps buffers for use with this crate, `barf`.
///
/// It exposes an associated Error type - usually [`core::convert::Infallible`], and functions to
/// interact with the buffer.
///
/// - [`Barfer::single`]: Add a single value of type `T` into the buffer.
/// - [`Barfer::many`]: Add an [`IntoIterator`] of values into the buffer.
/// - [`Barfer::slice`]: Add an [`AsRef<T>`] of values into the buffer, only exists if `T` implements [`Clone`].
pub trait Barfer<T> {
    /// Error type of the three functions, usually [`core::convert::Infallible`].
    ///
    /// Could be used to express errors such as not having enough capacity to fit new values.
    type Error;

    /// Add a single value to the buffer.
    ///
    /// # Examples
    /// ```
    /// # use barf::Barfer;
    /// let mut buf: Vec<u8> = Vec::new();
    /// buf.single(42);
    ///
    /// assert_eq!(buf[0], 42);
    /// ```
    fn single(&mut self, value: T) -> Result<(), Self::Error>;

    /// Add a single value of type `T` into the buffer.
    ///
    /// # Examples
    /// ```
    /// # use barf::Barfer;
    /// let mut buf: Vec<u8> = Vec::new();
    /// buf.many([1, 2, 3]);
    ///
    /// assert_eq!(buf.as_slice(), [1, 2, 3]);
    /// ```
    fn many<I: IntoIterator<Item = T>>(&mut self, iter: I) -> Result<(), Self::Error> {
        for value in iter {
            self.single(value)?;
        }

        Ok(())
    }

    /// Add an [`AsRef<T>`] of values into the buffer.
    ///
    /// Only exists if `T` implements [`Clone`].
    ///
    /// # Examples
    /// ```
    /// # use barf::Barfer;
    /// let mut buf: Vec<u8> = Vec::new();
    /// buf.slice([1, 2, 3]);
    ///
    /// assert_eq!(buf.as_slice(), [1, 2, 3]);
    /// ```
    fn slice<S: AsRef<[T]>>(&mut self, slice: S) -> Result<(), Self::Error>
    where
        T: Clone;
}

#[cfg(any(feature = "std", feature = "alloc"))]
impl<T> Barfer<T> for Vec<T> {
    type Error = core::convert::Infallible;

    #[inline]
    fn single(&mut self, value: T) -> Result<(), Self::Error> {
        self.push(value);
        Ok(())
    }

    #[inline]
    fn many<I: IntoIterator<Item = T>>(&mut self, iter: I) -> Result<(), Self::Error> {
        self.extend(iter);
        Ok(())
    }

    #[inline]
    fn slice<S: AsRef<[T]>>(&mut self, slice: S) -> Result<(), Self::Error>
    where
        T: Clone,
    {
        self.extend_from_slice(slice.as_ref());
        Ok(())
    }
}

#[cfg(any(feature = "std", feature = "alloc"))]
impl Barfer<char> for String {
    type Error = core::convert::Infallible;

    #[inline]
    fn single(&mut self, value: char) -> Result<(), Self::Error> {
        self.push(value);
        Ok(())
    }

    #[inline]
    fn many<I: IntoIterator<Item = char>>(&mut self, iter: I) -> Result<(), Self::Error> {
        self.extend(iter);
        Ok(())
    }

    #[inline]
    fn slice<S: AsRef<[char]>>(&mut self, slice: S) -> Result<(), Self::Error> {
        let slice = slice.as_ref();
        let mut buf = [0; 4];

        for c in slice {
            self.push_str(c.encode_utf8(&mut buf));
        }
        Ok(())
    }
}