Package com.sleepycat.bind.tuple

## Class TupleOutput

- java.lang.Object
- - java.io.OutputStream
  - - com.sleepycat.util.FastOutputStream
    - - com.sleepycat.bind.tuple.TupleOutput

- All Implemented Interfaces:
    `java.io.Closeable`, `java.io.Flushable`, `java.lang.AutoCloseable`

      public class TupleOutput
      extends FastOutputStream

  An `OutputStream` with `DataOutput`-like methods for writing tuple fields. It is used by `TupleBinding`.

  This class has many methods that have the same signatures as methods in the `DataOutput` interface. The reason this class does not implement `DataOutput` is because it would break the interface contract for those methods because of data format differences.

  See Also:
    Tuple Formats

- - ### Field Summary

    - ### Fields inherited from class com.sleepycat.util.FastOutputStream

      `DEFAULT_BUMP_SIZE, DEFAULT_INIT_SIZE`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `TupleOutput()` | Creates a tuple output object for writing a byte array of tuple data.
    `TupleOutput​(byte[] buffer)` | Creates a tuple output object for writing a byte array of tuple data, using a given buffer.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static int` | `getBigDecimalMaxByteLength​(java.math.BigDecimal val)` | Returns the maximum byte length that would be output for a given `BigDecimal` value if `writeBigDecimal(java.math.BigDecimal)` were called.
    `static int` | `getBigIntegerByteLength​(java.math.BigInteger val)` | Returns the exact byte length that would would be output for a given `BigInteger` value if `writeBigInteger(java.math.BigInteger)` were called.
    `static int` | `getSortedBigDecimalMaxByteLength​(java.math.BigDecimal val)` | Returns the maximum byte length that would be output for a given `BigDecimal` value if `writeSortedBigDecimal(java.math.BigDecimal)` were called.
    `TupleOutput` | `writeBigDecimal​(java.math.BigDecimal val)` | Writes an unsorted `BigDecimal`.
    `TupleOutput` | `writeBigInteger​(java.math.BigInteger val)` | Writes a `BigInteger`.
    `TupleOutput` | `writeBoolean​(boolean val)` | Writes a boolean (one byte) unsigned value to the buffer, writing one if the value is true and zero if it is false.
    `TupleOutput` | `writeByte​(int val)` | Writes an signed byte (one byte) value to the buffer.
    `TupleOutput` | `writeBytes​(char[] chars)` | Writes the specified bytes to the buffer, converting each character to an unsigned byte value.
    `TupleOutput` | `writeBytes​(java.lang.String val)` | Writes the specified bytes to the buffer, converting each character to an unsigned byte value.
    `TupleOutput` | `writeChar​(int val)` | Writes a char (two byte) unsigned value to the buffer.
    `TupleOutput` | `writeChars​(char[] chars)` | Writes the specified characters to the buffer, converting each character to a two byte unsigned value.
    `TupleOutput` | `writeChars​(java.lang.String val)` | Writes the specified characters to the buffer, converting each character to a two byte unsigned value.
    `TupleOutput` | `writeDouble​(double val)` | Writes an unsorted double (eight byte) value to the buffer.
    `TupleOutput` | `writeFloat​(float val)` | Writes an unsorted float (four byte) value to the buffer.
    `TupleOutput` | `writeInt​(int val)` | Writes an signed int (four byte) value to the buffer.
    `TupleOutput` | `writeLong​(long val)` | Writes an signed long (eight byte) value to the buffer.
    `TupleOutput` | `writePackedInt​(int val)` | Writes an unsorted packed integer.
    `TupleOutput` | `writePackedLong​(long val)` | Writes an unsorted packed long integer.
    `TupleOutput` | `writeShort​(int val)` | Writes an signed short (two byte) value to the buffer.
    `TupleOutput` | `writeSortedBigDecimal​(java.math.BigDecimal val)` | Writes a sorted `BigDecimal`.
    `TupleOutput` | `writeSortedDouble​(double val)` | Writes a sorted double (eight byte) value to the buffer.
    `TupleOutput` | `writeSortedFloat​(float val)` | Writes a sorted float (four byte) value to the buffer.
    `TupleOutput` | `writeSortedPackedInt​(int val)` | Writes a sorted packed integer.
    `TupleOutput` | `writeSortedPackedLong​(long val)` | Writes a sorted packed long integer.
    `TupleOutput` | `writeString​(char[] chars)` | Writes the specified characters to the buffer, converting each character to UTF format.
    `TupleOutput` | `writeString​(java.lang.String val)` | Writes the specified characters to the buffer, converting each character to UTF format, and adding a null terminator byte.
    `TupleOutput` | `writeUnsignedByte​(int val)` | Writes an unsigned byte (one byte) value to the buffer.
    `TupleOutput` | `writeUnsignedInt​(long val)` | Writes an unsigned int (four byte) value to the buffer.
    `TupleOutput` | `writeUnsignedShort​(int val)` | Writes an unsigned short (two byte) value to the buffer.

    - ### Methods inherited from class com.sleepycat.util.FastOutputStream

      `addSize, getBufferBytes, getBufferLength, getBufferOffset, makeSpace, reset, size, toByteArray, toString, toString, write, write, write, writeFast, writeFast, writeFast, writeTo`

    - ### Methods inherited from class java.io.OutputStream

      `close, flush, nullOutputStream`

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

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

- - ### Constructor Detail

    - #### TupleOutput

          public TupleOutput()

      Creates a tuple output object for writing a byte array of tuple data.

    - #### TupleOutput

          public TupleOutput​(byte[] buffer)

      Creates a tuple output object for writing a byte array of tuple data, using a given buffer. A new buffer will be allocated only if the number of bytes needed is greater than the length of this buffer. A reference to the byte array will be kept by this object and therefore the byte array should not be modified while this object is in use.
      Parameters:
        `buffer` - is the byte array to use as the buffer.

  - ### Method Detail

    - #### writeBytes

          public final TupleOutput writeBytes​(java.lang.String val)

      Writes the specified bytes to the buffer, converting each character to an unsigned byte value. Writes values that can be read using `TupleInput.readBytes(int)`.
      Parameters:
        `val` - is the string containing the values to be written. Only characters with values below 0x100 may be written using this method, since the high-order 8 bits of all characters are discarded.
      Returns:
        this tuple output object.
      Throws:
        `java.lang.NullPointerException` - if the val parameter is null.
      See Also:
        Integer Formats

    - #### writeChars

          public final TupleOutput writeChars​(java.lang.String val)

      Writes the specified characters to the buffer, converting each character to a two byte unsigned value. Writes values that can be read using `TupleInput.readChars(int)`.
      Parameters:
        `val` - is the string containing the characters to be written.
      Returns:
        this tuple output object.
      Throws:
        `java.lang.NullPointerException` - if the val parameter is null.
      See Also:
        Integer Formats

    - #### writeString

          public final TupleOutput writeString​(java.lang.String val)

      Writes the specified characters to the buffer, converting each character to UTF format, and adding a null terminator byte. Writes values that can be read using `TupleInput.readString()`.
      Parameters:
        `val` - is the string containing the characters to be written.
      Returns:
        this tuple output object.
      See Also:
        String Formats

    - #### writeChar

          public final TupleOutput writeChar​(int val)

      Writes a char (two byte) unsigned value to the buffer. Writes values that can be read using `TupleInput.readChar()`.
      Parameters:
        `val` - is the value to write to the buffer.
      Returns:
        this tuple output object.
      See Also:
        Integer Formats

    - #### writeBoolean

          public final TupleOutput writeBoolean​(boolean val)

      Writes a boolean (one byte) unsigned value to the buffer, writing one if the value is true and zero if it is false. Writes values that can be read using `TupleInput.readBoolean()`.
      Parameters:
        `val` - is the value to write to the buffer.
      Returns:
        this tuple output object.
      See Also:
        Integer Formats

    - #### writeByte

          public final TupleOutput writeByte​(int val)

      Writes an signed byte (one byte) value to the buffer. Writes values that can be read using `TupleInput.readByte()`.
      Parameters:
        `val` - is the value to write to the buffer.
      Returns:
        this tuple output object.
      See Also:
        Integer Formats

    - #### writeShort

          public final TupleOutput writeShort​(int val)

      Writes an signed short (two byte) value to the buffer. Writes values that can be read using `TupleInput.readShort()`.
      Parameters:
        `val` - is the value to write to the buffer.
      Returns:
        this tuple output object.
      See Also:
        Integer Formats

    - #### writeInt

          public final TupleOutput writeInt​(int val)

      Writes an signed int (four byte) value to the buffer. Writes values that can be read using `TupleInput.readInt()`.
      Parameters:
        `val` - is the value to write to the buffer.
      Returns:
        this tuple output object.
      See Also:
        Integer Formats

    - #### writeLong

          public final TupleOutput writeLong​(long val)

      Writes an signed long (eight byte) value to the buffer. Writes values that can be read using `TupleInput.readLong()`.
      Parameters:
        `val` - is the value to write to the buffer.
      Returns:
        this tuple output object.
      See Also:
        Integer Formats

    - #### writeFloat

          public final TupleOutput writeFloat​(float val)

      Writes an unsorted float (four byte) value to the buffer. Writes values that can be read using `TupleInput.readFloat()`.
      Parameters:
        `val` - is the value to write to the buffer.
      Returns:
        this tuple output object.
      See Also:
        Floating Point Formats

    - #### writeDouble

          public final TupleOutput writeDouble​(double val)

      Writes an unsorted double (eight byte) value to the buffer. Writes values that can be read using `TupleInput.readDouble()`.
      Parameters:
        `val` - is the value to write to the buffer.
      Returns:
        this tuple output object.
      See Also:
        Floating Point Formats

    - #### writeSortedFloat

          public final TupleOutput writeSortedFloat​(float val)

      Writes a sorted float (four byte) value to the buffer. Writes values that can be read using `TupleInput.readSortedFloat()`.
      Parameters:
        `val` - is the value to write to the buffer.
      Returns:
        this tuple output object.
      See Also:
        Floating Point Formats

    - #### writeSortedDouble

          public final TupleOutput writeSortedDouble​(double val)

      Writes a sorted double (eight byte) value to the buffer. Writes values that can be read using `TupleInput.readSortedDouble()`.
      Parameters:
        `val` - is the value to write to the buffer.
      Returns:
        this tuple output object.
      See Also:
        Floating Point Formats

    - #### writeBytes

          public final TupleOutput writeBytes​(char[] chars)

      Writes the specified bytes to the buffer, converting each character to an unsigned byte value. Writes values that can be read using `TupleInput.readBytes(int)`.
      Parameters:
        `chars` - is the array of values to be written. Only characters with values below 0x100 may be written using this method, since the high-order 8 bits of all characters are discarded.
      Returns:
        this tuple output object.
      Throws:
        `java.lang.NullPointerException` - if the chars parameter is null.
      See Also:
        Integer Formats

    - #### writeChars

          public final TupleOutput writeChars​(char[] chars)

      Writes the specified characters to the buffer, converting each character to a two byte unsigned value. Writes values that can be read using `TupleInput.readChars(int)`.
      Parameters:
        `chars` - is the array of characters to be written.
      Returns:
        this tuple output object.
      Throws:
        `java.lang.NullPointerException` - if the chars parameter is null.
      See Also:
        Integer Formats

    - #### writeString

          public final TupleOutput writeString​(char[] chars)

      Writes the specified characters to the buffer, converting each character to UTF format. Writes values that can be read using `TupleInput.readString(int)` or `TupleInput.readString(char[])`.
      Parameters:
        `chars` - is the array of characters to be written.
      Returns:
        this tuple output object.
      Throws:
        `java.lang.NullPointerException` - if the chars parameter is null.
      See Also:
        String Formats

    - #### writeUnsignedByte

          public final TupleOutput writeUnsignedByte​(int val)

      Writes an unsigned byte (one byte) value to the buffer. Writes values that can be read using `TupleInput.readUnsignedByte()`.
      Parameters:
        `val` - is the value to write to the buffer.
      Returns:
        this tuple output object.
      See Also:
        Integer Formats

    - #### writeUnsignedShort

          public final TupleOutput writeUnsignedShort​(int val)

      Writes an unsigned short (two byte) value to the buffer. Writes values that can be read using `TupleInput.readUnsignedShort()`.
      Parameters:
        `val` - is the value to write to the buffer.
      Returns:
        this tuple output object.
      See Also:
        Integer Formats

    - #### writeUnsignedInt

          public final TupleOutput writeUnsignedInt​(long val)

      Writes an unsigned int (four byte) value to the buffer. Writes values that can be read using `TupleInput.readUnsignedInt()`.
      Parameters:
        `val` - is the value to write to the buffer.
      Returns:
        this tuple output object.
      See Also:
        Integer Formats

    - #### writePackedInt

          public final TupleOutput writePackedInt​(int val)

      Writes an unsorted packed integer.
      Parameters:
        `val` - is the value to write to the buffer.
      Returns:
        this tuple output object.
      See Also:
        Integer Formats

    - #### writePackedLong

          public final TupleOutput writePackedLong​(long val)

      Writes an unsorted packed long integer.
      Parameters:
        `val` - is the value to write to the buffer.
      Returns:
        this tuple output object.
      See Also:
        Integer Formats

    - #### writeSortedPackedInt

          public final TupleOutput writeSortedPackedInt​(int val)

      Writes a sorted packed integer.
      Parameters:
        `val` - is the value to write to the buffer.
      Returns:
        this tuple output object.
      See Also:
        Integer Formats

    - #### writeSortedPackedLong

          public final TupleOutput writeSortedPackedLong​(long val)

      Writes a sorted packed long integer.
      Parameters:
        `val` - is the value to write to the buffer.
      Returns:
        this tuple output object.
      See Also:
        Integer Formats

    - #### writeBigInteger

          public final TupleOutput writeBigInteger​(java.math.BigInteger val)

      Writes a `BigInteger`.
      Parameters:
        `val` - is the value to write to the buffer.
      Returns:
        this tuple output object.
      Throws:
        `java.lang.NullPointerException` - if val is null.
        `java.lang.IllegalArgumentException` - if the byte array representation of val is larger than 0x7fff bytes.
      See Also:
        Integer Formats

    - #### getBigIntegerByteLength

          public static int getBigIntegerByteLength​(java.math.BigInteger val)

      Returns the exact byte length that would would be output for a given `BigInteger` value if `writeBigInteger(java.math.BigInteger)` were called.
      Parameters:
        `val` - the BigInteger
      Returns:
        the byte length.
      See Also:
        Integer Formats

    - #### writeBigDecimal

          public final TupleOutput writeBigDecimal​(java.math.BigDecimal val)

      Writes an unsorted `BigDecimal`.
      Parameters:
        `val` - is the value to write to the buffer.
      Returns:
        this tuple output object.
      Throws:
        `java.lang.NullPointerException` - if val is null.
      See Also:
        BigDecimal Formats

    - #### getBigDecimalMaxByteLength

          public static int getBigDecimalMaxByteLength​(java.math.BigDecimal val)

      Returns the maximum byte length that would be output for a given `BigDecimal` value if `writeBigDecimal(java.math.BigDecimal)` were called.
      Parameters:
        `val` - the BigDecimal.
      Returns:
        the byte length.
      See Also:
        BigDecimal Formats

    - #### writeSortedBigDecimal

          public final TupleOutput writeSortedBigDecimal​(java.math.BigDecimal val)

      Writes a sorted `BigDecimal`.
      Parameters:
        `val` - is the value to write to the buffer.
      Returns:
        this tuple output object.
      See Also:
        BigDecimal Formats

    - #### getSortedBigDecimalMaxByteLength

          public static int getSortedBigDecimalMaxByteLength​(java.math.BigDecimal val)

      Returns the maximum byte length that would be output for a given `BigDecimal` value if `writeSortedBigDecimal(java.math.BigDecimal)` were called.
      Parameters:
        `val` - the BigDecimal.
      Returns:
        the byte length.
      See Also:
        BigDecimal Formats

Copyright (c) 1996, 2020 Oracle and/or its affiliates. All rights reserved.