com.fasterxml.jackson.core.util

## Class TextBuffer

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

Direct Known Subclasses:
  ReadConstrainedTextBuffer

    public class TextBuffer
    extends 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
`` `TextBuffer(BufferRecycler allocator)`
`protected` `TextBuffer(BufferRecycler allocator, char[] initialSegment)`

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
`protected void` `_reportBufferOverflow(int prev, int curr)`
`void` `append(char c)`
`void` `append(char[] c, int start, int len)`
`void` `append(String str, int offset, int len)`
`char[]` `contentsAsArray()`
`BigDecimal` `contentsAsDecimal()` Deprecated. Since 2.15 just access String contents if necessary, call `NumberInput.parseBigDecimal(String, boolean)` (or other overloads) directly instead
`double` `contentsAsDouble()` Deprecated. use `contentsAsDouble(boolean)`
`double` `contentsAsDouble(boolean useFastParser)` Convenience method for converting contents of the buffer into a Double value.
`float` `contentsAsFloat()` Deprecated. use `contentsAsFloat(boolean)`
`float` `contentsAsFloat(boolean useFastParser)` Convenience method for converting contents of the buffer into a Float value.
`int` `contentsAsInt(boolean neg)` Specialized convenience method that will decode a 32-bit int, of at most 9 digits (and possible leading minus sign).
`long` `contentsAsLong(boolean neg)` Specialized convenience method that will decode a 64-bit int, of at most 18 digits (and possible leading minus sign).
`String` `contentsAsString()` Accessor that may be used to get the contents of this buffer as a single `String` regardless of whether they were collected in a segmented fashion or not: this typically require construction of the result String.
`int` `contentsToWriter(Writer w)` Accessor that will write buffered contents using given `Writer`.
`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.
`String` `finishAndReturn(int lastSegmentEnd, boolean trimTrailingSpaces)`
`char[]` `finishCurrentSegment()`
`static TextBuffer` `fromInitial(char[] initialSegment)` Factory method for constructing an instance with no allocator, and with initial full segment.
`char[]` `getBufferWithoutReset()` Method for accessing the currently active (last) content segment without changing state of the buffer
`char[]` `getCurrentSegment()`
`int` `getCurrentSegmentSize()`
`char[]` `getTextBuffer()` Accessor that may be used to get the contents of this buffer as a single `char[]` regardless of whether they were collected in a segmented fashion or not: this typically require allocation of the result buffer.
`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` `resetWith(char ch)` Method for clearing out possibly existing content, and replacing them with a single-character content (so `size()` would return `1`)
`void` `resetWithCopy(char[] buf, int offset, int len)`
`void` `resetWithCopy(String text, 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 offset, 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(String value)`
`String` `setCurrentAndReturn(int len)` Convenience method that finishes the current active content segment (by specifying how many characters within consists of valid content) and aggregates and returns resulting contents (similar to a call to `contentsAsString()`).
`void` `setCurrentLength(int len)`
`int` `size()`
`String` `toString()` Note: calling this method may not be as efficient as calling `contentsAsString()`, since it's not guaranteed that resulting String is cached.
`protected void` `validateStringLength(int length)` Convenience method that can be used to verify that a String of specified length does not exceed maximum specific by this constraints object: if it does, a `JsonParseException` is thrown.

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

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

### Constructor Detail

#### TextBuffer

    public TextBuffer(BufferRecycler allocator)

#### TextBuffer

    protected TextBuffer(BufferRecycler allocator,
                         char[] initialSegment)

### Method Detail

#### fromInitial

    public static TextBuffer fromInitial(char[] initialSegment)

Factory method for constructing an instance with no allocator, and with initial full segment.

Parameters:
  `initialSegment` - Initial, full segment to use for creating buffer (buffer `size()` would return length of `initialSegment`)
Returns:
  TextBuffer constructed
Since:
  2.10

#### 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: since Jackson 2.11, calling this method will NOT clear already aggregated contents (that is, `_currentSegment`, to retain current token text if (but only if!) already aggregated.

#### resetWithEmpty

    public void resetWithEmpty()

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

#### resetWith

    public void resetWith(char ch)

Method for clearing out possibly existing content, and replacing them with a single-character content (so `size()` would return `1`)

Parameters:
  `ch` - Character to set as the buffer contents
Since:
  2.9

#### resetWithShared

    public void resetWithShared(char[] buf,
                                int offset,
                                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).

Parameters:
  `buf` - Buffer that contains shared contents
  `offset` - Offset of the first content character in `buf`
  `len` - Length of content in `buf`

#### resetWithCopy

    public void resetWithCopy(char[] buf,
                              int offset,
                              int len)
                       throws IOException

Parameters:
  `buf` - Buffer that contains new contents
  `offset` - Offset of the first content character in `buf`
  `len` - Length of content in `buf`
Throws:
  `IOException` - if the buffer has grown too large, see `StreamReadConstraints.Builder.maxStringLength(int)`

#### resetWithCopy

    public void resetWithCopy(String text,
                              int start,
                              int len)
                       throws IOException

Parameters:
  `text` - String that contains new contents
  `start` - Offset of the first content character in `text`
  `len` - Length of content in `text`
Throws:
  `IOException` - if the buffer has grown too large, see `StreamReadConstraints.Builder.maxStringLength(int)`
Since:
  2.9

#### resetWithString

    public void resetWithString(String value)
                         throws IOException

Parameters:
  `value` - to replace existing buffer
Throws:
  `IOException` - if the value is too large, see `StreamReadConstraints.Builder.maxStringLength(int)`

#### getBufferWithoutReset

    public char[] getBufferWithoutReset()

Method for accessing the currently active (last) content segment without changing state of the buffer

Returns:
  Currently active (last) content segment
Since:
  2.9

#### size

    public int size()

Returns:
  Number of characters currently stored in this buffer

#### getTextOffset

    public int getTextOffset()

#### hasTextAsCharacters

    public boolean hasTextAsCharacters()

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

Returns:
  `True` if access via `getTextBuffer()` would be efficient (that is, content already available as aggregated `char[]`)

#### getTextBuffer

    public char[] getTextBuffer()
                         throws IOException

Accessor that may be used to get the contents of this buffer as a single `char[]` regardless of whether they were collected in a segmented fashion or not: this typically require allocation of the result buffer.

Returns:
  Aggregated `char[]` that contains all buffered content
Throws:
  `IOException` - if the text is too large, see `StreamReadConstraints.Builder.maxStringLength(int)`

#### contentsAsString

    public String contentsAsString()
                            throws IOException

Accessor that may be used to get the contents of this buffer as a single `String` regardless of whether they were collected in a segmented fashion or not: this typically require construction of the result String.

Returns:
  Aggregated buffered contents as a `String`
Throws:
  `IOException` - if the contents are too large, see `StreamReadConstraints.Builder.maxStringLength(int)`

#### contentsAsArray

    public char[] contentsAsArray()
                           throws IOException

Returns:
  char array
Throws:
  `IOException` - if the text is too large, see `StreamReadConstraints.Builder.maxStringLength(int)`

#### contentsAsDouble

    public double contentsAsDouble(boolean useFastParser)
                            throws NumberFormatException

Convenience method for converting contents of the buffer into a Double value.

Parameters:
  `useFastParser` - whether to use `FastDoubleParser`
Returns:
  Buffered text value parsed as a `Double`, if possible
Throws:
  `NumberFormatException` - if contents are not a valid Java number
Since:
  2.14

#### contentsAsDouble

    @Deprecated
    public double contentsAsDouble()
                                        throws NumberFormatException

Deprecated. use `contentsAsDouble(boolean)`
Convenience method for converting contents of the buffer into a Double value.

Returns:
  Buffered text value parsed as a `Double`, if possible
Throws:
  `NumberFormatException` - if contents are not a valid Java number

#### contentsAsFloat

    @Deprecated
    public float contentsAsFloat()
                                      throws NumberFormatException

Deprecated. use `contentsAsFloat(boolean)`
Convenience method for converting contents of the buffer into a Float value.

Returns:
  Buffered text value parsed as a `Float`, if possible
Throws:
  `NumberFormatException` - if contents are not a valid Java number

#### contentsAsFloat

    public float contentsAsFloat(boolean useFastParser)
                          throws NumberFormatException

Convenience method for converting contents of the buffer into a Float value.

Parameters:
  `useFastParser` - whether to use `FastDoubleParser`
Returns:
  Buffered text value parsed as a `Float`, if possible
Throws:
  `NumberFormatException` - if contents are not a valid Java number
Since:
  2.14

#### contentsAsDecimal

    @Deprecated
    public BigDecimal contentsAsDecimal()
                                             throws NumberFormatException

Deprecated. Since 2.15 just access String contents if necessary, call `NumberInput.parseBigDecimal(String, boolean)` (or other overloads) directly instead

Returns:
  Buffered text value parsed as a `BigDecimal`, if possible
Throws:
  `NumberFormatException` - if contents are not a valid Java number

#### contentsAsInt

    public int contentsAsInt(boolean neg)

Specialized convenience method that will decode a 32-bit int, of at most 9 digits (and possible leading minus sign).

NOTE: method DOES NOT verify that the contents actually are a valid Java `int` value (either regarding format, or value range): caller MUST validate that.

Parameters:
  `neg` - Whether contents start with a minus sign
Returns:
  Buffered text value parsed as an `int` using `NumberInput.parseInt(String)` method (which does NOT validate input)
Since:
  2.9

#### contentsAsLong

    public long contentsAsLong(boolean neg)

Specialized convenience method that will decode a 64-bit int, of at most 18 digits (and possible leading minus sign).

NOTE: method DOES NOT verify that the contents actually are a valid Java `long` value (either regarding format, or value range): caller MUST validate that.

Parameters:
  `neg` - Whether contents start with a minus sign
Returns:
  Buffered text value parsed as an `long` using `NumberInput.parseLong(String)` method (which does NOT validate input)
Since:
  2.9

#### contentsToWriter

    public int contentsToWriter(Writer w)
                         throws IOException

Accessor that will write buffered contents using given `Writer`.

Parameters:
  `w` - Writer to use for writing out buffered content
Returns:
  Number of characters written (same as `size()`)
Throws:
  `IOException` - If write using `Writer` parameter fails
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)
                throws IOException

Parameters:
  `c` - char to append
Throws:
  `IOException` - if the buffer has grown too large, see `StreamReadConstraints.Builder.maxStringLength(int)`

#### append

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

Parameters:
  `c` - char array to append
  `start` - the start index within the array (from which we read chars to append)
  `len` - number of chars to take from the array
Throws:
  `IOException` - if the buffer has grown too large, see `StreamReadConstraints.Builder.maxStringLength(int)`

#### append

    public void append(String str,
                       int offset,
                       int len)
                throws IOException

Parameters:
  `str` - string to append
  `offset` - the start index within the string (from which we read chars to append)
  `len` - number of chars to take from the string
Throws:
  `IOException` - if the buffer has grown too large, see `StreamReadConstraints.Builder.maxStringLength(int)`

#### getCurrentSegment

    public char[] getCurrentSegment()

#### emptyAndGetCurrentSegment

    public char[] emptyAndGetCurrentSegment()

#### getCurrentSegmentSize

    public int getCurrentSegmentSize()

#### setCurrentLength

    public void setCurrentLength(int len)

#### setCurrentAndReturn

    public String setCurrentAndReturn(int len)
                               throws IOException

Convenience method that finishes the current active content segment (by specifying how many characters within consists of valid content) and aggregates and returns resulting contents (similar to a call to `contentsAsString()`).

Parameters:
  `len` - Length of content (in characters) of the current active segment
Returns:
  String that contains all buffered content
Throws:
  `IOException` - if the text is too large, see `StreamReadConstraints.Builder.maxStringLength(int)`
Since:
  2.6

#### finishCurrentSegment

    public char[] finishCurrentSegment()
                                throws IOException

Returns:
  char array
Throws:
  `IOException` - if the text is too large, see `StreamReadConstraints.Builder.maxStringLength(int)`

#### finishAndReturn

    public String finishAndReturn(int lastSegmentEnd,
                                  boolean trimTrailingSpaces)
                           throws IOException

Parameters:
  `lastSegmentEnd` - End offset in the currently active segment, could be 0 in the case of first character is delimiter or end-of-line
  `trimTrailingSpaces` - Whether trailing spaces should be trimmed or not
Returns:
  token as text
Throws:
  `IOException` - If length constraints (of longest allowed Text value) are violated
Since:
  2.15

#### 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. Method will both expand the segment and return it

Returns:
  Expanded current segment

#### 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
Returns:
  Expanded current segment
Since:
  2.4

#### toString

    public 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 `Object`

#### _reportBufferOverflow

    protected void _reportBufferOverflow(int prev,
                                         int curr)

#### validateStringLength

    protected void validateStringLength(int length)
                                 throws IOException

Convenience method that can be used to verify that a String of specified length does not exceed maximum specific by this constraints object: if it does, a `JsonParseException` is thrown.

Parameters:
  `length` - Length of string in input units
Throws:
  `IOException` - If length exceeds maximum
Since:
  2.15