11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.lang;
27
28 import java.io.ObjectStreamField;
29 import java.io.UnsupportedEncodingException;
30 import java.nio.charset.Charset;
31 import java.util.ArrayList;
32 import java.util.Arrays;
33 import java.util.Comparator;
34 import java.util.Formatter;
35 import java.util.Locale;
36 import java.util.Objects;
37 import java.util.StringJoiner;
38 import java.util.regex.Matcher;
39 import java.util.regex.Pattern;
40 import java.util.regex.PatternSyntaxException;
41
42 /**
43 * The {@code String} class represents character strings. All
44 * string literals in Java programs, such as {@code "abc"}, are
45 * implemented as instances of this class.
46 * <p>
47 * Strings are constant; their values cannot be changed after they
48 * are created. String buffers support mutable strings.
49 * Because String objects are immutable they can be shared. For example:
50 * <blockquote><pre>
435 * The number of bytes to decode
436 *
437 * @param charset
438 * The {@linkplain java.nio.charset.Charset charset} to be used to
439 * decode the {@code bytes}
440 *
441 * @throws IndexOutOfBoundsException
442 * If the {@code offset} and {@code length} arguments index
443 * characters outside the bounds of the {@code bytes} array
444 *
445 * @since 1.6
446 */
447 public String(byte bytes[], int offset, int length, Charset charset) {
448 if (charset == null)
449 throw new NullPointerException("charset");
450 checkBounds(bytes, offset, length);
451 this.value = StringCoding.decode(charset, bytes, offset, length);
452 }
453
454 /**
455 * Constructs a new {@code String} by decoding the specified array of bytes
456 * using the specified {@linkplain java.nio.charset.Charset charset}. The
457 * length of the new {@code String} is a function of the charset, and hence
458 * may not be equal to the length of the byte array.
459 *
460 * <p> The behavior of this constructor when the given bytes are not valid
461 * in the given charset is unspecified. The {@link
462 * java.nio.charset.CharsetDecoder} class should be used when more control
463 * over the decoding process is required.
464 *
465 * @param bytes
466 * The bytes to be decoded into characters
467 *
468 * @param charsetName
469 * The name of a supported {@linkplain java.nio.charset.Charset
470 * charset}
471 *
472 * @throws UnsupportedEncodingException
473 * If the named charset is not supported
474 *
908
909 /**
910 * Encodes this {@code String} into a sequence of bytes using the given
911 * {@linkplain java.nio.charset.Charset charset}, storing the result into a
912 * new byte array.
913 *
914 * <p> This method always replaces malformed-input and unmappable-character
915 * sequences with this charset's default replacement byte array. The
916 * {@link java.nio.charset.CharsetEncoder} class should be used when more
917 * control over the encoding process is required.
918 *
919 * @param charset
920 * The {@linkplain java.nio.charset.Charset} to be used to encode
921 * the {@code String}
922 *
923 * @return The resultant byte array
924 *
925 * @since 1.6
926 */
927 public byte[] getBytes(Charset charset) {
928 if (charset == null) throw new NullPointerException();
929 return StringCoding.encode(charset, value, 0, value.length);
930 }
931
932 /**
933 * Encodes this {@code String} into a sequence of bytes using the
934 * platform's default charset, storing the result into a new byte array.
935 *
936 * <p> The behavior of this method when this string cannot be encoded in
937 * the default charset is unspecified. The {@link
938 * java.nio.charset.CharsetEncoder} class should be used when more control
939 * over the encoding process is required.
940 *
941 * @return The resultant byte array
942 *
943 * @since 1.1
944 */
945 public byte[] getBytes() {
946 return StringCoding.encode(value, 0, value.length);
947 }
948
949 /**
|
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.lang;
27
28 import java.io.ObjectStreamField;
29 import java.io.UnsupportedEncodingException;
30 import java.nio.charset.Charset;
31 import java.nio.ByteBuffer;
32 import java.util.ArrayList;
33 import java.util.Arrays;
34 import java.util.Comparator;
35 import java.util.Formatter;
36 import java.util.Locale;
37 import java.util.Objects;
38 import java.util.StringJoiner;
39 import java.util.regex.Matcher;
40 import java.util.regex.Pattern;
41 import java.util.regex.PatternSyntaxException;
42
43 /**
44 * The {@code String} class represents character strings. All
45 * string literals in Java programs, such as {@code "abc"}, are
46 * implemented as instances of this class.
47 * <p>
48 * Strings are constant; their values cannot be changed after they
49 * are created. String buffers support mutable strings.
50 * Because String objects are immutable they can be shared. For example:
51 * <blockquote><pre>
436 * The number of bytes to decode
437 *
438 * @param charset
439 * The {@linkplain java.nio.charset.Charset charset} to be used to
440 * decode the {@code bytes}
441 *
442 * @throws IndexOutOfBoundsException
443 * If the {@code offset} and {@code length} arguments index
444 * characters outside the bounds of the {@code bytes} array
445 *
446 * @since 1.6
447 */
448 public String(byte bytes[], int offset, int length, Charset charset) {
449 if (charset == null)
450 throw new NullPointerException("charset");
451 checkBounds(bytes, offset, length);
452 this.value = StringCoding.decode(charset, bytes, offset, length);
453 }
454
455 /**
456 * Constructs a new {@code String} by decoding the specified
457 * {@linkplain java.nio.ByteBuffer byte buffer} using the specified
458 * {@linkplain java.nio.charset.Charset charset}.
459 * The length of the new {@code String} is a function of the charset, and
460 * hence may not be equal to the remaining number of bytes in the
461 * {@linkplain java.nio.ByteBuffer byte buffer}.
462 *
463 * <p> This method always replaces malformed-input and unmappable-character
464 * sequences with this charset's default replacement string. The {@link
465 * java.nio.charset.CharsetDecoder} class should be used when more control
466 * over the decoding process is required.
467 *
468 * <p>
469 * Bytes are read between <code>position()</code> and <code>limit()</code>
470 * of the {@link java.nio.ByteBuffer}.
471 * After the bytes have been read the <code>position()</code> will be
472 * updated.
473 *
474 * @param bytes
475 * The bytes to be decoded into characters
476 *
477 * @param charset
478 * The {@linkplain java.nio.charset.Charset charset} to be used to
479 * decode the {@code bytes}
480 *
481 * @since 1.9
482 */
483 public String(ByteBuffer bytes, Charset charset) {
484 if (charset == null)
485 throw new NullPointerException("charset");
486 this.value = StringCoding.decode(charset, bytes);
487 }
488
489 /**
490 * Constructs a new {@code String} by decoding the specified array of bytes
491 * using the specified {@linkplain java.nio.charset.Charset charset}. The
492 * length of the new {@code String} is a function of the charset, and hence
493 * may not be equal to the length of the byte array.
494 *
495 * <p> The behavior of this constructor when the given bytes are not valid
496 * in the given charset is unspecified. The {@link
497 * java.nio.charset.CharsetDecoder} class should be used when more control
498 * over the decoding process is required.
499 *
500 * @param bytes
501 * The bytes to be decoded into characters
502 *
503 * @param charsetName
504 * The name of a supported {@linkplain java.nio.charset.Charset
505 * charset}
506 *
507 * @throws UnsupportedEncodingException
508 * If the named charset is not supported
509 *
943
944 /**
945 * Encodes this {@code String} into a sequence of bytes using the given
946 * {@linkplain java.nio.charset.Charset charset}, storing the result into a
947 * new byte array.
948 *
949 * <p> This method always replaces malformed-input and unmappable-character
950 * sequences with this charset's default replacement byte array. The
951 * {@link java.nio.charset.CharsetEncoder} class should be used when more
952 * control over the encoding process is required.
953 *
954 * @param charset
955 * The {@linkplain java.nio.charset.Charset} to be used to encode
956 * the {@code String}
957 *
958 * @return The resultant byte array
959 *
960 * @since 1.6
961 */
962 public byte[] getBytes(Charset charset) {
963 Objects.requireNonNull(charset);
964 return StringCoding.encode(charset, value, 0, value.length);
965 }
966
967 /**
968 * Encodes this {@code String} into a sequence of bytes using the given
969 * {@linkplain java.nio.charset.Charset charset}, storing the result into a
970 * byte array that has been passed as an argument.
971 * <p>
972 * The number of bytes written during encoding is a function of the charset
973 * used to perform the encoding and is returned from this method. It may not
974 * be equal to the length of this
975 * String. At most <code>destBuffer.length - destOffset</code> bytes will be written.
976 *
977 * @param destBuffer
978 * The destination array
979 *
980 * @param destOffset
981 * The start offset in the destination array
982 *
983 * @param charset
984 * The {@linkplain java.nio.charset.Charset} to be used to encode
985 * the {@code String}
986 *
987 * @return the number of bytes written
988 *
989 * @since 1.9
990 */
991 public int getBytes(byte[] destBuffer, int destOffset, Charset charset) {
992 Objects.requireNonNull(destBuffer);
993 Objects.requireNonNull(charset);
994 return StringCoding.encode(charset, value, 0, value.length, destBuffer, destOffset);
995 }
996
997 /**
998 * Encodes as many characters as possible from this {@code String} into a
999 * sequence of bytes using the given
1000 * {@linkplain java.nio.charset.Charset charset}, storing the result into a
1001 * {@linkplain java.nio.ByteBuffer byte buffer} that has been passed as an argument.
1002 * <p>
1003 * The number of bytes written during encoding is a function of the charset
1004 * used to perform the encoding and is returned from this method. It may not
1005 * be equal to the length of this
1006 * String. At most <code>destBuffer.remaining()</code> bytes will be written.
1007 * <p>
1008 * The buffer's position will be advanced to reflect the characters read and
1009 * the bytes written, but its mark and limit will not be modified.
1010 *
1011 * @param destBuffer
1012 * The destination {@linkplain java.nio.ByteBuffer}
1013 *
1014 * @param charset
1015 * The {@linkplain java.nio.charset.Charset} to be used to encode
1016 * the {@code String}
1017 *
1018 * @return the number of bytes written
1019 *
1020 * @since 1.9
1021 */
1022 public int getBytes(ByteBuffer destBuffer, Charset charset) {
1023 Objects.requireNonNull(destBuffer);
1024 Objects.requireNonNull(charset);
1025 return StringCoding.encode(charset, value, 0, value.length, destBuffer);
1026 }
1027
1028 /**
1029 * Encodes this {@code String} into a sequence of bytes using the
1030 * platform's default charset, storing the result into a new byte array.
1031 *
1032 * <p> The behavior of this method when this string cannot be encoded in
1033 * the default charset is unspecified. The {@link
1034 * java.nio.charset.CharsetEncoder} class should be used when more control
1035 * over the encoding process is required.
1036 *
1037 * @return The resultant byte array
1038 *
1039 * @since 1.1
1040 */
1041 public byte[] getBytes() {
1042 return StringCoding.encode(value, 0, value.length);
1043 }
1044
1045 /**
|