1 //! Extra utilities for `Buf` and `BufMut` types.
2 
3 use super::{Buf, BufMut};
4 
5 mod chain;
6 mod limit;
7 #[cfg(feature = "std")]
8 mod reader;
9 mod take;
10 #[cfg(feature = "std")]
11 mod writer;
12 
13 pub use self::chain::Chain;
14 pub use self::limit::Limit;
15 pub use self::take::Take;
16 
17 #[cfg(feature = "std")]
18 pub use self::{reader::Reader, writer::Writer};
19 
20 /// Extra methods for implementations of `Buf`.
21 pub trait BufExt: Buf {
22     /// Creates an adaptor which will read at most `limit` bytes from `self`.
23     ///
24     /// This function returns a new instance of `Buf` which will read at most
25     /// `limit` bytes.
26     ///
27     /// # Examples
28     ///
29     /// ```
30     /// use bytes::{BufMut, buf::BufExt};
31     ///
32     /// let mut buf = b"hello world"[..].take(5);
33     /// let mut dst = vec![];
34     ///
35     /// dst.put(&mut buf);
36     /// assert_eq!(dst, b"hello");
37     ///
38     /// let mut buf = buf.into_inner();
39     /// dst.clear();
40     /// dst.put(&mut buf);
41     /// assert_eq!(dst, b" world");
42     /// ```
take(self, limit: usize) -> Take<Self> where Self: Sized,43     fn take(self, limit: usize) -> Take<Self>
44     where
45         Self: Sized,
46     {
47         take::new(self, limit)
48     }
49 
50     /// Creates an adaptor which will chain this buffer with another.
51     ///
52     /// The returned `Buf` instance will first consume all bytes from `self`.
53     /// Afterwards the output is equivalent to the output of next.
54     ///
55     /// # Examples
56     ///
57     /// ```
58     /// use bytes::{Buf, buf::BufExt};
59     ///
60     /// let mut chain = b"hello "[..].chain(&b"world"[..]);
61     ///
62     /// let full = chain.to_bytes();
63     /// assert_eq!(full.bytes(), b"hello world");
64     /// ```
chain<U: Buf>(self, next: U) -> Chain<Self, U> where Self: Sized,65     fn chain<U: Buf>(self, next: U) -> Chain<Self, U>
66     where
67         Self: Sized,
68     {
69         Chain::new(self, next)
70     }
71 
72     /// Creates an adaptor which implements the `Read` trait for `self`.
73     ///
74     /// This function returns a new value which implements `Read` by adapting
75     /// the `Read` trait functions to the `Buf` trait functions. Given that
76     /// `Buf` operations are infallible, none of the `Read` functions will
77     /// return with `Err`.
78     ///
79     /// # Examples
80     ///
81     /// ```
82     /// use bytes::{Bytes, buf::BufExt};
83     /// use std::io::Read;
84     ///
85     /// let buf = Bytes::from("hello world");
86     ///
87     /// let mut reader = buf.reader();
88     /// let mut dst = [0; 1024];
89     ///
90     /// let num = reader.read(&mut dst).unwrap();
91     ///
92     /// assert_eq!(11, num);
93     /// assert_eq!(&dst[..11], &b"hello world"[..]);
94     /// ```
95     #[cfg(feature = "std")]
reader(self) -> Reader<Self> where Self: Sized,96     fn reader(self) -> Reader<Self>
97     where
98         Self: Sized,
99     {
100         reader::new(self)
101     }
102 }
103 
104 impl<B: Buf + ?Sized> BufExt for B {}
105 
106 /// Extra methods for implementations of `BufMut`.
107 pub trait BufMutExt: BufMut {
108     /// Creates an adaptor which can write at most `limit` bytes to `self`.
109     ///
110     /// # Examples
111     ///
112     /// ```
113     /// use bytes::{BufMut, buf::BufMutExt};
114     ///
115     /// let arr = &mut [0u8; 128][..];
116     /// assert_eq!(arr.remaining_mut(), 128);
117     ///
118     /// let dst = arr.limit(10);
119     /// assert_eq!(dst.remaining_mut(), 10);
120     /// ```
limit(self, limit: usize) -> Limit<Self> where Self: Sized,121     fn limit(self, limit: usize) -> Limit<Self>
122     where
123         Self: Sized,
124     {
125         limit::new(self, limit)
126     }
127 
128     /// Creates an adaptor which implements the `Write` trait for `self`.
129     ///
130     /// This function returns a new value which implements `Write` by adapting
131     /// the `Write` trait functions to the `BufMut` trait functions. Given that
132     /// `BufMut` operations are infallible, none of the `Write` functions will
133     /// return with `Err`.
134     ///
135     /// # Examples
136     ///
137     /// ```
138     /// use bytes::buf::BufMutExt;
139     /// use std::io::Write;
140     ///
141     /// let mut buf = vec![].writer();
142     ///
143     /// let num = buf.write(&b"hello world"[..]).unwrap();
144     /// assert_eq!(11, num);
145     ///
146     /// let buf = buf.into_inner();
147     ///
148     /// assert_eq!(*buf, b"hello world"[..]);
149     /// ```
150     #[cfg(feature = "std")]
writer(self) -> Writer<Self> where Self: Sized,151     fn writer(self) -> Writer<Self>
152     where
153         Self: Sized,
154     {
155         writer::new(self)
156     }
157 
158     /// Creates an adapter which will chain this buffer with another.
159     ///
160     /// The returned `BufMut` instance will first write to all bytes from
161     /// `self`. Afterwards, it will write to `next`.
162     ///
163     /// # Examples
164     ///
165     /// ```
166     /// use bytes::{BufMut, buf::BufMutExt};
167     ///
168     /// let mut a = [0u8; 5];
169     /// let mut b = [0u8; 6];
170     ///
171     /// let mut chain = (&mut a[..]).chain_mut(&mut b[..]);
172     ///
173     /// chain.put_slice(b"hello world");
174     ///
175     /// assert_eq!(&a[..], b"hello");
176     /// assert_eq!(&b[..], b" world");
177     /// ```
chain_mut<U: BufMut>(self, next: U) -> Chain<Self, U> where Self: Sized,178     fn chain_mut<U: BufMut>(self, next: U) -> Chain<Self, U>
179     where
180         Self: Sized,
181     {
182         Chain::new(self, next)
183     }
184 }
185 
186 impl<B: BufMut + ?Sized> BufMutExt for B {}
187