Package uk.ac.bristol.star.cdf.record
Interface Buf
- All Known Implementing Classes:
BankBuf
,SimpleNioBuf
,WrapperBuf
public interface Buf
Represents a sequence of bytes along with operations to read
primitive values from it.
This interface abstracts away implementation details such as storage
mechanism, data encoding and pointer length.
It is capable of dealing with 64-bit lengths and offsets.
All of the
read*
methods are safe for use from multiple
threads concurrently.- Since:
- 18 Jun 2013
-
Method Summary
Modifier and TypeMethodDescriptioncreateInputStream
(long offset) Returns an input stream consisting of all the bytes in this buf starting from the given offset.fillNewBuf
(long count, InputStream in) Creates a new Buf of a given length populated from a given input stream.long
Returns the extent of this buf in bytes.boolean
Determines the data encoding of this buf.boolean
isBit64()
Determines the 64bit-ness of this buf.readAsciiString
(Pointer ptr, int nbyte) Reads a fixed number of bytes interpreting them as ASCII characters and returns the result as a string.void
readDataBytes
(long offset, int count, byte[] array) Reads a sequence of byte values from this buf into an array.void
readDataDoubles
(long offset, int count, double[] array) Reads a sequence of double values from this buf into an array.void
readDataFloats
(long offset, int count, float[] array) Reads a sequence of float values from this buf into an array.void
readDataInts
(long offset, int count, int[] array) Reads a sequence of int values from this buf into an array.void
readDataLongs
(long offset, int count, long[] array) Reads a sequence of long integer values from this buf into an array.void
readDataShorts
(long offset, int count, short[] array) Reads a sequence of short values from this buf into an array.int
Reads a signed big-endian 4-byte integer from the pointer position.long
readOffset
(Pointer ptr) Reads a file offset or size from the pointer position.int
readUnsignedByte
(Pointer ptr) Reads a single byte from the pointer position, returning a value in the range 0..255.void
setBit64
(boolean isBit64) Sets the 64bit-ness of this buf.void
setEncoding
(boolean isBigendian) Sets the encoding for reading numeric values as performed by thereadData*
methods.
-
Method Details
-
getLength
long getLength()Returns the extent of this buf in bytes.- Returns:
- buffer length
-
readUnsignedByte
Reads a single byte from the pointer position, returning a value in the range 0..255. Pointer position is moved on appropriately.- Parameters:
ptr
- pointer- Returns:
- byte value
- Throws:
IOException
-
readInt
Reads a signed big-endian 4-byte integer from the pointer position. Pointer position is moved on appropriately.- Parameters:
ptr
- pointer- Returns:
- integer value
- Throws:
IOException
-
readOffset
Reads a file offset or size from the pointer position. This is a signed big-endian integer, occupying either 4 or 8 bytes according to the return value ofisBit64()
. Pointer position is moved on appropriately.- Returns:
- buffer size or offset value
- Throws:
IOException
-
readAsciiString
Reads a fixed number of bytes interpreting them as ASCII characters and returns the result as a string. If a character 0x00 appears beforenbyte
bytes have been read, it is taken as the end of the string. Pointer position is moved on appropriately.- Parameters:
ptr
- pointernbyte
- maximum number of bytes in string- Returns:
- ASCII string
- Throws:
IOException
-
setBit64
void setBit64(boolean isBit64) Sets the 64bit-ness of this buf. This determines whetherreadOffset
reads 4- or 8-byte values.This method should be called before the
readOffset
method is invoked.- Parameters:
isBit64
- true for 8-byte offsets, false for 4-byte offsets
-
isBit64
boolean isBit64()Determines the 64bit-ness of this buf. This determines whetherreadOffset
reads 4- or 8-byte values.- Returns:
- true for 8-byte offsets, false for 4-byte offsets
-
setEncoding
void setEncoding(boolean isBigendian) Sets the encoding for reading numeric values as performed by thereadData*
methods.As currently specified, there are only two possibiliies, Big-Endian and Little-Endian. Interface and implementation would need to be reworked somewhat to accommodate the (presumably, rarely seen in this day and age) D_FLOAT and G_FLOAT encodings supported by the CDF standard.
This method should be called before any of the
readData*
methods are invoked.- Parameters:
isBigendian
- true for big-endian, false for little-endian
-
isBigendian
boolean isBigendian()Determines the data encoding of this buf.- Returns:
- true for big-endian, false for little-endian
-
readDataBytes
Reads a sequence of byte values from this buf into an array.- Parameters:
offset
- position sequence start in this buffer in bytescount
- number of byte values to readarray
- array to receive values, starting at array element 0- Throws:
IOException
-
readDataShorts
Reads a sequence of short values from this buf into an array.- Parameters:
offset
- position sequence start in this buffer in bytescount
- number of short values to readarray
- array to receive values, starting at array element 0- Throws:
IOException
-
readDataInts
Reads a sequence of int values from this buf into an array.- Parameters:
offset
- position sequence start in this buffer in bytescount
- number of int values to readarray
- array to receive values, starting at array element 0- Throws:
IOException
-
readDataLongs
Reads a sequence of long integer values from this buf into an array.- Parameters:
offset
- position sequence start in this buffer in bytescount
- number of long values to readarray
- array to receive values, starting at array element 0- Throws:
IOException
-
readDataFloats
Reads a sequence of float values from this buf into an array.- Parameters:
offset
- position sequence start in this buffer in bytescount
- number of float values to readarray
- array to receive values, starting at array element 0- Throws:
IOException
-
readDataDoubles
Reads a sequence of double values from this buf into an array.- Parameters:
offset
- position sequence start in this buffer in bytescount
- number of double values to readarray
- array to receive values, starting at array element 0- Throws:
IOException
-
createInputStream
Returns an input stream consisting of all the bytes in this buf starting from the given offset.- Parameters:
offset
- position of first byte in buf that will appear in the returned stream- Returns:
- input stream
-
fillNewBuf
Creates a new Buf of a given length populated from a given input stream. The new buf object must have the same data encoding and 64bit-ness as this one.- Parameters:
count
- size of new buffer in bytesin
- input stream capable of supplying (at least)count
bytes- Returns:
- new buffer of length
count
filled with bytes fromin
- Throws:
IOException
-