Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8303650

Add String.indexOf(String str, int beginIndex, int endIndex)

    XMLWordPrintable

Details

    • CSR
    • Resolution: Approved
    • P4
    • 21
    • core-libs
    • None
    • minimal
    • This is an new method in a final class, so the compatibility risk is minimal.
    • Java API
    • SE

    Description

      Summary

      Add an indexOf(String,int,int) variant allowing to specify both a lower and an upper bound on the search.

      Problem

      Currently, String doesn't expose an indexOf(String,int,int) variant allowing to specify an upper bound on the search, although the codebase includes such functionality in non-publicly accessible methods.

      Solution

      This CSR proposes to expose the functionality already implemented internally. For higher resilience, however, the method throws when the indices do not meet a condition similar to the one of substring(int,int), rather than simply returning -1.

      It also adds an @apiNote to the existing indexOf(String,int) method.

      Specification

            * }</pre>
            * If no such value of {@code k} exists, then {@code -1} is returned.
            *
      +     * @apiNote
      +     * Unlike {@link #substring(int)}, for example, this method does not throw
      +     * an exception when {@code fromIndex} is outside the valid range.
      +     * Rather, it returns -1 when {@code fromIndex} is larger than the length of
      +     * the string.
      +     * This result is, by itself, indistinguishable from a genuine absence of
      +     * {@code str} in the string.
      +     * If stricter behavior is needed, {@link #indexOf(String, int, int)}
      +     * should be considered instead.
      +     * On {@link String} {@code s} and a non-empty {@code str}, for example,
      +     * {@code s.indexOf(str, fromIndex, s.length())} would throw if
      +     * {@code fromIndex} were larger than the string length, or were negative.
      +     *
            * @param   str         the substring to search for.
            * @param   fromIndex   the index from which to start the search.
            * @return  the index of the first occurrence of the specified substring,
            *          starting at the specified index,
            *          or {@code -1} if there is no such occurrence.
            */
           public int indexOf(String str, int fromIndex) {
      +    /**
      +     * Returns the index of the first occurrence of the specified substring
      +     * within the specified index range of {@code this} string.
      +     *
      +     * <p>This method returns the same result as the one of the invocation
      +     * <pre>{@code
      +     *     s.substring(beginIndex, endIndex).indexOf(str) + beginIndex
      +     * }</pre>
      +     * if the index returned by {@link #indexOf(String)} is non-negative,
      +     * and returns -1 otherwise.
      +     * (No substring is instantiated, though.)
      +     *
      +     * @param   str         the substring to search for.
      +     * @param   beginIndex  the index to start the search from (included).
      +     * @param   endIndex    the index to stop the search at (excluded).
      +     * @return  the index of the first occurrence of the specified substring
      +     *          within the specified index range,
      +     *          or {@code -1} if there is no such occurrence.
      +     * @throws  StringIndexOutOfBoundsException if {@code beginIndex}
      +     *          is negative, or {@code endIndex} is larger than the length of
      +     *          this {@code String} object, or {@code beginIndex} is larger than
      +     *          {@code endIndex}.
      +     * @since   21
      +     */
      +    public int indexOf(String str, int beginIndex, int endIndex) {

      Attachments

        Issue Links

          Activity

            People

              rgiulietti Raffaello Giulietti
              rgiulietti Raffaello Giulietti
              Alan Bateman
              Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: