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

String::trim JavaDoc should clarify meaning of space

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P3
    • Resolution: Approved
    • Fix Version/s: 11
    • Component/s: core-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      Clarifying existing behavior.
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

      Summary

      The JavaDoc for String::trim should make it clear which definition of "space" is being used in the code.

      Problem

      The current JavaDoc for String::trim does not make it clear which definition of "space" is being used in the code. With additional trimming methods coming in the near future that use a different definition of space, clarification is imperative.

      String::trim uses the definition of space as any codepoint that is less than or equal to the space character codepoint (\u0020.)

      Newer trimming methods will use the definition of (white) space as any codepoint that returns true when passed to the Character::isWhitespace predicate.

      Solution

      Rework the String::trim JavaDoc to clarify the meaning of "space."

      Specification

      old:
          /**
           * Returns a string whose value is this string, with any leading and trailing
           * whitespace removed.
           * <p>
           * If this {@code String} object represents an empty character
           * sequence, or the first and last characters of character sequence
           * represented by this {@code String} object both have codes
           * greater than {@code '\u005Cu0020'} (the space character), then a
           * reference to this {@code String} object is returned.
           * <p>
           * Otherwise, if there is no character with a code greater than
           * {@code '\u005Cu0020'} in the string, then a
           * {@code String} object representing an empty string is
           * returned.
           * <p>
           * Otherwise, let <i>k</i> be the index of the first character in the
           * string whose code is greater than {@code '\u005Cu0020'}, and let
           * <i>m</i> be the index of the last character in the string whose code
           * is greater than {@code '\u005Cu0020'}. A {@code String}
           * object is returned, representing the substring of this string that
           * begins with the character at index <i>k</i> and ends with the
           * character at index <i>m</i>-that is, the result of
           * {@code this.substring(k, m + 1)}.
           * <p>
           * This method may be used to trim whitespace (as defined above) from
           * the beginning and end of a string.
           *
           * @return  A string whose value is this string, with any leading and trailing white
           *          space removed, or this string if it has no leading or
           *          trailing white space.
           */
      
      new:
          /**
           * Returns a string whose value is this string, with all leading
           * and trailing space removed, where space is defined
           * as any character whose codepoint is less than or equal to
           * {@code '\u005Cu0020'} (the space character).
           * <p>
           * If this {@code String} object represents an empty character
           * sequence, or the first and last characters of character sequence
           * represented by this {@code String} object both have codes
           * that are not space (as defined above), then a
           * reference to this {@code String} object is returned.
           * <p>
           * Otherwise, if all characters in this string are space (as
           * defined above), then a  {@code String} object representing an
           * empty string is returned.
           * <p>
           * Otherwise, let <i>k</i> be the index of the first character in the
           * string whose code is not a space (as defined above) and let
           * <i>m</i> be the index of the last character in the string whose code
           * is not a space (as defined above). A {@code String}
           * object is returned, representing the substring of this string that
           * begins with the character at index <i>k</i> and ends with the
           * character at index <i>m</i>-that is, the result of
           * {@code this.substring(k, m + 1)}.
           * <p>
           * This method may be used to trim space (as defined above) from
           * the beginning and end of a string.
           *
           * @return  a string whose value is this string, with all leading
           *          and trailing space removed, or this string if it
           *          has no leading or trailing space.
           */
      

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                jlaskey Jim Laskey
                Reporter:
                jlaskey Jim Laskey
                Reviewed By:
                Sundararajan Athijegannathan, Xueming Shen
              • Votes:
                0 Vote for this issue
                Watchers:
                4 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: