variable.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/>.
 */
 
#ifndef _das_var_h_
#define _das_var_h_
 
#include <das3/descriptor.h>
#include <das3/buffer.h>
#include <das3/datum.h>
#include <das3/units.h>
#include <das3/generator.h>
#include <das3/form.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* ========================================================================= *
 *
 * A variable, here a DasVar, is the top level interface for data values.  It
 * pulls together multiple concepts:
 *
 * 1. Datum: Found at each full external index of a variable is a datum.  The
 *    value can come in multiple forms, from simple integers, to rotation
 *    matrices, to strings.  DasVar_get() provides datums, though it's not
 *    a fast function and there are better ways to retrieve data.
 *
 * 2. Elements: Each datum is composed of one or more elements.  For simple
 *    variables a datum is just a single floating point number.  For utf-8
 *    or byte strings, it is a byte.
 *
 * 3. Formalisms: Some datums obey a given set of math rules.  Each one is a
 *    vector, or a complex number, or an affine point.  Formalisms (DasForm)
 *    provide binary operations on their values and on related forms.  To get
 *    a variable's formalism call DasVar_form().
 *
 * 4. Generators: (DasGen) provides elements.  Generators don't know what math
 *    rules apply, they operate below that level and either create values via
 *    binary operations, provide them from a backing array store, or by simple
 *    rules based on the provided index.  Application code typically does not
 *    interact with this level, but every variable has a generator.
 *
 * There are four variable classes, but that is an implementation detail as
 * interactions with each one are typically via virtual functions.  The only
 * time application code needs to concern itself with the type of a variable
 * is when constructing DasVar derived objects of their own.  The constructors
 * are:
 *
 * new_DasVar()
 *   Creates a variable that has no internal indices, but may have a math
 *   form.  Example values are calendar times, which follow the affine
 *   (point) formalism.
 *
 * new_DasVarComp()
 *   Creates a variable with internal indices and an optional math formalism.
 *   Example values are geodetic locations.  These have three elements for
 *   each value and follow the "position" formalism.
 *
 * new_DasVarBin()
 *   Creates a variable that is a binary operation on two other variables,
 *   such as providing a 2-D Qube array of time values given a reference
 *   array and an offset time array.
 *
 * new_DasVarBytes()
 *   Creates a variable with a single internal index for each value.  These
 *   hold strings or binary blobs of bytes and may not have a math formalism.
 *
 * ========================================================================= */
 
/* ========================================================================= *
 * DasVar, the base.
 * ========================================================================= */
 
typedef struct das_var DasVar;
 
/* ========================================================================= *
 * The scalar case.  One value per point, no internal index.  There is NO
 * DasVarScalar struct: a scalar IS the base DasVar, and its only formalisms so
 * far are linear or point.
 *
 * Wire, a plain linear scalar.  Linear is the default, so nothing is stated:
 *
 *   <scalar semantic="real" units="Hz" index="*">
 *     <packet numItems="1" itemBytes="8" encoding="LEreal"/>
 *   </scalar>
 *
 * Wire, a time scalar.  This is where the word "point" appears.  The affine
 * rule needs no parameters, so kind= alone carries it.  semantic="datetime"
 * still rides along as the display and calendar-units directive.  Child order is
 * properties, then ops, then generator:
 *
 *   <scalar semantic="datetime" units="TT2000" index="*">
 *     <ops kind="point"/>
 *     <packet numItems="1" itemBytes="8" encoding="LEint"/>
 *   </scalar>
 *
 * A future parameter-bearing scalar formalism (a scalar with a point spread
 * function) is no longer an open item: it is a formalism with parameters on a
 * scalar, exactly like vector on a composite.  Same struct, same store.
 * ========================================================================= */
 
/* The dispatch table is in var_priv.h: nothing outside das2C implements one,
   and there is no registration path if it wanted to. */
struct DasVar_VTbl;
 
 
 
struct das_var {
 
   DasDesc base;          /* a variable IS a descriptor: it has properties, a
                             parent, and it serializes */
 
   const struct DasVar_VTbl* pVTbl;
 
   DasGen* pGen;          /* The variable owns a generator, is not one.
                             Swapping array for sequence does not change the
                             variable's type. */
 
 
   DasForm* pForm;        /* Heap owned and refcounted, symmetric
                             with pGen: pGen says how values are produced,
                             pForm says what they mean to arithmetic.  NEVER
                             NULL for a numeric variable -- an absent <ops> binds
                             the explicit linear form and an unrecognized
                             kind= binds DasFormGeneric, so "I do not know
                             this math" has a vtable to refuse from.  Only
                             DasVarBytes leaves it NULL: a byte run has no
                             auto-math and its CLASS says so. */
 
   /* One unit. Some DasForm objects may need more, in which
      case they can provide storage for them */
   das_units units;
 
   int   nRef;
   void* pUser;
};
 
DAS_API const char* DasVar_serialType(const DasVar* pThis);
 
#define DasVar_units(P)    ((P)->units)
#define DasVar_gen(P)      ((P)->pGen)
#define DasVar_form(P)     ((P)->pForm)
 
#define DasVar_formIs(P,VT) (((P) != NULL)&&DasForm_isKind(DasVar_form(P), VT))
 
DAS_API const char* DasVar_compSym(const DasVar* pThis, int iComp);
 
DAS_API int DasVar_compLabels(
   const DasVar* pThis, char** psBuf, int nMax, size_t uLenEa
);
 
DAS_API das_elem_type DasVar_elemType(const DasVar* pThis);
 
 
DAS_API int inc_DasVar(DasVar* pThis);
 
DAS_API int dec_DasVar(DasVar* pThis);
 
DAS_API int DasVar_get(
   const DasVar* pThis, ptrdiff_t* pLoc, das_byte_seq work, das_datum* pOut
);
 
DAS_API bool DasVar_getNeedsBuf(const DasVar* pThis);
 
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 bool DasVar_degenerate(const DasVar* pThis, int iIndex);
 
DAS_API const char* DasVar_role(const DasVar* pThis);
 
DAS_API DasAry* DasVar_subset(
   const DasVar* pThis, int nRank, const ptrdiff_t* pMin, const ptrdiff_t* pMax,
   const DasVar* pShapeFrom
);
 
DAS_API DasAry* DasVar_materialize(
   const DasVar* pThis, int nRank, const ptrdiff_t* pMin, const ptrdiff_t* pMax,
   const DasVar* pShapeFrom
);
 
DAS_API DasAry* DasVar_subsetQube(
   const DasVar* pThis, int nRank, const ptrdiff_t* pMin, const ptrdiff_t* pMax,
   const DasVar* pShapeFrom
);
 
DAS_API DasAry* DasVar_materializeQube(
   const DasVar* pThis, int nRank, const ptrdiff_t* pMin, const ptrdiff_t* pMax,
   const DasVar* pShapeFrom
);
 
#define DasVar_allVals(P, R)  DasVar_subset((P), (R), NULL, NULL, NULL)
 
 
DAS_API bool DasVar_isNumeric(const DasVar* pThis);
 
DAS_API char* DasVar_toStr(const DasVar* pThis, char* sBuf, size_t uLen);
 
DAS_API DasVar* DasVar_copy(const DasVar* pThis);
 
DAS_API das_val_type DasVar_valType(const DasVar* pThis);
 
DAS_API DasAry* DasVar_getAry(const DasVar* pThis);
 
#define DasVar_hasAry(P)  (DasVar_getAry(P) != NULL)
 
DAS_API bool DasVar_setAry(DasVar* pThis, DasAry* pNew);
 
DAS_API DasErrCode DasVar_encode(DasVar* pThis, const char* sRole, DasBuf* pBuf);
 
 
DAS_API DasVar* new_DasVar(
   DasGen* pGen, das_units units, DasForm* pForm
);
 
/* ========================================================================= *
 * DasVarBin: an operation over two variables.
 *
 * This is the one variable class with NO wire element.  das3 has no binary
 * element: a stream carries reference and offset as two separate variables
 * and the dimension combines them.  So a DasVarBin is never DECODED -- it is
 * built in code, and serializing one means MATERIALIZING it: walking the
 * operands into an array and emitting that as though it had been array-backed
 * all along.
 *
 * It keeps the operand VARIABLES, not just their generators.  A generator has
 * no units and no ops, so operands reduced to generators leave nobody able to
 * ask what was combined.  The generator half still exists underneath (DasGenOp
 * holds the operand GENERATORS and does the numeric walking); each layer keeps
 * what it knows.
 *
 * The pairing resolves ONCE, at construction: what math combined the two is
 * settled then and never asked again, so units, form and value type on the
 * result are ordinary fields from that point on.  See form.h for the rule
 * that puts the walk here rather than in the formalisms.
 * ========================================================================= */
 
typedef struct das_var_bin {
 
   DasVar base;         /* base.pForm and base.units are the RESOLVED result,
                           decided once by binOpLeft/binOpRight at construction
                           and thereafter just fields -- which is why
                           _DasVar_subset() never asks what math made a value */
 
   DasVar*     pLeft;   /* references held; operand identity stays askable */
   DasVar*     pRight;
   int         op;      /* a D2BOP_* code from operator.h */
 
   /* The pairing, resolved ONCE at construction.  Six facts and one function
      pointer; the walk reads them and never asks the forms again.  Shared on
      copy, never re-resolved: two copies of one variable must not disagree about
      what math they are. */
   DasBinOp*   pRecipe;
 
} DasVarBin;
 
DAS_API DasVarBin* new_DasVarBin(DasVar* pLeft, char cOp, DasVar* pRight);
 
 
 
/* ========================================================================= *
 * Values with an internal index: DasVarComp (<composite>) and DasVarBytes
 * (<bytes>).
 *
 * The internal layout is pure SHAPE.  The formalism does not live in the shape.
 * A 3;3 rotation and a 3;3 plain matrix share the same layout and differ only
 * in their formalism.  Real data includes 3;3 matrices that are not rotations
 * (covariances, pressure tensors), so this matters.
 *
 *   element is etUByte    ->  the byte run branch: string or blob.  Empty
 *                             formalism.  No table lookup.  <bytes> on the wire.
 *
 *   element is numeric    ->  base.form carries the row.  A hit gives a rich
 *                             datum.  A miss is the generic case: carry the
 *                             token, hand back plain numbers.
 * ========================================================================= */
 
/* ========================================================================= *
 * The byte run: DasVarBytes, the <bytes> element.  Element type is etUByte.
 *
 * One class for one wire element.  A byte run cannot carry math and there is
 * no field saying so: the CLASS says it, which is why new_DasVarBytes() takes
 * no formalism argument at all and why a byte run can never reach the binop
 * registry.  The structural family comes from the element name, so no
 * semantic is needed for structure.  string and blob are told apart by the
 * packet encoding, an explicit required triplet:
 *
 *   encoding="utf8"    text
 *   encoding="base64"  ASCII-armored binary, decode to get the bytes
 *   encoding="raw"     no transform, opaque bytes
 *
 * raw is a NAMED token, not an omitted attribute, so a forgotten encoding is a
 * loud error rather than a silent default.
 *
 * Wire:
 *
 *   <bytes index="*">
 *     <packet numItems="1" itemBytes="*" encoding="utf8" valTerm=";"/>
 *   </bytes>
 *
 *   <bytes index="*">
 *     <packet numItems="1" itemBytes="*" encoding="raw" embedded="image/png"/>
 *   </bytes>
 *
 * The primary encoding gets the bytes off the wire.  An embedded= attribute,
 * if present, is the extension-codec trigger: it names the format the bytes
 * must further be decoded FROM to realize the declared values, and a reader
 * with no handler fails loud.  A purely descriptive content label rides in a
 * property (contentType) instead.  Two independent stages on two attributes.
 *
 * The only difference between string and blob is the sentinel, so it rides as
 * one flag rather than two classes: both are the same wire element and the same
 * structure.  A string ends in a REQUIRED trailing null in the array's last
 * index, which is why it can hand out a bare char*.  A blob is stored AS GIVEN
 * with no sentinel, which is why it must always be carried as pointer plus
 * length.  Fixed versus ragged is orthogonal; both can be either.
 * ========================================================================= */
 
typedef struct das_var_comp {
 
   DasVar base;           /* base.form: the formalism row, token, bindings */
 
   /* Internal layout exactly as declared.  "3" is a vector.  "3;3" is a
      matrix.  Ragged levels are Flags.  Multi-level shapes read and write
      end to end (examples/ex40_rotation is the 3;3 case) */
   int       nIntRank;
   ptrdiff_t aIntShape[VARIDX_MAX];
 
   /* Per component labels live at this structural level, readable without
      understanding the formalism (the skippability contract: a dumb client
      still stacks N labeled lines).  Per component units WOULD live here
      too; until a holder exists the ';' list fails loud, see base.units. */
   /* TODO structural label storage */
 
} DasVarComp;
 
/* The byte run: DasVarBytes, the <bytes> element.  Internal rank is ALWAYS 1
   (the index is the byte number), so one extent replaces a shape array. */
typedef struct das_var_bytes {
 
   DasVar base;           /* base.form is unused: a byte run has no math */
 
   ptrdiff_t nExtent;     /* item length in bytes, VARIDX_RAGGED if var-width */
 
   /* string, not blob: a required trailing null in the last index, which is
      what lets a datum be a bare char*.  A blob is stored as given and must
      always be carried as pointer plus length. */
   bool bSentinel;
 
} DasVarBytes;
 
DAS_API DasVarComp* new_DasVarComp(
   DasGen* pGen, das_units units, DasForm* pForm,
   int nIntRank, const ptrdiff_t* pIntShape
);
 
DAS_API DasVarBytes* new_DasVarBytes(
   DasGen* pGen, das_units units, bool bSentinel, ptrdiff_t nExtent
);
 
#ifdef __cplusplus
}
#endif
 
#endif /* _das_var_h_ */