diff --git a/src/borrowed.rs b/src/borrowed.rs index eb2571f..9b41eae 100644 --- a/src/borrowed.rs +++ b/src/borrowed.rs @@ -29,6 +29,14 @@ pub struct IndexedChars<'a> { impl<'a> IndexedChars<'a> { /// Constructs a new [`IndexedChars`] instance from a [`&str`]. This is O(n), but the cost should only be paid once ideally. + /// + /// + /// # Examples + /// ```rust + /// # use char_index::IndexedChars; + /// let index = IndexedChars::new("foo"); + /// # assert_eq!(index.get_char(0), Some('f')); + /// ``` #[must_use] pub fn new(s: &'a str) -> Self { let inner = IndexedCharsInner::new(s); @@ -39,10 +47,22 @@ impl<'a> IndexedChars<'a> { /// Indexes into the backing string to retrieve the nth codepoint. /// /// This operation has an average case of O(1), and a worst case of O(log n). + /// + /// # Examples + /// ```rust + /// # use char_index::IndexedChars; + /// assert_eq!(IndexedChars::new("foobar").get_char(3), Some('b')); + /// ``` #[must_use] pub fn get_char(&self, index: usize) -> Option { self.inner.get_char(self.buf, index) } + + /// Returns a reference to the backing `&str` + #[must_use] + pub fn as_str(&self) -> &str { + self.buf + } } // The following lines are all trait implementations made to mirror what str does, and be compatible with str diff --git a/src/owned.rs b/src/owned.rs index 70cfdec..9300645 100644 --- a/src/owned.rs +++ b/src/owned.rs @@ -31,6 +31,16 @@ pub struct OwnedIndexedChars { impl OwnedIndexedChars { /// Constructs a new [`OwnedIndexedChars`] instance from a [`String`]. This is O(n), but the cost should only be paid once ideally. + /// + /// # Examples + /// ```rust + /// # use char_index::OwnedIndexedChars; + /// let index = OwnedIndexedChars::new(String::from("foo")); + /// + /// // we can still access str methods through deref + /// _ = index.chars(); + /// # assert_eq!(index.get_char(0), Some('f')); + /// ``` #[must_use] pub fn new(s: String) -> Self { let inner = IndexedCharsInner::new(&s); @@ -41,16 +51,38 @@ impl OwnedIndexedChars { /// Indexes into the backing string to retrieve the nth codepoint. /// /// This operation has an average case of O(1), and a worst case of O(log n). + /// + /// # Examples + /// ```rust + /// # use char_index::OwnedIndexedChars; + /// let s = OwnedIndexedChars::new(String::from("foo")); + /// + /// assert_eq!(s.get_char(1), Some('o')); + /// ``` #[must_use] pub fn get_char(&self, index: usize) -> Option { self.inner.get_char(&self.buf, index) } - /// Drops index data and returns backing string allocation + /// Drops index data and returns backing `String` allocation. #[must_use] pub fn into_string(self) -> String { self.buf } + + /// Returns a reference to the backing `String` allocation. + /// + /// Generally you don't want this, and should instead use [`as_str`][OwnedIndexedChars::as_str] or [`Deref`] + #[must_use] + pub fn as_string(&self) -> &String { + &self.buf + } + + /// Returns a reference to the backing `String` as a `&str`. + #[must_use] + pub fn as_str(&self) -> &str { + self.buf.as_str() + } } // The following lines are all trait implementations made to mirror what str does, and be compatible with str