generator.h

Go to the documentation of this file.

/* Copyright (C) 2026 Chris Piker <chris-piker@uiowa.edu>
 *
 * Author: C. Piker, via Claude Fable 5
 *
 * 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/>.
 */
 
/* Note this is a library-internal file, not stable public API is defined here */
 
#ifndef _das_generator_h_
#define _das_generator_h_
 
#include <das3/value.h>
#include <das3/array.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* ------------------------------------------------------------------------- *
 * The index vocabulary.
 *
 * An array declares extents that are either a real count or unbounded, and it
 * says so with unsigned values (see ARYIDX_UNBOUND in array.h).  From here up
 * the stack an extent can also be BORROWED from the container or entirely
 * UNUSED by this variable, so the model needs signed values and three distinct
 * negative markers.  This is where those first mean anything, which is why they
 * live here rather than one layer down.
 *
 * The flags walk DOWNWARD from VARIDX_RAGGED on purpose.  das_varlength_merge()
 * implements the precedence lattice
 *
 *      Ragged > Number > Borrow > Unused
 *
 * so the flags have to descend in precedence order for it to be right.
 * ------------------------------------------------------------------------- */
 
#define VARIDX_MAX     ARYIDX_MAX
 
/* VARIDX_RAGGED lives in array.h: DasAry_shape() has to write it. */
#define VARIDX_BORROW  (VARIDX_RAGGED - 1)  /* no intrinsic extent, take the container's */
#define VARIDX_UNUSED  (VARIDX_BORROW - 1)  /* a change in this index changes nothing here */
 
#define VARIDX_MAXFLG  VARIDX_RAGGED
 
#define VARIDX_INIT_UNUSED {-3,-3,-3,-3,-3,-3,-3,-3}
#define VARIDX_INIT_BEGIN  { 0, 0, 0, 0, 0, 0, 0, 0}
 
DAS_API void das_varindex_merge(int nRank, ptrdiff_t* pDest, ptrdiff_t* pSrc);
 
DAS_API ptrdiff_t das_varlength_merge(ptrdiff_t nLeft, ptrdiff_t nRight);
 
DAS_API DasErrCode das_shape_fromStr(
   const char* sShape, int nMaxRank, bool bAllowFlags, ptrdiff_t* pShape,
   int* pnRank, const char* sWhere
);
 
DAS_API char* das_shape_toStr(
   const ptrdiff_t* pShape, int nRank, char* sBuf, size_t uLen
);
 
DAS_API int das_shape_info(
   const ptrdiff_t* pShape, int nExtRank, int nShapeLen, char* sBuf, size_t uLen
);
 
DAS_API void das_varindex_prndir(bool bFastLast);
 
/* ------------------------------------------------------------------------- *
 * The generator (gt).
 *
 * A generator is a value source and nothing more.  It answers one question:
 * what raw elements sit at a given external index?  It does not know what
 * those elements mean.  It does not know it is a vector, a complex, or a
 * timestamp.  That meaning is the variable's job, one layer up in variable.h.
 *
 * Generators varies independently of the variable type.  The same
 * geometric vector can be backed by an array on Monday and a sequence on
 * Tuesday, and it is the same vector both days.  So a variable owns a
 * generator by composition.  A variable is not a generator.
 * ------------------------------------------------------------------------- */
 
 
 
/* Generator type (gt).  How the values are produced. */
typedef enum das_gen_type_e {
   gtArray = 1,   /* a lookup into a backing DasAry */
   gtSeq,         /* an intercept plus an interval, computed on demand */
   gtConst,       /* one value, everywhere */
   gtUnop,        /* a unary operation on one child generator */
   gtBinop        /* a binary operation on two child generators */
} das_gen_type;
 
 
typedef struct das_generator DasGen;
 
typedef struct DasGen_VTbl {
 
   /* Fill the caller's buffer with the internal run of raw elements this
      generator produces at one external index.  The run length is the
      variable's item count: one for a scalar, ncomp for a composite.
      Returns the count written, or a negative das error code. */
   int (*eval)(
      const DasGen* pThis, const ptrdiff_t* pExtLoc, ubyte* pRun, size_t uRunMax
   );
 
   /* The external shape this generator can address, VARIDX_RAGGED /
      VARIDX_BORROW / VARIDX_UNUSED vocabulary.  For an array this is the
      array shape minus the internal indices.  For a sequence it is the
      declared extent. */
   int (*extShape)(const DasGen* pThis, ptrdiff_t* pShape);
 
   /* External length at a partial index, for ragged external runs.  Keep the
      MIN merge semantics that DasDs_lengthIn already relies on. */
   ptrdiff_t (*lengthIn)(const DasGen* pThis, int nIdx, ptrdiff_t* pLoc);
 
   /* A pointer to the item run IN PLACE, for values that are views rather
      than copies: a string datum carries a pointer into the backing array,
      a blob carries pointer plus length, and both can exceed any fixed
      buffer.  Only a backed generator can answer (gtArray); computed
      sources return NULL, a computed string having no home to point at.
      *pCount receives the run element count (ragged aware). */
   const ubyte* (*at)(
      const DasGen* pThis, const ptrdiff_t* pExtLoc, size_t* pCount
   );
 
   /* Hand back a rectangular DasAry covering the external range [pMin,pMax)
      without copying, when the generator's storage already has that shape.
 
      Only an array-backed generators provide this feature, others return NULL
      which means "not supported, allocate and call subsetInto" which is the
      same not-my-job answer that at() gives.
 
      The returned array holds one reference for the caller and saves its
      memory owner, exactly as new_DasAry() would 
      @see DasAry_subSetIn. 
   */
   DasAry* (*subsetView)(
      const DasGen* pThis, int nExtRank, const ptrdiff_t* pMin,
      const ptrdiff_t* pMax
   );
 
   /* What you use if subsetView() can provide a fast wrapper over existing
      data. Write every item run in [pMin,pMax) into the caller's buffer in
      row-major order (last external index fastest).
 
      Ragged index ranges are padded out with fill values as needed.
      So a subset of any variable, ragged or not is *always* rectangular.
 
      This property is needed for writing CDFs and other formats that will not
      accept variable length records.
 
      Returns item runs written, or a negative das error code. */
   int (*subsetInto)(
      const DasGen* pThis, int nExtRank, const ptrdiff_t* pMin,
      const ptrdiff_t* pMax, ubyte* pBuf, size_t uBufLen
   );
 
   void (*destroy)(DasGen* pThis);   /* called by DasGen_decRef at zero */
 
} DasGen_VTbl;
 
 
struct das_generator {
 
   das_gen_type   kind; /* how values are produced */
 
   const DasGen_VTbl* pVTbl;
 
   /* Element types are answered by the generator, because "what one element
      holds" is a fact about the source, not the index presentation or the
      mathematical formalism. */
   das_elem_type elem;
 
   int nRef;
};
 
/* Nothing below is tagged DAS_API.  A generator is reached through the DasVar
   that owns it, so in a language with the notion these would be package
   private: visible across the library, not part of its published surface.
   Test programs link the static library and so still see them. */
 
#define DasGen_type(P)     ((P)->kind)
 
#define DasGen_elemType(P) ((P)->elem)
 
DAS_API int DasGen_incRef(DasGen* pThis);
 
DAS_API int DasGen_decRef(DasGen* pThis);
 
int DasGen_eval(
   const DasGen* pThis, const ptrdiff_t* pExtLoc, ubyte* pRun, size_t uRunMax
);
 
int DasGen_extShape(const DasGen* pThis, ptrdiff_t* pShape);
 
ptrdiff_t DasGen_lengthIn(const DasGen* pThis, int nIdx, ptrdiff_t* pLoc);
 
const ubyte* DasGen_at(
   const DasGen* pThis, const ptrdiff_t* pExtLoc, size_t* pCount
);
 
DasAry* DasGen_subsetView(
   const DasGen* pThis, int nExtRank, const ptrdiff_t* pMin, const ptrdiff_t* pMax
);
 
int DasGen_subsetInto(
   const DasGen* pThis, int nExtRank, const ptrdiff_t* pMin,
   const ptrdiff_t* pMax, ubyte* pBuf, size_t uBufLen
);
 
DAS_API const ubyte* DasGen_getFill(const DasGen* pThis);
 
size_t DasGen_itemElems(const DasGen* pThis);
 
DasGen* DasGen_copy(const DasGen* pThis);
 
char* DasGen_expression(const DasGen* pThis, char* sBuf, size_t uLen);
 
DasAry* DasGen_getArray(const DasGen* pThis);
 
bool DasGen_setArray(DasGen* pThis, DasAry* pNew);
 
 
/* The concrete generators. ------------------------------------------------ */
 
typedef struct das_gen_array {
   DasGen base;
 
   DasAry* pAry;               /* referenced (incRef held), owned by the dataset */
 
   /* external index -> array index; VARIDX_UNUSED marks a degenerate
      external index.  Array indices past the mapped ones are the item run. */
   int  nExtRank;
   int8_t idxmap[VARIDX_MAX];
 
   /* elements in one item run, product of the unmapped (internal) array
      extents.  v1 handles cubic internal shapes; a ragged INTERNAL extent
      fails loud at construction until the run walk migrates. */
   size_t uItemElems;
} DasGenAry;
 
/* Every intercept and slope sits in a slot this wide, the largest element,
   a broken-down time */
#define DASGEN_SEQ_SLOT sizeof(das_time)
 
typedef struct das_gen_seq {
   DasGen base;
 
   /* One intercept per component, one interval per (component, external
      index), in one heap block sized by the component count: a sequence has
      as many components as the item it fills.  For etTime the intercept is a
      das_time and the slopes are doubles in seconds (the affine rule at the
      storage layer). */
   int    nComps;               /* 1 for a scalar sequence */
   ubyte* pIntercept;           /* nComps slots */
   ubyte* pInterval;            /* nComps * VARIDX_MAX slots, component major */
 
   int       nExtRank;                 /* declared extent, since a sequence  */
   ptrdiff_t aExtShape[VARIDX_MAX];    /* has no backing store to derive one */
} DasGenSeq;
 
#define DasGenSeq_intercept(P,c) ((P)->pIntercept + (size_t)(c)*DASGEN_SEQ_SLOT)
 
#define DasGenSeq_interval(P,c,i) \
   ((P)->pInterval + ((size_t)(c)*VARIDX_MAX + (size_t)(i))*DASGEN_SEQ_SLOT)
 
typedef struct das_gen_const {
   DasGen base;
   ubyte aValue[sizeof(double)];
 
   int       nExtRank;
   ptrdiff_t aExtShape[VARIDX_MAX];
} DasGenConst;
 
/* gtUnop / gtBinop.  The generator stays formalism-ignorant: it holds a bare
   bytes-in bytes-out apply function handed down by the variable layer, which got
   it from the binop registry.  Scalar-only in v1: children must produce
   one-element runs, fail loud otherwise. */
typedef bool (*das_gen_applyfn)(
   das_elem_type etL, das_elem_type etR,
   const ubyte* pL, const ubyte* pR, ubyte* pOut
);
 
typedef struct das_gen_op {
   DasGen  base;               /* base.elem is the RESULT element type */
   das_gen_applyfn apply;
   DasGen* pLeft;
   DasGen* pRight;             /* NULL for gtUnop (none exist yet) */
   double  rRightScale;        /* brings right values into left scale; 1.0
                                  when none needed.  Scaling promotes the
                                  right operand to double before apply. */
} DasGenOp;
 
 
DAS_API DasGen* new_DasGenAry(DasAry* pAry, int nExtRank, const int8_t* pIdxMap);
 
DAS_API DasGen* new_DasGenSeq(
   das_elem_type et, const ubyte* pIntercept, int nExtRank,
   const ubyte* pIntervals, const ptrdiff_t* pExtShape
);
 
DAS_API DasGen* new_DasGenSeqN(
   das_elem_type et, int nComps, const ubyte* pIntercepts, int nExtRank,
   const ubyte* pIntervals, const ptrdiff_t* pExtShape
);
 
DAS_API DasGen* new_DasGenConst(
   das_elem_type et, const ubyte* pVal, int nExtRank, const ptrdiff_t* pExtShape
);
 
DAS_API DasGen* new_DasGenBinop(
   das_gen_applyfn apply, das_elem_type etOut, DasGen* pLeft, DasGen* pRight,
   double rRightScale
);
 
 
#ifdef __cplusplus
}
#endif
 
#endif /* _das_generator_h_ */