## org.das2.qds.buffer.BufferDataSet

rank 1, 2, 3, and 4 datasets backed by NIO buffers. These have the advantage that data can be stored outside of the JVM, and in fact they can be backed by a huge file on disk. This code was copied from BinaryDataSource.

## BufferDataSet( int rank, int reclen, int recoffs, int len0, int len1, int len2, Object type, java.nio.ByteBuffer back )

Create a new BufferDataSet of the given type. Simple sanity checks are made, including:

- rank 1 dataset may not have len1>1.
- reclen cannot be shorter than the byte length of the field type.
- buffer must have room for the dataset

## BufferDataSet( int rank, int reclen, int recoffs, int len0, int len1, int len2, int len3, Object type, java.nio.ByteBuffer back )

Create a new BufferDataSet of the given type. Simple sanity checks are made, including:

- rank 1 dataset may not have len1>1.
- reclen cannot be shorter than the byte length of the field type.
- buffer must have room for the dataset

## BufferDataSet( int rank, int reclen, int recoffs, Object bitByte, int len0, int len1, int len2, int len3, Object type, java.nio.ByteBuffer back )

Create a new BufferDataSet of the given type. Simple sanity checks are made, including:

- rank 1 dataset may not have len1>1.
- reclen cannot be shorter than the byte length of the field type.
- buffer must have room for the dataset

## DOUBLE

the data is in 8 byte doubles.

## FLOAT

the data is in 4 byte floats.

## TRUNCATEDFLOAT

the data is in 16 bit real that has exponent like a FLOAT but mantissa precision is reduced.

## VAX_FLOAT

VAX floats.

## INT24

three-byte ints.

## UINT24

three-byte unsigned ints.

## NYBBLE

four-bit unsigned ints.

## LONG

8 byte signed longs.

## INT

4 byte signed integers.

## INTEGER

4 byte signed integers, INT is canonical but INTEGER should be accepted.

## UINT

4 byte unsigned integers. Note 4-byte signed ints are used to store the data which is unpacked in the value() method.

## SHORT

2 byte short integer.

## USHORT

2 byte unsigned short.

## BYTE

1 byte signed byte.

## UBYTE

1 byte unsigned byte.

## BYTES

constructor units are in bytes.

## BITS

constructor units are in bits.

## about

about( ) → void

print some info about this BufferDataSet.

### Returns:

void (returns nothing)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## append

append( org.das2.qds.buffer.BufferDataSet ds ) → void

append the dataset with the same geometry but different number of records (zeroth dim) to this. An IllegalArgumentException is thrown when there is not enough room. See grow(newRecCount). This buffer's capacity will be something like java.nio.DirectByteBuffer[pos=0 lim=6256 cap=13760] and the dataset ds's buffer will have java.nio.DirectByteBufferR[pos=0 lim=6256 cap=6256]. After this append operation, the buffer of the second will be copied into the first's: java.nio.DirectByteBuffer[pos=0 lim=12512 cap=13760]. Not thread safe--we need to go through and make it so...

### Parameters

ds - a BufferDataSet

### Returns:

void (returns nothing)

### See Also:

grow(int)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## append

append( org.das2.qds.buffer.BufferDataSet ths, org.das2.qds.buffer.BufferDataSet ds ) → org.das2.qds.buffer.BufferDataSet

append the two datasets. The two datasets need only have convertible units, so for example two time arrays may be appended even if their units don't have the same base. Only properties of the two datasets that do not change are preserved.

### Parameters

ths - rank N dataset
ds - rank N dataset of the same type and geometry as ths.

### Returns:

the dataset
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## bitCount

bitCount( Object type ) → int

### Parameters

type - an Object

### Returns:

int
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## byteCount

byteCount( Object type ) → int

return the number of bytes of each type (double=8, etc).

### Parameters

type - DOUBLE, FLOAT, UBYTE, TIME28, etc.

### Returns:

8, 4, 1, etc.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## canAppend

canAppend( org.das2.qds.buffer.BufferDataSet ds ) → boolean

return true if the dataset can be appended. Note this assumes that the same length, etc. This just checks that we have the number of spare records in the backing store.

### Parameters

ds - dataset of the same rank and len1, len2, and len3.

### Returns:

true if the dataset can be appended.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## compact

compact( ) → org.das2.qds.buffer.BufferDataSet

get rid of extra spaces between records.

### Returns:

new BufferDataSet without gaps.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## copy

copy( QDataSet ds ) → org.das2.qds.buffer.BufferDataSet

return a copy of the data. If the data is a BufferDataSet, then a new BufferDataSet is used for the copy. Note this does not consider isMutable. If the dataset is not mutable, then the original data could be returned (probably).

### Parameters

ds - any qube dataset.

### Returns:

a BufferDataSet copy of the dataset.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## copy

copy( Object type, QDataSet ds ) → org.das2.qds.buffer.BufferDataSet

Copy to array of specific type. For example, copy( DOUBLE, ds ) would return a copy in a DoubleDataSet.

### Parameters

type - the primitive type to use (e.g. double.class).
ds - the data to copy.

### Returns:

BufferDataSet of specific type.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## create

create( int rank, Object type, int len0, int[] size ) → org.das2.qds.buffer.BufferDataSet

create a dataset backed by the given type.

### Parameters

rank - the rank of the data
type - DOUBLE, FLOAT, UINT, etc
len0 - number of records (ignored for rank 0).
size - size of each record

### Returns:

BufferDataSet of the given type.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## createRank0

createRank0( Object type ) → org.das2.qds.buffer.BufferDataSet

create a rank 0 dataset backed by the given type.

### Parameters

type - DOUBLE, FLOAT, UINT, etc

### Returns:

BufferDataSet of the given type.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## createRank1

createRank1( Object type, int len0 ) → org.das2.qds.buffer.BufferDataSet

create a rank 1 dataset backed by the given type.

### Parameters

type - DOUBLE, FLOAT, UINT, etc
len0 - length of the zeroth index

### Returns:

BufferDataSet of the given type.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## createRank2

createRank2( Object type, int len0, int len1 ) → org.das2.qds.buffer.BufferDataSet

create a rank 2 dataset backed by the given type.

### Parameters

type - DOUBLE, FLOAT, UINT, etc
len0 - length of the zeroth index
len1 - length of the first index

### Returns:

BufferDataSet of the given type.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## createRank3

createRank3( Object type, int len0, int len1, int len2 ) → org.das2.qds.buffer.BufferDataSet

create a rank 3 dataset backed by the given type.

### Parameters

type - DOUBLE, FLOAT, UINT, etc
len0 - length of the zeroth index
len1 - length of the first index
len2 - length of the second index

### Returns:

BufferDataSet of the given type.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## createRank4

createRank4( Object type, int len0, int len1, int len2, int len3 ) → org.das2.qds.buffer.BufferDataSet

create a rank 4 dataset backed by the given type.

### Parameters

type - DOUBLE, FLOAT, UINT, etc
len0 - length of the zeroth index
len1 - length of the first index
len2 - length of the second index
len3 - length of the third index

### Returns:

BufferDataSet of the given type.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getCompatibleComponentType

getCompatibleComponentType( ) → java.lang.Class

return the Java type that is capable of containing elements of this dataset. For unsigned types, the next Java class is used, for example int.class is used to store unsigned shorts.

### Returns:

double.class, float.class, long.class, etc.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getFieldStride

getFieldStride( ) → int

return the number of bytes to advance for each field.

### Returns:

the number of bytes to advance for each field.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getRecordStride

getRecordStride( ) → int

return the number of bytes to advance for each record.

### Returns:

the number of bytes to advance for each record.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getType

getType( ) → Object

return the type of this dataset, for example BufferDataSet.INT, BufferDataSet.DOUBLE, etc...

### Returns:

the type of this dataset.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## grow

grow( int newRecCount ) → void

grow the internal store so that append may be used to resize the dataset. This simply grows the internal buffer, so for example length() will return the same value after.

### Parameters

newRecCount - the new record count, generally larger than the old rec count.

### Returns:

void (returns nothing)

### See Also:

append(org.das2.qds.buffer.BufferDataSet)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## guessBackingStore

guessBackingStore( QDataSet ds ) → Object

guess the type of the backing store, returning double.class if it cannot be determined.

### Parameters

ds - the dataset

### Returns:

the backing store class, one of double.class, float.class, etc.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## isCompact

isCompact( ) → boolean

returns true if the dataset is compact, meaning that there are no gaps between records, and no byte offset.

### Returns:

true if the dataset is compact
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## jvmMemory

jvmMemory( ) → int

estimate the jvmMemory occupied by this dataset, looking at the NIO buffer to see if it is direct as has no JVM memory cost, or if it has been made into an array.

### Returns:

the estimated number bytes that the dataSet occupies.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## length

length( ) → int

### Returns:

int
[search for examples] [view on GitHub] [view on old javadoc] [view source]
length( int i ) → int [view source]
length( int i0, int i1 ) → int [view source]
length( int i0, int i1, int i2 ) → int [view source]

## makeDataSet

makeDataSet( int rank, int reclen, int recoffs, int len0, int len1, int len2, int len3, java.nio.ByteBuffer buf, Object type ) → org.das2.qds.buffer.BufferDataSet

Make a BufferDataSet of the given type.

### Parameters

rank - the rank (number of indeces) of the data.
reclen - length in bytes of each record. This may be longer than len1*len2*len3*byteCount(type)
recoffs - byte offset of each record
len0 - number of elements in the first index
len1 - number of elements in the second index
len2 - number of elements in the third index
len3 - number of elements in the fourth index
buf - ByteBuffer containing the data, which should be at least recoffs + reclen * len0 bytes long.
type - BufferDataSet.INT, BufferDataSet.DOUBLE, etc...

### Returns:

BufferDataSet of the given type.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## makeDataSet

makeDataSet( int rank, int reclen, int recoffs, int[] qube, java.nio.ByteBuffer buf, Object type ) → org.das2.qds.buffer.BufferDataSet

Make a BufferDataSet of the given type.

### Parameters

rank - the rank (number of indeces) of the data.
reclen - length in bytes of each record
recoffs - byte offset of each record
qube - integer array of the number of elements in each index. If rank is less than the number of elements, then ignore extra trailing elements.
buf - ByteBuffer containing the data, which should be at least recoffs + reclen * len0 bytes long.
type - BufferDataSet.INT, BufferDataSet.DOUBLE, etc...

### Returns:

BufferDataSet of the given type.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## makeDataSetBits

makeDataSetBits( int rank, int reclenbits, int recoffsbits, int len0, int len1, int len2, int len3, java.nio.ByteBuffer buf, Object type ) → org.das2.qds.buffer.BufferDataSet

support binary types that are not a multiple of 8 bits. This was added to support Nybbles, and 12-bit ints.

### Parameters

rank - an int
reclenbits - number of bits per record
recoffsbits - number of bits offset. Note this must be a multiple of 8, for now.
len0 - number of elements in the first index
len1 - number of elements in the second index
len2 - number of elements in the third index
len3 - number of elements in the fourth index
buf - ByteBuffer containing the data, which should be at least recoffsbits/8 + reclenbits/8 * len0 bytes long.
type - BufferDataSet.NYBBLE, etc

### Returns:

BufferDataSet of the given type.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## maybeCopy

maybeCopy( QDataSet ds ) → org.das2.qds.buffer.BufferDataSet

Copy the dataset to an BufferDataSet only if the dataset is not already an BufferDataSet.

### Parameters

ds - a QDataSet

### Returns:

a BufferDataSet.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## rank

rank( ) → int

### Returns:

int
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## setFieldStride

setFieldStride( int bytes ) → void

allow clients to override the cadence of data. By default, this is just the number of bytes in each field.

### Parameters

bytes - number of bytes between field beginnings.

### Returns:

void (returns nothing)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## setLength

setLength( int len0 ) → void

reset the number of records.

### Parameters

len0 - the new number of records.

### Returns:

void (returns nothing)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## setLength1

setLength1( int len1 ) → void

reset the length (in fields) of each record of the rank 2 dataset.

### Parameters

len1 - the length of each record of the rank 2 dataset.

### Returns:

void (returns nothing)

### See Also:

Ops#decimateBufferDataSet(org.das2.qds.buffer.BufferDataSet, int, int)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## setRecordStride

setRecordStride( int bytes ) → void

allow clients to override the cadece of the records. By default, this is the number of bytes in each record.

### Parameters

bytes - number of bytes between record beginnings.

### Returns:

void (returns nothing)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## shouldAllocateDirect

shouldAllocateDirect( ) → int

return 1 if direct allocate should be used, 0 if not. Direct allocations are memory allocations outside of the JVM heap memory. (The internal variable has a -1 initial state, which is why this is not boolean.) This looks for 32bit Javas, and if more than 1/2 Gig is being used then it will allocate direct. This is because 32bit Javas cannot access any memory outside of 1Gig.

### Returns:

1 or 0 if direct allocations should not be made.

### See Also:

https://sourceforge.net/p/autoplot/bugs/1395/
http://stackoverflow.com/questions/807263/how-do-i-detect-which-kind-of-jre-is-installed-32bit-vs-64bit
http://stackoverflow.com/questions/3651737/why-the-odd-performance-curve-differential-between-bytebuffer-allocate-and-byt "How ByteBuffer works and why Direct (Byte) "How ByteBuffer works and why Direct (Byte)Buffers are the only truly useful now"
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## slice

slice( int i ) → QDataSet

### Parameters

i - an int

### Returns:

org.das2.qds.QDataSet
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## trim

trim( int ist, int ien ) → QDataSet

### Parameters

ist - an int
ien - an int

### Returns:

org.das2.qds.QDataSet
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## typeFor

typeFor( java.lang.Class c ) → Object

Return the type for the given class. Note that there is a type for each native type (Byte,Short,Float,etc), but not a class for each type. (E.g. UBYTE is unsigned byte.)

### Parameters

c - java class

### Returns:

DOUBLE,FLOAT,etc.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## value

value( ) → double

### Returns:

double
[search for examples] [view on GitHub] [view on old javadoc] [view source]
value( int i0 ) → double [view source]
value( int i0, int i1 ) → double [view source]
value( int i0, int i1, int i2 ) → double [view source]
value( int i0, int i1, int i2, int i3 ) → double [view source]