array.h

Go to the documentation of this file.

/* Copyright (C) 2017-2024 Chris Piker <chris-piker@uiowa.edu>
 *
 * This file is part of das2C, the Core Das2 C Library.
 *
 * Das2C 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.
 *
 * Das2C 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 das2C; 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 <das3/value.h>
#include <das3/units.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
#define ARYIDX_MAX 8
 
#define ARYIDX_LAST {-1,-1,-1,-1,-1,-1,-1,-1}
 
#define ARYIDX_UNBOUND 0
 
#define VARIDX_RAGGED -1
 
DAS_API extern const char g_sIdxLower[ARYIDX_MAX];
DAS_API extern const char g_sIdxUpper[ARYIDX_MAX];
   
#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
 
#define RNG_1(i,I) 1, (ptrdiff_t[1]){i}, (ptrdiff_t[1]){I}
#define RNG_2(i,I,j,J) 2, (ptrdiff_t[2]){i,j}, (ptrdiff_t[2]){I,J}
#define RNG_3(i,I,j,J,k,K) 3, (ptrdiff_t[3]){i,j,k}, (ptrdiff_t[3]){I,J,K}
#define RNG_4(i,I,j,J,k,K,l,L) 4, (ptrdiff_t[4]){i,j,k,l}, (ptrdiff_t[4]){I,J,K,L}
#define RNG_5(i,I,j,J,k,K,l,L,m,M) 5, (ptrdiff_t[5]){i,j,k,l,m}, (ptrdiff_t[5]){I,J,K,L,M}
#define RNG_6(i,I,j,J,k,K,l,L,m,M,n,N) 6, (ptrdiff_t[6]){i,j,k,l,m,n}, (ptrdiff_t[6]){I,J,K,L,M,N}
#define RNG_7(i,I,j,J,k,K,l,L,m,M,n,N,o,O) 7, (ptrdiff_t[7]){i,j,k,l,m,n,o}, (ptrdiff_t[7]){I,J,K,L,M,N,O}
 
DAS_API int das_rng2shape(
   int nRngRank, const ptrdiff_t* pMin, const ptrdiff_t* pMax, size_t* pShape
);
 
/* 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{
   
   ubyte* pBuf;               /* The beginning a continuous buffer uSize long */
   ubyte* pHead;              /* The beginning of valid values in the buffer  */
   /*ubyte* 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 */
   
   ubyte* pFill;              /* Pointer to fill value buffer */
   ubyte  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[DAS_MAX_ID_BUFSZ];   /* 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[ARYIDX_MAX];
 
   /* bool     bOwned[16]; */   /* Same as pBufs[i] == &(bufs[i]) */
   DynaBuf    bufs[ARYIDX_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 ubyte* vpFirst, const ubyte* 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;
   
   /* Used to notify the owner of my memory that I'm not using it anymore. */
   struct das_array* pMemOwner;
   
   unsigned int uFlags;      /* Store flags indicating intended use */
   
   das_units units;
 
   void* pUser;
 
} DasAry;
 
DAS_API DasAry* new_DasAry(
   const char* id, das_val_type et, size_t sz_each, const ubyte* fill,
   int rank, size_t* shape, das_units units
);
 
 
DAS_API bool DasAry_init(
   DasAry* pThis, const char* id, das_val_type et, size_t sz_each,
   const ubyte* fill, int rank, size_t* shape, das_units units
);
 
DAS_API DasAry* new_DasPtrAry(const char* sType, int rank, size_t* shape);
 
#define D2ARY_AS_SUBSEQ 0x00000001
 
#define D2ARY_FILL_TERM 0x00000003
 
#define D2ARY_AS_STRING 0x00000007
 
DAS_API unsigned int DasAry_setUsage(DasAry* pThis, unsigned int uFlags);
 
DAS_API unsigned int DasAry_getUsage(DasAry* pThis);
 
DAS_API int inc_DasAry(DasAry* pThis);
 
DAS_API int ref_DasAry(const DasAry* pThis);
 
DAS_API void dec_DasAry(DasAry* pThis);
 
DAS_API void DasAry_deInit(DasAry* pThis);
 
 
DAS_API ubyte* DasAry_disownElements(
   DasAry* pThis, size_t* pLen, size_t* pOffset
);
 
DAS_API bool DasAry_ownsElements(const DasAry* pThis);
 
DAS_API const char* DasAry_id(const DasAry* pThis);
 
DAS_API void DasAry_setId(DasAry* pThis, const char* sId);
 
#define DasAry_rank(pThis) pThis->nRank
 
/* DAS_API int DasAry_rank(const DasAry* pThis); */
 
DAS_API das_units DasAry_units(const DasAry* pThis);
 
DAS_API das_val_type DasAry_valType(const DasAry* pThis);
 
DAS_API const char* DasAry_valTypeStr(const DasAry* pThis);
 
DAS_API char* DasAry_toStr(const DasAry* pThis, char* sInfo, size_t uLen);
 
DAS_API size_t DasAry_size(const DasAry* pThis);
 
DAS_API size_t DasAry_valSize(const DasAry* pThis);
 
 
DAS_API size_t DasAry_memUsed(const DasAry* pThis);
 
DAS_API size_t DasAry_memOwned(const DasAry* pThis);
 
 
DAS_API size_t DasAry_memIndexed(const DasAry* pThis);
 
 
DAS_API size_t DasAry_lengthIn(const DasAry* pThis, int nIdx, ptrdiff_t* pLoc);
 
DAS_API size_t DasAry_itemsIn(const DasAry* pThis, int nIdx, ptrdiff_t* pLoc);
 
DAS_API int DasAry_shape(const DasAry* pThis, ptrdiff_t* pShape);
 
 
DAS_API int DasAry_stride(
   const DasAry* pThis, ptrdiff_t* pShape, ptrdiff_t* pStride
);
 
DAS_API const ubyte* DasAry_getFill(const DasAry* pThis);
 
DAS_API bool DasAry_setFill(DasAry* pThis, das_val_type vt, const ubyte* pFill);
 
 
DAS_API bool DasAry_validAt(const DasAry* pThis, ptrdiff_t* pLoc);
 
DAS_API const ubyte* 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)  *((ubyte*)(DasAry_getAt(pThis, vtUByte, 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)))
 
#define DasAry_getPtrAt(pThis, pLoc)  *((void**)(DasAry_getAt(pThis, vtUnknown, pLoc)))
 
 
DAS_API bool DasAry_putAt(DasAry* pThis, ptrdiff_t* pStart, const ubyte* pVals, size_t uVals);
 
DAS_API const ubyte* DasAry_getIn(
   const DasAry* pThis, das_val_type et, int nDim, ptrdiff_t* pLoc, size_t* pCount
);
 
DAS_API ubyte* DasAry_getBuf(
   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_getCharsIn(T, ...) (const char*) DasAry_getIn(T, vtUByte, __VA_ARGS__)
 
#define DasAry_getBytesIn(T, ...) (const ubyte*) DasAry_getIn(T, vtUByte, __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__)
 
DAS_API const ubyte* DasAry_getAllVals(
   const DasAry* pThis, size_t* pElSize, size_t* pElements
);
 
DAS_API DasAry* DasAry_subSetIn(
   DasAry* pThis, const char* id, int nIndices, ptrdiff_t* pLoc
);
 
DAS_API size_t DasAry_qubeIn(DasAry* pThis, int iRecDim);
 
DAS_API ubyte* DasAry_append(DasAry* pThis, const ubyte* pVals, size_t uCount);
 
DAS_API 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 DasAry_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 DasAry_rmTail(Array* pThis, size_t uRecs); */
 
DAS_API size_t DasAry_clear(DasAry* pThis);
 
DAS_API int DasAry_cmp(DasAry* pThis, const ubyte* vpFirst, const ubyte* vpSecond );
 
DAS_API void DasAry_setSrc(DasAry* pThis, int nPktId, size_t uStartItem, size_t uItems);
 
 
#ifdef __cplusplus
}
#endif
 
#endif /* _das_array_h_ */