src/java.base/share/classes/java/lang/String.java

*** 26,35 ****
--- 26,36 ----
  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,459 ****
--- 451,494 ----
          checkBounds(bytes, offset, length);
          this.value = StringCoding.decode(charset, bytes, offset, length);
      }
      
      /**
+      * Constructs a new {@code String} by decoding 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
+      * updated.
+      *
+      * @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) {
+         if (charset == null)
+             throw new NullPointerException("charset");
+         this.value = StringCoding.decode(charset, 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,937 ****
       * @return  The resultant byte array
       *
       * @since  1.6
       */
      public byte[] getBytes(Charset charset) {
!         if (charset == null) throw new NullPointerException();
          return StringCoding.encode(charset, value, 0, value.length);
      }
  
      /**
       * 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
--- 958,1033 ----
       * @return  The resultant byte array
       *
       * @since  1.6
       */
      public byte[] getBytes(Charset charset) {
!         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>
+      * 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>
+      * The buffer's position will be advanced to reflect the characters read and
+      * 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 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