Interface CharsetStringBuilder

All Known Implementing Classes:
CharsetStringBuilder.DecoderStringBuilder, CharsetStringBuilder.Iso88591StringBuilder, CharsetStringBuilder.UsAsciiStringBuilder, Utf8StringBuilder
public interface CharsetStringBuilder

Build a string from a sequence of bytes and/or characters.

Implementations of this interface are optimized for processing a mix of calls to already decoded character based appends (e.g. append(char)) and calls to undecoded byte methods (e.g. append(byte)). This is particularly useful for decoding % encoded strings that are mostly already decoded but may contain escaped byte sequences that are not decoded. The standard CharsetDecoder API is not well suited for this use-case.

Any coding errors in the string will be reported by a CharacterCodingException thrown from the build() method.

See Also:

  • Method Details

    • append

      void append(byte b)
      Parameters:
      b - An encoded byte to append

    • append

      void append(char c)
      Parameters:
      c - A decoded character to append

    • append

      default void append(byte[] bytes)
      Parameters:
      bytes - Array of encoded bytes to append

    • append

      default void append(byte[] b, int offset, int length)
      Parameters:
      b - Array of encoded bytes
      offset - offset into the array
      length - the number of bytes to append from the array.

    • append

      default void append(CharSequence chars, int offset, int length)
      Parameters:
      chars - sequence of decoded characters
      offset - offset into the array
      length - the number of character to append from the sequence.

    • append

      default void append(ByteBuffer buf)
      Parameters:
      buf - Buffer of encoded bytes to append. The bytes are consumed from the buffer.

    • build

      default String build() throws CharacterCodingException

      Build the completed string and reset the buffer.

      Returns:
      The decoded built string which must be complete in regard to any multibyte sequences.
      Throws:
      CharacterCodingException - If the bytes cannot be correctly decoded or a multibyte sequence is incomplete.

    • build

      String build(boolean allowPartialString) throws CharacterCodingException

      Attempt to build the completed string and reset the buffer, returning a partial string if there are encoding errors

      Note, only some implementations support the allowPartialString parameter

      Parameters:
      allowPartialString - true if a partial string is allowed to be returned, false means if complete string cannot be returned, an exception is thrown.
      Returns:
      The available string (complete or partial)
      Throws:
      CharacterCodingException - (only if allowPartialString is false) thrown if the bytes cannot be correctly decoded or a multibyte sequence is incomplete.

    • hasCodingErrors

      default boolean hasCodingErrors()

      Test for if there are and detected encoding errors

      Returns:
      True if the characters in the builder contain encoding errors. Such as bad sequences, incomplete sequences, replacement characters, etc.

    • replaceIncomplete

      default boolean replaceIncomplete()

      If there is an incomplete sequence, replace it with the encoding specific replacement character.

      Will set the encoding errors to true for hasCodingErrors()

      Returns:
      true if replacement occurred, false if there was no issue.

    • length

      int length()
      Returns:
      the length in characters

    • reset

      void reset()

      Resets this sequence to be empty.

    • forCharset

      static CharsetStringBuilder forCharset(Charset charset)
      Parameters:
      charset - The charset
      Returns:
      A CharsetStringBuilder suitable for the charset.

    • forCharset

      static CharsetStringBuilder forCharset(Charset charset, CodingErrorAction onMalformedInput, CodingErrorAction onUnmappableCharacter)