Add utf8_hop_overshoot()

This is like utf8_hop_safe(), but also returns the number of characters
that would have overshot the edge if it had been allowed to go beyond
the edge

Author: khwilliamson

embed.fnc

@@ -3630,10 +3630,16 @@ ARTdip	|U8 *	|utf8_hop_forward_overshoot				\
 				|SSize_t off				\
 				|NN const U8 * const end		\
 				|NULLOK SSize_t *remaining
-ARTdip	|U8 *	|utf8_hop_safe	|NN const U8 *s 			\
+ARTdip	|U8 *	|utf8_hop_overshoot					\
+				|NN const U8 *s 			\
 				|SSize_t off				\
-				|NN const U8 *start			\
-				|NN const U8 *end
+				|NN const U8 * const start		\
+				|NN const U8 * const end		\
+				|NULLOK SSize_t *remaining
+ARTdmp	|U8 *	|utf8_hop_safe	|NN const U8 *s 			\
+				|SSize_t off				\
+				|NN const U8 * const start		\
+				|NN const U8 * const end
 ARdp	|STRLEN |utf8_length	|NN const U8 *s0			\
 				|NN const U8 *e
 

embed.h

@@ -790,6 +790,7 @@
 # define utf8_hop_back_overshoot                Perl_utf8_hop_back_overshoot
 # define utf8_hop_forward                       Perl_utf8_hop_forward
 # define utf8_hop_forward_overshoot             Perl_utf8_hop_forward_overshoot
+# define utf8_hop_overshoot                     Perl_utf8_hop_overshoot
 # define utf8_hop_safe                          Perl_utf8_hop_safe
 # define utf8_length(a,b)                       Perl_utf8_length(aTHX_ a,b)
 # define utf8_to_bytes(a,b)                     Perl_utf8_to_bytes(aTHX_ a,b)

inline.h

@@ -2816,39 +2816,51 @@ Perl_utf8_hop_back_overshoot(const U8 *s, SSize_t off,
 }
 
 /*
-=for apidoc utf8_hop_safe
+=for apidoc      utf8_hop_safe
+=for apidoc_item utf8_hop_safe_overshoot
 
-Return the UTF-8 pointer C<s> displaced by up to C<off> characters,
-either forward or backward.  C<s> does not need to be pointing to the starting
-byte of a character.  If it isn't, one count of C<off> will be used up to get
-to the start of the next character for forward hops, and to the start of the
-current character for negative ones.
+These each take as input a string encoded as UTF-8 which starts at C<start>,
+ending at C<end>, and a position into it given by C<s>, and return the
+position within it that is C<s> displaced by up to C<off> characters, either
+forwards if C<off> is positive, or backwards if C<off> is negative.  (Nothing
+is done if C<off> is 0.)
+
+If there are fewer than C<off> characters between C<s> and the respective edge,
+the functions return that edge.
 
-When moving backward it will not move before C<start>.
+The functions differ in that C<utf8_hop_overshoot> can return how many
+characters beyond the edge the request was for.  When its parameter,
+C<&remaining>, is not NULL, the function stores into it the count of the
+excess; zero if the request was completely fulfilled.  The actual number of
+characters that were displaced can then be calculated as S<C<off - remaining>>.
+This function acts identically to plain C<utf8_hop_safe> when this parameter is
+NULL.
 
-When moving forward it will not move beyond C<end>.
+C<s> does not need to be pointing to the starting byte of a character.  If it
+isn't, one count of C<off> will be used up to get to that start.
 
-Will not exceed those limits even if the string is not valid "UTF-8".
+To be more precise, the displacement is by the absolute value of C<off>, and
+the excess count is the absolute value of C<remaining>.
 
 =cut
 */
 
+#define Perl_utf8_hop_safe(s, o, b, e)  Perl_utf8_hop_overshoot(s, o, b, e, 0)
+
 PERL_STATIC_INLINE U8 *
-Perl_utf8_hop_safe(const U8 *s, SSize_t off, const U8 *start, const U8 *end)
+Perl_utf8_hop_overshoot(const U8 *s, SSize_t off,
+                   const U8 * const start, const U8 * const end,
+                   SSize_t * remaining)
 {
-    PERL_ARGS_ASSERT_UTF8_HOP_SAFE;
-
-    /* Note: cannot use UTF8_IS_...() too eagerly here since e.g
-     * the bitops (especially ~) can create illegal UTF-8.
-     * In other words: in Perl UTF-8 is not just for Unicode. */
+    PERL_ARGS_ASSERT_UTF8_HOP_OVERSHOOT;
 
     assert(start <= s && s <= end);
 
     if (off >= 0) {
-        return utf8_hop_forward(s, off, end);
+        return utf8_hop_forward_overshoot(s, off, end, remaining);
     }
     else {
-        return utf8_hop_back(s, off, start);
+        return utf8_hop_back_overshoot(s, off, start, remaining);
     }
 }