1#![allow(missing_copy_implementations)]
2
3#[cfg(test)]
4mod tests;
5
6use crate::fmt;
7use crate::io::{
8 self, BorrowedCursor, BufRead, IoSlice, IoSliceMut, Read, Seek, SeekFrom, SizeHint, Write,
9};
10
11/// `Empty` ignores any data written via [`Write`], and will always be empty
12/// (returning zero bytes) when read via [`Read`].
13///
14/// This struct is generally created by calling [`empty()`]. Please
15/// see the documentation of [`empty()`] for more details.
16#[stable(feature = "rust1", since = "1.0.0")]
17#[non_exhaustive]
18#[derive(Copy, Clone, Debug, Default)]
19pub struct Empty;
20
21/// Creates a value that is always at EOF for reads, and ignores all data written.
22///
23/// All calls to [`write`] on the returned instance will return [`Ok(buf.len())`]
24/// and the contents of the buffer will not be inspected.
25///
26/// All calls to [`read`] from the returned reader will return [`Ok(0)`].
27///
28/// [`Ok(buf.len())`]: Ok
29/// [`Ok(0)`]: Ok
30///
31/// [`write`]: Write::write
32/// [`read`]: Read::read
33///
34/// # Examples
35///
36/// ```rust
37/// use std::io::{self, Write};
38///
39/// let buffer = vec![1, 2, 3, 5, 8];
40/// let num_bytes = io::empty().write(&buffer).unwrap();
41/// assert_eq!(num_bytes, 5);
42/// ```
43///
44///
45/// ```rust
46/// use std::io::{self, Read};
47///
48/// let mut buffer = String::new();
49/// io::empty().read_to_string(&mut buffer).unwrap();
50/// assert!(buffer.is_empty());
51/// ```
52#[must_use]
53#[stable(feature = "rust1", since = "1.0.0")]
54#[rustc_const_stable(feature = "const_io_structs", since = "1.79.0")]
55pub const fn empty() -> Empty {
56 Empty
57}
58
59#[stable(feature = "rust1", since = "1.0.0")]
60impl Read for Empty {
61 #[inline]
62 fn read(&mut self, _buf: &mut [u8]) -> io::Result<usize> {
63 Ok(0)
64 }
65
66 #[inline]
67 fn read_buf(&mut self, _cursor: BorrowedCursor<'_>) -> io::Result<()> {
68 Ok(())
69 }
70
71 #[inline]
72 fn read_vectored(&mut self, _bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {
73 Ok(0)
74 }
75
76 #[inline]
77 fn is_read_vectored(&self) -> bool {
78 // Do not force `Chain<Empty, T>` or `Chain<T, Empty>` to use vectored
79 // reads, unless the other reader is vectored.
80 false
81 }
82
83 #[inline]
84 fn read_exact(&mut self, buf: &mut [u8]) -> io::Result<()> {
85 if !buf.is_empty() { Err(io::Error::READ_EXACT_EOF) } else { Ok(()) }
86 }
87
88 #[inline]
89 fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> io::Result<()> {
90 if cursor.capacity() != 0 { Err(io::Error::READ_EXACT_EOF) } else { Ok(()) }
91 }
92
93 #[inline]
94 fn read_to_end(&mut self, _buf: &mut Vec<u8>) -> io::Result<usize> {
95 Ok(0)
96 }
97
98 #[inline]
99 fn read_to_string(&mut self, _buf: &mut String) -> io::Result<usize> {
100 Ok(0)
101 }
102}
103#[stable(feature = "rust1", since = "1.0.0")]
104impl BufRead for Empty {
105 #[inline]
106 fn fill_buf(&mut self) -> io::Result<&[u8]> {
107 Ok(&[])
108 }
109
110 #[inline]
111 fn consume(&mut self, _n: usize) {}
112
113 #[inline]
114 fn has_data_left(&mut self) -> io::Result<bool> {
115 Ok(false)
116 }
117
118 #[inline]
119 fn read_until(&mut self, _byte: u8, _buf: &mut Vec<u8>) -> io::Result<usize> {
120 Ok(0)
121 }
122
123 #[inline]
124 fn skip_until(&mut self, _byte: u8) -> io::Result<usize> {
125 Ok(0)
126 }
127
128 #[inline]
129 fn read_line(&mut self, _buf: &mut String) -> io::Result<usize> {
130 Ok(0)
131 }
132}
133
134#[stable(feature = "empty_seek", since = "1.51.0")]
135impl Seek for Empty {
136 #[inline]
137 fn seek(&mut self, _pos: SeekFrom) -> io::Result<u64> {
138 Ok(0)
139 }
140
141 #[inline]
142 fn stream_len(&mut self) -> io::Result<u64> {
143 Ok(0)
144 }
145
146 #[inline]
147 fn stream_position(&mut self) -> io::Result<u64> {
148 Ok(0)
149 }
150}
151
152impl SizeHint for Empty {
153 #[inline]
154 fn upper_bound(&self) -> Option<usize> {
155 Some(0)
156 }
157}
158
159#[stable(feature = "empty_write", since = "1.73.0")]
160impl Write for Empty {
161 #[inline]
162 fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
163 Ok(buf.len())
164 }
165
166 #[inline]
167 fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
168 let total_len = bufs.iter().map(|b| b.len()).sum();
169 Ok(total_len)
170 }
171
172 #[inline]
173 fn is_write_vectored(&self) -> bool {
174 true
175 }
176
177 #[inline]
178 fn write_all(&mut self, _buf: &[u8]) -> io::Result<()> {
179 Ok(())
180 }
181
182 #[inline]
183 fn write_all_vectored(&mut self, _bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
184 Ok(())
185 }
186
187 #[inline]
188 fn write_fmt(&mut self, _args: fmt::Arguments<'_>) -> io::Result<()> {
189 Ok(())
190 }
191
192 #[inline]
193 fn flush(&mut self) -> io::Result<()> {
194 Ok(())
195 }
196}
197
198#[stable(feature = "empty_write", since = "1.73.0")]
199impl Write for &Empty {
200 #[inline]
201 fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
202 Ok(buf.len())
203 }
204
205 #[inline]
206 fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
207 let total_len = bufs.iter().map(|b| b.len()).sum();
208 Ok(total_len)
209 }
210
211 #[inline]
212 fn is_write_vectored(&self) -> bool {
213 true
214 }
215
216 #[inline]
217 fn write_all(&mut self, _buf: &[u8]) -> io::Result<()> {
218 Ok(())
219 }
220
221 #[inline]
222 fn write_all_vectored(&mut self, _bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
223 Ok(())
224 }
225
226 #[inline]
227 fn write_fmt(&mut self, _args: fmt::Arguments<'_>) -> io::Result<()> {
228 Ok(())
229 }
230
231 #[inline]
232 fn flush(&mut self) -> io::Result<()> {
233 Ok(())
234 }
235}
236
237/// A reader which yields one byte over and over and over and over and over and...
238///
239/// This struct is generally created by calling [`repeat()`]. Please
240/// see the documentation of [`repeat()`] for more details.
241#[stable(feature = "rust1", since = "1.0.0")]
242pub struct Repeat {
243 byte: u8,
244}
245
246/// Creates an instance of a reader that infinitely repeats one byte.
247///
248/// All reads from this reader will succeed by filling the specified buffer with
249/// the given byte.
250///
251/// # Examples
252///
253/// ```
254/// use std::io::{self, Read};
255///
256/// let mut buffer = [0; 3];
257/// io::repeat(0b101).read_exact(&mut buffer).unwrap();
258/// assert_eq!(buffer, [0b101, 0b101, 0b101]);
259/// ```
260#[must_use]
261#[stable(feature = "rust1", since = "1.0.0")]
262#[rustc_const_stable(feature = "const_io_structs", since = "1.79.0")]
263pub const fn repeat(byte: u8) -> Repeat {
264 Repeat { byte }
265}
266
267#[stable(feature = "rust1", since = "1.0.0")]
268impl Read for Repeat {
269 #[inline]
270 fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
271 buf.fill(self.byte);
272 Ok(buf.len())
273 }
274
275 #[inline]
276 fn read_exact(&mut self, buf: &mut [u8]) -> io::Result<()> {
277 buf.fill(self.byte);
278 Ok(())
279 }
280
281 #[inline]
282 fn read_buf(&mut self, mut buf: BorrowedCursor<'_>) -> io::Result<()> {
283 // SAFETY: No uninit bytes are being written.
284 unsafe { buf.as_mut() }.write_filled(self.byte);
285 // SAFETY: the entire unfilled portion of buf has been initialized.
286 unsafe { buf.advance_unchecked(buf.capacity()) };
287 Ok(())
288 }
289
290 #[inline]
291 fn read_buf_exact(&mut self, buf: BorrowedCursor<'_>) -> io::Result<()> {
292 self.read_buf(buf)
293 }
294
295 /// This function is not supported by `io::Repeat`, because there's no end of its data
296 fn read_to_end(&mut self, _: &mut Vec<u8>) -> io::Result<usize> {
297 Err(io::Error::from(io::ErrorKind::OutOfMemory))
298 }
299
300 /// This function is not supported by `io::Repeat`, because there's no end of its data
301 fn read_to_string(&mut self, _: &mut String) -> io::Result<usize> {
302 Err(io::Error::from(io::ErrorKind::OutOfMemory))
303 }
304
305 #[inline]
306 fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {
307 let mut nwritten = 0;
308 for buf in bufs {
309 nwritten += self.read(buf)?;
310 }
311 Ok(nwritten)
312 }
313
314 #[inline]
315 fn is_read_vectored(&self) -> bool {
316 true
317 }
318}
319
320impl SizeHint for Repeat {
321 #[inline]
322 fn lower_bound(&self) -> usize {
323 usize::MAX
324 }
325
326 #[inline]
327 fn upper_bound(&self) -> Option<usize> {
328 None
329 }
330}
331
332#[stable(feature = "std_debug", since = "1.16.0")]
333impl fmt::Debug for Repeat {
334 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
335 f.debug_struct(name:"Repeat").finish_non_exhaustive()
336 }
337}
338
339/// A writer which will move data into the void.
340///
341/// This struct is generally created by calling [`sink()`]. Please
342/// see the documentation of [`sink()`] for more details.
343#[stable(feature = "rust1", since = "1.0.0")]
344#[non_exhaustive]
345#[derive(Copy, Clone, Debug, Default)]
346pub struct Sink;
347
348/// Creates an instance of a writer which will successfully consume all data.
349///
350/// All calls to [`write`] on the returned instance will return [`Ok(buf.len())`]
351/// and the contents of the buffer will not be inspected.
352///
353/// [`write`]: Write::write
354/// [`Ok(buf.len())`]: Ok
355///
356/// # Examples
357///
358/// ```rust
359/// use std::io::{self, Write};
360///
361/// let buffer = vec![1, 2, 3, 5, 8];
362/// let num_bytes = io::sink().write(&buffer).unwrap();
363/// assert_eq!(num_bytes, 5);
364/// ```
365#[must_use]
366#[stable(feature = "rust1", since = "1.0.0")]
367#[rustc_const_stable(feature = "const_io_structs", since = "1.79.0")]
368pub const fn sink() -> Sink {
369 Sink
370}
371
372#[stable(feature = "rust1", since = "1.0.0")]
373impl Write for Sink {
374 #[inline]
375 fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
376 Ok(buf.len())
377 }
378
379 #[inline]
380 fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
381 let total_len = bufs.iter().map(|b| b.len()).sum();
382 Ok(total_len)
383 }
384
385 #[inline]
386 fn is_write_vectored(&self) -> bool {
387 true
388 }
389
390 #[inline]
391 fn write_all(&mut self, _buf: &[u8]) -> io::Result<()> {
392 Ok(())
393 }
394
395 #[inline]
396 fn write_all_vectored(&mut self, _bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
397 Ok(())
398 }
399
400 #[inline]
401 fn write_fmt(&mut self, _args: fmt::Arguments<'_>) -> io::Result<()> {
402 Ok(())
403 }
404
405 #[inline]
406 fn flush(&mut self) -> io::Result<()> {
407 Ok(())
408 }
409}
410
411#[stable(feature = "write_mt", since = "1.48.0")]
412impl Write for &Sink {
413 #[inline]
414 fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
415 Ok(buf.len())
416 }
417
418 #[inline]
419 fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
420 let total_len = bufs.iter().map(|b| b.len()).sum();
421 Ok(total_len)
422 }
423
424 #[inline]
425 fn is_write_vectored(&self) -> bool {
426 true
427 }
428
429 #[inline]
430 fn write_all(&mut self, _buf: &[u8]) -> io::Result<()> {
431 Ok(())
432 }
433
434 #[inline]
435 fn write_all_vectored(&mut self, _bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
436 Ok(())
437 }
438
439 #[inline]
440 fn write_fmt(&mut self, _args: fmt::Arguments<'_>) -> io::Result<()> {
441 Ok(())
442 }
443
444 #[inline]
445 fn flush(&mut self) -> io::Result<()> {
446 Ok(())
447 }
448}
449