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

The documentation of the Scanner.hasNextLine is incorrect

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P4
    • Resolution: Approved
    • Fix Version/s: 18
    • Component/s: core-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      Clarification of the existing spec.
    • Scope:
      SE

      Description

      Summary

      The Scanner documentation for "hasNextLine()" is vague as to whether or not it will return true if there is no line delimiter in remaining scanner input. This fix clarifies that it can return true even if there are no more line separators in the input of the Scanner. The proposed change is a rewording of the spec to make it more explicit on existing behavior. There are no behavior changes proposed here.

      Problem

      The documentation clause for the return value of hasNext() is unclear as to whether a line separator in the remaining input is necessary for it to return true.

      Solution

      Updated the spec to further clarify when hasNextLine() returns true. The method uses a line pattern such that:

      private static final String LINE_SEPARATOR_PATTERN = "\r\n|[\n\r\u2028\u2029\u0085]";
      private static final String LINE_PATTERN = ".*("+LINE_SEPARATOR_PATTERN+")|.+$";

      This means that it will return true given any input where the input stream is non-empty. It's essentially the same as hasNext() with one caveat: it will return true if the input simply contains a line separator. We could note it this way, but I believe it's more succinct to simply say that the method will return true if there is a line separator or if there are additional characters in the input. Since the regular expression explicitly includes line separators in its match even though the Pattern compilation that this method uses does not use DOTALL, this is a correct description. Every character considered a line terminator by java.util.regex.Pattern is captured in the scanner line separator pattern.

      Specification

      The return portion of the documentation for hasNextLine() now reads:

      --- a/src/java.base/share/classes/java/util/Scanner.java
      +++ b/src/java.base/share/classes/java/util/Scanner.java
      @@ -1600,7 +1600,8 @@ public final class Scanner implements Iterator<String>, Closeable {
            * This method may block while waiting for input. The scanner does not
            * advance past any input.
            *
      -     * @return true if and only if this scanner has another line of input
      +     * @return true if there is a line separator in the remaining input
      +     * or if the input has other remaining characters
            * @throws IllegalStateException if this scanner is closed
            */
           public boolean hasNextLine() {

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              igraves Ian Graves
              Reporter:
              webbuggrp Webbug Group
              Reviewed By:
              Brian Burkhalter, Iris Clark, Roger Riggs
              Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: