Merge rust-bitcoin/rust-bitcoin#3823: Improve Cursor ref API

ae129d84ac api: Run just check-api (Tobin C. Harding)
3f433f1cde Improve Cursor ref API (Tobin C. Harding)

Pull request description:

  Our `Cursor` is a replacement of sorts for the `std::io::Cursor`. Users of the `Cursor` are likely to expect the same API so to get a reference and/or mutable reference users will likely reach for `get_ref` and `get_mut`. We should provide these.

  Deprecate `inner` since it is the same as `get_ref` but less idiomatically named (should have been `as_inner`).

  Add `get_ref` and `get_mut` methods to the `Cursor` type.

ACKs for top commit:
  apoelstra:
    ACK ae129d84ace03fba57bb980cace5aa60ff6bc10e; successfully ran local tests

Tree-SHA512: 664d08cc977c9d6e3319767c49bbabc8f21d681d570f50c514797a7737469cf861af60158ccc1c71d28baed542dabbbca586968144d60691ee0183a549a7b765

api/io/all-features.txt

@@ -214,6 +214,8 @@ pub fn bitcoin_io::BufRead::consume(&mut self, amount: usize)
 pub fn bitcoin_io::BufRead::fill_buf(&mut self) -> bitcoin_io::Result<&[u8]>
 pub fn bitcoin_io::Cursor<T>::consume(&mut self, amount: usize)
 pub fn bitcoin_io::Cursor<T>::fill_buf(&mut self) -> bitcoin_io::Result<&[u8]>
+pub fn bitcoin_io::Cursor<T>::get_mut(&mut self) -> &mut T
+pub fn bitcoin_io::Cursor<T>::get_ref(&self) -> &T
 pub fn bitcoin_io::Cursor<T>::inner(&self) -> &T
 pub fn bitcoin_io::Cursor<T>::into_inner(self) -> T
 pub fn bitcoin_io::Cursor<T>::new(inner: T) -> Self

api/io/alloc-only.txt

@@ -91,6 +91,8 @@ pub fn bitcoin_io::BufRead::consume(&mut self, amount: usize)
 pub fn bitcoin_io::BufRead::fill_buf(&mut self) -> bitcoin_io::Result<&[u8]>
 pub fn bitcoin_io::Cursor<T>::consume(&mut self, amount: usize)
 pub fn bitcoin_io::Cursor<T>::fill_buf(&mut self) -> bitcoin_io::Result<&[u8]>
+pub fn bitcoin_io::Cursor<T>::get_mut(&mut self) -> &mut T
+pub fn bitcoin_io::Cursor<T>::get_ref(&self) -> &T
 pub fn bitcoin_io::Cursor<T>::inner(&self) -> &T
 pub fn bitcoin_io::Cursor<T>::into_inner(self) -> T
 pub fn bitcoin_io::Cursor<T>::new(inner: T) -> Self

api/io/no-features.txt

@@ -87,6 +87,8 @@ pub fn bitcoin_io::BufRead::consume(&mut self, amount: usize)
 pub fn bitcoin_io::BufRead::fill_buf(&mut self) -> bitcoin_io::Result<&[u8]>
 pub fn bitcoin_io::Cursor<T>::consume(&mut self, amount: usize)
 pub fn bitcoin_io::Cursor<T>::fill_buf(&mut self) -> bitcoin_io::Result<&[u8]>
+pub fn bitcoin_io::Cursor<T>::get_mut(&mut self) -> &mut T
+pub fn bitcoin_io::Cursor<T>::get_ref(&self) -> &T
 pub fn bitcoin_io::Cursor<T>::inner(&self) -> &T
 pub fn bitcoin_io::Cursor<T>::into_inner(self) -> T
 pub fn bitcoin_io::Cursor<T>::new(inner: T) -> Self

io/src/lib.rs

@@ -224,6 +224,19 @@ impl<T: AsRef<[u8]>> Cursor<T> {
     ///
     /// This is the whole wrapped buffer, including the bytes already read.
     #[inline]
+    pub fn get_ref(&self) -> &T { &self.inner }
+
+    /// Returns a mutable reference to the inner buffer.
+    ///
+    /// This is the whole wrapped buffer, including the bytes already read.
+    #[inline]
+    pub fn get_mut(&mut self) -> &mut T { &mut self.inner }
+
+    /// Returns a reference to the inner buffer.
+    ///
+    /// This is the whole wrapped buffer, including the bytes already read.
+    #[inline]
+    #[deprecated(since = "TBD", note = "use `get_ref()` instead")]
     pub fn inner(&self) -> &T { &self.inner }
 }