Package org.apache.datasketches.memory

Interface Memory

  • All Superinterfaces:
    AutoCloseable, Resource
    All Known Subinterfaces:
    WritableMemory
    public interface Memory
extends Resource
    Defines the read-only API for offset access to a resource.

    The classes in this package are not thread-safe.

    Author:
    Lee Rhodes

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      default Buffer asBuffer()
      Returns a new Buffer view of this object.
      Buffer asBuffer​(ByteOrder byteOrder)
      Returns a new Buffer view of this object, with the given byte order.
      int compareTo​(long thisOffsetBytes, long thisLengthBytes, Memory that, long thatOffsetBytes, long thatLengthBytes)
      Compares the bytes of this Memory to that Memory.
      void copyTo​(long srcOffsetBytes, WritableMemory destination, long dstOffsetBytes, long lengthBytes)
      Copies bytes from a source range of this Memory to a destination range of the given Memory with the same semantics when copying between overlapping ranges of bytes as method System.arraycopy(Object, int, Object, int, int) has.
      boolean getBoolean​(long offsetBytes)
      Gets the boolean value at the given offset
      void getBooleanArray​(long offsetBytes, boolean[] dstArray, int dstOffsetBooleans, int lengthBooleans)
      Gets the boolean array at the given offset
      byte getByte​(long offsetBytes)
      Gets the byte value at the given offset
      void getByteArray​(long offsetBytes, byte[] dstArray, int dstOffsetBytes, int lengthBytes)
      Gets the byte array at the given offset
      char getChar​(long offsetBytes)
      Gets the char value at the given offset
      void getCharArray​(long offsetBytes, char[] dstArray, int dstOffsetChars, int lengthChars)
      Gets the char array at the given offset
      int getCharsFromUtf8​(long offsetBytes, int utf8LengthBytes, Appendable dst)
      Gets UTF-8 encoded bytes from this Memory, starting at offsetBytes to a length of utf8LengthBytes, decodes them into characters and appends them to the given Appendable.
      int getCharsFromUtf8​(long offsetBytes, int utf8LengthBytes, StringBuilder dst)
      Gets UTF-8 encoded bytes from this Memory, starting at offsetBytes to a length of utf8LengthBytes, decodes them into characters and appends them to the given StringBuilder.
      double getDouble​(long offsetBytes)
      Gets the double value at the given offset
      void getDoubleArray​(long offsetBytes, double[] dstArray, int dstOffsetDoubles, int lengthDoubles)
      Gets the double array at the given offset
      float getFloat​(long offsetBytes)
      Gets the float value at the given offset
      void getFloatArray​(long offsetBytes, float[] dstArray, int dstOffsetFloats, int lengthFloats)
      Gets the float array at the given offset
      int getInt​(long offsetBytes)
      Gets the int value at the given offset
      void getIntArray​(long offsetBytes, int[] dstArray, int dstOffsetInts, int lengthInts)
      Gets the int array at the given offset
      long getLong​(long offsetBytes)
      Gets the long value at the given offset
      void getLongArray​(long offsetBytes, long[] dstArray, int dstOffsetLongs, int lengthLongs)
      Gets the long array at the given offset
      short getShort​(long offsetBytes)
      Gets the short value at the given offset
      void getShortArray​(long offsetBytes, short[] dstArray, int dstOffsetShorts, int lengthShorts)
      Gets the short array at the given offset
      static Memory map​(File file)
      Maps the entire given file into native-ordered Memory for read operations Calling this method is equivalent to calling map(file, 0, file.length(), ByteOrder.nativeOrder()).
      static Memory map​(File file, long fileOffsetBytes, long capacityBytes, ByteOrder byteOrder)
      Maps the specified portion of the given file into Memory for read operations.
      default Memory region​(long offsetBytes, long capacityBytes)
      A region is a read-only view of this object.
      Memory region​(long offsetBytes, long capacityBytes, ByteOrder byteOrder)
      A region is a read-only view of this object.
      static Memory wrap​(boolean[] array)
      Wraps the given primitive array for read operations assuming native byte order.
      static Memory wrap​(byte[] array)
      Wraps the given primitive array for read operations assuming native byte order.
      static Memory wrap​(byte[] array, int offsetBytes, int lengthBytes, ByteOrder byteOrder)
      Wraps the given primitive array for read operations with the given byte order.
      static Memory wrap​(byte[] array, ByteOrder byteOrder)
      Wraps the given primitive array for read operations with the given byte order.
      static Memory wrap​(char[] array)
      Wraps the given primitive array for read operations assuming native byte order.
      static Memory wrap​(double[] array)
      Wraps the given primitive array for read operations assuming native byte order.
      static Memory wrap​(float[] array)
      Wraps the given primitive array for read operations assuming native byte order.
      static Memory wrap​(int[] array)
      Wraps the given primitive array for read operations assuming native byte order.
      static Memory wrap​(long[] array)
      Wraps the given primitive array for read operations assuming native byte order.
      static Memory wrap​(short[] array)
      Wraps the given primitive array for read operations assuming native byte order.
      static Memory wrap​(ByteBuffer byteBuffer)
      Accesses the given ByteBuffer for read-only operations.
      static Memory wrap​(ByteBuffer byteBuffer, ByteOrder byteOrder)
      Accesses the given ByteBuffer for read-only operations.
      void writeTo​(long offsetBytes, long lengthBytes, WritableByteChannel out)
      Writes bytes from a source range of this Memory to the given WritableByteChannel.

    • Method Detail

      • wrap

        static Memory wrap​(ByteBuffer byteBuffer)
        Accesses the given ByteBuffer for read-only operations. The returned Memory object has the same byte order, as the given ByteBuffer.
        Parameters:
        byteBuffer - the given ByteBuffer. It must be non-null and with capacity ≥ 0.
        Returns:
        a new Memory for read-only operations on the given ByteBuffer.

      • wrap

        static Memory wrap​(ByteBuffer byteBuffer,
                   ByteOrder byteOrder)
        Accesses the given ByteBuffer for read-only operations. The returned Memory object has the given byte order, ignoring the byte order of the given ByteBuffer for future reads and writes.
        Parameters:
        byteBuffer - the given ByteBuffer. It must be non-null and with capacity ≥ 0.
        byteOrder - the byte order to be used. It must be non-null.
        Returns:
        a new Memory for read-only operations on the given ByteBuffer.

      • map

        static Memory map​(File file)
        Maps the entire given file into native-ordered Memory for read operations Calling this method is equivalent to calling map(file, 0, file.length(), ByteOrder.nativeOrder()).
        Parameters:
        file - the given file to map. It must be non-null, length ≥ 0, and readable.
        Returns:
        Memory for managing the mapped memory.

      • map

        static Memory map​(File file,
                  long fileOffsetBytes,
                  long capacityBytes,
                  ByteOrder byteOrder)
        Maps the specified portion of the given file into Memory for read operations.
        Parameters:
        file - the given file to map. It must be non-null and readable.
        fileOffsetBytes - the position in the given file in bytes. It must not be negative.
        capacityBytes - the size of the mapped memory. It must not be negative.
        byteOrder - the byte order to be used for the mapped memory. It must be non-null.
        Returns:
        Memory for managing the mapped memory.

      • region

        default Memory region​(long offsetBytes,
                      long capacityBytes)
        A region is a read-only view of this object.
        • Returned object's origin = this object's origin + offsetBytes
        • Returned object's capacity = capacityBytes
        Parameters:
        offsetBytes - the starting offset with respect to the origin of this Memory. It must be ≥ 0.
        capacityBytes - the capacity of the region in bytes. It must be ≥ 0.
        Returns:
        a new Memory representing the defined region based on the given offsetBytes and capacityBytes.

      • region

        Memory region​(long offsetBytes,
              long capacityBytes,
              ByteOrder byteOrder)
        A region is a read-only view of this object.
        • Returned object's origin = this object's origin + offsetBytes
        • Returned object's capacity = capacityBytes
        • Returned object's byte order = byteOrder
        Parameters:
        offsetBytes - the starting offset with respect to the origin of this Memory. It must be ≥ 0.
        capacityBytes - the capacity of the region in bytes. It must be ≥ 0.
        byteOrder - the given byte order. It must be non-null.
        Returns:
        a new Memory representing the defined region based on the given offsetBytes, capacityBytes and byteOrder.

      • asBuffer

        default Buffer asBuffer()
        Returns a new Buffer view of this object.
        • Returned object's origin = this object's origin
        • Returned object's start = 0
        • Returned object's position = 0
        • Returned object's end = this object's capacity
        • Returned object's capacity = this object's capacity
        • Returned object's start, position and end are mutable
        Returns:
        a new Buffer

      • asBuffer

        Buffer asBuffer​(ByteOrder byteOrder)
        Returns a new Buffer view of this object, with the given byte order.
        • Returned object's origin = this object's origin
        • Returned object's start = 0
        • Returned object's position = 0
        • Returned object's end = this object's capacity
        • Returned object's capacity = this object's capacity
        • Returned object's start, position and end are mutable
        Parameters:
        byteOrder - the given byte order
        Returns:
        a new Buffer with the given byteOrder.

      • wrap

        static Memory wrap​(byte[] array)
        Wraps the given primitive array for read operations assuming native byte order.
        Parameters:
        array - the given primitive array.
        Returns:
        a new Memory for read operations

      • wrap

        static Memory wrap​(byte[] array,
                   ByteOrder byteOrder)
        Wraps the given primitive array for read operations with the given byte order.
        Parameters:
        array - the given primitive array.
        byteOrder - the byte order to be used
        Returns:
        a new Memory for read operations

      • wrap

        static Memory wrap​(byte[] array,
                   int offsetBytes,
                   int lengthBytes,
                   ByteOrder byteOrder)
        Wraps the given primitive array for read operations with the given byte order.
        Parameters:
        array - the given primitive array.
        offsetBytes - the byte offset into the given array
        lengthBytes - the number of bytes to include from the given array
        byteOrder - the byte order to be used
        Returns:
        a new Memory for read operations

      • wrap

        static Memory wrap​(boolean[] array)
        Wraps the given primitive array for read operations assuming native byte order.
        Parameters:
        array - the given primitive array.
        Returns:
        a new Memory for read operations

      • wrap

        static Memory wrap​(char[] array)
        Wraps the given primitive array for read operations assuming native byte order.
        Parameters:
        array - the given primitive array.
        Returns:
        a new Memory for read operations

      • wrap

        static Memory wrap​(short[] array)
        Wraps the given primitive array for read operations assuming native byte order.
        Parameters:
        array - the given primitive array.
        Returns:
        a new Memory for read operations

      • wrap

        static Memory wrap​(int[] array)
        Wraps the given primitive array for read operations assuming native byte order.
        Parameters:
        array - the given primitive array.
        Returns:
        a new Memory for read operations

      • wrap

        static Memory wrap​(long[] array)
        Wraps the given primitive array for read operations assuming native byte order.
        Parameters:
        array - the given primitive array.
        Returns:
        a new Memory for read operations

      • wrap

        static Memory wrap​(float[] array)
        Wraps the given primitive array for read operations assuming native byte order.
        Parameters:
        array - the given primitive array.
        Returns:
        a new Memory for read operations

      • wrap

        static Memory wrap​(double[] array)
        Wraps the given primitive array for read operations assuming native byte order.
        Parameters:
        array - the given primitive array.
        Returns:
        a new Memory for read operations

      • getBoolean

        boolean getBoolean​(long offsetBytes)
        Gets the boolean value at the given offset
        Parameters:
        offsetBytes - offset bytes relative to this Memory start
        Returns:
        the boolean at the given offset

      • getBooleanArray

        void getBooleanArray​(long offsetBytes,
                     boolean[] dstArray,
                     int dstOffsetBooleans,
                     int lengthBooleans)
        Gets the boolean array at the given offset
        Parameters:
        offsetBytes - offset bytes relative to this Memory start
        dstArray - The preallocated destination array.
        dstOffsetBooleans - offset in array units
        lengthBooleans - number of array units to transfer

      • getByte

        byte getByte​(long offsetBytes)
        Gets the byte value at the given offset
        Parameters:
        offsetBytes - offset bytes relative to this Memory start
        Returns:
        the byte at the given offset

      • getByteArray

        void getByteArray​(long offsetBytes,
                  byte[] dstArray,
                  int dstOffsetBytes,
                  int lengthBytes)
        Gets the byte array at the given offset
        Parameters:
        offsetBytes - offset bytes relative to this Memory start
        dstArray - The preallocated destination array.
        dstOffsetBytes - offset in array units
        lengthBytes - number of array units to transfer

      • getChar

        char getChar​(long offsetBytes)
        Gets the char value at the given offset
        Parameters:
        offsetBytes - offset bytes relative to this Memory start
        Returns:
        the char at the given offset

      • getCharArray

        void getCharArray​(long offsetBytes,
                  char[] dstArray,
                  int dstOffsetChars,
                  int lengthChars)
        Gets the char array at the given offset
        Parameters:
        offsetBytes - offset bytes relative to this Memory start
        dstArray - The preallocated destination array.
        dstOffsetChars - offset in array units
        lengthChars - number of array units to transfer

      • getCharsFromUtf8

        int getCharsFromUtf8​(long offsetBytes,
                     int utf8LengthBytes,
                     Appendable dst)
              throws IOException,
                     Utf8CodingException
        Gets UTF-8 encoded bytes from this Memory, starting at offsetBytes to a length of utf8LengthBytes, decodes them into characters and appends them to the given Appendable. This is specifically designed to reduce the production of intermediate objects (garbage), thus significantly reducing pressure on the JVM Garbage Collector.
        Parameters:
        offsetBytes - offset bytes relative to the Memory start
        utf8LengthBytes - the number of encoded UTF-8 bytes to decode. It is assumed that the caller has the correct number of utf8 bytes required to decode the number of characters to be appended to dst. Characters outside the ASCII range can require 2, 3 or 4 bytes per character to decode.
        dst - the destination Appendable to append the decoded characters to.
        Returns:
        the number of characters decoded
        Throws:
        IOException - if dst.append() throws IOException
        Utf8CodingException - in case of malformed or illegal UTF-8 input

      • getCharsFromUtf8

        int getCharsFromUtf8​(long offsetBytes,
                     int utf8LengthBytes,
                     StringBuilder dst)
              throws Utf8CodingException
        Gets UTF-8 encoded bytes from this Memory, starting at offsetBytes to a length of utf8LengthBytes, decodes them into characters and appends them to the given StringBuilder. This method does *not* reset the length of the destination StringBuilder before appending characters to it. This is specifically designed to reduce the production of intermediate objects (garbage), thus significantly reducing pressure on the JVM Garbage Collector.
        Parameters:
        offsetBytes - offset bytes relative to the Memory start
        utf8LengthBytes - the number of encoded UTF-8 bytes to decode. It is assumed that the caller has the correct number of utf8 bytes required to decode the number of characters to be appended to dst. Characters outside the ASCII range can require 2, 3 or 4 bytes per character to decode.
        dst - the destination StringBuilder to append decoded characters to.
        Returns:
        the number of characters decoded.
        Throws:
        Utf8CodingException - in case of malformed or illegal UTF-8 input

      • getDouble

        double getDouble​(long offsetBytes)
        Gets the double value at the given offset
        Parameters:
        offsetBytes - offset bytes relative to this Memory start
        Returns:
        the double at the given offset

      • getDoubleArray

        void getDoubleArray​(long offsetBytes,
                    double[] dstArray,
                    int dstOffsetDoubles,
                    int lengthDoubles)
        Gets the double array at the given offset
        Parameters:
        offsetBytes - offset bytes relative to this Memory start
        dstArray - The preallocated destination array.
        dstOffsetDoubles - offset in array units
        lengthDoubles - number of array units to transfer

      • getFloat

        float getFloat​(long offsetBytes)
        Gets the float value at the given offset
        Parameters:
        offsetBytes - offset bytes relative to this Memory start
        Returns:
        the float at the given offset

      • getFloatArray

        void getFloatArray​(long offsetBytes,
                   float[] dstArray,
                   int dstOffsetFloats,
                   int lengthFloats)
        Gets the float array at the given offset
        Parameters:
        offsetBytes - offset bytes relative to this Memory start
        dstArray - The preallocated destination array.
        dstOffsetFloats - offset in array units
        lengthFloats - number of array units to transfer

      • getInt

        int getInt​(long offsetBytes)
        Gets the int value at the given offset
        Parameters:
        offsetBytes - offset bytes relative to this Memory start
        Returns:
        the int at the given offset

      • getIntArray

        void getIntArray​(long offsetBytes,
                 int[] dstArray,
                 int dstOffsetInts,
                 int lengthInts)
        Gets the int array at the given offset
        Parameters:
        offsetBytes - offset bytes relative to this Memory start
        dstArray - The preallocated destination array.
        dstOffsetInts - offset in array units
        lengthInts - number of array units to transfer

      • getLong

        long getLong​(long offsetBytes)
        Gets the long value at the given offset
        Parameters:
        offsetBytes - offset bytes relative to this Memory start
        Returns:
        the long at the given offset

      • getLongArray

        void getLongArray​(long offsetBytes,
                  long[] dstArray,
                  int dstOffsetLongs,
                  int lengthLongs)
        Gets the long array at the given offset
        Parameters:
        offsetBytes - offset bytes relative to this Memory start
        dstArray - The preallocated destination array.
        dstOffsetLongs - offset in array units
        lengthLongs - number of array units to transfer

      • getShort

        short getShort​(long offsetBytes)
        Gets the short value at the given offset
        Parameters:
        offsetBytes - offset bytes relative to this Memory start
        Returns:
        the short at the given offset

      • getShortArray

        void getShortArray​(long offsetBytes,
                   short[] dstArray,
                   int dstOffsetShorts,
                   int lengthShorts)
        Gets the short array at the given offset
        Parameters:
        offsetBytes - offset bytes relative to this Memory start
        dstArray - The preallocated destination array.
        dstOffsetShorts - offset in array units
        lengthShorts - number of array units to transfer

      • compareTo

        int compareTo​(long thisOffsetBytes,
              long thisLengthBytes,
              Memory that,
              long thatOffsetBytes,
              long thatLengthBytes)
        Compares the bytes of this Memory to that Memory. Returns (this < that) ? (some negative value) : (this > that) ? (some positive value) : 0;. If all bytes are equal up to the shorter of the two lengths, the shorter length is considered to be less than the other.
        Parameters:
        thisOffsetBytes - the starting offset for this Memory
        thisLengthBytes - the length of the region to compare from this Memory
        that - the other Memory to compare with
        thatOffsetBytes - the starting offset for that Memory
        thatLengthBytes - the length of the region to compare from that Memory
        Returns:
        (this < that) ? (some negative value) : (this > that) ? (some positive value) : 0;

      • copyTo

        void copyTo​(long srcOffsetBytes,
            WritableMemory destination,
            long dstOffsetBytes,
            long lengthBytes)
        Copies bytes from a source range of this Memory to a destination range of the given Memory with the same semantics when copying between overlapping ranges of bytes as method System.arraycopy(Object, int, Object, int, int) has. However, if the source and the destination ranges are exactly the same, this method throws IllegalArgumentException, because it should never be needed in real-world scenarios and therefore indicates a bug.
        Parameters:
        srcOffsetBytes - the source offset for this Memory
        destination - the destination Memory, which may not be Read-Only.
        dstOffsetBytes - the destination offset
        lengthBytes - the number of bytes to copy

      • writeTo

        void writeTo​(long offsetBytes,
             long lengthBytes,
             WritableByteChannel out)
      throws IOException
        Writes bytes from a source range of this Memory to the given WritableByteChannel.
        Parameters:
        offsetBytes - the source offset for this Memory
        lengthBytes - the number of bytes to copy
        out - the destination WritableByteChannel
        Throws:
        IOException - may occur while writing to the WritableByteChannel