This is the mail archive of the
java-patches@gcc.gnu.org
mailing list for the Java project.
Patch: FYI: Partial String merge
- From: Tom Tromey <tromey at redhat dot com>
- To: GCC libjava patches <java-patches at gcc dot gnu dot org>
- Date: 29 Mar 2003 22:33:05 -0700
- Subject: Patch: FYI: Partial String merge
- Reply-to: tromey at redhat dot com
I'm checking this in on the trunk.
Inspired by Michael Koch, I rearranged String to follow Classpath and
merged in the javadoc. This is the first step in resurrecting Eric
Blake's String merge patch, which I've let languish for over a year
now. Rearranging like this makes it much easier to compare the
classpath and libgcj code.
This patch is reordering and comment additions only.
Tom
Index: ChangeLog
from Tom Tromey <tromey at redhat dot com>
* java/lang/String.java: Reordered to follow Classpath; merged in
javadoc.
Index: java/lang/String.java
===================================================================
RCS file: /cvs/gcc/gcc/libjava/java/lang/String.java,v
retrieving revision 1.19
diff -u -r1.19 String.java
--- java/lang/String.java 24 Mar 2003 00:50:18 -0000 1.19
+++ java/lang/String.java 30 Mar 2003 05:34:30 -0000
@@ -1,12 +1,44 @@
-/* Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003 Free Software Foundation
+/* String.java -- immutable character sequences; the object of string literals
+ Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003
+ Free Software Foundation, Inc.
+
+This file is part of GNU Classpath.
+
+GNU Classpath is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2, or (at your option)
+any later version.
+
+GNU Classpath is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with GNU Classpath; see the file COPYING. If not, write to the
+Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+02111-1307 USA.
+
+Linking this library statically or dynamically with other modules is
+making a combined work based on this library. Thus, the terms and
+conditions of the GNU General Public License cover the whole
+combination.
+
+As a special exception, the copyright holders of this library give you
+permission to link this library with independent modules to produce an
+executable, regardless of the license terms of these independent
+modules, and to copy and distribute the resulting executable under
+terms of your choice, provided that you also meet, for each linked
+independent module, the terms and conditions of the license of that
+module. An independent module is a module which is not derived from
+or based on this library. If you modify this library, you may extend
+this exception to your version of the library, but you are not
+obligated to do so. If you do not wish to do so, delete this
+exception statement from your version. */
- This file is part of libgcj.
-
-This software is copyrighted work licensed under the terms of the
-Libgcj License. Please consult the file "LIBGCJ_LICENSE" for
-details. */
package java.lang;
+
import java.io.UnsupportedEncodingException;
import java.io.Serializable;
import java.lang.Comparable;
@@ -14,40 +46,68 @@
import java.util.Locale;
/**
+ * Strings represent an immutable set of characters. All String literals
+ * are instances of this class, and two string literals with the same contents
+ * refer to the same String object.
+ *
+ * <p>This class also includes a number of methods for manipulating the
+ * contents of strings (of course, creating a new object if there are any
+ * changes, as String is immutable). Case mapping relies on Unicode 3.0.0
+ * standards, where some character sequences have a different number of
+ * characters in the uppercase version than the lower case.
+ *
+ * <p>Strings are special, in that they are the only object with an overloaded
+ * operator. When you use '+' with at least one String argument, both
+ * arguments have String conversion performed on them, and another String (not
+ * guaranteed to be unique) results.
+ *
+ * <p>String is special-cased when doing data serialization - rather than
+ * listing the fields of this class, a String object is converted to a string
+ * literal in the object stream.
+ *
+ * @author Paul N. Fisher
+ * @author Eric Blake <ebb9 at email dot byu dot edu>
* @author Per Bothner <bothner at cygnus dot com>
- * @date September 4, 1998.
- */
-/* Written using "Java Class Libraries", 2nd edition, plus online
- * API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status: Complete to 1.3.
+ * @since 1.0
+ * @status updated to 1.4
*/
-
public final class String implements Serializable, Comparable, CharSequence
{
+ // WARNING: String is a CORE class in the bootstrap cycle. See the comments
+ // in vm/reference/java/lang/Runtime for implications of this fact.
+
+ /**
+ * This is probably not necessary because this class is special cased already
+ * but it will avoid showing up as a discrepancy when comparing SUIDs.
+ */
+ private static final long serialVersionUID = -6849794470754667710L;
+
private Object data;
private int boffset; // Note this is a byte offset - don't use in Java code!
int count;
- // This is probably not necessary because this class is special cased already
- // but it will avoid showing up as a discrepancy when comparing SUIDs.
- private static final long serialVersionUID = -6849794470754667710L;
-
/**
* An implementation for { at link CASE_INSENSITIVE_ORDER}.
- * This must be { at link Serializable}.
+ * This must be { at link Serializable}. The class name is dictated by
+ * compatibility with Sun's JDK.
*/
private static final class CaseInsensitiveComparator
implements Comparator, Serializable
{
/**
- * The default private constructor generates unnecessary overhead
+ * Compatible with JDK 1.2.
+ */
+ private static final long serialVersionUID = 8575799808933029326L;
+
+ /**
+ * The default private constructor generates unnecessary overhead.
*/
CaseInsensitiveComparator() {}
/**
- * Compares two Strings, using
+ * Compares to Strings, using
* <code>String.compareToIgnoreCase(String)</code>.
- *
+ *
* @param o1 the first string
* @param o2 the second string
* @return < 0, 0, or > 0 depending on the case-insensitive
@@ -60,69 +120,194 @@
{
return ((String) o1).compareToIgnoreCase((String) o2);
}
- }
+ } // class CaseInsensitiveComparator
/**
* A Comparator that uses <code>String.compareToIgnoreCase(String)</code>.
- * This comparator is { at link Serializable}.
+ * This comparator is { at link Serializable}. Note that it ignores Locale,
+ * for that, you want a Collator.
*
+ * @see Collator#compare(String, String)
* @since 1.2
*/
public static final Comparator CASE_INSENSITIVE_ORDER
= new CaseInsensitiveComparator();
+ /**
+ * Creates an empty String (length 0). Unless you really need a new object,
+ * consider using <code>""</code> instead.
+ */
public String ()
{
init();
}
- public String (String value)
+ /**
+ * Copies the contents of a String to a new String. Since Strings are
+ * immutable, only a shallow copy is performed.
+ *
+ * @param str String to copy
+ * @throws NullPointerException if value is null
+ */
+ public String (String str)
{
- data = value.data;
- boffset = value.boffset;
- count = value.count;
+ data = str.data;
+ boffset = str.boffset;
+ count = str.count;
}
- public String (StringBuffer buffer)
+ /**
+ * Creates a new String using the character sequence of the char array.
+ * Subsequent changes to data do not affect the String.
+ *
+ * @param data char array to copy
+ * @throws NullPointerException if data is null
+ */
+ public String (char[] data)
{
- synchronized (buffer)
- {
- buffer.shared = true;
- init (buffer.value, 0, buffer.count, true);
- }
+ init(data, 0, data.length, false);
}
- // This is used by gnu.gcj.runtime.StringBuffer, so it must have
- // package-private protection. It is accessed via CNI and so avoids
- // ordinary protection mechanisms.
- String (gnu.gcj.runtime.StringBuffer buffer)
+ /**
+ * Creates a new String using the character sequence of a subarray of
+ * characters. The string starts at offset, and copies count chars.
+ * Subsequent changes to data do not affect the String.
+ *
+ * @param data char array to copy
+ * @param offset position (base 0) to start copying out of data
+ * @param count the number of characters from data to copy
+ * @throws NullPointerException if data is null
+ * @throws IndexOutOfBoundsException if (offset < 0 || count < 0
+ * || offset + count > data.length)
+ * (while unspecified, this is a StringIndexOutOfBoundsException)
+ */
+ public String (char[] data, int offset, int count)
{
- // No need to synchronize or mark the buffer, since we know it is
- // only used once.
- init (buffer.value, 0, buffer.count, true);
+ init(data, offset, count, false);
}
- public String (char[] data)
+ /**
+ * Creates a new String using an 8-bit array of integer values, starting at
+ * an offset, and copying up to the count. Each character c, using
+ * corresponding byte b, is created in the new String as if by performing:
+ *
+ * <pre>
+ * c = (char) (((hibyte & 0xff) << 8) | (b & 0xff))
+ * </pre>
+ *
+ * @param ascii array of integer values
+ * @param hibyte top byte of each Unicode character
+ * @param offset position (base 0) to start copying out of ascii
+ * @param count the number of characters from ascii to copy
+ * @throws NullPointerException if ascii is null
+ * @throws IndexOutOfBoundsException if (offset < 0 || count < 0
+ * || offset + count > ascii.length)
+ * (while unspecified, this is a StringIndexOutOfBoundsException)
+ * @see #String(byte[])
+ * @see #String(byte[], String)
+ * @see #String(byte[], int, int)
+ * @see #String(byte[], int, int, String)
+ * @deprecated use { at link #String(byte[], int, int, String)} to perform
+ * correct encoding
+ */
+ public String (byte[] ascii, int hibyte, int offset, int count)
{
- init(data, 0, data.length, false);
+ init(ascii, hibyte, offset, count);
}
- public String (char[] data, int offset, int count)
+ /**
+ * Creates a new String using an 8-bit array of integer values. Each
+ * character c, using corresponding byte b, is created in the new String
+ * as if by performing:
+ *
+ * <pre>
+ * c = (char) (((hibyte & 0xff) << 8) | (b & 0xff))
+ * </pre>
+ *
+ * @param ascii array of integer values
+ * @param hibyte top byte of each Unicode character
+ * @throws NullPointerException if ascii is null
+ * @see #String(byte[])
+ * @see #String(byte[], String)
+ * @see #String(byte[], int, int)
+ * @see #String(byte[], int, int, String)
+ * @see #String(byte[], int, int, int)
+ * @deprecated use { at link #String(byte[], String)} to perform
+ * correct encoding
+ */
+ public String (byte[] ascii, int hibyte)
{
- init(data, offset, count, false);
+ init(ascii, hibyte, 0, ascii.length);
}
- // This is used by Integer.toString(int,int).
- String (char[] data, int offset, int count, boolean dont_copy)
+ /**
+ * Creates a new String using the portion of the byte array starting at the
+ * offset and ending at offset + count. Uses the specified encoding type
+ * to decode the byte array, so the resulting string may be longer or
+ * shorter than the byte array. For more decoding control, use
+ * { at link java.nio.charset.CharsetDecoder}, and for valid character sets,
+ * see { at link java.nio.charset.Charset}. The behavior is not specified if
+ * the decoder encounters invalid characters; this implementation throws
+ * an Error.
+ *
+ * @param data byte array to copy
+ * @param offset the offset to start at
+ * @param count the number of characters in the array to use
+ * @param encoding the name of the encoding to use
+ * @throws NullPointerException if data or encoding is null
+ * @throws IndexOutOfBoundsException if offset or count is incorrect
+ * (while unspecified, this is a StringIndexOutOfBoundsException)
+ * @throws UnsupportedEncodingException if encoding is not found
+ * @throws Error if the decoding fails
+ * @since 1.1
+ */
+ public String (byte[] byteArray, int offset, int count, String enc)
+ throws UnsupportedEncodingException
{
- init(data, offset, count, dont_copy);
+ init (byteArray, offset, count, enc);
}
- public String (byte[] byteArray)
+ /**
+ * Creates a new String using the byte array. Uses the specified encoding
+ * type to decode the byte array, so the resulting string may be longer or
+ * shorter than the byte array. For more decoding control, use
+ * { at link java.nio.charset.CharsetDecoder}, and for valid character sets,
+ * see { at link java.nio.charset.Charset}. The behavior is not specified if
+ * the decoder encounters invalid characters; this implementation throws
+ * an Error.
+ *
+ * @param data byte array to copy
+ * @param encoding the name of the encoding to use
+ * @throws NullPointerException if data or encoding is null
+ * @throws UnsupportedEncodingException if encoding is not found
+ * @throws Error if the decoding fails
+ * @see #String(byte[], int, int, String)
+ * @since 1.1
+ */
+ public String (byte[] byteArray, String enc)
+ throws UnsupportedEncodingException
{
- this (byteArray, 0, byteArray.length);
+ this (byteArray, 0, byteArray.length, enc);
}
+ /**
+ * Creates a new String using the portion of the byte array starting at the
+ * offset and ending at offset + count. Uses the encoding of the platform's
+ * default charset, so the resulting string may be longer or shorter than
+ * the byte array. For more decoding control, use
+ * { at link java.nio.charset.CharsetDecoder}. The behavior is not specified
+ * if the decoder encounters invalid characters; this implementation throws
+ * an Error.
+ *
+ * @param data byte array to copy
+ * @param offset the offset to start at
+ * @param count the number of characters in the array to use
+ * @throws NullPointerException if data is null
+ * @throws IndexOutOfBoundsException if offset or count is incorrect
+ * @throws Error if the decoding fails
+ * @see #String(byte[], int, int, String)
+ * @since 1.1
+ */
public String (byte[] byteArray, int offset, int count)
{
try
@@ -144,61 +329,153 @@
}
}
- public String (byte[] byteArray, String enc)
- throws UnsupportedEncodingException
- {
- this (byteArray, 0, byteArray.length, enc);
- }
-
- public String (byte[] byteArray, int offset, int count, String enc)
- throws UnsupportedEncodingException
- {
- init (byteArray, offset, count, enc);
- }
-
- public static String copyValueOf(char[] data)
- {
- return copyValueOf (data, 0, data.length);
- }
-
- public static String copyValueOf(char[] data, int offset, int count)
+ /**
+ * Creates a new String using the byte array. Uses the encoding of the
+ * platform's default charset, so the resulting string may be longer or
+ * shorter than the byte array. For more decoding control, use
+ * { at link java.nio.charset.CharsetDecoder}. The behavior is not specified
+ * if the decoder encounters invalid characters; this implementation throws
+ * an Error.
+ *
+ * @param data byte array to copy
+ * @throws NullPointerException if data is null
+ * @throws Error if the decoding fails
+ * @see #String(byte[], int, int)
+ * @see #String(byte[], int, int, String)
+ * @since 1.1
+ */
+ public String (byte[] byteArray)
{
- String r = new String ();
- r.init(data, offset, count, false);
- return r;
+ this (byteArray, 0, byteArray.length);
}
- /** @deprecated */
- public String (byte[] ascii, int hibyte)
+ /**
+ * Creates a new String using the character sequence represented by
+ * the StringBuffer. Subsequent changes to buf do not affect the String.
+ *
+ * @param buffer StringBuffer to copy
+ * @throws NullPointerException if buffer is null
+ */
+ public String (StringBuffer buffer)
{
- init(ascii, hibyte, 0, ascii.length);
+ synchronized (buffer)
+ {
+ buffer.shared = true;
+ init (buffer.value, 0, buffer.count, true);
+ }
}
- /** @deprecated */
- public String (byte[] ascii, int hibyte, int offset, int count)
+ /**
+ * Special constructor which can share an array when safe to do so.
+ *
+ * @param data the characters to copy
+ * @param offset the location to start from
+ * @param count the number of characters to use
+ * @param dont_copy true if the array is trusted, and need not be copied
+ * @throws NullPointerException if chars is null
+ * @throws StringIndexOutOfBoundsException if bounds check fails
+ */
+ String (char[] data, int offset, int count, boolean dont_copy)
{
- init(ascii, hibyte, offset, count);
+ init(data, offset, count, dont_copy);
}
- public String toString ()
+ // This is used by gnu.gcj.runtime.StringBuffer, so it must have
+ // package-private protection. It is accessed via CNI and so avoids
+ // ordinary protection mechanisms.
+ String (gnu.gcj.runtime.StringBuffer buffer)
{
- return this;
+ // No need to synchronize or mark the buffer, since we know it is
+ // only used once.
+ init (buffer.value, 0, buffer.count, true);
}
- public native boolean equals (Object anObject);
-
- public native int hashCode ();
-
- public int length ()
+ /**
+ * Returns the number of characters contained in this String.
+ *
+ * @return the length of this String
+ */
+ public int length()
{
return count;
}
+ /**
+ * Returns the character located at the specified index within this String.
+ *
+ * @param index position of character to return (base 0)
+ * @return character located at position index
+ * @throws IndexOutOfBoundsException if index < 0 || index >= length()
+ * (while unspecified, this is a StringIndexOutOfBoundsException)
+ */
public native char charAt (int index);
+ /**
+ * Copies characters from this String starting at a specified start index,
+ * ending at a specified stop index, to a character array starting at
+ * a specified destination begin index.
+ *
+ * @param srcBegin index to begin copying characters from this String
+ * @param srcEnd index after the last character to be copied from this String
+ * @param dst character array which this String is copied into
+ * @param dstBegin index to start writing characters into dst
+ * @throws NullPointerException if dst is null
+ * @throws IndexOutOfBoundsException if any indices are out of bounds
+ * (while unspecified, source problems cause a
+ * StringIndexOutOfBoundsException, and dst problems cause an
+ * ArrayIndexOutOfBoundsException)
+ */
public native void getChars (int srcBegin, int srcEnd,
char[] dst, int dstBegin);
+ /**
+ * Copies the low byte of each character from this String starting at a
+ * specified start index, ending at a specified stop index, to a byte array
+ * starting at a specified destination begin index.
+ *
+ * @param srcBegin index to being copying characters from this String
+ * @param srcEnd index after the last character to be copied from this String
+ * @param dst byte array which each low byte of this String is copied into
+ * @param dstBegin index to start writing characters into dst
+ * @throws NullPointerException if dst is null and copy length is non-zero
+ * @throws IndexOutOfBoundsException if any indices are out of bounds
+ * (while unspecified, source problems cause a
+ * StringIndexOutOfBoundsException, and dst problems cause an
+ * ArrayIndexOutOfBoundsException)
+ * @see #getBytes()
+ * @see #getBytes(String)
+ * @deprecated use { at link #getBytes()}, which uses a char to byte encoder
+ */
+ public native void getBytes (int srcBegin, int srcEnd,
+ byte[] dst, int dstBegin);
+
+ /**
+ * Converts the Unicode characters in this String to a byte array. Uses the
+ * specified encoding method, so the result may be longer or shorter than
+ * the String. For more encoding control, use
+ * { at link java.nio.charset.CharsetEncoder}, and for valid character sets,
+ * see { at link java.nio.charset.Charset}. The behavior is not specified if
+ * the encoder encounters a problem; this implementation returns null.
+ *
+ * @param enc encoding name
+ * @return the resulting byte array, or null on a problem
+ * @throws NullPointerException if enc is null
+ * @throws UnsupportedEncodingException if encoding is not supported
+ * @since 1.1
+ */
+ public native byte[] getBytes (String enc)
+ throws UnsupportedEncodingException;
+
+ /**
+ * Converts the Unicode characters in this String to a byte array. Uses the
+ * encoding of the platform's default charset, so the result may be longer
+ * or shorter than the String. For more encoding control, use
+ * { at link java.nio.charset.CharsetEncoder}. The behavior is not specified if
+ * the encoder encounters a problem; this implementation returns null.
+ *
+ * @return the resulting byte array, or null on a problem
+ * @since 1.1
+ */
public byte[] getBytes ()
{
try
@@ -222,84 +499,269 @@
}
}
- public native byte[] getBytes (String enc)
- throws UnsupportedEncodingException;
-
- /** @deprecated */
- public native void getBytes (int srcBegin, int srcEnd,
- byte[] dst, int dstBegin);
-
- public native char[] toCharArray ();
+ /**
+ * Predicate which compares anObject to this. This is true only for Strings
+ * with the same character sequence.
+ *
+ * @param anObject the object to compare
+ * @return true if anObject is semantically equal to this
+ * @see #compareTo(String)
+ * @see #equalsIgnoreCase(String)
+ */
+ public native boolean equals (Object anObject);
+ /**
+ * Compares a String to this String, ignoring case. This does not handle
+ * multi-character capitalization exceptions; instead the comparison is
+ * made on a character-by-character basis, and is true if:<br><ul>
+ * <li><code>c1 == c2</code></li>
+ * <li><code>Character.toUpperCase(c1)
+ * == Character.toUpperCase(c2)</code></li>
+ * <li><code>Character.toLowerCase(c1)
+ * == Character.toLowerCase(c2)</code></li>
+ * </ul>
+ *
+ * @param anotherString String to compare to this String
+ * @return true if anotherString is equal, ignoring case
+ * @see #equals(Object)
+ * @see Character#toUpperCase(char)
+ * @see Character#toLowerCase(char)
+ */
public native boolean equalsIgnoreCase (String anotherString);
+ /**
+ * Compares this String and another String (case sensitive,
+ * lexicographically). The result is less than 0 if this string sorts
+ * before the other, 0 if they are equal, and greater than 0 otherwise.
+ * After any common starting sequence is skipped, the result is
+ * <code>this.charAt(k) - anotherString.charAt(k)</code> if both strings
+ * have characters remaining, or
+ * <code>this.length() - anotherString.length()</code> if one string is
+ * a subsequence of the other.
+ *
+ * @param anotherString the String to compare against
+ * @return the comparison
+ * @throws NullPointerException if anotherString is null
+ */
public native int compareTo (String anotherString);
- public int compareTo (Object obj)
+ /**
+ * Behaves like <code>compareTo(java.lang.String)</code> unless the Object
+ * is not a <code>String</code>. Then it throws a
+ * <code>ClassCastException</code>.
+ *
+ * @param o the object to compare against
+ * @return the comparison
+ * @throws NullPointerException if o is null
+ * @throws ClassCastException if o is not a <code>String</code>
+ * @since 1.2
+ */
+ public int compareTo(Object o)
{
- return compareTo ((String)obj);
+ return compareTo((String) o);
}
-
+
+ /**
+ * Compares this String and another String (case insensitive). This
+ * comparison is <em>similar</em> to equalsIgnoreCase, in that it ignores
+ * locale and multi-characater capitalization, and compares characters
+ * after performing
+ * <code>Character.toLowerCase(Character.toUpperCase(c))</code> on each
+ * character of the string. This is unsatisfactory for locale-based
+ * comparison, in which case you should use { at link java.text.Collator}.
+ *
+ * @param s the string to compare against
+ * @return the comparison
+ * @see Collator#compare(String, String)
+ * @since 1.2
+ */
public int compareToIgnoreCase (String str)
{
return this.toUpperCase().toLowerCase().compareTo(
str.toUpperCase().toLowerCase());
}
+ /**
+ * Predicate which determines if this String matches another String
+ * starting at a specified offset for each String and continuing
+ * for a specified length. Indices out of bounds are harmless, and give
+ * a false result.
+ *
+ * @param toffset index to start comparison at for this String
+ * @param other String to compare region to this String
+ * @param oofset index to start comparison at for other
+ * @param len number of characters to compare
+ * @return true if regions match (case sensitive)
+ * @throws NullPointerException if other is null
+ */
public native boolean regionMatches (int toffset,
String other, int ooffset, int len);
+ /**
+ * Predicate which determines if this String matches another String
+ * starting at a specified offset for each String and continuing
+ * for a specified length, optionally ignoring case. Indices out of bounds
+ * are harmless, and give a false result. Case comparisons are based on
+ * <code>Character.toLowerCase()</code> and
+ * <code>Character.toUpperCase()</code>, not on multi-character
+ * capitalization expansions.
+ *
+ * @param ignoreCase true if case should be ignored in comparision
+ * @param toffset index to start comparison at for this String
+ * @param other String to compare region to this String
+ * @param oofset index to start comparison at for other
+ * @param len number of characters to compare
+ * @return true if regions match, false otherwise
+ * @throws NullPointerException if other is null
+ */
public native boolean regionMatches (boolean ignoreCase, int toffset,
String other, int ooffset, int len);
+ /**
+ * Predicate which determines if this String contains the given prefix,
+ * beginning comparison at toffset. The result is false if toffset is
+ * negative or greater than this.length(), otherwise it is the same as
+ * <code>this.subString(toffset).startsWith(prefix)</code>.
+ *
+ * @param prefix String to compare
+ * @param toffset offset for this String where comparison starts
+ * @return true if this String starts with prefix
+ * @throws NullPointerException if prefix is null
+ * @see #regionMatches(boolean, int, String, int, int)
+ */
+ public native boolean startsWith (String prefix, int toffset);
+
+ /**
+ * Predicate which determines if this String starts with a given prefix.
+ * If the prefix is an empty String, true is returned.
+ *
+ * @param prefex String to compare
+ * @return true if this String starts with the prefix
+ * @throws NullPointerException if prefix is null
+ * @see #startsWith(String, int)
+ */
public boolean startsWith (String prefix)
{
return startsWith (prefix, 0);
}
- public native boolean startsWith (String prefix, int toffset);
-
+ /**
+ * Predicate which determines if this String ends with a given suffix.
+ * If the suffix is an empty String, true is returned.
+ *
+ * @param suffix String to compare
+ * @return true if this String ends with the suffix
+ * @throws NullPointerException if suffix is null
+ * @see #regionMatches(boolean, int, String, int, int)
+ */
public boolean endsWith (String suffix)
{
return regionMatches (this.count - suffix.count, suffix, 0, suffix.count);
}
- // No such method specified in the doc, including JDK 1.2.
- // public boolean endsWith (String suffix, int toffset)
- // {
- // return regionMatches (toffset, suffix, 0, suffix.count);
- // }
-
- // The Language Specification, and the JDK 1.2 API docs say that
- // index and lastIndex take an int, while the Class Libraries
- // say they take a char. The former wins ...
+ /**
+ * Computes the hashcode for this String. This is done with int arithmetic,
+ * where ** represents exponentiation, by this formula:<br>
+ * <code>s[0]*31**(n-1) + s[1]*31**(n-2) + ... + s[n-1]</code>.
+ *
+ * @return hashcode value of this String
+ */
+ public native int hashCode ();
+ /**
+ * Finds the first instance of a character in this String.
+ *
+ * @param ch character to find
+ * @return location (base 0) of the character, or -1 if not found
+ */
public int indexOf (int ch)
{
return indexOf (ch, 0);
}
+ /**
+ * Finds the first instance of a character in this String, starting at
+ * a given index. If starting index is less than 0, the search
+ * starts at the beginning of this String. If the starting index
+ * is greater than the length of this String, -1 is returned.
+ *
+ * @param ch character to find
+ * @param fromIndex index to start the search
+ * @return location (base 0) of the character, or -1 if not found
+ */
public native int indexOf (int ch, int fromIndex);
- public int indexOf (String str)
+ /**
+ * Finds the last instance of a character in this String.
+ *
+ * @param ch character to find
+ * @return location (base 0) of the character, or -1 if not found
+ */
+ public int lastIndexOf (int ch)
{
- return indexOf (str, 0);
+ return lastIndexOf (ch, count - 1);
}
- public native int indexOf (String str, int fromIndex);
+ /**
+ * Finds the last instance of a character in this String, starting at
+ * a given index. If starting index is greater than the maximum valid
+ * index, then the search begins at the end of this String. If the
+ * starting index is less than zero, -1 is returned.
+ *
+ * @param ch character to find
+ * @param fromIndex index to start the search
+ * @return location (base 0) of the character, or -1 if not found
+ */
+ public native int lastIndexOf (int ch, int fromIndex);
- public int lastIndexOf (int ch)
+ /**
+ * Finds the first instance of a String in this String.
+ *
+ * @param str String to find
+ * @return location (base 0) of the String, or -1 if not found
+ * @throws NullPointerException if str is null
+ */
+ public int indexOf (String str)
{
- return lastIndexOf (ch, count - 1);
+ return indexOf (str, 0);
}
- public native int lastIndexOf (int ch, int fromIndex);
+ /**
+ * Finds the first instance of a String in this String, starting at
+ * a given index. If starting index is less than 0, the search
+ * starts at the beginning of this String. If the starting index
+ * is greater than the length of this String, -1 is returned.
+ *
+ * @param str String to find
+ * @param fromIndex index to start the search
+ * @return location (base 0) of the String, or -1 if not found
+ * @throws NullPointerException if str is null
+ */
+ public native int indexOf (String str, int fromIndex);
+ /**
+ * Finds the last instance of a String in this String.
+ *
+ * @param str String to find
+ * @return location (base 0) of the String, or -1 if not found
+ * @throws NullPointerException if str is null
+ */
public int lastIndexOf (String str)
{
return lastIndexOf (str, count - str.count);
}
+ /**
+ * Finds the last instance of a String in this String, starting at
+ * a given index. If starting index is greater than the maximum valid
+ * index, then the search begins at the end of this String. If the
+ * starting index is less than zero, -1 is returned.
+ *
+ * @param str String to find
+ * @param fromIndex index to start the search
+ * @return location (base 0) of the String, or -1 if not found
+ * @throws NullPointerException if str is null
+ */
public int lastIndexOf (String str, int fromIndex)
{
if (fromIndex >= count)
@@ -315,19 +777,42 @@
/**
* Creates a substring of this String, starting at a specified index
+ * and ending at the end of this String.
+ *
+ * @param begin index to start substring (base 0)
+ * @return new String which is a substring of this String
+ * @throws IndexOutOfBoundsException if begin < 0 || begin > length()
+ * (while unspecified, this is a StringIndexOutOfBoundsException)
+ */
+ public String substring (int beginIndex)
+ {
+ return substring (beginIndex, count);
+ }
+
+ /**
+ * Creates a substring of this String, starting at a specified index
* and ending at one character before a specified index.
- * <p>
- * To implement <code>CharSequence</code>.
- * Calls <code>substring(beginIndex, endIndex)</code>.
- *
- * @param beginIndex index to start substring (base 0)
- * @param endIndex index after the last character to be
- * copied into the substring
- *
+ *
+ * @param begin index to start substring (inclusive, base 0)
+ * @param end index to end at (exclusive)
* @return new String which is a substring of this String
+ * @throws IndexOutOfBoundsException if begin < 0 || end > length()
+ * || begin > end (while unspecified, this is a
+ * StringIndexOutOfBoundsException)
+ */
+ public native String substring (int beginIndex, int endIndex);
+
+ /**
+ * Creates a substring of this String, starting at a specified index
+ * and ending at one character before a specified index. This behaves like
+ * <code>substring(beginIndex, endIndex)</code>.
*
- * @exception StringIndexOutOfBoundsException
- * if (beginIndex < 0 || endIndex > this.length() || beginIndex > endIndex)
+ * @param beginIndex index to start substring (inclusive, base 0)
+ * @param endIndex index to end at (exclusive)
+ * @return new String which is a substring of this String
+ * @throws IndexOutOfBoundsException if begin < 0 || end > length()
+ * || begin > end
+ * @since 1.4
*/
public CharSequence subSequence(int beginIndex, int endIndex)
throws IndexOutOfBoundsException
@@ -335,20 +820,48 @@
return substring(beginIndex, endIndex);
}
- public String substring (int beginIndex)
- {
- return substring (beginIndex, count);
- }
-
- public native String substring (int beginIndex, int endIndex);
-
+ /**
+ * Concatenates a String to this String. This results in a new string unless
+ * one of the two originals is "".
+ *
+ * @param str String to append to this String
+ * @return newly concatenated String
+ * @throws NullPointerException if str is null
+ */
public native String concat (String str);
+ /**
+ * Replaces every instance of a character in this String with a new
+ * character. If no replacements occur, this is returned.
+ *
+ * @param oldChar the old character to replace
+ * @param newChar the new character
+ * @return new String with all instances of oldChar replaced with newChar
+ */
public native String replace (char oldChar, char newChar);
+ /**
+ * Lowercases this String according to a particular locale. This uses
+ * Unicode's special case mappings, as applied to the given Locale, so the
+ * resulting string may be a different length.
+ *
+ * @param loc locale to use
+ * @return new lowercased String, or this if no characters were lowercased
+ * @throws NullPointerException if loc is null
+ * @see #toUpperCase(Locale)
+ * @since 1.1
+ */
public native String toLowerCase (Locale locale);
- public native String toUpperCase (Locale locale);
+ /**
+ * Lowercases this String. This uses Unicode's special case mappings, as
+ * applied to the platform's default Locale, so the resulting string may
+ * be a different length.
+ *
+ * @return new lowercased String, or this if no characters were lowercased
+ * @see #toLowerCase(Locale)
+ * @see #toUpperCase()
+ */
public String toLowerCase ()
{
// The JDK is a bit confused about what to do here. If we pass in
@@ -358,6 +871,28 @@
return toLowerCase (null);
}
+ /**
+ * Uppercases this String according to a particular locale. This uses
+ * Unicode's special case mappings, as applied to the given Locale, so the
+ * resulting string may be a different length.
+ *
+ * @param loc locale to use
+ * @return new uppercased String, or this if no characters were uppercased
+ * @throws NullPointerException if loc is null
+ * @see #toLowerCase(Locale)
+ * @since 1.1
+ */
+ public native String toUpperCase (Locale locale);
+
+ /**
+ * Uppercases this String. This uses Unicode's special case mappings, as
+ * applied to the platform's default Locale, so the resulting string may
+ * be a different length.
+ *
+ * @return new uppercased String, or this if no characters were uppercased
+ * @see #toUpperCase(Locale)
+ * @see #toLowerCase()
+ */
public String toUpperCase ()
{
// The JDK is a bit confused about what to do here. If we pass in
@@ -367,45 +902,191 @@
return toUpperCase (null);
}
+ /**
+ * Trims all characters less than or equal to <code>'\u0020'</code>
+ * (<code>' '</code>) from the beginning and end of this String. This
+ * includes many, but not all, ASCII control characters, and all
+ * { at link Character#whitespace(char)}.
+ *
+ * @return new trimmed String, or this if nothing trimmed
+ */
public native String trim ();
+ /**
+ * Returns this, as it is already a String!
+ *
+ * @return this
+ */
+ public String toString ()
+ {
+ return this;
+ }
+
+ /**
+ * Copies the contents of this String into a character array. Subsequent
+ * changes to the array do not affect the String.
+ *
+ * @return character array copying the String
+ */
+ public native char[] toCharArray ();
+
+ /**
+ * Returns a String representation of an Object. This is "null" if the
+ * object is null, otherwise it is <code>obj.toString()</code> (which
+ * can be null).
+ *
+ * @param obj the Object
+ * @return the string conversion of obj
+ */
public static String valueOf (Object obj)
{
return obj == null ? "null" : obj.toString();
}
+ /**
+ * Returns a String representation of a character array. Subsequent
+ * changes to the array do not affect the String.
+ *
+ * @param data the character array
+ * @return a String containing the same character sequence as data
+ * @throws NullPointerException if data is null
+ * @see #valueOf(char[], int, int)
+ * @see #String(char[])
+ */
public static String valueOf (char[] data)
{
return valueOf (data, 0, data.length);
}
+ /**
+ * Returns a String representing the character sequence of the char array,
+ * starting at the specified offset, and copying chars up to the specified
+ * count. Subsequent changes to the array do not affect the String.
+ *
+ * @param data character array
+ * @param offset position (base 0) to start copying out of data
+ * @param count the number of characters from data to copy
+ * @return String containing the chars from data[offset..offset+count]
+ * @throws NullPointerException if data is null
+ * @throws IndexOutOfBoundsException if (offset < 0 || count < 0
+ * || offset + count > data.length)
+ * (while unspecified, this is a StringIndexOutOfBoundsException)
+ * @see #String(char[], int, int)
+ */
public static native String valueOf (char[] data, int offset, int count);
+ /**
+ * Returns a String representing the character sequence of the char array,
+ * starting at the specified offset, and copying chars up to the specified
+ * count. Subsequent changes to the array do not affect the String.
+ *
+ * @param data character array
+ * @param offset position (base 0) to start copying out of data
+ * @param count the number of characters from data to copy
+ * @return String containing the chars from data[offset..offset+count]
+ * @throws NullPointerException if data is null
+ * @throws IndexOutOfBoundsException if (offset < 0 || count < 0
+ * || offset + count > data.length)
+ * (while unspecified, this is a StringIndexOutOfBoundsException)
+ * @see #String(char[], int, int)
+ */
+ public static String copyValueOf(char[] data, int offset, int count)
+ {
+ String r = new String ();
+ r.init(data, offset, count, false);
+ return r;
+ }
+
+ /**
+ * Returns a String representation of a character array. Subsequent
+ * changes to the array do not affect the String.
+ *
+ * @param data the character array
+ * @return a String containing the same character sequence as data
+ * @throws NullPointerException if data is null
+ * @see #copyValueOf(char[], int, int)
+ * @see #String(char[])
+ */
+ public static String copyValueOf(char[] data)
+ {
+ return copyValueOf (data, 0, data.length);
+ }
+
+ /**
+ * Returns a String representing a boolean.
+ *
+ * @param b the boolean
+ * @return "true" if b is true, else "false"
+ */
public static String valueOf (boolean b)
{
return b ? "true" : "false";
}
+ /**
+ * Returns a String representing a character.
+ *
+ * @param c the character
+ * @return String containing the single character c
+ */
public static native String valueOf (char c);
+ /**
+ * Returns a String representing an integer.
+ *
+ * @param i the integer
+ * @return String containing the integer in base 10
+ * @see Integer#toString(int)
+ */
public static native String valueOf (int i);
+ /**
+ * Returns a String representing a long.
+ *
+ * @param l the long
+ * @return String containing the long in base 10
+ * @see Long#toString(long)
+ */
public static String valueOf (long l)
{
return Long.toString(l);
}
+ /**
+ * Returns a String representing a float.
+ *
+ * @param f the float
+ * @return String containing the float
+ * @see Float#toString(float)
+ */
public static String valueOf (float f)
{
return Float.toString(f);
}
+ /**
+ * Returns a String representing a double.
+ *
+ * @param d the double
+ * @return String containing the double
+ * @see Double#toString(double)
+ */
public static String valueOf (double d)
{
return Double.toString(d);
}
+ /**
+ * Fetches this String from the intern hashtable. If two Strings are
+ * considered equal, by the equals() method, then intern() will return the
+ * same String instance. ie. if (s1.equals(s2)) then
+ * (s1.intern() == s2.intern()). All string literals and string-valued
+ * constant expressions are already interned.
+ *
+ * @return the interned String
+ */
public native String intern ();
+
private native void init ();
private native void init (char[] chars, int offset, int count,