array.h

Go to the documentation of this file.

/* Copyright (C) 2017-2018 Chris Piker <chris-piker@uiowa.edu>
 *
 * This file is part of libdas2, the Core Das2 C Library.
 *
 * Libdas2 is free software; you can redistribute it and/or modify it under
 * the terms of the GNU Lesser General Public License version 2.1 as published
 * by the Free Software Foundation.
 *
 * Libdas2 is distributed in the hope that it will be useful, but WITHOUT ANY
 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 * FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for
 * more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * version 2.1 along with libdas2; if not, see <http://www.gnu.org/licenses/>.
 */

/* I'm sure this kind of buffer has been done many times before, but I haven't
 * seen an implementation that handles arbitrarily ragged arrays.  Thanks to
 * Larry Granroth, and Matt Leifert for helping me talk through the issues 
 * around this class.  
 * -cwp
 */

#ifndef _das_array_h_
#define _das_array_h_

#include <stdarg.h>
#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>

#include <das2/value.h>
#include <das2/units.h>

#ifdef __cplusplus
extern "C" {
#endif


#define DASIDX_MAX 16
   
/* WARNING!  If the values below change, update das_varindex_merge */
/*           and update das_varlength_merge */
   
#define DASIDX_RAGGED -1
#define DASIDX_FUNC   -2
#define DASIDX_UNUSED -3   

#define DASIDX_INIT_UNUSED {-3,-3,-3,-3,-3,-3,-3,-3,-3,-3,-3,-3,-3,-3,-3,-3}
#define DASIDX_INIT_BEGIN { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0}
   
char* das_shape_prnRng(
   ptrdiff_t* pShape, int iFirstInternal, int nShapeLen, char* sBuf, int nBufLen
);


#define RANK_1(I) 1, (size_t[1]){I}
#define RANK_2(I, J) 2, (size_t[2]){I, J}
#define RANK_3(I, J, K) 3, (size_t[3]){I, J, K}
#define RANK_4(I, J, K, L) 4, (size_t[4]){I, J, K, L}
#define RANK_5(I, J, K, L, M) 5, (size_t[5]){I, J, K, L, M}
#define RANK_6(I, J, K, L, M, N) 6, (size_t[6]){I, J, K, L, M, N}
#define RANK_7(I, J, K, L, M, N, O) 7, (size_t[7]){I, J, K, L, M, N, O}
#define RANK_8(I, J, K, L, M, N, O, P) 8, (size_t[8]){I, J, K, L, M, N, O, P}

#define DIM0  0, (NULL)
#define DIM1_AT(I)  1, (ptrdiff_t[1]){I}
#define DIM2_AT(I,J)  2, (ptrdiff_t[2]){I,J}
#define DIM3_AT(I,J,K)  3, (ptrdiff_t[3]){I,J,K}
#define DIM4_AT(I,J,K,L)  4, (ptrdiff_t[4]){I,J,K,L}
#define DIM5_AT(I,J,K,L,M)  5, (ptrdiff_t[5]){I,J,K,L,M}
#define DIM6_AT(I,J,K,L,M,N)  6, (ptrdiff_t[6]){I,J,K,L,M,N}
#define DIM7_AT(I,J,K,L,M,N,O)  7, (ptrdiff_t[7]){I,J,K,L,M,N,O}

#define IDX0(I) (ptrdiff_t[1]){I}
#define IDX1(I,J) (ptrdiff_t[2]){I,J}
#define IDX2(I,J,K) (ptrdiff_t[3]){I,J,K}
#define IDX3(I,J,K,L) (ptrdiff_t[4]){I,J,K,L}
#define IDX4(I,J,K,L,M) (ptrdiff_t[5]){I,J,K,L,M}
#define IDX5(I,J,K,L,M,N) (ptrdiff_t[6]){I,J,K,L,M,N}
#define IDX6(I,J,K,L,M,N,O) (ptrdiff_t[7]){I,J,K,L,M,N,O}
#define IDX7(I,J,K,L,M,N,O,P) (ptrdiff_t[8]){I,J,K,L,M,N,O,P}

#define DIM1 1
#define DIM2 2
#define DIM3 3
#define DIM4 4
#define DIM5 5
#define DIM6 6
#define DIM7 7

/* Higher dimensions are handled by index buffers.  These are the elements for
 * the index buffers */
typedef struct child_info_t{
   ptrdiff_t nOffset;        /* Start of child elements data in child buffer */
   size_t uCount;            /* The count child elements in child buffer     */
}das_idx_info;

typedef struct dyna_buf{
   /* Stores the fill value as a hidden item below the first index */
   byte* pBuf;               /* The beginning a continuous buffer uSize long */
   byte* pHead;              /* The beginning of valid values in the buffer  */
   /*byte* pWrite;*/         /* The beginning of the append point for the buffer */
   size_t uSize;             /* The amount of space in the backing buffer    */
   size_t uValid;            /* The number of valid elements in this buffer  */
   size_t uElemSz;           /* The number of bytes occupied by each element */
   byte* pFill;              /* Pointer to fill value buffer */
   byte  fillBuf[sizeof(das_idx_info)];        /* Storage for short fill items */

   size_t uChunkSz;           /* Alloc helper, if set, allocate in even chunks
                               * of this size. */
   size_t uShape;             /* Qube helper, how many items in this array per
                               * parent item, 0 means ragged */
   das_val_type etype;       /* The element type */

   bool bRollParent;          /* The end mark.  If set, adding data to the array
                               * will clear the end mark and trigger creation of
                               * a new parent.  If this is set on all indexes
                               * attempting to add data will fail */

   bool bKeepMem;            /* If true memory will not be deleted when the
                              * buffer is deleted */
} DynaBuf;

typedef struct das_array {
   char        sId[64];   /* A text identifier of this instance of the array */
   int           nRank;   /* The number of index dimensions for the array */
   das_idx_info*   pIdx0;   /* top lever container, may not point here */

   /* bool      bTopOwned;*/   /* Same as pIdx0 == &index0 */
   das_idx_info   index0;   /* Storage for element 0 of buffer 0, if needed */

   /* Pointers to item arrays.  One array is needed for each dimension,
    * these may point to internal locations if the array is owned */
   DynaBuf*  pBufs[DASIDX_MAX];

   /* bool     bOwned[16]; */   /* Same as pBufs[i] == bufs + i */
   DynaBuf    bufs[DASIDX_MAX];    /* Storage for dynamic buffers, if needed */

   /* Current compare function, set automatically if a known type is used,
    * otherwise user needs to supply their own */
   int (*compare)(const void* vpFirst, const void* vpSecond);

   /* Where to send/read data when streaming */
   int nSrcPktId;
   size_t uStartItem;
   size_t uItems;
   
   /* Since so many datasets and functions can reference the same array,
    * a reference count is needed to make sure they aren't deleted if 
    * still in use. */
   int refcount;
   
   unsigned int uFlags;      /* Store flags indicating intended use */
   
   das_units units;

} DasAry;


DasAry* new_DasAry(
   const char* id, das_val_type et, size_t sz_each, const void* fill,
   int rank, size_t* shape, das_units units
);

#define D2ARY_AS_SUBSEQ 0x00000001

#define D2ARY_FILL_TERM 0x00000003

#define D2ARY_AS_STRING 0x00000007

unsigned int DasAry_setUsage(DasAry* pThis, unsigned int uFlags);

unsigned int DasAry_getUsage(DasAry* pThis);

int inc_DasAry(DasAry* pThis);

int ref_DasAry(const DasAry* pThis);

void dec_DasAry(DasAry* pThis);


byte* DasAry_disownElements(DasAry* pThis, size_t* pLen);

const char* DasAry_id(const DasAry* pThis);

int DasAry_rank(const DasAry* pThis);

das_units DasAry_units(const DasAry* pThis);

enum das_val_type DasAry_valType(const DasAry* pThis);

const char* DasAry_valTypeStr(const DasAry* pThis);

char* DasAry_toStr(const DasAry* pThis, char* sInfo, size_t uLen);

size_t DasAry_size(const DasAry* pThis);

size_t DasAry_valSize(const DasAry* pThis);


size_t DasAry_lengthIn(const DasAry* pThis, int nIdx, ptrdiff_t* pLoc);

int DasAry_shape(const DasAry* pThis, ptrdiff_t* pShape);


const void* DasAry_getFill(const DasAry* pThis);


bool DasAry_validAt(const DasAry* pThis, ptrdiff_t* pLoc);

const void* DasAry_getAt(const DasAry* pThis, das_val_type et, ptrdiff_t* pLoc);

#define DasAry_getFloatAt(pThis, pLoc)  *((float*)(DasAry_getAt(pThis, vtFloat, pLoc)))

#define DasAry_getDoubleAt(pThis, pLoc)  *((double*)(DasAry_getAt(pThis, vtDouble, pLoc)))

#define DasAry_getByteAt(pThis, pLoc)  *((byte*)(DasAry_getAt(pThis, vtByte, pLoc)))

#define DasAry_getUShortAt(pThis, pLoc)  *((uint16_t*)(DasAry_getAt(pThis, etUint16, pLoc)))

#define DasAry_getShortAt(pThis, pLoc)  *((int16_t*)(DasAry_getAt(pThis, etInt16, pLoc)))

#define DasAry_getIntAt(pThis, pLoc)  *((int32_t*)(DasAry_getAt(pThis, etInt32, pLoc)))

#define DasAry_getLongAt(pThis, pLoc)  *((int64_t*)(DasAry_getAt(pThis, etInt64, pLoc)))

#define DasAry_getTimeAt(pThis, pLoc)  *((das_time*)(DasAry_getAt(pThis, vtTime, pLoc)))

#define DasAry_getTextAt(pThis, pLoc)  *((char**)(DasAry_getAt(pThis, vtText, pLoc)))


bool DasAry_putAt(DasAry* pThis, ptrdiff_t* pStart, const void* pVals, size_t uVals);

const void* DasAry_getIn(
   const DasAry* pThis, das_val_type et, int nDim, ptrdiff_t* pLoc, size_t* pCount
);

#define DasAry_getFloatsIn(T, ...) (const float*) DasAry_getIn(T, vtFloat, __VA_ARGS__)

#define DasAry_getDoublesIn(T, ...) (const double*) DasAry_getIn(T, vtDouble, __VA_ARGS__)

#define DasAry_getBytesIn(T, ...) (const byte*) DasAry_getIn(T, vtByte, __VA_ARGS__)

#define DasAry_getUShortsIn(T, ...) (const uint16_t*) DasAry_getIn(T, vtUShort, __VA_ARGS__)

#define DasAry_getShortsIn(T, ...) (const int16_t*) DasAry_getIn(T, vtShort, __VA_ARGS__)

#define DasAry_getIntsIn(T, ...) (const int32_t*) DasAry_getIn(T, vtInt, __VA_ARGS__)

#define DasAry_getLongsIn(T, ...) (const int64_t*) DasAry_getIn(T, vtLong, __VA_ARGS__)

#define DasAry_getTimesIn(T, ...) (const das_time*) DasAry_getIn(T, vtTime, __VA_ARGS__)

#define DasAry_getTextIn(T, ...) (const char**) DasAry_getIn(T, vtText, __VA_ARGS__)

DasAry* DasAry_subSetIn(
   const DasAry* pThis, const char* id, int nIndices, ptrdiff_t* pLoc
);

size_t DasAry_qubeIn(DasAry* pThis, int iRecDim);

bool DasAry_append(DasAry* pThis, const void* pVals, size_t uCount);

void DasAry_markEnd(DasAry* pThis, int iDim);

/* Remove some number of records in a given index.
 *
 * This does not actually delete any data it just removes references to it.
 * Thus any subsets of this array will still reference the existing values.
 *
 * @see rmLastRec() for the definition of a record
 */
/* size_t Array_rmHead(Array* pThis, size_t uCount, int nIndex);*/

/* Remove N records from the end of the array
 *
 * For rank 1 arrays, a 'record' is just a single value, for higher rank
 * arrays a record is the number of values represented by a change in the
 * first index.  For example, for the array:
 * @code
 *    a[][10][4]
 * @endcode
 * calling
 * @code
 *   rmTail(pArray, 2)
 * @endcode
 * will result in 80 individual values being remove from the array.
 *
 * @param pThis the array to change
 * @param uRecs the number of records to remove.  If uRecs is greater than
 *        the shape of the first index, everything is removed and an error
 *        is thrown.
 * @returns The new size of the array
 * @memberof DasAry
 */
/* size_t Array_rmTail(Array* pThis, size_t uRecs); */

size_t DasAry_clear(DasAry* pThis);

int DasAry_cmp(DasAry* pThis, const void* vpFirst, const void* vpSecond );

void DasAry_setSrc(DasAry* pThis, int nPktId, size_t uStartItem, size_t uItems);


#ifdef __cplusplus
}
#endif

#endif /* _das_array_h_ */