deprecates Pointer::split_at, adds Pointer::split_at_offset

CHANGELOG.md

@@ -5,24 +5,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-
 ## [Unreleased]
 
 ### Added
 
--   Adds method `into_buf` for `Box<Pointer>` and `impl From<PathBuf> for Box<Pointer>`. 
+-   Adds method `into_buf` for `Box<Pointer>` and `impl From<PathBuf> for Box<Pointer>`.
 -   Adds unsafe associated methods `Pointer::new_unchecked` and `PointerBuf::new_unchecked` for
     external zero-cost construction.
 -   Adds `Pointer::starts_with` and `Pointer::ends_with` for prefix and suffix matching.
 -   Adds new `ParseIndexError` variant to express the presence non-digit characters in the token.
 -   Adds `Token::is_next` for checking if a token represents the `-` character.
+-   Adds `Pointer::split_at_offset` to replace the deprecated `Pointer::split_at`.
 
 ### Changed
 
 -   Changed signature of `PathBuf::parse` to avoid requiring allocation.
 -   Bumps minimum Rust version to 1.79.
 -   `Pointer::get` now accepts ranges and can produce `Pointer` segments as output (similar to
     `slice::get`).
+-   Deprecates `Pointer::split_at`
 
 ### Fixed
 

src/pointer.rs

@@ -233,7 +233,37 @@ impl Pointer {
     /// assert_eq!(tail, Pointer::from_static("/bar/baz"));
     /// assert_eq!(ptr.split_at(3), None);
     /// ```
+    #[deprecated(
+        since = "0.8.0",
+        note = "renamed to `split_at_offset` - `split_at` will become position (index) based by 1.0"
+    )]
     pub fn split_at(&self, offset: usize) -> Option<(&Self, &Self)> {
+        self.split_at_offset(offset)
+    }
+
+    /// Splits the `Pointer` at the given offset if the character at the index is
+    /// a separator backslash (`'/'`), returning `Some((head, tail))`. Otherwise,
+    /// returns `None`.
+    ///
+    /// For the following JSON Pointer, the following splits are possible (0, 4, 8):
+    /// ```text
+    /// /foo/bar/baz
+    /// ↑   ↑   ↑
+    /// 0   4   8
+    /// ```
+    /// All other indices will return `None`.
+    ///
+    /// ## Example
+    ///
+    /// ```rust
+    /// # use jsonptr::Pointer;
+    /// let ptr = Pointer::from_static("/foo/bar/baz");
+    /// let (head, tail) = ptr.split_at(4).unwrap();
+    /// assert_eq!(head, Pointer::from_static("/foo"));
+    /// assert_eq!(tail, Pointer::from_static("/bar/baz"));
+    /// assert_eq!(ptr.split_at_offset(3), None);
+    /// ```
+    pub fn split_at_offset(&self, offset: usize) -> Option<(&Self, &Self)> {
         if self.0.as_bytes().get(offset).copied() != Some(b'/') {
             return None;
         }
@@ -393,7 +423,7 @@ impl Pointer {
             }
             idx += a.encoded().len() + 1;
         }
-        self.split_at(idx).map_or(self, |(head, _)| head)
+        self.split_at_offset(idx).map_or(self, |(head, _)| head)
     }
 
     /// Attempts to delete a `serde_json::Value` based upon the path in this