| // Licensed to the Apache Software Foundation (ASF) under one |
| // or more contributor license agreements. See the NOTICE file |
| // distributed with this work for additional information |
| // regarding copyright ownership. The ASF licenses this file |
| // to you under the Apache License, Version 2.0 (the |
| // "License"); you may not use this file except in compliance |
| // with the License. You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, |
| // software distributed under the License is distributed on an |
| // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| // KIND, either express or implied. See the License for the |
| // specific language governing permissions and limitations |
| // under the License.. |
| |
| use crate::io::prelude::*; |
| use crate::io::{self, Error, ErrorKind, Initializer, IoSlice, IoSliceMut, SeekFrom}; |
| use core::cmp; |
| use core::convert::TryInto; |
| |
| /// A `Cursor` wraps an in-memory buffer and provides it with a |
| /// [`Seek`] implementation. |
| /// |
| /// `Cursor`s are used with in-memory buffers, anything implementing |
| /// `AsRef<[u8]>`, to allow them to implement [`Read`] and/or [`Write`], |
| /// allowing these buffers to be used anywhere you might use a reader or writer |
| /// that does actual I/O. |
| /// |
| /// The standard library implements some I/O traits on various types which |
| /// are commonly used as a buffer, like `Cursor<`[`Vec`]`<u8>>` and |
| /// `Cursor<`[`&[u8]`][bytes]`>`. |
| /// |
| |
| #[derive(Clone, Debug, Default, Eq, PartialEq)] |
| pub struct Cursor<T> { |
| inner: T, |
| pos: u64, |
| } |
| |
| impl<T> Cursor<T> { |
| /// Creates a new cursor wrapping the provided underlying in-memory buffer. |
| /// |
| /// Cursor initial position is `0` even if underlying buffer (e.g., `Vec`) |
| /// is not empty. So writing to cursor starts with overwriting `Vec` |
| /// content, not with appending to it. |
| /// |
| pub fn new(inner: T) -> Cursor<T> { |
| Cursor { pos: 0, inner } |
| } |
| |
| /// Consumes this cursor, returning the underlying value. |
| pub fn into_inner(self) -> T { |
| self.inner |
| } |
| |
| /// Gets a reference to the underlying value in this cursor. |
| pub fn get_ref(&self) -> &T { |
| &self.inner |
| } |
| |
| /// Gets a mutable reference to the underlying value in this cursor. |
| /// |
| /// Care should be taken to avoid modifying the internal I/O state of the |
| /// underlying value as it may corrupt this cursor's position. |
| pub fn get_mut(&mut self) -> &mut T { |
| &mut self.inner |
| } |
| |
| /// Returns the current position of this cursor. |
| pub fn position(&self) -> u64 { |
| self.pos |
| } |
| |
| /// Sets the position of this cursor. |
| pub fn set_position(&mut self, pos: u64) { |
| self.pos = pos; |
| } |
| } |
| |
| impl<T> io::Seek for Cursor<T> |
| where |
| T: AsRef<[u8]>, |
| { |
| fn seek(&mut self, style: SeekFrom) -> io::Result<u64> { |
| let (base_pos, offset) = match style { |
| SeekFrom::Start(n) => { |
| self.pos = n; |
| return Ok(n); |
| } |
| SeekFrom::End(n) => (self.inner.as_ref().len() as u64, n), |
| SeekFrom::Current(n) => (self.pos, n), |
| }; |
| let new_pos = if offset >= 0 { |
| base_pos.checked_add(offset as u64) |
| } else { |
| base_pos.checked_sub((offset.wrapping_neg()) as u64) |
| }; |
| match new_pos { |
| Some(n) => { |
| self.pos = n; |
| Ok(self.pos) |
| } |
| None => Err(Error::new( |
| ErrorKind::InvalidInput, |
| "invalid seek to a negative or overflowing position", |
| )), |
| } |
| } |
| |
| fn stream_len(&mut self) -> io::Result<u64> { |
| Ok(self.inner.as_ref().len() as u64) |
| } |
| |
| fn stream_position(&mut self) -> io::Result<u64> { |
| Ok(self.pos) |
| } |
| } |
| |
| impl<T> Read for Cursor<T> |
| where |
| T: AsRef<[u8]>, |
| { |
| fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> { |
| let n = Read::read(&mut self.fill_buf()?, buf)?; |
| self.pos += n as u64; |
| Ok(n) |
| } |
| |
| fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> { |
| let mut nread = 0; |
| for buf in bufs { |
| let n = self.read(buf)?; |
| nread += n; |
| if n < buf.len() { |
| break; |
| } |
| } |
| Ok(nread) |
| } |
| |
| fn read_exact(&mut self, buf: &mut [u8]) -> io::Result<()> { |
| let n = buf.len(); |
| Read::read_exact(&mut self.fill_buf()?, buf)?; |
| self.pos += n as u64; |
| Ok(()) |
| } |
| |
| #[inline] |
| unsafe fn initializer(&self) -> Initializer { |
| Initializer::nop() |
| } |
| } |
| |
| impl<T> BufRead for Cursor<T> |
| where |
| T: AsRef<[u8]>, |
| { |
| fn fill_buf(&mut self) -> io::Result<&[u8]> { |
| let amt = cmp::min(self.pos, self.inner.as_ref().len() as u64); |
| Ok(&self.inner.as_ref()[(amt as usize)..]) |
| } |
| fn consume(&mut self, amt: usize) { |
| self.pos += amt as u64; |
| } |
| } |
| |
| // Non-resizing write implementation |
| #[inline] |
| fn slice_write(pos_mut: &mut u64, slice: &mut [u8], buf: &[u8]) -> io::Result<usize> { |
| let pos = cmp::min(*pos_mut, slice.len() as u64); |
| let amt = (&mut slice[(pos as usize)..]).write(buf)?; |
| *pos_mut += amt as u64; |
| Ok(amt) |
| } |
| |
| #[inline] |
| fn slice_write_vectored( |
| pos_mut: &mut u64, |
| slice: &mut [u8], |
| bufs: &[IoSlice<'_>], |
| ) -> io::Result<usize> { |
| let mut nwritten = 0; |
| for buf in bufs { |
| let n = slice_write(pos_mut, slice, buf)?; |
| nwritten += n; |
| if n < buf.len() { |
| break; |
| } |
| } |
| Ok(nwritten) |
| } |
| |
| // Resizing write implementation |
| fn vec_write(pos_mut: &mut u64, vec: &mut Vec<u8>, buf: &[u8]) -> io::Result<usize> { |
| let pos: usize = (*pos_mut).try_into().map_err(|_| { |
| Error::new( |
| ErrorKind::InvalidInput, |
| "cursor position exceeds maximum possible vector length", |
| ) |
| })?; |
| // Make sure the internal buffer is as least as big as where we |
| // currently are |
| let len = vec.len(); |
| if len < pos { |
| // use `resize` so that the zero filling is as efficient as possible |
| vec.resize(pos, 0); |
| } |
| // Figure out what bytes will be used to overwrite what's currently |
| // there (left), and what will be appended on the end (right) |
| { |
| let space = vec.len() - pos; |
| let (left, right) = buf.split_at(cmp::min(space, buf.len())); |
| vec[pos..pos + left.len()].copy_from_slice(left); |
| vec.extend_from_slice(right); |
| } |
| |
| // Bump us forward |
| *pos_mut = (pos + buf.len()) as u64; |
| Ok(buf.len()) |
| } |
| |
| fn vec_write_vectored( |
| pos_mut: &mut u64, |
| vec: &mut Vec<u8>, |
| bufs: &[IoSlice<'_>], |
| ) -> io::Result<usize> { |
| let mut nwritten = 0; |
| for buf in bufs { |
| nwritten += vec_write(pos_mut, vec, buf)?; |
| } |
| Ok(nwritten) |
| } |
| |
| impl Write for Cursor<&mut [u8]> { |
| #[inline] |
| fn write(&mut self, buf: &[u8]) -> io::Result<usize> { |
| slice_write(&mut self.pos, self.inner, buf) |
| } |
| |
| #[inline] |
| fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> { |
| slice_write_vectored(&mut self.pos, self.inner, bufs) |
| } |
| |
| #[inline] |
| fn flush(&mut self) -> io::Result<()> { |
| Ok(()) |
| } |
| } |
| |
| impl Write for Cursor<&mut Vec<u8>> { |
| fn write(&mut self, buf: &[u8]) -> io::Result<usize> { |
| vec_write(&mut self.pos, self.inner, buf) |
| } |
| |
| fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> { |
| vec_write_vectored(&mut self.pos, self.inner, bufs) |
| } |
| |
| #[inline] |
| fn flush(&mut self) -> io::Result<()> { |
| Ok(()) |
| } |
| } |
| |
| impl Write for Cursor<Vec<u8>> { |
| fn write(&mut self, buf: &[u8]) -> io::Result<usize> { |
| vec_write(&mut self.pos, &mut self.inner, buf) |
| } |
| |
| fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> { |
| vec_write_vectored(&mut self.pos, &mut self.inner, bufs) |
| } |
| |
| #[inline] |
| fn flush(&mut self) -> io::Result<()> { |
| Ok(()) |
| } |
| } |
| |
| impl Write for Cursor<Box<[u8]>> { |
| #[inline] |
| fn write(&mut self, buf: &[u8]) -> io::Result<usize> { |
| slice_write(&mut self.pos, &mut self.inner, buf) |
| } |
| |
| #[inline] |
| fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> { |
| slice_write_vectored(&mut self.pos, &mut self.inner, bufs) |
| } |
| |
| #[inline] |
| fn flush(&mut self) -> io::Result<()> { |
| Ok(()) |
| } |
| } |