TextBuffer
Date: 2016-12-03

com.fasterxml.jackson.core.util

## Class TextBuffer

- java.lang.Object
- - com.fasterxml.jackson.core.util.TextBuffer

-     public final class TextBuffer
      extends java.lang.Object

  TextBuffer is a class similar to `StringBuffer`, with following differences:
  - TextBuffer uses segments character arrays, to avoid having to do additional array copies when array is not big enough. This means that only reallocating that is necessary is done only once: if and when caller wants to access contents in a linear array (char[], String).
  - TextBuffer can also be initialized in "shared mode", in which it will just act as a wrapper to a single char array managed by another object (like parser that owns it)
  - TextBuffer is not synchronized.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `TextBuffer(BufferRecycler allocator)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `append(char c)`
    `void` | `append(char[] c, int start, int len)`
    `void` | `append(java.lang.String str, int offset, int len)`
    `char[]` | `contentsAsArray()`
    `java.math.BigDecimal` | `contentsAsDecimal()` Convenience method for converting contents of the buffer into a `BigDecimal`.
    `double` | `contentsAsDouble()` Convenience method for converting contents of the buffer into a Double value.
    `java.lang.String` | `contentsAsString()`
    `int` | `contentsToWriter(java.io.Writer w)`
    `char[]` | `emptyAndGetCurrentSegment()`
    `void` | `ensureNotShared()` Method called to make sure that buffer is not using shared input buffer; if it is, it will copy such contents to private buffer.
    `char[]` | `expandCurrentSegment()` Method called to expand size of the current segment, to accommodate for more contiguous content.
    `char[]` | `expandCurrentSegment(int minSize)` Method called to expand size of the current segment, to accommodate for more contiguous content.
    `char[]` | `finishCurrentSegment()`
    `char[]` | `getCurrentSegment()`
    `int` | `getCurrentSegmentSize()`
    `char[]` | `getTextBuffer()` Accessor that may be used to get the contents of this buffer in a single `char` array regardless of whether they were collected in a segmented fashion or not.
    `int` | `getTextOffset()`
    `boolean` | `hasTextAsCharacters()` Method that can be used to check whether textual contents can be efficiently accessed using `getTextBuffer()`.
    `void` | `releaseBuffers()` Method called to indicate that the underlying buffers should now be recycled if they haven't yet been recycled.
    `void` | `resetWithCopy(char[] buf, int start, int len)`
    `void` | `resetWithEmpty()` Method called to clear out any content text buffer may have, and initializes buffer to use non-shared data.
    `void` | `resetWithShared(char[] buf, int start, int len)` Method called to initialize the buffer with a shared copy of data; this means that buffer will just have pointers to actual data.
    `void` | `resetWithString(java.lang.String value)`
    `java.lang.String` | `setCurrentAndReturn(int len)`
    `void` | `setCurrentLength(int len)`
    `int` | `size()`
    `java.lang.String` | `toString()` Note: calling this method may not be as efficient as calling `contentsAsString()`, since it's not guaranteed that resulting String is cached.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### TextBuffer

          public TextBuffer(BufferRecycler allocator)

  - ### Method Detail

    - #### releaseBuffers

          public void releaseBuffers()

      Method called to indicate that the underlying buffers should now be recycled if they haven't yet been recycled. Although caller can still use this text buffer, it is not advisable to call this method if that is likely, since next time a buffer is needed, buffers need to reallocated. Note: calling this method automatically also clears contents of the buffer.

    - #### resetWithEmpty

          public void resetWithEmpty()

      Method called to clear out any content text buffer may have, and initializes buffer to use non-shared data.

    - #### resetWithShared

          public void resetWithShared(char[] buf,
                             int start,
                             int len)

      Method called to initialize the buffer with a shared copy of data; this means that buffer will just have pointers to actual data. It also means that if anything is to be appended to the buffer, it will first have to unshare it (make a local copy).

    - #### resetWithCopy

          public void resetWithCopy(char[] buf,
                           int start,
                           int len)

    - #### resetWithString

          public void resetWithString(java.lang.String value)

    - #### size

          public int size()

      Returns:
        Number of characters currently stored by this collector

    - #### getTextOffset

          public int getTextOffset()

    - #### hasTextAsCharacters

          public boolean hasTextAsCharacters()

      Method that can be used to check whether textual contents can be efficiently accessed using `getTextBuffer()`.

    - #### getTextBuffer

          public char[] getTextBuffer()

      Accessor that may be used to get the contents of this buffer in a single `char` array regardless of whether they were collected in a segmented fashion or not.

    - #### contentsAsString

          public java.lang.String contentsAsString()

    - #### contentsAsArray

          public char[] contentsAsArray()

    - #### contentsAsDecimal

          public java.math.BigDecimal contentsAsDecimal()
                                                 throws java.lang.NumberFormatException

      Convenience method for converting contents of the buffer into a `BigDecimal`.
      Throws:
        `java.lang.NumberFormatException`

    - #### contentsAsDouble

          public double contentsAsDouble()
                                  throws java.lang.NumberFormatException

      Convenience method for converting contents of the buffer into a Double value.
      Throws:
        `java.lang.NumberFormatException`

    - #### contentsToWriter

          public int contentsToWriter(java.io.Writer w)
                               throws java.io.IOException

      Throws:
        `java.io.IOException`
      Since:
        2.8

    - #### ensureNotShared

          public void ensureNotShared()

      Method called to make sure that buffer is not using shared input buffer; if it is, it will copy such contents to private buffer.

    - #### append

          public void append(char c)

    - #### append

          public void append(char[] c,
                    int start,
                    int len)

    - #### append

          public void append(java.lang.String str,
                    int offset,
                    int len)

    - #### getCurrentSegment

          public char[] getCurrentSegment()

    - #### emptyAndGetCurrentSegment

          public char[] emptyAndGetCurrentSegment()

    - #### getCurrentSegmentSize

          public int getCurrentSegmentSize()

    - #### setCurrentLength

          public void setCurrentLength(int len)

    - #### setCurrentAndReturn

          public java.lang.String setCurrentAndReturn(int len)

      Since:
        2.6

    - #### finishCurrentSegment

          public char[] finishCurrentSegment()

    - #### expandCurrentSegment

          public char[] expandCurrentSegment()

      Method called to expand size of the current segment, to accommodate for more contiguous content. Usually only used when parsing tokens like names if even then.

    - #### expandCurrentSegment

          public char[] expandCurrentSegment(int minSize)

      Method called to expand size of the current segment, to accommodate for more contiguous content. Usually only used when parsing tokens like names if even then.
      Parameters:
        `minSize` - Required minimum strength of the current segment
      Since:
        2.4.0

    - #### toString

          public java.lang.String toString()

      Note: calling this method may not be as efficient as calling `contentsAsString()`, since it's not guaranteed that resulting String is cached.
      Overrides:
        `toString` in class `java.lang.Object`