codec.h

Go to the documentation of this file.

/* Copyright (C) 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/>. 
 */
 
#ifndef _das_codec_h_
#define _das_codec_h_
 
#include <stdint.h>
 
#include <das3/value.h>
#include <das3/array.h>
#include <das3/buffer.h>
 
#include <das3/encoding.h>  /* <-- only to get DASENC_FMT_LEN */
                            /* otherwise independent */
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* Not public, only here because used in a macro */
#define DASENC_VALID    0x0001
 
typedef struct das_codec {
 
   bool bResLossWarn; /* If true, the resolution loss warning has already been emitted */
 
   uint32_t uProc; /* Internal processing flags setup on the call to _init */
 
   int nAryValSz;  /* The size of each array value in internal buffer */
 
   const char* sEncType;  /* a canonical DAS_ENC_* global, or NULL */
 
   int16_t nBufValSz;  /* Width of a single value in the external buffer, -1 is  */
 
   das_val_type vtBuf; /* The value type in the external buffer */
 
   const char* sSemantic; /* Intended meaning: a canonical DAS_SEM_* global, or NULL */
 
   DasAry* pAry;  /* The array for which values are encoded/decoded */
 
   ubyte nSep;
   char sSepSet[VARIDX_MAX];  /* Split strings on these chars by rank */
 
   ubyte nExtRagged;  /* Number of the variable's EXTERNAL ragged indices inside a packet
                         (excludes the packet-framed streaming index and any internal axis
                         such as a string's chars).  This is the count of idxTerm run
                         terminators the var needs; set from the index= shape at creation. */
 
   bool bItemLen;       /* Ignore nSep, read val lengths from packet data */
 
   uint32_t uMaxString; /* If we are storing fixed strings, this is set */
 
   das_units timeUnits; /* If ascii times are to be stored as an integral type
                           this is needed */
 
   /* For output, the sprintf string (if UTF8) or the stream encode type */
   char sOutFmt[DASENC_FMT_LEN];
 
   char* pOverflow;   /* If the size of a variable length value breaks the */
   size_t uOverflow;  /* small vector assumption, extra space is here */
 
} DasCodec;
 
 
#define DASENC_VARSZOUT -1
#define DASENC_READ  true
#define DASENC_WRITE false
 
#define DASENC_ITEM_TERM -9  /* Packet items are terminated by a special byte sequence 
                               aka: "Hi There!|Go Away.|" */
 
#define DASENC_ITEM_LEN -1 /* Packet items have explicit byte lengths in packets
                              aka:  "|9|Hi There!|8|Go Away." */
 
#define DasCodec_isValid(pCd) (((pCd)->uProc & DASENC_VALID)==(DASENC_VALID))
 
DAS_API DasErrCode DasCodec_init(
   bool bRead, DasCodec* pThis, DasAry* pAry, const char* sSemantic, 
   const char* sEncType, int16_t uSzEach, ubyte cSep, das_units epoch, 
   const char* sOutFmt
);
 
DAS_API DasErrCode DasCodec_update(
   bool bRead, DasCodec* pThis, const char* sEncType, int16_t uSzEach, 
   ubyte cSep, das_units epoch, const char* sOutFmt
);
 
DAS_API void DasCodec_eatSpace(DasCodec* pThis, bool bEat);
 
DAS_API void DasCodec_setTrim(DasCodec* pThis, bool bTrim);
 
DAS_API bool DasCodec_isTrim(const DasCodec* pThis);
 
DAS_API void DasCodec_postBlit(DasCodec* pThis, DasAry* pAry);
 
DAS_API DasErrCode DasCodec_setIdxTerms(DasCodec* pThis, ubyte nLevels, const char* sLevels);
 
DAS_API bool DasCodec_isReader(const DasCodec* pThis);
 
DAS_API bool DasCodec_isText(const DasCodec* pThis);
 
DAS_API int DasCodec_decode(
   DasCodec* pThis, const ubyte* pBuf, int nBufLen, int nExpect, int* pValsRead
);
 
DAS_API int DasCodec_raggedIndices(const DasCodec* pThis, int* aRagIdx);
 
DAS_API int DasCodec_decodeRuns(
   DasCodec* pThis, const ubyte* pBuf, int nBufLen, bool bLastVar, int* pValsRead
);
 
#define DASENC_PKT_LAST 0x02
#define DASENC_IN_HDR   0x04
 
DAS_API int DasCodec_encode(
   DasCodec* pThis, DasBuf* pBuf, int nDim, ptrdiff_t* pLoc, int nExpect,
   uint32_t uFlags
);
 
DAS_API int DasCodec_encodeRuns(DasCodec* pThis, DasBuf* pBuf, ptrdiff_t iRec);
 
DAS_API void DasCodec_deInit(DasCodec* pThis);
 
#ifdef __cplusplus
}
#endif
 
 
#endif /* _das_codec_h_ */