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