Package org.simpleframework.util.buffer

## Interface Buffer

- All Superinterfaces:
    `Stream`
  All Known Implementing Classes:
    `ArrayBuffer`, `BufferAllocator`

      public interface Buffer
      extends Stream

  The `Buffer` interface represents a collection of bytes that can be written to and later read. This is used to provide a region of memory is such a way that the underlying representation of that memory is independent of its use. Typically buffers are implemented as either allocated byte arrays or files.
  Author:
    Niall Gallagher
  See Also:
    `Allocator`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `Buffer` | `allocate()` | This method is used to allocate a segment of this buffer as a separate buffer object.
    `Buffer` | `append​(byte[] array)` | This method is used to append bytes to the end of the buffer.
    `Buffer` | `append​(byte[] array, int off, int len)` | This method is used to append bytes to the end of the buffer.
    `void` | `clear()` | This will clear all data from the buffer.
    `void` | `close()` | This method is used to ensure the buffer can be closed.
    `java.lang.String` | `encode()` | This method is used to acquire the buffered bytes as a string.
    `java.lang.String` | `encode​(java.lang.String charset)` | This method is used to acquire the buffered bytes as a string.

    - ### Methods inherited from interface org.simpleframework.util.buffer.Stream

      `getInputStream`

- - ### Method Detail

    - #### allocate

          Buffer allocate()
                   throws java.io.IOException

      This method is used to allocate a segment of this buffer as a separate buffer object. This allows the buffer to be sliced in to several smaller independent buffers, while still allowing the parent buffer to manage a single buffer. This is useful if the parent is split in to logically smaller segments.
      Returns:
        this returns a buffer which is a segment of this buffer
      Throws:
        `java.io.IOException`

    - #### encode

          java.lang.String encode()
                           throws java.io.IOException

      This method is used to acquire the buffered bytes as a string. This is useful if the contents need to be manipulated as a string or transferred into another encoding. If the UTF-8 content encoding is not supported the platform default is used, however this is unlikely as UTF-8 should be supported.
      Returns:
        this returns a UTF-8 encoding of the buffer contents
      Throws:
        `java.io.IOException`

    - #### encode

          java.lang.String encode​(java.lang.String charset)
                           throws java.io.IOException

      This method is used to acquire the buffered bytes as a string. This is useful if the contents need to be manipulated as a string or transferred into another encoding. This will convert the bytes using the specified character encoding format.
      Parameters:
        `charset` - this is the charset to encode the data with
      Returns:
        this returns the encoding of the buffer contents
      Throws:
        `java.io.IOException`

    - #### append

          Buffer append​(byte[] array)
                 throws java.io.IOException

      This method is used to append bytes to the end of the buffer. This will expand the capacity of the buffer if there is not enough space to accommodate the extra bytes.
      Parameters:
        `array` - this is the byte array to append to this buffer
      Returns:
        this returns this buffer for another operation
      Throws:
        `java.io.IOException`

    - #### append

          Buffer append​(byte[] array,
                        int off,
                        int len)
                 throws java.io.IOException

      This method is used to append bytes to the end of the buffer. This will expand the capacity of the buffer if there is not enough space to accommodate the extra bytes.
      Parameters:
        `array` - this is the byte array to append to this buffer
        `len` - the number of bytes to be read from the array
        `off` - this is the offset to begin reading the bytes from
      Returns:
        this returns this buffer for another operation
      Throws:
        `java.io.IOException`

    - #### clear

          void clear()
              throws java.io.IOException

      This will clear all data from the buffer. This simply sets the count to be zero, it will not clear the memory occupied by the instance as the internal buffer will remain. This allows the memory occupied to be reused as many times as is required.
      Throws:
        `java.io.IOException`

    - #### close

          void close()
              throws java.io.IOException

      This method is used to ensure the buffer can be closed. Once the buffer is closed it is an immutable collection of bytes and can not longer be modified. This ensures that it can be passed by value without the risk of modification of the bytes.
      Throws:
        `java.io.IOException`