Top Description Fields Constructors Methods
com.fasterxml.jackson.core.util

public Class TextBuffer

extends Object
Class Inheritance
Known Direct Subclasses
com.fasterxml.jackson.core.util.ReadConstrainedTextBuffer
Imports
java.io.*, java.math.BigDecimal, java.util.*, com.fasterxml.jackson.core.JsonParseException, com.fasterxml.jackson.core.io.NumberInput

TextBuffer is a class similar to java.lang.StringBuffer, with following differences:

Field Summary

Modifier and TypeField and Description
private final BufferRecycler
private char[]
private int
_currentSize

Number of characters in currently active (last) segment

private boolean
_hasSegments

Flag that indicates whether _seqments is non-empty

private char[]
_inputBuffer

Shared input buffer; stored here in case some input can be returned as is, without being copied to collector's own buffers.

private int
private int
_inputStart

Character offset of first char in input buffer; -1 to indicate that input buffer currently does not contain any useful char data

private char[]
private String
_resultString

String that will be constructed when the whole contents are needed; will be temporarily stored in case asked for again.

private ArrayList<char[]>
_segments

List of segments prior to currently active segment.

private int
_segmentSize

Amount of characters in segments in _segments

pack-priv static final int
MAX_SEGMENT_LEN

Let's limit maximum segment length to something sensible.

pack-priv static final int
MIN_SEGMENT_LEN

Let's start with sizable but not huge buffer, will grow as necessary

Reduced from 1000 down to 500 in 2.10.

pack-priv static final char[]

Constructor Summary

AccessConstructor and Description
public
protected
TextBuffer(BufferRecycler allocator, char[] initialSegment)

Method Summary

Modifier and TypeMethod and Description
private String
_doTrim(int ptr)

protected void
_reportBufferOverflow(int prev, int curr)

public void
append(char
char to append
c
)

public void
append(char[]
char array to append
c
,
int
the start index within the array (from which we read chars to append)
start
,
int
number of chars to take from the array
len
)

public void
append(String
string to append
str
,
int
the start index within the string (from which we read chars to append)
offset
,
int
number of chars to take from the string
len
)

private char[]
buf(int needed)

public BufferRecycler
private char[]
carr(int len)

private void
public char[]

Returns:

char array
contentsAsArray
()

public BigDecimal
contentsAsDecimal()
Deprecated Since 2.15 use contentsAsDecimal(boolean) instead.

public BigDecimal
contentsAsDecimal(final boolean useFastParser)

public double

Returns:

Buffered text value parsed as a Double, if possible
contentsAsDouble
(final boolean
whether to use FastDoubleParser
useFastParser
)

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

public double

Returns:

Buffered text value parsed as a Double, if possible
contentsAsDouble
()
Deprecated use contentsAsDouble(boolean)

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

public float

Returns:

Buffered text value parsed as a Float, if possible
contentsAsFloat
()
Deprecated use contentsAsFloat(boolean)

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

public float

Returns:

Buffered text value parsed as a Float, if possible
contentsAsFloat
(final boolean
whether to use FastDoubleParser
useFastParser
)

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

public int

Returns:

Buffered text value parsed as an int using NumberInput#parseInt(String) method (which does NOT validate input)
contentsAsInt
(boolean
Whether contents start with a minus sign
neg
)

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

public long

Returns:

Buffered text value parsed as an long using NumberInput#parseLong(String) method (which does NOT validate input)
contentsAsLong
(boolean
Whether contents start with a minus sign
neg
)

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

public String

Returns:

Aggregated buffered contents as a java.lang.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.

public int

Returns:

Number of characters written (same as size())
contentsToWriter
(Writer
Writer to use for writing out buffered content
w
)

Accessor that will write buffered contents using given Writer.

public char[]
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.

private void
public char[]

Returns:

Expanded current segment
expandCurrentSegment
()

Method called to expand size of the current segment, to accommodate for more contiguous content.

public char[]

Returns:

Expanded current segment
expandCurrentSegment
(int
Required minimum strength of the current segment
minSize
)

Method called to expand size of the current segment, to accommodate for more contiguous content.

public String

Returns:

token as text
finishAndReturn
(int
End offset in the currently active segment, could be 0 in the case of first character is delimiter or end-of-line
lastSegmentEnd
,
boolean
Whether trailing spaces should be trimmed or not
trimTrailingSpaces
)

public char[]

Returns:

char array
finishCurrentSegment
()

public static TextBuffer

Returns:

TextBuffer constructed
fromInitial
(char[]
Initial, full segment to use for creating buffer (buffer size() would return length of initialSegment)
initialSegment
)

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

public char[]

Returns:

Currently active (last) content segment
getBufferWithoutReset
()

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

public char[]
public int
public char[]

Returns:

Aggregated char[] that contains all buffered content
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.

public int
public boolean

Returns:

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

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

public void
releaseBuffers()

Method called to indicate that the underlying buffers should now be recycled if they haven't yet been recycled.

public void
resetWith(char
Character to set as the buffer contents
ch
)

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

public void
resetWithCopy(char[]
Buffer that contains new contents
buf
,
int
Offset of the first content character in buf
offset
,
int
Length of content in buf
len
)

public void
resetWithCopy(String
String that contains new contents
text
,
int
Offset of the first content character in text
start
,
int
Length of content in text
len
)

public void
resetWithEmpty()

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

public void
resetWithShared(char[]
Buffer that contains shared contents
buf
,
int
Offset of the first content character in buf
offset
,
int
Length of content in buf
len
)

Method called to initialize the buffer with a shared copy of data; this means that buffer will just have pointers to actual data.

public void
resetWithString(String
to replace existing buffer
value
)

private char[]
public String

Returns:

String that contains all buffered content
setCurrentAndReturn
(int
Length of content (in characters) of the current active segment
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()).

public void
public int

Returns:

Number of characters currently stored in this buffer
size
()

public String
toString()

Overrides java.lang.Object.toString.

Note

calling this method may not be as efficient as calling contentsAsString, since it's not guaranteed that resulting String is cached.

private void
unshare(int needExtra)

Method called if/when we need to append content when we have been initialized to use shared buffer.

private void
validateAppend(int toAppend)

protected void
validateStringLength(int
Length of string in input units
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.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

_allocatorback to summary
private final BufferRecycler _allocator
_currentSegmentback to summary
private char[] _currentSegment
_currentSizeback to summary
private int _currentSize

Number of characters in currently active (last) segment

_hasSegmentsback to summary
private boolean _hasSegments

Flag that indicates whether _seqments is non-empty

_inputBufferback to summary
private char[] _inputBuffer

Shared input buffer; stored here in case some input can be returned as is, without being copied to collector's own buffers. Note that this is read-only for this Object.

_inputLenback to summary
private int _inputLen
_inputStartback to summary
private int _inputStart

Character offset of first char in input buffer; -1 to indicate that input buffer currently does not contain any useful char data

_resultArrayback to summary
private char[] _resultArray
_resultStringback to summary
private String _resultString

String that will be constructed when the whole contents are needed; will be temporarily stored in case asked for again.

_segmentsback to summary
private ArrayList<char[]> _segments

List of segments prior to currently active segment.

_segmentSizeback to summary
private int _segmentSize

Amount of characters in segments in _segments

MAX_SEGMENT_LENback to summary
pack-priv static final int MAX_SEGMENT_LEN

Let's limit maximum segment length to something sensible. For 2.10, let's limit to using 64kc chunks (128 kB) -- was 256kC/512kB up to 2.9

MIN_SEGMENT_LENback to summary
pack-priv static final int MIN_SEGMENT_LEN

Let's start with sizable but not huge buffer, will grow as necessary

Reduced from 1000 down to 500 in 2.10.

NO_CHARSback to summary
pack-priv static final char[] NO_CHARS

Constructor Detail

TextBufferback to summary
public TextBuffer(BufferRecycler allocator)
TextBufferback to summary
protected TextBuffer(BufferRecycler allocator, char[] initialSegment)

Method Detail

_doTrimback to summary
private String _doTrim(int ptr) throws IOException
_reportBufferOverflowback to summary
protected void _reportBufferOverflow(int prev, int curr)
appendback to summary
public void append(char c) throws IOException
Parameters
c:char

char to append

Exceptions
IOException:
if the buffer has grown too large, see com.fasterxml.jackson.core.StreamReadConstraints.Builder#maxStringLength(int)
appendback to summary
public void append(char[] c, int start, int len) throws IOException
Parameters
c:char[]

char array to append

start:int

the start index within the array (from which we read chars to append)

len:int

number of chars to take from the array

Exceptions
IOException:
if the buffer has grown too large, see com.fasterxml.jackson.core.StreamReadConstraints.Builder#maxStringLength(int)
appendback to summary
public void append(String str, int offset, int len) throws IOException
Parameters
str:String

string to append

offset:int

the start index within the string (from which we read chars to append)

len:int

number of chars to take from the string

Exceptions
IOException:
if the buffer has grown too large, see com.fasterxml.jackson.core.StreamReadConstraints.Builder#maxStringLength(int)
bufback to summary
private char[] buf(int needed)
bufferRecyclerback to summary
public BufferRecycler bufferRecycler()
Since
2.17
carrback to summary
private char[] carr(int len)
clearSegmentsback to summary
private void clearSegments()
contentsAsArrayback to summary
public char[] contentsAsArray() throws IOException
Returns:char[]

char array

Exceptions
IOException:
if the text is too large, see com.fasterxml.jackson.core.StreamReadConstraints.Builder#maxStringLength(int)
contentsAsDecimalback to summary
public BigDecimal contentsAsDecimal() throws NumberFormatException

Deprecated

Since 2.15 use contentsAsDecimal(boolean) instead.

Annotations
@Deprecated
contentsAsDecimalback to summary
public BigDecimal contentsAsDecimal(final boolean useFastParser) throws NumberFormatException
Since
2.18
contentsAsDoubleback to summary
public double contentsAsDouble(final boolean useFastParser) throws NumberFormatException

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

Note

Caller MUST validate contents before calling this method, to ensure textual version is valid JSON floating-point token -- this method is not guaranteed to do any validation and behavior with invalid content is not defined (either throws an exception or returns arbitrary number).

Parameters
useFastParser:boolean

whether to use FastDoubleParser

Returns:double

Buffered text value parsed as a Double, if possible

Exceptions
NumberFormatException:
may (but is not guaranteed!) be thrown if contents are not a valid JSON floating-point number representation
Since
2.14
contentsAsDoubleback to summary
public double contentsAsDouble() throws NumberFormatException

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

Returns:double

Buffered text value parsed as a Double, if possible

Annotations
@Deprecated
Exceptions
NumberFormatException:
if contents are not a valid Java number
contentsAsFloatback to summary
public float contentsAsFloat() throws NumberFormatException

Deprecated

use contentsAsFloat(boolean)

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

Returns:float

Buffered text value parsed as a Float, if possible

Annotations
@Deprecated
Exceptions
NumberFormatException:
if contents are not a valid Java number
contentsAsFloatback to summary
public float contentsAsFloat(final boolean useFastParser) throws NumberFormatException

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

Note

Caller MUST validate contents before calling this method, to ensure textual version is valid JSON floating-point token -- this method is not guaranteed to do any validation and behavior with invalid content is not defined (either throws an exception or returns arbitrary number).

Parameters
useFastParser:boolean

whether to use FastDoubleParser

Returns:float

Buffered text value parsed as a Float, if possible

Exceptions
NumberFormatException:
may (but is not guaranteed!) be thrown if contents are not a valid JSON floating-point number representation
Since
2.14
contentsAsIntback to summary
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:boolean

Whether contents start with a minus sign

Returns:int

Buffered text value parsed as an int using NumberInput#parseInt(String) method (which does NOT validate input)

Since
2.9
contentsAsLongback to summary
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:boolean

Whether contents start with a minus sign

Returns:long

Buffered text value parsed as an long using NumberInput#parseLong(String) method (which does NOT validate input)

Since
2.9
contentsAsStringback to summary
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:String

Aggregated buffered contents as a java.lang.String

Exceptions
IOException:
if the contents are too large, see com.fasterxml.jackson.core.StreamReadConstraints.Builder#maxStringLength(int)
contentsToWriterback to summary
public int contentsToWriter(Writer w) throws IOException

Accessor that will write buffered contents using given Writer.

Parameters
w:Writer

Writer to use for writing out buffered content

Returns:int

Number of characters written (same as size())

Exceptions
IOException:
If write using Writer parameter fails
Since
2.8
emptyAndGetCurrentSegmentback to summary
public char[] emptyAndGetCurrentSegment()
ensureNotSharedback to summary
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.

expandback to summary
private void expand()
expandCurrentSegmentback to summary
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:char[]

Expanded current segment

expandCurrentSegmentback to summary
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:int

Required minimum strength of the current segment

Returns:char[]

Expanded current segment

Since
2.4
finishAndReturnback to summary
public String finishAndReturn(int lastSegmentEnd, boolean trimTrailingSpaces) throws IOException
Parameters
lastSegmentEnd:int

End offset in the currently active segment, could be 0 in the case of first character is delimiter or end-of-line

trimTrailingSpaces:boolean

Whether trailing spaces should be trimmed or not

Returns:String

token as text

Exceptions
IOException:
If length constraints (of longest allowed Text value) are violated
Since
2.15
finishCurrentSegmentback to summary
public char[] finishCurrentSegment() throws IOException
Returns:char[]

char array

Exceptions
IOException:
if the text is too large, see com.fasterxml.jackson.core.StreamReadConstraints.Builder#maxStringLength(int)
fromInitialback to summary
public static TextBuffer fromInitial(char[] initialSegment)

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

Parameters
initialSegment:char[]

Initial, full segment to use for creating buffer (buffer size() would return length of initialSegment)

Returns:TextBuffer

TextBuffer constructed

Since
2.10
getBufferWithoutResetback to summary
public char[] getBufferWithoutReset()

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

Returns:char[]

Currently active (last) content segment

Since
2.9
getCurrentSegmentback to summary
public char[] getCurrentSegment()
getCurrentSegmentSizeback to summary
public int getCurrentSegmentSize()
getTextBufferback to summary
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:char[]

Aggregated char[] that contains all buffered content

Exceptions
IOException:
if the text is too large, see com.fasterxml.jackson.core.StreamReadConstraints.Builder#maxStringLength(int)
getTextOffsetback to summary
public int getTextOffset()
hasTextAsCharactersback to summary
public boolean hasTextAsCharacters()

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

Returns:boolean

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

releaseBuffersback to summary
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.

resetWithback to summary
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:char

Character to set as the buffer contents

Since
2.9
resetWithCopyback to summary
public void resetWithCopy(char[] buf, int offset, int len) throws IOException
Parameters
buf:char[]

Buffer that contains new contents

offset:int

Offset of the first content character in buf

len:int

Length of content in buf

Exceptions
IOException:
if the buffer has grown too large, see com.fasterxml.jackson.core.StreamReadConstraints.Builder#maxStringLength(int)
resetWithCopyback to summary
public void resetWithCopy(String text, int start, int len) throws IOException
Parameters
text:String

String that contains new contents

start:int

Offset of the first content character in text

len:int

Length of content in text

Exceptions
IOException:
if the buffer has grown too large, see com.fasterxml.jackson.core.StreamReadConstraints.Builder#maxStringLength(int)
Since
2.9
resetWithEmptyback to summary
public void resetWithEmpty()

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

resetWithSharedback to summary
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:char[]

Buffer that contains shared contents

offset:int

Offset of the first content character in buf

len:int

Length of content in buf

resetWithStringback to summary
public void resetWithString(String value) throws IOException
Parameters
value:String

to replace existing buffer

Exceptions
IOException:
if the value is too large, see com.fasterxml.jackson.core.StreamReadConstraints.Builder#maxStringLength(int)
resultArrayback to summary
private char[] resultArray() throws IOException
setCurrentAndReturnback to summary
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:int

Length of content (in characters) of the current active segment

Returns:String

String that contains all buffered content

Exceptions
IOException:
if the text is too large, see com.fasterxml.jackson.core.StreamReadConstraints.Builder#maxStringLength(int)
Since
2.6
setCurrentLengthback to summary
public void setCurrentLength(int len)
sizeback to summary
public int size()
Returns:int

Number of characters currently stored in this buffer

toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Note

calling this method may not be as efficient as calling contentsAsString, since it's not guaranteed that resulting String is cached.

Returns:String

Doc from java.lang.Object.toString.

a string representation of the object

Annotations
@Override
unshareback to summary
private void unshare(int needExtra)

Method called if/when we need to append content when we have been initialized to use shared buffer.

validateAppendback to summary
private void validateAppend(int toAppend) throws IOException
validateStringLengthback to summary
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:int

Length of string in input units

Exceptions
IOException:
If length exceeds maximum
Since
2.15