variable.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/>.
 */
 
#ifndef _das_variable_h_
#define _das_variable_h_
 
#include <das2/array.h>
#include <das2/datum.h>
 
#include "units.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* Current max length of a vector (internal index) can be changed */
#define D2V_MAX_VEC_LEN 4  
 
enum var_type { 
   D2V_CONST, D2V_SEQUENCE, D2V_ARRAY, D2V_UNARY_OP, D2V_BINARY_OP
};
 
#ifdef _D
#error macro _D already defined, pick something else
#else
#define _D DASIDX_UNUSED
#endif 
 
 
#define SCALAR_0  0, (NULL), 0
#define SCALAR_1(I)  1, (int8_t[DASIDX_MAX]){I,_D,_D,_D,_D,_D,_D,_D}, 0
#define SCALAR_2(I,J)  2, (int8_t[DASIDX_MAX]){I,J,_D,_D,_D,_D,_D,_D}, 0
#define SCALAR_3(I,J,K)  3, (int8_t[DASIDX_MAX]){I,J,K,_D,_D,_D,_D,_D}, 0
#define SCALAR_4(I,J,K,L)  4, (int8_t[DASIDX_MAX]){I,J,K,L,_D,_D,_D,_D}, 0
#define SCALAR_5(I,J,K,L,M)  5, (int8_t[DASIDX_MAX]){I,J,K,L,M,_D,_D,_D}, 0
#define SCALAR_6(I,J,K,L,M,N)  6, (int8_t[DASIDX_MAX]){I,J,K,L,M,N,_D,_D}, 0
#define SCALAR_7(I,J,K,L,M,N,O)  7, (int8_t[DASIDX_MAX]){I,J,K,L,M,N,O,_D}, 0
#define SCALAR_8(I,J,K,L,M,N,O,P)  8, (int8_t[DASIDX_MAX]){I,J,K,L,M,N,O,P}, 0
 
#define VEC_0   0, (int8_t[DASIDX_MAX]){_D,_D,_D,_D,_D,_D,_D,_D}, 1
#define VEC_1(I)  1, (int8_t[DASIDX_MAX]){I,_D,_D,_D,_D,_D,_D,_D}, 1
#define VEC_2(I,J)  2, (int8_t[DASIDX_MAX]){I,J,_D,_D,_D,_D,_D,_D}, 1
#define VEC_3(I,J,K)  3, (int8_t[DASIDX_MAX]){I,J,K,_D,_D,_D,_D,_D}, 1
#define VEC_4(I,J,K,L)  4, (int8_t[DASIDX_MAX]){I,J,K,L,_D,_D,_D,_D}, 1
#define VEC_5(I,J,K,L,M)  5, (int8_t[DASIDX_MAX]){I,J,K,L,M,_D,_D,_D}, 1
#define VEC_6(I,J,K,L,M,N)  6, (int8_t[DASIDX_MAX]){I,J,K,L,M,N,_D,_D}, 1
#define VEC_7(I,J,K,L,M,N,O)  7, (int8_t[DASIDX_MAX]){I,J,K,L,M,N,O,_D}, 1
 
 
/* Internal function for merging variable, and dimension shapes.  Different
 * rules apply for arrays to variable shape merges.
 * 
 * Combinding index rules:
 * 
 *    '*' + '-'    = '*'
 *    '*' + Number = Number      ('*' means undefined length, represented by)
 *    '-' + Number = Number      ('-' means no dependency,    negative nums )
 *    Big Number + Small Number = Small Number
 * 
 */
DAS_API void das_varindex_merge(int nRank, ptrdiff_t* pDest, ptrdiff_t* pSrc);
 
/* Internal function for merging length in a particular dimension. */
DAS_API ptrdiff_t das_varlength_merge(ptrdiff_t nLeft, ptrdiff_t nRight);
 
#define D2V_EXP_UNITS 0x02
#define D2V_EXP_RANGE 0x04
#define D2V_EXP_SUBEX 0x08
#define D2V_EXP_INTR  0x10
#define D2V_EXP_TYPE  0x20
 
DAS_API void das_varindex_prndir(bool bFastLast);
 
typedef struct das_variable{
   enum var_type vartype;  /* CONST, ARRAY, SEQUENCE, UNARY_OP, BINARY_OP ... */
   das_val_type  vt;       /* vtUByte, vtText, vtTime, vtVector ... */
   
   size_t        vsize;    /* The size in bytes of each value in the variable
                            * for non-scalar items, this yields the unusual value
                            * of sizeof(void*) */
   
   /* Number of external indexes.  Many of these may not be used and are
    * thus marked as degenerate */
   int nExtRank;
 
   /* Number of internal indexes, essentially the item rank.  Is zero except
      for text strings and geometric vectors */
   int nIntRank;
   
   /* Since it is possible to create variables in all kinds of ways (not just
    * backing arrays) we have to have our own units storage location.
    * Transforming backing arrays such that they are no longer in the units
    * they had when the variable was created will NOT automatically update this
    * variable. 
    */
   das_units units;
 
   /* Reference count on this variable.  Needed to make sure it's not
    * deleted out from under us. */
   int nRef;
 
   
   /* Get identifier for this variable, may be NULL for anoymous vars */
   const char* (*id)(const struct das_variable* pThis);
   
   /* Get full shape of this variable */
   int (*shape)(const struct das_variable* pThis, ptrdiff_t* pShape);
 
   /* Get the internal shape of this variable.
    *
    * Combine this with DasVar_intrType to get the purpose of the internal
    * indicies.
    */
   int (*intrShape)(const struct das_variable* pThis, ptrdiff_t* pComp);
   
   /* Write an expression (i.e. a representation) of this variable to a 
    * buffer.
    *
    * @param uFlags - D2V_EXP_UNITS include units in the expression
    *                 D2V_EXP_RANGE include the range in the expression
    *                 D2V_EXP_INTER include internal component information
    * 
    * @returns The write point to add more text to the buffer
    */
   char* (*expression)(const struct das_variable* pThis, char* sBuf, int nLen, 
                       unsigned int uFlags);
   
   /* Get the external length of this variable at a partial index */
   ptrdiff_t (*lengthIn)(
      const struct das_variable* pThis, int nIdx, ptrdiff_t* pLoc
   );
   
   bool (*get)(
      const struct das_variable* pThis, ptrdiff_t* pIdx, das_datum* pDatum
   );
   
   bool (*isFill)(
      const struct das_variable* pThis, const ubyte* pCheck, das_val_type vt  
   );
   
   /* Does this variable provide simple numbers */
   bool (*isNumeric)(const struct das_variable* pThis);
 
   DasAry* (*subset)(
      const struct das_variable* pThis, int nRank, const ptrdiff_t* pMin,
      const ptrdiff_t* pMax
   );
   
   int (*incRef)(struct das_variable* pThis);
   
   int (*decRef)(struct das_variable* pThis);
 
   bool (*degenerate)(const struct das_variable* pThis, int iIndex);
 
 
   void* pUser;
   
} DasVar;
 
DAS_API DasVar* new_DasVarUnary(const char* sOp, const DasVar* pVar);
 
/* Internal version for use by the expression lexer */
DAS_API DasVar* new_DasVarUnary_tok(int nOpTok, const DasVar* pVar);
 
DAS_API DasVar* new_DasVarBinary(
   const char* sId, DasVar* pLeft, const char* sOp, DasVar* pRight
);
 
 
DAS_API DasVar* new_DasConstant(const char* sId, const das_datum* pDm);
 
 
DAS_API DasVar* new_DasVarSeq(
   const char* sId, das_val_type vt, size_t vSz, const void* pMin, 
   const void* pInterval, int nExtRank, int8_t* pMap, int nIntRank, 
   das_units units
);
 
DAS_API DasVar* new_DasVarArray(DasAry* pAry, int nExtRank, int8_t* pMap, int nIntRank);
 
 
DAS_API DasVar* new_DasVarVecAry(
   DasAry* pAry, int nExtRank, int8_t* pMap, int nIntRank, 
   const char* sFrame, ubyte nFrameId, ubyte frametype, ubyte nDirs,
   const ubyte* pDir
);
 
DAS_API int inc_DasVar(DasVar* pThis);
 
DAS_API int dec_DasVar(DasVar* pThis);
 
 
int ref_DasVar(const DasVar* pThis);
 
const char* DasVar_id(const DasVar* pThis);
 
enum var_type DasVar_type(const DasVar* pThis);
 
das_val_type DasVar_valType(const DasVar* pThis);
 
size_t DasVar_valSize(const DasVar* pThis); 
 
das_units DasVar_units(const DasVar* pThis); 
 
 
DAS_API DasAry* DasVarAry_getArray(DasVar* pThis);
 
 
/* Evaluate all sub-variable expressions and a single array variable
 */
DAS_API DasVar* new_DasVarEval(const DasVar* pVar);
 
DAS_API bool DasVar_orthoginal(const DasVar* pThis, const DasVar* pOther);
 
DAS_API bool DasVar_degenerate(const DasVar* pThis, int iIndex);
 
 
DAS_API int DasVar_shape(const DasVar* pThis, ptrdiff_t* pShape);
 
DAS_API int DasVar_intrShape(const DasVar* pThis, ptrdiff_t* pShape);
 
 
DAS_API ptrdiff_t DasVar_lengthIn(const DasVar* pThis, int nIdx, ptrdiff_t* pLoc);
 
DAS_API char* DasVar_toStr(const DasVar* pThis, char* sBuf, int nLen);
 
 
DAS_API bool DasVar_isNumeric(const DasVar* pThis);
 
 
DAS_API bool DasVar_get(
   const DasVar* pThis, ptrdiff_t* pIdx, das_datum* pDatum
);
 
 
DAS_API bool DasVar_isFill(
   const DasVar* pThis, const ubyte* pCheck, das_val_type vt
);
 
DAS_API bool DasVar_isComposite(const DasVar* pVar);
 
 
DAS_API DasAry* DasVar_subset(
   const DasVar* pThis, int nRank, const ptrdiff_t* pMin, const ptrdiff_t* pMax
);
 
#ifdef __cplusplus
}
#endif
 
#endif /* _das_variable_h */