src/java.base/share/classes/java/lang/String.java
Print this page
@@ -26,10 +26,11 @@
package java.lang;
import java.io.ObjectStreamField;
import java.io.UnsupportedEncodingException;
import java.nio.charset.Charset;
+import java.nio.ByteBuffer;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Comparator;
import java.util.Formatter;
import java.util.Locale;
@@ -450,10 +451,83 @@
checkBounds(bytes, offset, length);
this.value = StringCoding.decode(charset, bytes, offset, length);
}
/**
+ * Constructs a new {@code String} by decoding the remaining bytes in the specified
+ * {@linkplain java.nio.ByteBuffer byte buffer} using the specified
+ * {@linkplain java.nio.charset.Charset charset}.
+ * The length of the new {@code String} is a function of the charset, and
+ * hence may not be equal to the remaining number of bytes in the
+ * {@linkplain java.nio.ByteBuffer byte buffer}.
+ *
+ * <p> This method always replaces malformed-input and unmappable-character
+ * sequences with this charset's default replacement string. The {@link
+ * java.nio.charset.CharsetDecoder} class should be used when more control
+ * over the decoding process is required.
+ *
+ * <p>
+ * Bytes are read between <code>position()</code> and <code>limit()</code>
+ * of the {@link java.nio.ByteBuffer}.
+ * After the bytes have been read the <code>position()</code> will be
+ * advanced to its <code>limit()</code>.
+ *
+ * @param bytes
+ * The bytes to be decoded into characters
+ *
+ * @param charset
+ * The {@linkplain java.nio.charset.Charset charset} to be used to
+ * decode the {@code bytes}
+ *
+ * @since 1.9
+ */
+ public String(ByteBuffer bytes, Charset charset) {
+ Objects.requireNonNull(bytes);
+ Objects.requireNonNull(charset);
+ this.value = StringCoding.decode(charset, bytes);
+ }
+
+ /**
+ * Constructs a new {@code String} by decoding the remaining bytes in the specified
+ * {@linkplain java.nio.ByteBuffer byte buffer} using the specified
+ * charset.
+ * The length of the new {@code String} is a function of the charset, and
+ * hence may not be equal to the remaining number of bytes in the
+ * {@linkplain java.nio.ByteBuffer byte buffer}.
+ *
+ * <p> This method always replaces malformed-input and unmappable-character
+ * sequences with this charset's default replacement string. The {@link
+ * java.nio.charset.CharsetDecoder} class should be used when more control
+ * over the decoding process is required.
+ *
+ * <p>
+ * Bytes are read between <code>position()</code> and <code>limit()</code>
+ * of the {@link java.nio.ByteBuffer}.
+ * After the bytes have been read the <code>position()</code> will be
+ * advanced to its <code>limit()</code>.
+ *
+ * @param bytes
+ * The bytes to be decoded into characters
+ *
+ * @param charsetName
+ * The name of a supported {@linkplain java.nio.charset.Charset
+ * charset}
+ *
+ * @throws UnsupportedEncodingException
+ * If the named charset is not supported
+ *
+ *
+ * @since 1.9
+ */
+ public String(ByteBuffer bytes, String charsetName)
+ throws UnsupportedEncodingException {
+ Objects.requireNonNull(bytes);
+ Objects.requireNonNull(charsetName);
+ this.value = StringCoding.decode(charsetName, bytes);
+ }
+
+ /**
* Constructs a new {@code String} by decoding the specified array of bytes
* using the specified {@linkplain java.nio.charset.Charset charset}. The
* length of the new {@code String} is a function of the charset, and hence
* may not be equal to the length of the byte array.
*
@@ -923,15 +997,162 @@
* @return The resultant byte array
*
* @since 1.6
*/
public byte[] getBytes(Charset charset) {
- if (charset == null) throw new NullPointerException();
+ Objects.requireNonNull(charset);
return StringCoding.encode(charset, value, 0, value.length);
}
/**
+ * Encodes this {@code String} into a sequence of bytes using the given
+ * {@linkplain java.nio.charset.Charset charset}, storing the result into a
+ * byte array that has been passed as an argument.
+ *
+ * <p> This method always replaces malformed-input and unmappable-character
+ * sequences with this charset's default replacement byte array. The {@link
+ * java.nio.charset.CharsetDecoder} class should be used when more control
+ * over the decoding process is required.
+ *
+ * <p> The number of bytes written during encoding is a function of the charset
+ * used to perform the encoding and is returned from this method. It may not
+ * be equal to the length of this
+ * String. At most <code>destBuffer.length - destOffset</code> bytes will be written.
+ *
+ * @param destBuffer
+ * The destination array
+ *
+ * @param destOffset
+ * The start offset in the destination array
+ *
+ * @param charset
+ * The {@linkplain java.nio.charset.Charset} to be used to encode
+ * the {@code String}
+ *
+ * @return the number of bytes written
+ *
+ * @since 1.9
+ */
+ public int getBytes(byte[] destBuffer, int destOffset, Charset charset) {
+ Objects.requireNonNull(destBuffer);
+ Objects.requireNonNull(charset);
+ return StringCoding.encode(charset, value, 0, value.length, destBuffer, destOffset);
+ }
+
+ /**
+ * Encodes as many characters as possible from this {@code String} into a
+ * sequence of bytes using the given
+ * {@linkplain java.nio.charset.Charset charset}, storing the result into a
+ * {@linkplain java.nio.ByteBuffer byte buffer} that has been passed as an argument.
+ *
+ * <p> The number of bytes written during encoding is a function of the charset
+ * used to perform the encoding and is returned from this method. It may not
+ * be equal to the length of this
+ * String. At most <code>destBuffer.remaining()</code> bytes will be written.
+ *
+ * <p> This method always replaces malformed-input and unmappable-character
+ * sequences with this charset's default replacement byte array. The {@link
+ * java.nio.charset.CharsetDecoder} class should be used when more control
+ * over the decoding process is required.
+ *
+ * <p> The buffer's position will be advanced to reflect the number of
+ * the bytes written, but its mark and limit will not be modified.
+ *
+ * @param destBuffer
+ * The destination {@linkplain java.nio.ByteBuffer}
+ *
+ * @param charset
+ * The {@linkplain java.nio.charset.Charset} to be used to encode
+ * the {@code String}
+ *
+ * @return the number of bytes written
+ *
+ * @since 1.9
+ */
+ public int getBytes(ByteBuffer destBuffer, Charset charset) {
+ Objects.requireNonNull(destBuffer);
+ Objects.requireNonNull(charset);
+ return StringCoding.encode(charset, value, 0, value.length, destBuffer);
+ }
+
+ /**
+ * Encodes as many characters as possible from this {@code String} into a
+ * sequence of bytes using the specified charset, storing the result into a
+ * {@linkplain java.nio.ByteBuffer byte buffer} that has been passed as an argument.
+ *
+ * <p> The number of bytes written during encoding is a function of the charset
+ * used to perform the encoding and is returned from this method. It may not
+ * be equal to the length of this
+ * String. At most <code>destBuffer.remaining()</code> bytes will be written.
+ *
+ * <p> This method always replaces malformed-input and unmappable-character
+ * sequences with this charset's default replacement byte array. The {@link
+ * java.nio.charset.CharsetDecoder} class should be used when more control
+ * over the decoding process is required.
+ *
+ * <p> The buffer's position will be advanced to reflect the number of
+ * the bytes written, but its mark and limit will not be modified.
+ *
+ * @param destBuffer
+ * The destination {@linkplain java.nio.ByteBuffer}
+ *
+ * @param charsetName
+ * The name of a supported {@linkplain java.nio.charset.Charset
+ * charset}
+ *
+ * @return the number of bytes written
+ *
+ * @throws UnsupportedEncodingException
+ * If the named charset is not supported
+ *
+ * @since 1.9
+ */
+ public int getBytes(ByteBuffer destBuffer, String charsetName) throws UnsupportedEncodingException {
+ Objects.requireNonNull(destBuffer);
+ Objects.requireNonNull(charsetName);
+ return StringCoding.encode(charsetName, value, 0, value.length, destBuffer);
+ }
+
+ /**
+ * Encodes as many characters as possible from this {@code String} into a
+ * sequence of bytes using the specified charset, storing the result into a
+ * byte array that has been passed as an argument.
+ *
+ * <p> The number of bytes written during encoding is a function of the charset
+ * used to perform the encoding and is returned from this method. It may not
+ * be equal to the length of this
+ * String. At most <code>destBuffer.length - destOffset</code> bytes will be written.
+ *
+ * <p> This method always replaces malformed-input and unmappable-character
+ * sequences with this charset's default replacement byte array. The {@link
+ * java.nio.charset.CharsetDecoder} class should be used when more control
+ * over the decoding process is required.
+ *
+ * @param destBuffer
+ * The destination array
+ *
+ * @param destOffset
+ * The start offset in the destination array
+ *
+ * @param charsetName
+ * The name of a supported {@linkplain java.nio.charset.Charset
+ * charset}
+ *
+ * @return the number of bytes written
+ *
+ * @throws UnsupportedEncodingException
+ * If the named charset is not supported
+ *
+ * @since 1.9
+ */
+ public int getBytes(byte[] destBuffer, int destOffset, String charsetName) throws UnsupportedEncodingException {
+ Objects.requireNonNull(destBuffer);
+ Objects.requireNonNull(charsetName);
+ return StringCoding.encode(charsetName, value, 0, value.length, destBuffer, destOffset);
+ }
+
+ /**
* Encodes this {@code String} into a sequence of bytes using the
* platform's default charset, storing the result into a new byte array.
*
* <p> The behavior of this method when this string cannot be encoded in
* the default charset is unspecified. The {@link