diff --git a/src/share/classes/java/lang/AbstractStringBuilder.java b/src/share/classes/java/lang/AbstractStringBuilder.java index fc513f55efe961811fabcccd4f9de270beb0184f..03999c445a55d0810a50e57ab9d460e03c9effe2 100644 --- a/src/share/classes/java/lang/AbstractStringBuilder.java +++ b/src/share/classes/java/lang/AbstractStringBuilder.java @@ -860,9 +860,9 @@ abstract class AbstractStringBuilder implements Appendable, CharSequence { * @return the specified subsequence. * * @throws IndexOutOfBoundsException - * if start or end are negative, - * if end is greater than length(), - * or if start is greater than end + * if {@code start} or {@code end} are negative, + * if {@code end} is greater than {@code length()}, + * or if {@code start} is greater than {@code end} * @spec JSR-51 */ @Override @@ -1292,7 +1292,7 @@ abstract class AbstractStringBuilder implements Appendable, CharSequence { /** * Returns the index within this string of the first occurrence of the * specified substring, starting at the specified index. The integer - * returned is the smallest value k for which: + * returned is the smallest value {@code k} for which: *
* k >= Math.min(fromIndex, str.length()) && * this.toString().startsWith(str, k) @@ -1418,7 +1418,7 @@ abstract class AbstractStringBuilder implements Appendable, CharSequence { public abstract String toString(); /** - * Needed by String for the contentEquals method. + * Needed by {@code String} for the contentEquals method. */ final char[] getValue() { return value; diff --git a/src/share/classes/java/lang/String.java b/src/share/classes/java/lang/String.java index d73a2f7c2e9c8d4f53ad26c5a8041971ef460685..a9bc2f376481be95a1b6777f29c783b6f6c23b56 100644 --- a/src/share/classes/java/lang/String.java +++ b/src/share/classes/java/lang/String.java @@ -615,10 +615,10 @@ public final class String } /** - * Returns true if, and only if, {@link #length()} is 0. + * Returns {@code true} if, and only if, {@link #length()} is {@code 0}. * - * @return true if {@link #length()} is 0, otherwise - * false + * @return {@code true} if {@link #length()} is {@code 0}, otherwise + * {@code false} * * @since 1.6 */ @@ -1229,23 +1229,23 @@ public final class String /** * Tests if two string regions are equal. *- * A substring of this String object is compared to a substring + * A substring of this {@code String} object is compared to a substring * of the argument other. The result is true if these substrings * represent identical character sequences. The substring of this - * String object to be compared begins at index toffset - * and has length len. The substring of other to be compared - * begins at index ooffset and has length len. The - * result is false if and only if at least one of the following + * {@code String} object to be compared begins at index {@code toffset} + * and has length {@code len}. The substring of other to be compared + * begins at index {@code ooffset} and has length {@code len}. The + * result is {@code false} if and only if at least one of the following * is true: - *
- toffset is negative. - *
- ooffset is negative. - *
- toffset+len is greater than the length of this - * String object. - *
- ooffset+len is greater than the length of the other + *
* * @param toffset the starting offset of the subregion in this string. @@ -1280,28 +1280,28 @@ public final class String /** * Tests if two string regions are equal. *
- {@code toffset} is negative. + *
- {@code ooffset} is negative. + *
- {@code toffset+len} is greater than the length of this + * {@code String} object. + *
- {@code ooffset+len} is greater than the length of the other * argument. - *
- There is some nonnegative integer k less than len + *
- There is some nonnegative integer k less than {@code len} * such that: - * this.charAt(toffset+k) != other.charAt(ooffset+k) + *
this.charAt(toffset+k) != other.charAt(ooffset+k)
*- * A substring of this String object is compared to a substring - * of the argument other. The result is true if these + * A substring of this {@code String} object is compared to a substring + * of the argument {@code other}. The result is {@code true} if these * substrings represent character sequences that are the same, ignoring - * case if and only if ignoreCase is true. The substring of - * this String object to be compared begins at index - * toffset and has length len. The substring of - * other to be compared begins at index ooffset and - * has length len. The result is false if and only if + * case if and only if {@code ignoreCase} is true. The substring of + * this {@code String} object to be compared begins at index + * {@code toffset} and has length {@code len}. The substring of + * {@code other} to be compared begins at index {@code ooffset} and + * has length {@code len}. The result is {@code false} if and only if * at least one of the following is true: - *
- toffset is negative. - *
- ooffset is negative. - *
- toffset+len is greater than the length of this - * String object. - *
- ooffset+len is greater than the length of the other + *
- * + * * The hash value will never be zero. * * @return a hash code value for this object. diff --git a/src/share/classes/java/lang/StringBuffer.java b/src/share/classes/java/lang/StringBuffer.java index 9fabad48d68c895b14bb379413a3b1a718dfbfb5..5d7754a0cc7d104d0f451fd70c14f620bf16327f 100644 --- a/src/share/classes/java/lang/StringBuffer.java +++ b/src/share/classes/java/lang/StringBuffer.java @@ -57,7 +57,7 @@ package java.lang; *
- {@code toffset} is negative. + *
- {@code ooffset} is negative. + *
- {@code toffset+len} is greater than the length of this + * {@code String} object. + *
- {@code ooffset+len} is greater than the length of the other * argument. - *
- ignoreCase is false and there is some nonnegative - * integer k less than len such that: + *
- {@code ignoreCase} is {@code false} and there is some nonnegative + * integer k less than {@code len} such that: *
- ** this.charAt(toffset+k) != other.charAt(ooffset+k) *- ignoreCase is true and there is some nonnegative - * integer k less than len such that: + *
- {@code ignoreCase} is {@code true} and there is some nonnegative + * integer k less than {@code len} such that: *
* Character.toLowerCase(this.charAt(toffset+k)) != Character.toLowerCase(other.charAt(ooffset+k)) @@ -1500,12 +1500,12 @@ public final class String * of {@code ch} in the range from 0 to 0xFFFF (inclusive), * this is the smallest value k such that: ** is true. For other values of {@code ch}, it is the * smallest value k such that: *- * (this.charAt(k) == ch) && (k >= fromIndex) + * (this.charAt(k) == ch) {@code &&} (k >= fromIndex) ** is true. In either case, if no such character occurs in this * string at or after position {@code fromIndex}, then @@ -1604,12 +1604,12 @@ public final class String * from 0 to 0xFFFF (inclusive), the index returned is the largest * value k such that: *- * (this.codePointAt(k) == ch) && (k >= fromIndex) + * (this.codePointAt(k) == ch) {@code &&} (k >= fromIndex) ** is true. For other values of {@code ch}, it is the * largest value k such that: *- * (this.charAt(k) == ch) && (k <= fromIndex) + * (this.charAt(k) == ch) {@code &&} (k <= fromIndex) ** is true. In either case, if no such character occurs in this * string at or before position {@code fromIndex}, then @@ -1690,7 +1690,7 @@ public final class String * *- * (this.codePointAt(k) == ch) && (k <= fromIndex) + * (this.codePointAt(k) == ch) {@code &&} (k <= fromIndex) *The returned index is the smallest value k for which: *
* If no such value of k exists, then {@code -1} is returned. * @@ -1799,7 +1799,7 @@ public final class String * *- * k >= fromIndex && this.startsWith(str, k) + * k >= fromIndex {@code &&} this.startsWith(str, k) *The returned index is the largest value k for which: *
* If no such value of k exists, then {@code -1} is returned. * @@ -2080,17 +2080,18 @@ public final class String * href="../util/regex/Pattern.html#sum">regular expression. * *- * k <= fromIndex && this.startsWith(str, k) + * k {@code <=} fromIndex {@code &&} this.startsWith(str, k) *An invocation of this method of the form - * str.matches(regex) yields exactly the + * str{@code .matches(}regex{@code )} yields exactly the * same result as the expression * - *
{@link java.util.regex.Pattern}.{@link - * java.util.regex.Pattern#matches(String,CharSequence) - * matches}(regex, str)+ *+ * {@link java.util.regex.Pattern}.{@link java.util.regex.Pattern#matches(String,CharSequence) + * matches(regex, str)} + ** * @param regex * the regular expression to which this string is to be matched * - * @return true if, and only if, this string matches the + * @return {@code true} if, and only if, this string matches the * given regular expression * * @throws PatternSyntaxException @@ -2124,18 +2125,20 @@ public final class String * given replacement. * *An invocation of this method of the form - * str.replaceFirst(regex, repl) + * str{@code .replaceFirst(}regex{@code ,} repl{@code )} * yields exactly the same result as the expression * - *
- * {@link java.util.regex.Pattern}.{@link java.util.regex.Pattern#compile - * compile}(regex).{@link - * java.util.regex.Pattern#matcher(java.lang.CharSequence) - * matcher}(str).{@link java.util.regex.Matcher#replaceFirst - * replaceFirst}(repl)+ *+ ** *+ * {@link java.util.regex.Pattern}.{@link + * java.util.regex.Pattern#compile compile}(regex).{@link + * java.util.regex.Pattern#matcher(java.lang.CharSequence) matcher}(str).{@link + * java.util.regex.Matcher#replaceFirst replaceFirst}(repl) + *
+ *- * Note that backslashes (\) and dollar signs ($) in the + * Note that backslashes ({@code \}) and dollar signs ({@code $}) in the * replacement string may cause the results to be different than if it were * being treated as a literal replacement string; see * {@link java.util.regex.Matcher#replaceFirst}. @@ -2147,7 +2150,7 @@ public final class String * @param replacement * the string to be substituted for the first match * - * @return The resulting String + * @return The resulting {@code String} * * @throws PatternSyntaxException * if the regular expression's syntax is invalid @@ -2167,18 +2170,20 @@ public final class String * given replacement. * *
An invocation of this method of the form - * str.replaceAll(regex, repl) + * str{@code .replaceAll(}regex{@code ,} repl{@code )} * yields exactly the same result as the expression * - *
- * {@link java.util.regex.Pattern}.{@link java.util.regex.Pattern#compile - * compile}(regex).{@link - * java.util.regex.Pattern#matcher(java.lang.CharSequence) - * matcher}(str).{@link java.util.regex.Matcher#replaceAll - * replaceAll}(repl)+ *+ ** *+ * {@link java.util.regex.Pattern}.{@link + * java.util.regex.Pattern#compile compile}(regex).{@link + * java.util.regex.Pattern#matcher(java.lang.CharSequence) matcher}(str).{@link + * java.util.regex.Matcher#replaceAll replaceAll}(repl) + *
+ *- * Note that backslashes (\) and dollar signs ($) in the + * Note that backslashes ({@code \}) and dollar signs ({@code $}) in the * replacement string may cause the results to be different than if it were * being treated as a literal replacement string; see * {@link java.util.regex.Matcher#replaceAll Matcher.replaceAll}. @@ -2190,7 +2195,7 @@ public final class String * @param replacement * the string to be substituted for each match * - * @return The resulting String + * @return The resulting {@code String} * * @throws PatternSyntaxException * if the regular expression's syntax is invalid @@ -2234,7 +2239,7 @@ public final class String * expression does not match any part of the input then the resulting array * has just one element, namely this string. * - *
The limit parameter controls the number of times the + *
The {@code limit} parameter controls the number of times the * pattern is applied and therefore affects the length of the resulting * array. If the limit n is greater than zero then the pattern * will be applied at most n - 1 times, the array's @@ -2245,7 +2250,7 @@ public final class String * the pattern will be applied as many times as possible, the array can * have any length, and trailing empty strings will be discarded. * - *
The string "boo:and:foo", for example, yields the + *
The string {@code "boo:and:foo"}, for example, yields the * following results with these parameters: * *
* *@@ -2256,33 +2261,34 @@ public final class String * *
+ * : *2 - *{ "boo", "and:foo" } {@code { "boo", "and:foo" }} *+ * : *5 - *{ "boo", "and", "foo" } {@code { "boo", "and", "foo" }} *+ * : *-2 - *{ "boo", "and", "foo" } {@code { "boo", "and", "foo" }} *+ * o *5 - *{ "b", "", ":and:f", "", "" } {@code { "b", "", ":and:f", "", "" }} *+ * o *-2 - *{ "b", "", ":and:f", "", "" } {@code { "b", "", ":and:f", "", "" }} *+ * o *0 - *{ "b", "", ":and:f" } {@code { "b", "", ":and:f" }} *An invocation of this method of the form - * str.split(regex, n) + * str.{@code split(}regex{@code ,} n{@code )} * yields the same result as the expression * *
- * {@link java.util.regex.Pattern}.{@link java.util.regex.Pattern#compile - * compile}(regex).{@link - * java.util.regex.Pattern#split(java.lang.CharSequence,int) - * split}(str, n) + ** * @@ -2364,7 +2370,7 @@ public final class String * argument of zero. Trailing empty strings are therefore not included in * the resulting array. * - *+ * {@link java.util.regex.Pattern}.{@link + * java.util.regex.Pattern#compile compile}(regex).{@link + * java.util.regex.Pattern#split(java.lang.CharSequence,int) split}(str, n) + *
*The string "boo:and:foo", for example, yields the following + *
The string {@code "boo:and:foo"}, for example, yields the following * results with these expressions: * *
* * @@ -2815,7 +2821,7 @@ public final class String * limited by the maximum dimension of a Java array as defined by * The Java™ Virtual Machine Specification. * The behaviour on a - * null argument depends on the conversion. * * @throws java.util.IllegalFormatException @@ -2828,7 +2834,7 @@ public final class String * formatter class specification. * * @throws NullPointerException - * If the format is null + * If the {@code format} is {@code null} * * @return A formatted string * @@ -2845,7 +2851,7 @@ public final class String * * @param l * The {@linkplain java.util.Locale locale} to apply during - * formatting. If l is null then no localization + * formatting. If {@code l} is {@code null} then no localization * is applied. * * @param format @@ -2859,7 +2865,7 @@ public final class String * limited by the maximum dimension of a Java array as defined by * The Java™ Virtual Machine Specification. * The behaviour on a - * null argument depends on the conversion. * * @throws java.util.IllegalFormatException @@ -2872,7 +2878,7 @@ public final class String * formatter class specification * * @throws NullPointerException - * If the format is null + * If the {@code format} is {@code null} * * @return A formatted string * @@ -3143,7 +3149,7 @@ public final class String * programmer should be aware that producing distinct integer results * for unequal objects may improve the performance of hash tables. *@@ -2373,9 +2379,9 @@ public final class String *
Result * *+ * : - *{ "boo", "and", "foo" } {@code { "boo", "and", "foo" }} *+ * o - *{ "b", "", ":and:f" } {@code { "b", "", ":and:f" }} ** In general, if sb refers to an instance of a {@code StringBuffer}, * then {@code sb.append(x)} has the same effect as - * {@code sb.insert(sb.length(), x)}. + * {@code sb.insert(sb.length(), x)}. *
* Whenever an operation occurs involving a source sequence (such as * appending or inserting from a source sequence), this class synchronizes @@ -80,7 +80,7 @@ package java.lang; * * As of release JDK 5, this class has been supplemented with an equivalent * class designed for use by a single thread, {@link StringBuilder}. The - * StringBuilder class should generally be used in preference to + * {@code StringBuilder} class should generally be used in preference to * this one, as it supports all of the same operations but it is faster, as * it performs no synchronization. * @@ -262,17 +262,17 @@ package java.lang; } /** - * Appends the specified StringBuffer to this sequence. + * Appends the specified {@code StringBuffer} to this sequence. *
- * The characters of the StringBuffer argument are appended, - * in order, to the contents of this StringBuffer, increasing the - * length of this StringBuffer by the length of the argument. - * If sb is null, then the four characters - * "null" are appended to this StringBuffer. + * The characters of the {@code StringBuffer} argument are appended, + * in order, to the contents of this {@code StringBuffer}, increasing the + * length of this {@code StringBuffer} by the length of the argument. + * If {@code sb} is {@code null}, then the four characters + * {@code "null"} are appended to this {@code StringBuffer}. *
* Let n be the length of the old character sequence, the one - * contained in the StringBuffer just prior to execution of the - * append method. Then the character at index k in + * contained in the {@code StringBuffer} just prior to execution of the + * {@code append} method. Then the character at index k in * the new character sequence is equal to the character at index k * in the old character sequence, if k is less than n; * otherwise, it is equal to the character at index k-n in the @@ -281,7 +281,7 @@ package java.lang; * This method synchronizes on {@code this}, the destination * object, but does not synchronize on the source ({@code sb}). * - * @param sb the StringBuffer to append. + * @param sb the {@code StringBuffer} to append. * @return a reference to this object. * @since 1.4 */ diff --git a/src/share/classes/java/lang/StringBuilder.java b/src/share/classes/java/lang/StringBuilder.java index acddd83a8a30983b8c3e578f5155f02146cff8bb..e9defe23f6f7c7a31e153ce17bbf46f10e167297 100644 --- a/src/share/classes/java/lang/StringBuilder.java +++ b/src/share/classes/java/lang/StringBuilder.java @@ -28,39 +28,39 @@ package java.lang; /** * A mutable sequence of characters. This class provides an API compatible - * with
StringBuffer
, but with no guarantee of synchronization. + * with {@code StringBuffer}, but with no guarantee of synchronization. * This class is designed for use as a drop-in replacement for - *StringBuffer
in places where the string buffer was being + * {@code StringBuffer} in places where the string buffer was being * used by a single thread (as is generally the case). Where possible, * it is recommended that this class be used in preference to - *StringBuffer
as it will be faster under most implementations. + * {@code StringBuffer} as it will be faster under most implementations. * - *The principal operations on a
StringBuilder
are the - *append
andinsert
methods, which are + *The principal operations on a {@code StringBuilder} are the + * {@code append} and {@code insert} methods, which are * overloaded so as to accept data of any type. Each effectively * converts a given datum to a string and then appends or inserts the * characters of that string to the string builder. The - *
append
method always adds these characters at the end - * of the builder; theinsert
method adds the characters at + * {@code append} method always adds these characters at the end + * of the builder; the {@code insert} method adds the characters at * a specified point. *- * For example, if
z
refers to a string builder object - * whose current contents are "start
", then - * the method callz.append("le")
would cause the string - * builder to contain "startle
", whereas - *z.insert(4, "le")
would alter the string builder to - * contain "starlet
". + * For example, if {@code z} refers to a string builder object + * whose current contents are "{@code start}", then + * the method call {@code z.append("le")} would cause the string + * builder to contain "{@code startle}", whereas + * {@code z.insert(4, "le")} would alter the string builder to + * contain "{@code starlet}". + *+ * In general, if sb refers to an instance of a {@code StringBuilder}, + * then {@code sb.append(x)} has the same effect as + * {@code sb.insert(sb.length(), x)}. *
- * In general, if sb refers to an instance of a
StringBuilder
, - * thensb.append(x)
has the same effect as - *sb.insert(sb.length(), x)
. - * * Every string builder has a capacity. As long as the length of the * character sequence contained in the string builder does not exceed * the capacity, it is not necessary to allocate a new internal * buffer. If the internal buffer overflows, it is automatically made larger. * - *Instances of
StringBuilder
are not safe for + *Instances of {@code StringBuilder} are not safe for * use by multiple threads. If such synchronization is required then it is * recommended that {@link java.lang.StringBuffer} be used. * @@ -87,11 +87,11 @@ public final class StringBuilder /** * Constructs a string builder with no characters in it and an - * initial capacity specified by the
capacity
argument. + * initial capacity specified by the {@code capacity} argument. * * @param capacity the initial capacity. - * @throws NegativeArraySizeException if thecapacity
- * argument is less than0
. + * @throws NegativeArraySizeException if the {@code capacity} + * argument is less than {@code 0}. */ public StringBuilder(int capacity) { super(capacity); @@ -100,10 +100,10 @@ public final class StringBuilder /** * Constructs a string builder initialized to the contents of the * specified string. The initial capacity of the string builder is - *16
plus the length of the string argument. + * {@code 16} plus the length of the string argument. * * @param str the initial contents of the buffer. - * @throws NullPointerException ifstr
isnull
+ * @throws NullPointerException if {@code str} is {@code null} */ public StringBuilder(String str) { super(str.length() + 16); @@ -112,12 +112,12 @@ public final class StringBuilder /** * Constructs a string builder that contains the same characters - * as the specifiedCharSequence
. The initial capacity of - * the string builder is16
plus the length of the - *CharSequence
argument. + * as the specified {@code CharSequence}. The initial capacity of + * the string builder is {@code 16} plus the length of the + * {@code CharSequence} argument. * * @param seq the sequence to copy. - * @throws NullPointerException ifseq
isnull
+ * @throws NullPointerException if {@code seq} is {@code null} */ public StringBuilder(CharSequence seq) { this(seq.length() + 16); @@ -136,22 +136,22 @@ public final class StringBuilder } /** - * Appends the specified StringBuffer to this sequence. + * Appends the specified {@code StringBuffer} to this sequence. *- * The characters of the StringBuffer argument are appended, + * The characters of the {@code StringBuffer} argument are appended, * in order, to this sequence, increasing the * length of this sequence by the length of the argument. - * If sb is null, then the four characters - * "null" are appended to this sequence. + * If {@code sb} is {@code null}, then the four characters + * {@code "null"} are appended to this sequence. *
* Let n be the length of this character sequence just prior to - * execution of the append method. Then the character at index + * execution of the {@code append} method. Then the character at index * k in the new character sequence is equal to the character at * index k in the old character sequence, if k is less than * n; otherwise, it is equal to the character at index k-n - * in the argument
sb
. + * in the argument {@code sb}. * - * @param sb the StringBuffer to append. + * @param sb the {@code StringBuffer} to append. * @return a reference to this object. */ public StringBuilder append(StringBuffer sb) { @@ -418,13 +418,13 @@ public final class StringBuilder } /** - * Save the state of the StringBuilder instance to a stream + * Save the state of the {@code StringBuilder} instance to a stream * (that is, serialize it). * * @serialData the number of characters currently stored in the string - * builder (int), followed by the characters in the - * string builder (char[]). The length of the - * char array may be greater than the number of + * builder ({@code int}), followed by the characters in the + * string builder ({@code char[]}). The length of the + * {@code char} array may be greater than the number of * characters currently stored in the string builder, in which * case extra characters are ignored. */ diff --git a/src/share/classes/java/lang/StringIndexOutOfBoundsException.java b/src/share/classes/java/lang/StringIndexOutOfBoundsException.java index 7067e29a88c75ae5d52e5de54f69c46fec85fd72..c3aa9b7a2dfa18dd4079dc82464ba182c2d43997 100644 --- a/src/share/classes/java/lang/StringIndexOutOfBoundsException.java +++ b/src/share/classes/java/lang/StringIndexOutOfBoundsException.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1994, 2008, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1994, 2012, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -26,7 +26,7 @@ package java.lang; /** - * Thrown byString
methods to indicate that an index + * Thrown by {@code String} methods to indicate that an index * is either negative or greater than the size of the string. For * some methods such as the charAt method, this exception also is * thrown when the index is equal to the size of the string. @@ -40,7 +40,7 @@ class StringIndexOutOfBoundsException extends IndexOutOfBoundsException { private static final long serialVersionUID = -6762910422159637258L; /** - * Constructs aStringIndexOutOfBoundsException
with no + * Constructs a {@code StringIndexOutOfBoundsException} with no * detail message. * * @since JDK1.0. @@ -50,7 +50,7 @@ class StringIndexOutOfBoundsException extends IndexOutOfBoundsException { } /** - * Constructs aStringIndexOutOfBoundsException
with + * Constructs a {@code StringIndexOutOfBoundsException} with * the specified detail message. * * @param s the detail message. @@ -60,7 +60,7 @@ class StringIndexOutOfBoundsException extends IndexOutOfBoundsException { } /** - * Constructs a newStringIndexOutOfBoundsException
+ * Constructs a new {@code StringIndexOutOfBoundsException} * class with an argument indicating the illegal index. * * @param index the illegal index.