- 0001
/* - 0002
* @(#)String.java 1.204 06/06/09 - 0003 *
- 0004 * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
- 0005 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
- 0006
*/ - 0007
- 0008package java.lang;
- 0009
- 0010import java.io.ObjectStreamClass;
- 0011import java.io.ObjectStreamField;
- 0012import java.io.UnsupportedEncodingException;
- 0013import java.nio.charset.Charset;
- 0014import java.util.ArrayList;
- 0015import java.util.Arrays;
- 0016import java.util.Comparator;
- 0017import java.util.Formatter;
- 0018import java.util.Locale;
- 0019import java.util.regex.Matcher;
- 0020import java.util.regex.Pattern;
- 0021import java.util.regex.PatternSyntaxException;
- 0022
- 0023
- 0024/**
- 0025 * The <code>String</code> class represents character strings. All
- 0026 * string literals in Java programs, such as <code>"abc"</code>, are
- 0027 * implemented as instances of this class.
- 0028 * <p>
- 0029 * Strings are constant; their values cannot be changed after they
- 0030 * are created. String buffers support mutable strings.
- 0031 * Because String objects are immutable they can be shared. For example:
- 0032 * <p><blockquote><pre>
- 0033 * String str = "abc";
- 0034 * </pre></blockquote><p>
- 0035 * is equivalent to:
- 0036 * <p><blockquote><pre>
- 0037 * char data[] = {'a', 'b', 'c'};
- 0038 * String str = new String(data);
- 0039 * </pre></blockquote><p>
- 0040 * Here are some more examples of how strings can be used:
- 0041 * <p><blockquote><pre>
- 0042 * System.out.println("abc");
- 0043 * String cde = "cde";
- 0044 * System.out.println("abc" + cde);
- 0045 * String c = "abc".substring(2,3);
- 0046 * String d = cde.substring(1, 2);
- 0047 * </pre></blockquote>
- 0048 * <p>
- 0049 * The class <code>String</code> includes methods for examining
- 0050 * individual characters of the sequence, for comparing strings, for
- 0051 * searching strings, for extracting substrings, and for creating a
- 0052 * copy of a string with all characters translated to uppercase or to
- 0053 * lowercase. Case mapping is based on the Unicode Standard version
- 0054 * specified by the {@link java.lang.Character Character} class.
- 0055 * <p>
- 0056 * The Java language provides special support for the string
- 0057 * concatenation operator ( + ), and for conversion of
- 0058 * other objects to strings. String concatenation is implemented
- 0059 * through the <code>StringBuilder</code>(or <code>StringBuffer</code>)
- 0060 * class and its <code>append</code> method.
- 0061 * String conversions are implemented through the method
- 0062 * <code>toString</code>, defined by <code>Object</code> and
- 0063 * inherited by all classes in Java. For additional information on
- 0064 * string concatenation and conversion, see Gosling, Joy, and Steele,
- 0065 * <i>The Java Language Specification</i>.
- 0066 *
- 0067 * <p> Unless otherwise noted, passing a <tt>null</tt> argument to a constructor
- 0068 * or method in this class will cause a {@link NullPointerException} to be
- 0069 * thrown.
- 0070 *
- 0071 * <p>A <code>String</code> represents a string in the UTF-16 format
- 0072 * in which <em>supplementary characters</em> are represented by <em>surrogate
- 0073 * pairs</em> (see the section <a href="Character.html#unicode">Unicode
- 0074 * Character Representations</a> in the <code>Character</code> class for
- 0075 * more information).
- 0076 * Index values refer to <code>char</code> code units, so a supplementary
- 0077 * character uses two positions in a <code>String</code>.
- 0078 * <p>The <code>String</code> class provides methods for dealing with
- 0079 * Unicode code points (i.e., characters), in addition to those for
- 0080 * dealing with Unicode code units (i.e., <code>char</code> values).
- 0081 *
- 0082 * @author Lee Boynton
- 0083 * @author Arthur van Hoff
- 0084 * @version 1.204, 06/09/06
- 0085 * @see java.lang.Object#toString()
- 0086 * @see java.lang.StringBuffer
- 0087 * @see java.lang.StringBuilder
- 0088 * @see java.nio.charset.Charset
- 0089 * @since JDK1.0
- 0090 */
- 0091
- 0092public final class String
- 0093 implements java.io.Serializable, Comparable<String>, CharSequence
- 0094{
- 0095 /** The value is used for character storage. */
- 0096 private final char value[];
- 0097
- 0098 /** The offset is the first index of the storage that is used. */
- 0099 private final int offset;
- 0100
- 0101 /** The count is the number of characters in the String. */
- 0102 private final int count;
- 0103
- 0104 /** Cache the hash code for the string */
- 0105 private int hash; // Default to 0
- 0106
- 0107 /** use serialVersionUID from JDK 1.0.2 for interoperability */
- 0108 private static final long serialVersionUID = -6849794470754667710L;
- 0109
- 0110 /**
- 0111 * Class String is special cased within the Serialization Stream Protocol.
- 0112 *
- 0113 * A String instance is written initially into an ObjectOutputStream in the
- 0114 * following format:
- 0115 * <pre>
- 0116 * <code>TC_STRING</code> (utf String)
- 0117 * </pre>
- 0118 * The String is written by method <code>DataOutput.writeUTF</code>.
- 0119 * A new handle is generated to refer to all future references to the
- 0120 * string instance within the stream.
- 0121 */
- 0122 private static final ObjectStreamField[] serialPersistentFields =
- 0123 new ObjectStreamField[0];
- 0124
- 0125 /**
- 0126 * Initializes a newly created {@code String} object so that it represents
- 0127 * an empty character sequence. Note that use of this constructor is
- 0128 * unnecessary since Strings are immutable.
- 0129 */
- 0130 public String() {
- 0131 this.offset = 0;
- 0132 this.count = 0;
- 0133 this.value = new char[0];
- 0134 }
- 0135
- 0136 /**
- 0137 * Initializes a newly created {@code String} object so that it represents
- 0138 * the same sequence of characters as the argument; in other words, the
- 0139 * newly created string is a copy of the argument string. Unless an
- 0140 * explicit copy of {@code original} is needed, use of this constructor is
- 0141 * unnecessary since Strings are immutable.
- 0142 *
- 0143 * @param original
- 0144 * A {@code String}
- 0145 */
- 0146 public String(String original) {
- 0147 int size = original.count;
- 0148 char[] originalValue = original.value;
- 0149 char[] v;
- 0150 if (originalValue.length > size) {
- 0151 // The array representing the String is bigger than the new
- 0152 // String itself. Perhaps this constructor is being called
- 0153 // in order to trim the baggage, so make a copy of the array.
- 0154 int off = original.offset;
- 0155 v = Arrays.copyOfRange(originalValue, off, off+size);
- 0156 } else {
- 0157 // The array representing the String is the same
- 0158 // size as the String, so no point in making a copy.
- 0159 v = originalValue;
- 0160 }
- 0161 this.offset = 0;
- 0162 this.count = size;
- 0163 this.value = v;
- 0164 }
- 0165
- 0166 /**
- 0167 * Allocates a new {@code String} so that it represents the sequence of
- 0168 * characters currently contained in the character array argument. The
- 0169 * contents of the character array are copied; subsequent modification of
- 0170 * the character array does not affect the newly created string.
- 0171 *
- 0172 * @param value
- 0173 * The initial value of the string
- 0174 */
- 0175 public String(char value[]) {
- 0176 int size = value.length;
- 0177 this.offset = 0;
- 0178 this.count = size;
- 0179 this.value = Arrays.copyOf(value, size);
- 0180 }
- 0181
- 0182 /**
- 0183 * Allocates a new {@code String} that contains characters from a subarray
- 0184 * of the character array argument. The {@code offset} argument is the
- 0185 * index of the first character of the subarray and the {@code count}
- 0186 * argument specifies the length of the subarray. The contents of the
- 0187 * subarray are copied; subsequent modification of the character array does
- 0188 * not affect the newly created string.
- 0189 *
- 0190 * @param value
- 0191 * Array that is the source of characters
- 0192 *
- 0193 * @param offset
- 0194 * The initial offset
- 0195 *
- 0196 * @param count
- 0197 * The length
- 0198 *
- 0199 * @throws IndexOutOfBoundsException
- 0200 * If the {@code offset} and {@code count} arguments index
- 0201 * characters outside the bounds of the {@code value} array
- 0202 */
- 0203 public String(char value[], int offset, int count) {
- 0204 if (offset < 0) {
- 0205 throw new StringIndexOutOfBoundsException(offset);
- 0206 }
- 0207 if (count < 0) {
- 0208 throw new StringIndexOutOfBoundsException(count);
- 0209 }
- 0210 // Note: offset or count might be near -1>>>1.
- 0211 if (offset > value.length - count) {
- 0212 throw new StringIndexOutOfBoundsException(offset + count);
- 0213 }
- 0214 this.offset = 0;
- 0215 this.count = count;
- 0216 this.value = Arrays.copyOfRange(value, offset, offset+count);
- 0217 }
- 0218
- 0219 /**
- 0220 * Allocates a new {@code String} that contains characters from a subarray
- 0221 * of the Unicode code point array argument. The {@code offset} argument
- 0222 * is the index of the first code point of the subarray and the
- 0223 * {@code count} argument specifies the length of the subarray. The
- 0224 * contents of the subarray are converted to {@code char}s; subsequent
- 0225 * modification of the {@code int} array does not affect the newly created
- 0226 * string.
- 0227 *
- 0228 * @param codePoints
- 0229 * Array that is the source of Unicode code points
- 0230 *
- 0231 * @param offset
- 0232 * The initial offset
- 0233 *
- 0234 * @param count
- 0235 * The length
- 0236 *
- 0237 * @throws IllegalArgumentException
- 0238 * If any invalid Unicode code point is found in {@code
- 0239 * codePoints}
- 0240 *
- 0241 * @throws IndexOutOfBoundsException
- 0242 * If the {@code offset} and {@code count} arguments index
- 0243 * characters outside the bounds of the {@code codePoints} array
- 0244 *
- 0245 * @since 1.5
- 0246 */
- 0247 public String(int[] codePoints, int offset, int count) {
- 0248 if (offset < 0) {
- 0249 throw new StringIndexOutOfBoundsException(offset);
- 0250 }
- 0251 if (count < 0) {
- 0252 throw new StringIndexOutOfBoundsException(count);
- 0253 }
- 0254 // Note: offset or count might be near -1>>>1.
- 0255 if (offset > codePoints.length - count) {
- 0256 throw new StringIndexOutOfBoundsException(offset + count);
- 0257 }
- 0258
- 0259 int expansion = 0;
- 0260 int margin = 1;
- 0261 char[] v = new char[count + margin];
- 0262 int x = offset;
- 0263 int j = 0;
- 0264 for (int i = 0; i < count; i++) {
- 0265 int c = codePoints[x++];
- 0266 if (c < 0) {
- 0267 throw new IllegalArgumentException();
- 0268 }
- 0269 if (margin <= 0 && (j+1) >= v.length) {
- 0270 if (expansion == 0) {
- 0271 expansion = (((-margin + 1) * count) << 10) / i;
- 0272 expansion >>= 10;
- 0273 if (expansion <= 0) {
- 0274 expansion = 1;
- 0275 }
- 0276 } else {
- 0277 expansion *= 2;
- 0278 }
- 0279 int newLen = Math.min(v.length+expansion, count*2);
- 0280 margin = (newLen - v.length) - (count - i);
- 0281 v = Arrays.copyOf(v, newLen);
- 0282 }
- 0283 if (c < Character.MIN_SUPPLEMENTARY_CODE_POINT) {
- 0284 v[j++] = (char) c;
- 0285 } else if (c <= Character.MAX_CODE_POINT) {
- 0286 Character.toSurrogates(c, v, j);
- 0287 j += 2;
- 0288 margin--;
- 0289 } else {
- 0290 throw new IllegalArgumentException();
- 0291 }
- 0292 }
- 0293 this.offset = 0;
- 0294 this.value = v;
- 0295 this.count = j;
- 0296 }
- 0297
- 0298 /**
- 0299 * Allocates a new {@code String} constructed from a subarray of an array
- 0300 * of 8-bit integer values.
- 0301 *
- 0302 * <p> The {@code offset} argument is the index of the first byte of the
- 0303 * subarray, and the {@code count} argument specifies the length of the
- 0304 * subarray.
- 0305 *
- 0306 * <p> Each {@code byte} in the subarray is converted to a {@code char} as
- 0307 * specified in the method above.
- 0308 *
- 0309 * @deprecated This method does not properly convert bytes into characters.
- 0310 * As of JDK 1.1, the preferred way to do this is via the
- 0311 * {@code String} constructors that take a {@link
- 0312 * java.nio.charset.Charset}, charset name, or that use the platform's
- 0313 * default charset.
- 0314 *
- 0315 * @param ascii
- 0316 * The bytes to be converted to characters
- 0317 *
- 0318 * @param hibyte
- 0319 * The top 8 bits of each 16-bit Unicode code unit
- 0320 *
- 0321 * @param offset
- 0322 * The initial offset
- 0323 * @param count
- 0324 * The length
- 0325 *
- 0326 * @throws IndexOutOfBoundsException
- 0327 * If the {@code offset} or {@code count} argument is invalid
- 0328 *
- 0329 * @see #String(byte[], int)
- 0330 * @see #String(byte[], int, int, java.lang.String)
- 0331 * @see #String(byte[], int, int, java.nio.charset.Charset)
- 0332 * @see #String(byte[], int, int)
- 0333 * @see #String(byte[], java.lang.String)
- 0334 * @see #String(byte[], java.nio.charset.Charset)
- 0335 * @see #String(byte[])
- 0336 */
- 0337 @Deprecated
- 0338 public String(byte ascii[], int hibyte, int offset, int count) {
- 0339 checkBounds(ascii, offset, count);
- 0340 char value[] = new char[count];
- 0341
- 0342 if (hibyte == 0) {
- 0343 for (int i = count ; i-- > 0 ;) {
- 0344 value[i] = (char) (ascii[i + offset] & 0xff);
- 0345 }
- 0346 } else {
- 0347 hibyte <<= 8;
- 0348 for (int i = count ; i-- > 0 ;) {
- 0349 value[i] = (char) (hibyte | (ascii[i + offset] & 0xff));
- 0350 }
- 0351 }
- 0352 this.offset = 0;
- 0353 this.count = count;
- 0354 this.value = value;
- 0355 }
- 0356
- 0357 /**
- 0358 * Allocates a new {@code String} containing characters constructed from
- 0359 * an array of 8-bit integer values. Each character <i>c</i>in the
- 0360 * resulting string is constructed from the corresponding component
- 0361 * <i>b</i> in the byte array such that:
- 0362 *
- 0363 * <blockquote><pre>
- 0364 * <b><i>c</i></b> == (char)(((hibyte & 0xff) << 8)
- 0365 * | (<b><i>b</i></b> & 0xff))
- 0366 * </pre></blockquote>
- 0367 *
- 0368 * @deprecated This method does not properly convert bytes into
- 0369 * characters. As of JDK 1.1, the preferred way to do this is via the
- 0370 * {@code String} constructors that take a {@link
- 0371 * java.nio.charset.Charset}, charset name, or that use the platform's
- 0372 * default charset.
- 0373 *
- 0374 * @param ascii
- 0375 * The bytes to be converted to characters
- 0376 *
- 0377 * @param hibyte
- 0378 * The top 8 bits of each 16-bit Unicode code unit
- 0379 *
- 0380 * @see #String(byte[], int, int, java.lang.String)
- 0381 * @see #String(byte[], int, int, java.nio.charset.Charset)
- 0382 * @see #String(byte[], int, int)
- 0383 * @see #String(byte[], java.lang.String)
- 0384 * @see #String(byte[], java.nio.charset.Charset)
- 0385 * @see #String(byte[])
- 0386 */
- 0387 @Deprecated
- 0388 public String(byte ascii[], int hibyte) {
- 0389 this(ascii, hibyte, 0, ascii.length);
- 0390 }
- 0391
- 0392 /* Common private utility method used to bounds check the byte array
- 0393 * and requested offset & length values used by the String(byte[],..)
- 0394 * constructors.
- 0395 */
- 0396 private static void checkBounds(byte[] bytes, int offset, int length) {
- 0397 if (length < 0)
- 0398 throw new StringIndexOutOfBoundsException(length);
- 0399 if (offset < 0)
- 0400 throw new StringIndexOutOfBoundsException(offset);
- 0401 if (offset > bytes.length - length)
- 0402 throw new StringIndexOutOfBoundsException(offset + length);
- 0403 }
- 0404
- 0405 /**
- 0406 * Constructs a new {@code String} by decoding the specified subarray of
- 0407 * bytes using the specified charset. The length of the new {@code String}
- 0408 * is a function of the charset, and hence may not be equal to the length
- 0409 * of the subarray.
- 0410 *
- 0411 * <p> The behavior of this constructor when the given bytes are not valid
- 0412 * in the given charset is unspecified. The {@link
- 0413 * java.nio.charset.CharsetDecoder} class should be used when more control
- 0414 * over the decoding process is required.
- 0415 *
- 0416 * @param bytes
- 0417 * The bytes to be decoded into characters
- 0418 *
- 0419 * @param offset
- 0420 * The index of the first byte to decode
- 0421 *
- 0422 * @param length
- 0423 * The number of bytes to decode
- 0424
- 0425 * @param charsetName
- 0426 * The name of a supported {@linkplain java.nio.charset.Charset
- 0427 * charset}
- 0428 *
- 0429 * @throws UnsupportedEncodingException
- 0430 * If the named charset is not supported
- 0431 *
- 0432 * @throws IndexOutOfBoundsException
- 0433 * If the {@code offset} and {@code length} arguments index
- 0434 * characters outside the bounds of the {@code bytes} array
- 0435 *
- 0436 * @since JDK1.1
- 0437 */
- 0438 public String(byte bytes[], int offset, int length, String charsetName)
- 0439 throws UnsupportedEncodingException
- 0440 {
- 0441 if (charsetName == null)
- 0442 throw new NullPointerException("charsetName");
- 0443 checkBounds(bytes, offset, length);
- 0444 char[] v = StringCoding.decode(charsetName, bytes, offset, length);
- 0445 this.offset = 0;
- 0446 this.count = v.length;
- 0447 this.value = v;
- 0448 }
- 0449
- 0450 /**
- 0451 * Constructs a new {@code String} by decoding the specified subarray of
- 0452 * bytes using the specified {@linkplain java.nio.charset.Charset charset}.
- 0453 * The length of the new {@code String} is a function of the charset, and
- 0454 * hence may not be equal to the length of the subarray.
- 0455 *
- 0456 * <p> This method always replaces malformed-input and unmappable-character
- 0457 * sequences with this charset's default replacement string. The {@link
- 0458 * java.nio.charset.CharsetDecoder} class should be used when more control
- 0459 * over the decoding process is required.
- 0460 *
- 0461 * @param bytes
- 0462 * The bytes to be decoded into characters
- 0463 *
- 0464 * @param offset
- 0465 * The index of the first byte to decode
- 0466 *
- 0467 * @param length
- 0468 * The number of bytes to decode
- 0469 *
- 0470 * @param charset
- 0471 * The {@linkplain java.nio.charset.Charset charset} to be used to
- 0472 * decode the {@code bytes}
- 0473 *
- 0474 * @throws IndexOutOfBoundsException
- 0475 * If the {@code offset} and {@code length} arguments index
- 0476 * characters outside the bounds of the {@code bytes} array
- 0477 *
- 0478 * @since 1.6
- 0479 */
- 0480 public String(byte bytes[], int offset, int length, Charset charset) {
- 0481 if (charset == null)
- 0482 throw new NullPointerException("charset");
- 0483 checkBounds(bytes, offset, length);
- 0484 char[] v = StringCoding.decode(charset, bytes, offset, length);
- 0485 this.offset = 0;
- 0486 this.count = v.length;
- 0487 this.value = v;
- 0488 }
- 0489
- 0490 /**
- 0491 * Constructs a new {@code String} by decoding the specified array of bytes
- 0492 * using the specified {@linkplain java.nio.charset.Charset charset}. The
- 0493 * length of the new {@code String} is a function of the charset, and hence
- 0494 * may not be equal to the length of the byte array.
- 0495 *
- 0496 * <p> The behavior of this constructor when the given bytes are not valid
- 0497 * in the given charset is unspecified. The {@link
- 0498 * java.nio.charset.CharsetDecoder} class should be used when more control
- 0499 * over the decoding process is required.
- 0500 *
- 0501 * @param bytes
- 0502 * The bytes to be decoded into characters
- 0503 *
- 0504 * @param charsetName
- 0505 * The name of a supported {@linkplain java.nio.charset.Charset
- 0506 * charset}
- 0507 *
- 0508 * @throws UnsupportedEncodingException
- 0509 * If the named charset is not supported
- 0510 *
- 0511 * @since JDK1.1
- 0512 */
- 0513 public String(byte bytes[], String charsetName)
- 0514 throws UnsupportedEncodingException
- 0515 {
- 0516 this(bytes, 0, bytes.length, charsetName);
- 0517 }
- 0518
- 0519 /**
- 0520 * Constructs a new {@code String} by decoding the specified array of
- 0521 * bytes using the specified {@linkplain java.nio.charset.Charset charset}.
- 0522 * The length of the new {@code String} is a function of the charset, and
- 0523 * hence may not be equal to the length of the byte array.
- 0524 *
- 0525 * <p> This method always replaces malformed-input and unmappable-character
- 0526 * sequences with this charset's default replacement string. The {@link
- 0527 * java.nio.charset.CharsetDecoder} class should be used when more control
- 0528 * over the decoding process is required.
- 0529 *
- 0530 * @param bytes
- 0531 * The bytes to be decoded into characters
- 0532 *
- 0533 * @param charset
- 0534 * The {@linkplain java.nio.charset.Charset charset} to be used to
- 0535 * decode the {@code bytes}
- 0536 *
- 0537 * @since 1.6
- 0538 */
- 0539 public String(byte bytes[], Charset charset) {
- 0540 this(bytes, 0, bytes.length, charset);
- 0541 }
- 0542
- 0543 /**
- 0544 * Constructs a new {@code String} by decoding the specified subarray of
- 0545 * bytes using the platform's default charset. The length of the new
- 0546 * {@code String} is a function of the charset, and hence may not be equal
- 0547 * to the length of the subarray.
- 0548 *
- 0549 * <p> The behavior of this constructor when the given bytes are not valid
- 0550 * in the default charset is unspecified. The {@link
- 0551 * java.nio.charset.CharsetDecoder} class should be used when more control
- 0552 * over the decoding process is required.
- 0553 *
- 0554 * @param bytes
- 0555 * The bytes to be decoded into characters
- 0556 *
- 0557 * @param offset
- 0558 * The index of the first byte to decode
- 0559 *
- 0560 * @param length
- 0561 * The number of bytes to decode
- 0562 *
- 0563 * @throws IndexOutOfBoundsException
- 0564 * If the {@code offset} and the {@code length} arguments index
- 0565 * characters outside the bounds of the {@code bytes} array
- 0566 *
- 0567 * @since JDK1.1
- 0568 */
- 0569 public String(byte bytes[], int offset, int length) {
- 0570 checkBounds(bytes, offset, length);
- 0571 char[] v = StringCoding.decode(bytes, offset, length);
- 0572 this.offset = 0;
- 0573 this.count = v.length;
- 0574 this.value = v;
- 0575 }
- 0576
- 0577 /**
- 0578 * Constructs a new {@code String} by decoding the specified array of bytes
- 0579 * using the platform's default charset. The length of the new {@code
- 0580 * String} is a function of the charset, and hence may not be equal to the
- 0581 * length of the byte array.
- 0582 *
- 0583 * <p> The behavior of this constructor when the given bytes are not valid
- 0584 * in the default charset is unspecified. The {@link
- 0585 * java.nio.charset.CharsetDecoder} class should be used when more control
- 0586 * over the decoding process is required.
- 0587 *
- 0588 * @param bytes
- 0589 * The bytes to be decoded into characters
- 0590 *
- 0591 * @since JDK1.1
- 0592 */
- 0593 public String(byte bytes[]) {
- 0594 this(bytes, 0, bytes.length);
- 0595 }
- 0596
- 0597 /**
- 0598 * Allocates a new string that contains the sequence of characters
- 0599 * currently contained in the string buffer argument. The contents of the
- 0600 * string buffer are copied; subsequent modification of the string buffer
- 0601 * does not affect the newly created string.
- 0602 *
- 0603 * @param buffer
- 0604 * A {@code StringBuffer}
- 0605 */
- 0606 public String(StringBuffer buffer) {
- 0607 String result = buffer.toString();
- 0608 this.value = result.value;
- 0609 this.count = result.count;
- 0610 this.offset = result.offset;
- 0611 }
- 0612
- 0613 /**
- 0614 * Allocates a new string that contains the sequence of characters
- 0615 * currently contained in the string builder argument. The contents of the
- 0616 * string builder are copied; subsequent modification of the string builder
- 0617 * does not affect the newly created string.
- 0618 *
- 0619 * <p> This constructor is provided to ease migration to {@code
- 0620 * StringBuilder}. Obtaining a string from a string builder via the {@code
- 0621 * toString} method is likely to run faster and is generally preferred.
- 0622 *
- 0623 * @param builder
- 0624 * A {@code StringBuilder}
- 0625 *
- 0626 * @since 1.5
- 0627 */
- 0628 public String(StringBuilder builder) {
- 0629 String result = builder.toString();
- 0630 this.value = result.value;
- 0631 this.count = result.count;
- 0632 this.offset = result.offset;
- 0633 }
- 0634
- 0635
- 0636 // Package private constructor which shares value array for speed.
- 0637 String(int offset, int count, char value[]) {
- 0638 this.value = value;
- 0639 this.offset = offset;
- 0640 this.count = count;
- 0641 }
- 0642
- 0643 /**
- 0644 * Returns the length of this string.
- 0645 * The length is equal to the number of <a href="Character.html#unicode">Unicode
- 0646 * code units</a> in the string.
- 0647 *
- 0648 * @return the length of the sequence of characters represented by this
- 0649 * object.
- 0650 */
- 0651 public int length() {
- 0652 return count;
- 0653 }
- 0654
- 0655 /**
- 0656 * Returns <tt>true</tt> if, and only if, {@link #length()} is <tt>0</tt>.
- 0657 *
- 0658 * @return <tt>true</tt> if {@link #length()} is <tt>0</tt>, otherwise
- 0659 * <tt>false</tt>
- 0660 *
- 0661 * @since 1.6
- 0662 */
- 0663 public boolean isEmpty() {
- 0664 return count == 0;
- 0665 }
- 0666
- 0667 /**
- 0668 * Returns the <code>char</code> value at the
- 0669 * specified index. An index ranges from <code>0</code> to
- 0670 * <code>length() - 1</code>. The first <code>char</code> value of the sequence
- 0671 * is at index <code>0</code>, the next at index <code>1</code>,
- 0672 * and so on, as for array indexing.
- 0673 *
- 0674 * <p>If the <code>char</code> value specified by the index is a
- 0675 * <a href="Character.html#unicode">surrogate</a>, the surrogate
- 0676 * value is returned.
- 0677 *
- 0678 * @param index the index of the <code>char</code> value.
- 0679 * @return the <code>char</code> value at the specified index of this string.
- 0680 * The first <code>char</code> value is at index <code>0</code>.
- 0681 * @exception IndexOutOfBoundsException if the <code>index</code>
- 0682 * argument is negative or not less than the length of this
- 0683 * string.
- 0684 */
- 0685 public char charAt(int index) {
- 0686 if ((index < 0) || (index >= count)) {
- 0687 throw new StringIndexOutOfBoundsException(index);
- 0688 }
- 0689 return value[index + offset];
- 0690 }
- 0691
- 0692 /**
- 0693 * Returns the character (Unicode code point) at the specified
- 0694 * index. The index refers to <code>char</code> values
- 0695 * (Unicode code units) and ranges from <code>0</code> to
- 0696 * {@link #length()}<code> - 1</code>.
- 0697 *
- 0698 * <p> If the <code>char</code> value specified at the given index
- 0699 * is in the high-surrogate range, the following index is less
- 0700 * than the length of this <code>String</code>, and the
- 0701 * <code>char</code> value at the following index is in the
- 0702 * low-surrogate range, then the supplementary code point
- 0703 * corresponding to this surrogate pair is returned. Otherwise,
- 0704 * the <code>char</code> value at the given index is returned.
- 0705 *
- 0706 * @param index the index to the <code>char</code> values
- 0707 * @return the code point value of the character at the
- 0708 * <code>index</code>
- 0709 * @exception IndexOutOfBoundsException if the <code>index</code>
- 0710 * argument is negative or not less than the length of this
- 0711 * string.
- 0712 * @since 1.5
- 0713 */
- 0714 public int codePointAt(int index) {
- 0715 if ((index < 0) || (index >= count)) {
- 0716 throw new StringIndexOutOfBoundsException(index);
- 0717 }
- 0718 return Character.codePointAtImpl(value, offset + index, offset + count);
- 0719 }
- 0720
- 0721 /**
- 0722 * Returns the character (Unicode code point) before the specified
- 0723 * index. The index refers to <code>char</code> values
- 0724 * (Unicode code units) and ranges from <code>1</code> to {@link
- 0725 * CharSequence#length() length}.
- 0726 *
- 0727 * <p> If the <code>char</code> value at <code>(index - 1)</code>
- 0728 * is in the low-surrogate range, <code>(index - 2)</code> is not
- 0729 * negative, and the <code>char</code> value at <code>(index -
- 0730 * 2)</code> is in the high-surrogate range, then the
- 0731 * supplementary code point value of the surrogate pair is
- 0732 * returned. If the <code>char</code> value at <code>index -
- 0733 * 1</code> is an unpaired low-surrogate or a high-surrogate, the
- 0734 * surrogate value is returned.
- 0735 *
- 0736 * @param index the index following the code point that should be returned
- 0737 * @return the Unicode code point value before the given index.
- 0738 * @exception IndexOutOfBoundsException if the <code>index</code>
- 0739 * argument is less than 1 or greater than the length
- 0740 * of this string.
- 0741 * @since 1.5
- 0742 */
- 0743 public int codePointBefore(int index) {
- 0744 int i = index - 1;
- 0745 if ((i < 0) || (i >= count)) {
- 0746 throw new StringIndexOutOfBoundsException(index);
- 0747 }
- 0748 return Character.codePointBeforeImpl(value, offset + index, offset);
- 0749 }
- 0750
- 0751 /**
- 0752 * Returns the number of Unicode code points in the specified text
- 0753 * range of this <code>String</code>. The text range begins at the
- 0754 * specified <code>beginIndex</code> and extends to the
- 0755 * <code>char</code> at index <code>endIndex - 1</code>. Thus the
- 0756 * length (in <code>char</code>s) of the text range is
- 0757 * <code>endIndex-beginIndex</code>. Unpaired surrogates within
- 0758 * the text range count as one code point each.
- 0759 *
- 0760 * @param beginIndex the index to the first <code>char</code> of
- 0761 * the text range.
- 0762 * @param endIndex the index after the last <code>char</code> of
- 0763 * the text range.
- 0764 * @return the number of Unicode code points in the specified text
- 0765 * range
- 0766 * @exception IndexOutOfBoundsException if the
- 0767 * <code>beginIndex</code> is negative, or <code>endIndex</code>
- 0768 * is larger than the length of this <code>String</code>, or
- 0769 * <code>beginIndex</code> is larger than <code>endIndex</code>.
- 0770 * @since 1.5
- 0771 */
- 0772 public int codePointCount(int beginIndex, int endIndex) {
- 0773 if (beginIndex < 0 || endIndex > count || beginIndex > endIndex) {
- 0774 throw new IndexOutOfBoundsException();
- 0775 }
- 0776 return Character.codePointCountImpl(value, offset+beginIndex, endIndex-beginIndex);
- 0777 }
- 0778
- 0779 /**
- 0780 * Returns the index within this <code>String</code> that is
- 0781 * offset from the given <code>index</code> by
- 0782 * <code>codePointOffset</code> code points. Unpaired surrogates
- 0783 * within the text range given by <code>index</code> and
- 0784 * <code>codePointOffset</code> count as one code point each.
- 0785 *
- 0786 * @param index the index to be offset
- 0787 * @param codePointOffset the offset in code points
- 0788 * @return the index within this <code>String</code>
- 0789 * @exception IndexOutOfBoundsException if <code>index</code>
- 0790 * is negative or larger then the length of this
- 0791 * <code>String</code>, or if <code>codePointOffset</code> is positive
- 0792 * and the substring starting with <code>index</code> has fewer
- 0793 * than <code>codePointOffset</code> code points,
- 0794 * or if <code>codePointOffset</code> is negative and the substring
- 0795 * before <code>index</code> has fewer than the absolute value
- 0796 * of <code>codePointOffset</code> code points.
- 0797 * @since 1.5
- 0798 */
- 0799 public int offsetByCodePoints(int index, int codePointOffset) {
- 0800 if (index < 0 || index > count) {
- 0801 throw new IndexOutOfBoundsException();
- 0802 }
- 0803 return Character.offsetByCodePointsImpl(value, offset, count,
- 0804 offset+index, codePointOffset) - offset;
- 0805 }
- 0806
- 0807 /**
- 0808 * Copy characters from this string into dst starting at dstBegin.
- 0809 * This method doesn't perform any range checking.
- 0810 */
- 0811 void getChars(char dst[], int dstBegin) {
- 0812 System.arraycopy(value, offset, dst, dstBegin, count);
- 0813 }
- 0814
- 0815 /**
- 0816 * Copies characters from this string into the destination character
- 0817 * array.
- 0818 * <p>
- 0819 * The first character to be copied is at index <code>srcBegin</code>;
- 0820 * the last character to be copied is at index <code>srcEnd-1</code>
- 0821 * (thus the total number of characters to be copied is
- 0822 * <code>srcEnd-srcBegin</code>). The characters are copied into the
- 0823 * subarray of <code>dst</code> starting at index <code>dstBegin</code>
- 0824 * and ending at index:
- 0825 * <p><blockquote><pre>
- 0826 * dstbegin + (srcEnd-srcBegin) - 1
- 0827 * </pre></blockquote>
- 0828 *
- 0829 * @param srcBegin index of the first character in the string
- 0830 * to copy.
- 0831 * @param srcEnd index after the last character in the string
- 0832 * to copy.
- 0833 * @param dst the destination array.
- 0834 * @param dstBegin the start offset in the destination array.
- 0835 * @exception IndexOutOfBoundsException If any of the following
- 0836 * is true:
- 0837 * <ul><li><code>srcBegin</code> is negative.