src/share/classes/java/lang/String.java

Print this page
rev 8642 : 7174936: several String methods claim to always create new String
Reviewed-by: XXX

@@ -1896,11 +1896,11 @@
             return start - sourceOffset + 1;
         }
     }
 
     /**
-     * Returns a new string that is a substring of this string. The
+     * Returns a string that is a substring of this string. The
      * substring begins with the character at the specified index and
      * extends to the end of this string. <p>
      * Examples:
      * <blockquote><pre>
      * "unhappy".substring(2) returns "happy"

@@ -1924,11 +1924,11 @@
         }
         return (beginIndex == 0) ? this : new String(value, beginIndex, subLen);
     }
 
     /**
-     * Returns a new string that is a substring of this string. The
+     * Returns a string that is a substring of this string. The
      * substring begins at the specified {@code beginIndex} and
      * extends to the character at index {@code endIndex - 1}.
      * Thus the length of the substring is {@code endIndex-beginIndex}.
      * <p>
      * Examples:

@@ -1961,11 +1961,11 @@
         return ((beginIndex == 0) && (endIndex == value.length)) ? this
                 : new String(value, beginIndex, subLen);
     }
 
     /**
-     * Returns a new character sequence that is a subsequence of this sequence.
+     * Returns a character sequence that is a subsequence of this sequence.
      *
      * <p> An invocation of this method of the form
      *
      * <blockquote><pre>
      * str.subSequence(begin,&nbsp;end)</pre></blockquote>

@@ -1973,16 +1973,17 @@
      * behaves in exactly the same way as the invocation
      *
      * <blockquote><pre>
      * str.substring(begin,&nbsp;end)</pre></blockquote>
      *
+     * @apiNote
      * This method is defined so that the {@code String} class can implement
      * the {@link CharSequence} interface.
      *
      * @param   beginIndex   the begin index, inclusive.
      * @param   endIndex     the end index, exclusive.
-     * @return  the specified subsequence.
+     * @return  the specified substring.
      *
      * @throws  IndexOutOfBoundsException
      *          if {@code beginIndex} or {@code endIndex} is negative,
      *          if {@code endIndex} is greater than {@code length()},
      *          or if {@code beginIndex} is greater than {@code endIndex}

@@ -1996,12 +1997,12 @@
 
     /**
      * Concatenates the specified string to the end of this string.
      * <p>
      * If the length of the argument string is {@code 0}, then this
-     * {@code String} object is returned. Otherwise, a new
-     * {@code String} object is created, representing a character
+     * {@code String} object is returned. Otherwise, a
+     * {@code String} object is returned, representing a character
      * sequence that is the concatenation of the character sequence
      * represented by this {@code String} object and the character
      * sequence represented by the argument string.<p>
      * Examples:
      * <blockquote><pre>

@@ -2024,17 +2025,17 @@
         str.getChars(buf, len);
         return new String(buf, true);
     }
 
     /**
-     * Returns a new string resulting from replacing all occurrences of
+     * Returns a string resulting from replacing all occurrences of
      * {@code oldChar} in this string with {@code newChar}.
      * <p>
      * If the character {@code oldChar} does not occur in the
      * character sequence represented by this {@code String} object,
      * then a reference to this {@code String} object is returned.
-     * Otherwise, a new {@code String} object is created that
+     * Otherwise, a {@code String} object is returned that
      * represents a character sequence identical to the character sequence
      * represented by this {@code String} object, except that every
      * occurrence of {@code oldChar} is replaced by an occurrence
      * of {@code newChar}.
      * <p>

@@ -2816,37 +2817,37 @@
     public String toUpperCase() {
         return toUpperCase(Locale.getDefault());
     }
 
     /**
-     * Returns a copy of the string, with leading and trailing whitespace
-     * omitted.
+     * 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 new
-     * {@code String} object representing an empty string is created
-     * and returned.
+     * {@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 new {@code String}
-     * object is created, representing the substring of this string that
+     * 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 copy of this string with leading and trailing white
+     * @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.
      */
     public String trim() {
         int len = value.length;

@@ -2979,16 +2980,16 @@
     }
 
     /**
      * Returns the string representation of the {@code char} array
      * argument. The contents of the character array are copied; subsequent
-     * modification of the character array does not affect the newly
-     * created string.
+     * modification of the character array does not affect the returned
+     * string.
      *
-     * @param   data   a {@code char} array.
-     * @return  a newly allocated string representing the same sequence of
-     *          characters contained in the character array argument.
+     * @param   data     the character array.
+     * @return  a {@code String} that contains the characters of the
+     *          character array.
      */
     public static String valueOf(char data[]) {
         return new String(data);
     }
 

@@ -2998,45 +2999,45 @@
      * <p>
      * The {@code offset} argument is the index of the first
      * character of the subarray. The {@code count} argument
      * specifies the length of the subarray. The contents of the subarray
      * are copied; subsequent modification of the character array does not
-     * affect the newly created string.
+     * affect the returned string.
      *
      * @param   data     the character array.
-     * @param   offset   the initial offset into the value of the
-     *                  {@code String}.
-     * @param   count    the length of the value of the {@code String}.
-     * @return  a string representing the sequence of characters contained
-     *          in the subarray of the character array argument.
+     * @param   offset   initial offset of the subarray.
+     * @param   count    length of the subarray.
+     * @return  a {@code String} that contains the characters of the
+     *          specified subarray of the character array.
      * @exception IndexOutOfBoundsException if {@code offset} is
      *          negative, or {@code count} is negative, or
      *          {@code offset+count} is larger than
      *          {@code data.length}.
      */
     public static String valueOf(char data[], int offset, int count) {
         return new String(data, offset, count);
     }
 
     /**
-     * Returns a String that represents the character sequence in the
-     * array specified.
+     * Identical to {@link #valueOf(char[], int, int)}.
      *
      * @param   data     the character array.
      * @param   offset   initial offset of the subarray.
      * @param   count    length of the subarray.
      * @return  a {@code String} that contains the characters of the
      *          specified subarray of the character array.
+     * @exception IndexOutOfBoundsException if {@code offset} is
+     *          negative, or {@code count} is negative, or
+     *          {@code offset+count} is larger than
+     *          {@code data.length}.
      */
     public static String copyValueOf(char data[], int offset, int count) {
-        // All public String constructors now copy the data.
         return new String(data, offset, count);
     }
 
     /**
-     * Returns a String that represents the character sequence in the
-     * array specified.
+     * Identical to {@link #valueOf(char[])}.
      *
      * @param   data   the character array.
      * @return  a {@code String} that contains the characters of the
      *          character array.
      */