src/share/classes/java/lang/String.java
Print this page
rev 8768 : 7174936: several String methods claim to always create new String
Reviewed-by: dholmes, bchristi
*** 1891,1901 ****
return start - sourceOffset + 1;
}
}
/**
! * Returns a new 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"
--- 1891,1901 ----
return start - sourceOffset + 1;
}
}
/**
! * 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"
*** 1919,1929 ****
}
return (beginIndex == 0) ? this : new String(value, beginIndex, subLen);
}
/**
! * Returns a new 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:
--- 1919,1929 ----
}
return (beginIndex == 0) ? this : new String(value, beginIndex, subLen);
}
/**
! * 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:
*** 1956,1966 ****
return ((beginIndex == 0) && (endIndex == value.length)) ? this
: new String(value, beginIndex, subLen);
}
/**
! * Returns a new character sequence that is a subsequence of this sequence.
*
* <p> An invocation of this method of the form
*
* <blockquote><pre>
* str.subSequence(begin, end)</pre></blockquote>
--- 1956,1966 ----
return ((beginIndex == 0) && (endIndex == value.length)) ? this
: new String(value, beginIndex, subLen);
}
/**
! * 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, end)</pre></blockquote>
*** 1968,1977 ****
--- 1968,1978 ----
* behaves in exactly the same way as the invocation
*
* <blockquote><pre>
* str.substring(begin, 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.
*** 1991,2002 ****
/**
* 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
* 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>
--- 1992,2003 ----
/**
* 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
! * {@code String} object is returned that represents 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>
*** 2019,2035 ****
str.getChars(buf, len);
return new String(buf, true);
}
/**
! * Returns a new 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
* 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>
--- 2020,2036 ----
str.getChars(buf, len);
return new String(buf, true);
}
/**
! * 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 {@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>
*** 2811,2847 ****
public String toUpperCase() {
return toUpperCase(Locale.getDefault());
}
/**
! * Returns a copy of the string, with leading and trailing whitespace
! * omitted.
* <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.
* <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
* 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
* space removed, or this string if it has no leading or
* trailing white space.
*/
public String trim() {
int len = value.length;
--- 2812,2848 ----
public String toUpperCase() {
return toUpperCase(Locale.getDefault());
}
/**
! * 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.
*/
public String trim() {
int len = value.length;
*** 2974,2989 ****
}
/**
* 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.
*
! * @param data a {@code char} array.
! * @return a newly allocated string representing the same sequence of
! * characters contained in the character array argument.
*/
public static String valueOf(char data[]) {
return new String(data);
}
--- 2975,2990 ----
}
/**
* 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 returned
! * string.
*
! * @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);
}
*** 2993,3037 ****
* <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.
*
* @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.
* @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.
*
* @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.
*/
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.
*
* @param data the character array.
* @return a {@code String} that contains the characters of the
* character array.
*/
--- 2994,3038 ----
* <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 returned string.
*
* @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 valueOf(char data[], int offset, int count) {
return new String(data, offset, count);
}
/**
! * Equivalent 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) {
return new String(data, offset, count);
}
/**
! * Equivalent to {@link #valueOf(char[])}.
*
* @param data the character array.
* @return a {@code String} that contains the characters of the
* character array.
*/