Package com.fasterxml.jackson.core.util

Class TextBuffer

  • Direct Known Subclasses:
    ReadConstrainedTextBuffer
    public 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.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method 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()
      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).
      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.
      int contentsToWriter​(java.io.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.
      java.lang.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​(java.lang.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​(java.lang.String value)  
      java.lang.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()  
      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

        equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

    • Constructor Detail

    • 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 java.io.IOException
        Parameters:
        buf - Buffer that contains new contents
        offset - Offset of the first content character in buf
        len - Length of content in buf
        Throws:
        java.io.IOException - if the buffer has grown too large, see StreamReadConstraints.Builder.maxStringLength(int)

      • resetWithCopy

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

      • resetWithString

        public void resetWithString​(java.lang.String value)
                     throws java.io.IOException
        Parameters:
        value - to replace existing buffer
        Throws:
        java.io.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 java.io.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:
        java.io.IOException - if the text is too large, see StreamReadConstraints.Builder.maxStringLength(int)

      • contentsAsString

        public java.lang.String contentsAsString()
                                  throws java.io.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:
        java.io.IOException - if the contents are too large, see StreamReadConstraints.Builder.maxStringLength(int)

      • contentsAsDouble

        public double contentsAsDouble​(boolean useFastParser)
                        throws java.lang.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:
        java.lang.NumberFormatException - if contents are not a valid Java number
        Since:
        2.14

      • contentsAsDouble

        @Deprecated
public double contentsAsDouble()
                        throws java.lang.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:
        java.lang.NumberFormatException - if contents are not a valid Java number

      • contentsAsFloat

        @Deprecated
public float contentsAsFloat()
                      throws java.lang.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:
        java.lang.NumberFormatException - if contents are not a valid Java number

      • contentsAsFloat

        public float contentsAsFloat​(boolean useFastParser)
                      throws java.lang.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:
        java.lang.NumberFormatException - if contents are not a valid Java number
        Since:
        2.14

      • contentsAsDecimal

        @Deprecated
public java.math.BigDecimal contentsAsDecimal()
                                       throws java.lang.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:
        java.lang.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​(java.io.Writer w)
                     throws java.io.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:
        java.io.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,
                   int start,
                   int len)
            throws java.io.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:
        java.io.IOException - if the buffer has grown too large, see StreamReadConstraints.Builder.maxStringLength(int)

      • append

        public void append​(java.lang.String str,
                   int offset,
                   int len)
            throws java.io.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:
        java.io.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 java.lang.String setCurrentAndReturn​(int len)
                                     throws java.io.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:
        java.io.IOException - if the text is too large, see StreamReadConstraints.Builder.maxStringLength(int)
        Since:
        2.6

      • finishAndReturn

        public java.lang.String finishAndReturn​(int lastSegmentEnd,
                                        boolean trimTrailingSpaces)
                                 throws java.io.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:
        java.io.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 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