GROOVY-11636: Create a SGM#next method which also takes an integer increment value

Author: paulk-asert

src/main/java/org/codehaus/groovy/runtime/StringGroovyMethods.java

@@ -1981,6 +1981,47 @@ public static String next(final CharSequence self) {
         return buffer.toString();
     }
 
+    /**
+     * A variant of next with an integer count parameter; equivalent to calling next() count times.
+     * <pre class="groovyTestCase">
+     * assert 'a'.next(1) == 'a'.next()
+     * assert 'a'.next(4) == 'e'
+     * assert 'a'.next(0) == 'a'
+     * assert 'a'.next(25) == 'z'
+     * assert 'A'.next(32) == 'a'
+     * assert (0..4).collect('a'::next) == 'a'..'e'
+     * assert 'car'.next(2) == 'cat'
+     * </pre>
+     *
+     * @param self a CharSequence
+     * @oaram n how many times to increment
+     * @see #next(CharSequence)
+     * @return a value obtained by incrementing the toString() of the CharSequence n times
+     *
+     * @since 5.0.0
+     */
+    public static String next(final CharSequence self, int n) {
+        if (n < 0) {
+            throw new IllegalArgumentException("A negative value for n is not supported");
+        }
+        StringBuilder buffer = new StringBuilder(self);
+        if (buffer.length() == 0) {
+            buffer.append(Character.MIN_VALUE);
+        } else {
+            char last = buffer.charAt(buffer.length() - 1);
+            for (; n > 0; n--) {
+                if (last == Character.MAX_VALUE) {
+                    buffer.append(Character.MIN_VALUE);
+                    last = Character.MIN_VALUE;
+                } else {
+                    last++;
+                }
+            }
+            buffer.setCharAt(buffer.length() - 1, last);
+        }
+        return buffer.toString();
+    }
+
     /**
      * Returns a String with linefeeds and carriage returns normalized to linefeeds.
      *