libcm is a C development framework with an emphasis on audio signal processing applications.
您最多选择25个主题 主题必须以字母或数字开头,可以包含连字符 (-),并且长度不得超过35个字符

cmData.h 32KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699
  1. #ifndef cmData_h
  2. #define cmData_h
  3. #ifdef __cplusplus
  4. extern "C" {
  5. #endif
  6. //( { file_desc:"Generic, introspective, data structure." }
  7. /*
  8. TODO:
  9. 0) Figure out an error handling scheme that does not rely on
  10. a global errno. This is not useful in multi-thread environments.
  11. It might be ok to go with an 'all errors are fatal' model
  12. (except in the var-args functions).
  13. Consider the use of a context object for use with functions
  14. that can have runtime errors or need to allocate memory.
  15. 1) Implement the canConvert and willTruncate functions.
  16. 2) Make a set of cmDataAllocXXXPtr() functions which take
  17. a flag indicating whether or not to dynamically allocate
  18. the array space. This will allow dynamic allocattion to
  19. occur at runtime. Make var args functions for list and
  20. record objects which also take this flag.
  21. Whereever a function may be implemented using
  22. static/dynamic allocation this flag should be present.
  23. (e.g. string allocation for pair labels)
  24. This choice is common enough that it may be worth
  25. suffixing function names with a capital letter to
  26. be clear what the functions memory policy is.
  27. 3) Come up with a var-args format which allows a
  28. hierchy of records to be defined in one line.
  29. 4) Implement the serialization functions.
  30. 5) Implement an ascii string/parse format for writing/reading.
  31. 6) Implement fast lookup of record fields.
  32. 7) Allow for user defined types. For example a 'matrix'
  33. data type. This might be as simple as adding an extra 'user_tid'
  34. field to cmData_t.
  35. 8) Implement type specific cmDataGetRecordValueXXX() functions.
  36. 9) Implement cmDataIsEqual(), cmDataIsLtE(), ...
  37. */
  38. enum
  39. {
  40. kOkDtRC = cmOkRC,
  41. kAssertErrDtRC,
  42. kConstErrDtRC,
  43. kCvtErrDtRC,
  44. kInvalidContDtRC,
  45. kInvalidTypeDtRC,
  46. kMissingFieldDtRC,
  47. kLexFailDtRC,
  48. kParseStackFailDtRC,
  49. kSyntaxErrDtRC,
  50. kEolDtRC
  51. };
  52. typedef unsigned cmDtRC_t;
  53. typedef enum
  54. {
  55. kInvalidTypeDtId,// 0
  56. kNullDtId, // 1 the data object exists but it has no data
  57. kBoolDtId, // 2
  58. kUCharDtId, // 3
  59. kCharDtId, // 4
  60. kUShortDtId, // 5
  61. kShortDtId, // 6
  62. kUIntDtId, // 7
  63. kIntDtId, // 8
  64. kULongDtId, // 9
  65. kLongDtId, // 10
  66. kFloatDtId, // 11
  67. kDoubleDtId, // 12
  68. kStrDtId, // 13 zero terminated string
  69. kBlobDtId, // 14 application defined raw memory object
  70. kStructDtId, // 15 node is a pair,list, or recd
  71. } cmDataTypeId_t;
  72. typedef enum
  73. {
  74. kInvalidCntDtId = kInvalidTypeDtId,
  75. kScalarDtId = 0x00100000,
  76. kArrayDtId = 0x00200000,
  77. kPairDtId = 0x00400000,
  78. kListDtId = 0x00800000,
  79. kRecordDtId = 0x01000000,
  80. kContainerDtMask = 0x01f00000,
  81. } cmDataContainerId_t;
  82. enum
  83. {
  84. kNoFlagsDtFl = 0x00,
  85. kOptArgDtFl = 0x02000000,
  86. // Indicate that the memory used by the data object
  87. // was dynamically allocated and should be released
  88. // by cmDataFree().
  89. kFreeObjDtFl = 0x04000000,
  90. // Indicate that the memory used by strings, blobs
  91. // and arrays should be freed by cmDataFree().
  92. kFreeValueDtFl = 0x08000000,
  93. // Indicate that the value of the object cannot be changed.
  94. // (but the object could be reassigned as a new type).
  95. kConstValueDtFl = 0x10000000,
  96. // Indicate that the type of the object cannot be changed.
  97. // (but the value may be changed).
  98. kConstObjDtFl = 0x20000000,
  99. // Indicate that the array or string should not be
  100. // internally reallocated but rather the source pointer
  101. // should be taken as the new value of the object.
  102. kNoCopyDtFl = 0x40000000,
  103. kFlagsDtMask = 0x7e000000
  104. };
  105. // The kInvalidDtXXX constants are used to indicate an error when returned
  106. // from the cmDtXXX() functions below.
  107. #define kInvalidDtFloat FLT_MAX
  108. #define kInvalidDtDouble DBL_MAX
  109. enum
  110. {
  111. kInvalidDtChar = 0xff,
  112. kInvalidDtShort = 0xffff,
  113. kInvalidDtInt = 0xffffffff,
  114. kInvalidDtLong = kInvalidDtInt,
  115. kInvalidDtBool = kInvalidDtInt
  116. };
  117. typedef struct cmData_str
  118. {
  119. cmDataTypeId_t tid; // data format id
  120. cmDataContainerId_t cid; // container id
  121. unsigned flags; //
  122. struct cmData_str* parent; // this childs parent
  123. struct cmData_str* sibling; // this childs left sibling
  124. unsigned cnt; // byte cnt for strings/blobs and ele count for arrays
  125. union
  126. {
  127. bool b;
  128. char c;
  129. unsigned char uc;
  130. short s;
  131. unsigned short us;
  132. int i;
  133. unsigned int ui;
  134. long l;
  135. unsigned long ul;
  136. float f;
  137. double d;
  138. cmChar_t* z;
  139. void* vp;
  140. struct cmData_str* child; // first child (list,record,pair)
  141. } u;
  142. } cmData_t;
  143. extern cmData_t cmDataNull;
  144. const cmChar_t* cmDataTypeToLabel( cmDataTypeId_t tid );
  145. cmDataTypeId_t cmDataLabelToType( const cmChar_t* typeLabelStr );
  146. // Returns 1 for kStrDtId.
  147. // Returns cmInvalidCnt if tid is not recognized.
  148. unsigned dmDataByteWidth( cmDataTypeId_t tid );
  149. const cmChar_t* cmDataContainerIdToLabel( cmDataContainerId_t tid );
  150. cmDataContainerId_t cmDataLabelToContainerId( const cmChar_t* contLabelStr );
  151. bool cmDataIsConstObj( const cmData_t* d );
  152. void cmDataEnableConstObj( cmData_t* d, bool enaFl );
  153. bool cmDataIsConstValue( const cmData_t* d );
  154. void cmDataEnableConstValue( cmData_t* d, bool enaFl );
  155. bool cmDataIsFreeValue( const cmData_t* d );
  156. void cmDataEnableFreeValue( cmData_t* d, bool enaFl );
  157. // Returns true if this is a scalar or array node.
  158. bool cmDataIsLeaf( const cmData_t* d);
  159. // Return true if this is NOT a scalar or array node.
  160. bool cmDataIsStruct( const cmData_t* d );
  161. //----------------------------------------------------------------------------
  162. // Scalar related functions
  163. //
  164. // Dynamically allocate a scalar object and set it's value.
  165. // The 'flags' argument may include kConstValueDtFl and kConstObjDtFl.
  166. // The string and blob constructors may also use the
  167. // kNoCopyDtFl and the kFreeValueDtFl.
  168. // Generic:
  169. // 'byteCnt' is ignored for all types other than strings and blobs.
  170. cmDtRC_t cmDataNewScalar( cmData_t* parent, cmDataTypeId_t tid, unsigned flags, void* vp, unsigned byteCnt, cmData_t** ref );
  171. // Type specific
  172. cmDtRC_t cmDataNewNull( cmData_t* parent, unsigned flags, cmData_t** ref );
  173. cmDtRC_t cmDataNewBool( cmData_t* parent, unsigned flags, bool v, cmData_t** ref );
  174. cmDtRC_t cmDataNewChar( cmData_t* parent, unsigned flags, char v, cmData_t** ref );
  175. cmDtRC_t cmDataNewUChar( cmData_t* parent, unsigned flags, unsigned char v, cmData_t** ref );
  176. cmDtRC_t cmDataNewShort( cmData_t* parent, unsigned flags, short v, cmData_t** ref );
  177. cmDtRC_t cmDataNewUShort( cmData_t* parent, unsigned flags, unsigned short v, cmData_t** ref );
  178. cmDtRC_t cmDataNewInt( cmData_t* parent, unsigned flags, int v, cmData_t** ref );
  179. cmDtRC_t cmDataNewUInt( cmData_t* parent, unsigned flags, unsigned int v, cmData_t** ref );
  180. cmDtRC_t cmDataNewLong( cmData_t* parent, unsigned flags, long v, cmData_t** ref );
  181. cmDtRC_t cmDataNewULong( cmData_t* parent, unsigned flags, unsigned long v, cmData_t** ref );
  182. cmDtRC_t cmDataNewFloat( cmData_t* parent, unsigned flags, float v, cmData_t** ref );
  183. cmDtRC_t cmDataNewDouble( cmData_t* parent, unsigned flags, double v, cmData_t** ref );
  184. cmDtRC_t cmDataNewStr( cmData_t* parent, unsigned flags, cmChar_t* str, cmData_t** ref );
  185. cmDtRC_t cmDataNewConstStr( cmData_t* parent, unsigned flags, const cmChar_t* str, cmData_t** ref );
  186. cmDtRC_t cmDataNewStrN( cmData_t* parent, unsigned flags, cmChar_t* str, unsigned charCnt, cmData_t** ref );
  187. cmDtRC_t cmDataNewConstStrN(cmData_t* parent, unsigned flags, const cmChar_t* str, unsigned charCnt, cmData_t** ref );
  188. cmDtRC_t cmDataNewBlob( cmData_t* parent, unsigned flags, void* vp, unsigned byteCnt, cmData_t** ref );
  189. cmDtRC_t cmDataNewConstBlob(cmData_t* parent, unsigned flags, const void* vp, unsigned byteCnt, cmData_t** ref );
  190. // Set the value and type of an existing scalar object.
  191. // These functions begin by releasing any resources held by *p
  192. // prior to resetting the type and value of the object.
  193. // The 'flags' argument to cmDataSetStr() and cmDataSetConstStr()
  194. // may use the kNoCopyDtFl and the kFreeValueDtFl
  195. cmDtRC_t cmDataSetScalarValue( cmData_t* d, cmDataTypeId_t tid, void* vp, unsigned byteCnt, unsigned flags );
  196. cmDtRC_t cmDataSetNull( cmData_t* p );
  197. cmDtRC_t cmDataSetBool( cmData_t* p, bool v );
  198. cmDtRC_t cmDataSetChar( cmData_t* p, char v );
  199. cmDtRC_t cmDataSetUChar( cmData_t* p, unsigned char v );
  200. cmDtRC_t cmDataSetShort( cmData_t* p, short v );
  201. cmDtRC_t cmDataSetUShort( cmData_t* p, unsigned short v );
  202. cmDtRC_t cmDataSetInt( cmData_t* p, int v );
  203. cmDtRC_t cmDataSetUInt( cmData_t* p, unsigned int v );
  204. cmDtRC_t cmDataSetLong( cmData_t* p, long v );
  205. cmDtRC_t cmDataSetULong( cmData_t* p, unsigned long v );
  206. cmDtRC_t cmDataSetFloat( cmData_t* p, float v );
  207. cmDtRC_t cmDataSetDouble( cmData_t* p, double v );
  208. cmDtRC_t cmDataSetStr( cmData_t* p, unsigned flags, cmChar_t* s );
  209. cmDtRC_t cmDataSetConstStr( cmData_t* p, unsigned flags, const cmChar_t* s );
  210. cmDtRC_t cmDataSetStrN( cmData_t* p, unsigned flags, cmChar_t* s, unsigned charCnt );
  211. cmDtRC_t cmDataSetConstStrN( cmData_t* p, unsigned flags, const cmChar_t* s, unsigned charCnt );
  212. cmDtRC_t cmDataSetBlob( cmData_t* p, unsigned flags, void* v, unsigned byteCnt );
  213. cmDtRC_t cmDataSetConstBlob( cmData_t* p, unsigned flags, const void* v, unsigned byteCnt );
  214. // Get the value of an object. No conversion is applied the
  215. // type must match exactly or an error is generated.
  216. cmDtRC_t cmDataBool( const cmData_t* p, bool* v );
  217. cmDtRC_t cmDataChar( const cmData_t* p, char* v );
  218. cmDtRC_t cmDataUChar( const cmData_t* p, unsigned char* v );
  219. cmDtRC_t cmDataShort( const cmData_t* p, short* v );
  220. cmDtRC_t cmDataUShort( const cmData_t* p, unsigned short* v );
  221. cmDtRC_t cmDataInt( const cmData_t* p, int* v );
  222. cmDtRC_t cmDataUInt( const cmData_t* p, unsigned int* v );
  223. cmDtRC_t cmDataLong( const cmData_t* p, long* v );
  224. cmDtRC_t cmDataULong( const cmData_t* p, unsigned long* v );
  225. cmDtRC_t cmDataFloat( const cmData_t* p, float* v );
  226. cmDtRC_t cmDataDouble( const cmData_t* p, double* v );
  227. cmDtRC_t cmDataStr( const cmData_t* p, cmChar_t** v );
  228. cmDtRC_t cmDataConstStr( const cmData_t* p, const cmChar_t** v );
  229. cmDtRC_t cmDataBlob( const cmData_t* p, void** v, unsigned* byteCntRef );
  230. cmDtRC_t cmDataConstBlob( const cmData_t* p, const void** v, unsigned* byteCntRef );
  231. // Functions in this group which return pointers will return NULL
  232. // on error. The other function indicate an error by returning
  233. // kInvalidDtXXX depending on their type.
  234. // Note that there is no guarantee, except as determined by the
  235. // application, that one of the kInvalidDtXXX is not in fact a legal return value.
  236. // These function are simple wrappers around calls to cmDataXXX() and
  237. // therefore do NOT do any type conversion.
  238. bool cmDtBool( const cmData_t* p );
  239. char cmDtChar( const cmData_t* p );
  240. unsigned char cmDtUChar( const cmData_t* p );
  241. short cmDtShort( const cmData_t* p );
  242. unsigned short cmDtUShort( const cmData_t* p );
  243. int cmDtInt( const cmData_t* p );
  244. unsigned cmDtUInt( const cmData_t* p );
  245. long cmDtLong( const cmData_t* p );
  246. unsigned long cmDtULong( const cmData_t* p );
  247. float cmDtFloat( const cmData_t* p );
  248. double cmDtDouble( const cmData_t* p );
  249. char* cmDtStr( const cmData_t* p );
  250. const char* cmDtConstStr( const cmData_t* p );
  251. void* cmDtBlob( const cmData_t* p, unsigned* byteCntRef );
  252. const void* cmDtConstBlob( const cmData_t* p, unsigned* byteCntRef );
  253. // Get the value of an object with conversion.
  254. cmDtRC_t cmDataGetBool( const cmData_t* p, bool* v );
  255. cmDtRC_t cmDataGetChar( const cmData_t* p, char* v );
  256. cmDtRC_t cmDataGetUChar( const cmData_t* p, unsigned char* v );
  257. cmDtRC_t cmDataGetShort( const cmData_t* p, short* v );
  258. cmDtRC_t cmDataGetUShort( const cmData_t* p, unsigned short* v );
  259. cmDtRC_t cmDataGetInt( const cmData_t* p, int* v );
  260. cmDtRC_t cmDataGetUInt( const cmData_t* p, unsigned int* v );
  261. cmDtRC_t cmDataGetLong( const cmData_t* p, long* v );
  262. cmDtRC_t cmDataGetULong( const cmData_t* p, unsigned long* v );
  263. cmDtRC_t cmDataGetFloat( const cmData_t* p, float* v );
  264. cmDtRC_t cmDataGetDouble( const cmData_t* p, double* v );
  265. // Functions in this group which return pointers will return NULL
  266. // on error. The other function indicate an error by returning
  267. // kInvalidDtXXX depending on their type.
  268. // Note that there is no guarantee, except as determined by the
  269. // application that one of the kInvalidDtXXX is not in fact a legal return value.
  270. // These function are simple wrappers around calls to cmDataGetXXX() and
  271. // therefore do type conversion.
  272. bool cmDtGetBool( const cmData_t* p );
  273. char cmDtGetChar( const cmData_t* p );
  274. unsigned char cmDtGetUChar( const cmData_t* p );
  275. short cmDtGetShort( const cmData_t* p );
  276. unsigned short cmDtGetUShort( const cmData_t* p );
  277. int cmDtGetInt( const cmData_t* p );
  278. unsigned cmDtGetUInt( const cmData_t* p );
  279. long cmDtGetLong( const cmData_t* p );
  280. unsigned long cmDtGetULong( const cmData_t* p );
  281. float cmDtGetFloat( const cmData_t* p );
  282. double cmDtGetDouble( const cmData_t* p );
  283. //----------------------------------------------------------------------------
  284. // Array related functions
  285. //
  286. // Notes:
  287. // 1) string arrays are arrays of string pointers.
  288. // 2) blob arrays (array of void pointers) are not supported because
  289. // there is no direct way to determine the length of each blob
  290. // and therefore they cannot be internally duplicated - a special scheme
  291. // could be devised (length goes in first 4 bytes) to make this
  292. // work but we will defer that until the need arises.
  293. //
  294. // Dynamically allocate a new array data object.
  295. //
  296. // eleCnt referes to the number of elements in the array pointed
  297. // to by 'vp'. The number of bytes pointed to by 'vp' is then
  298. // cmDataByteWidth(tid)*eleCnt.
  299. //
  300. // If no flags are set then the array pointed to by 'vp' is reallocated
  301. // and kDataFreeDtFl is set.
  302. //
  303. // If kFreeValueDtFl is set then the object will take responsibility for
  304. // releasing the memory pointed to by 'vp' when the object is destroyed
  305. // or the array is reassigned.
  306. //
  307. // If kNoCopyDtFl is set then 'vp' becomes the internal array
  308. // value (vp[cnt]) is NOT reallocated). In this case the client is
  309. // responsibile for eventually releasing the associated memory - when
  310. // the data object is no longer valid.
  311. cmDtRC_t cmDataNewArray( cmData_t* parent, cmDataTypeId_t tid, void* vp, unsigned eleCnt, unsigned flags, cmData_t** ref );
  312. cmDtRC_t cmDataNewBoolArray( cmData_t* parent, bool* v, unsigned eleCnt, unsigned flags, cmData_t** ref );
  313. cmDtRC_t cmDataNewCharArray( cmData_t* parent, char* v, unsigned eleCnt, unsigned flags, cmData_t** ref );
  314. cmDtRC_t cmDataNewUCharArray( cmData_t* parent, unsigned char* v, unsigned eleCnt, unsigned flags, cmData_t** ref );
  315. cmDtRC_t cmDataNewShortArray( cmData_t* parent, short* v, unsigned eleCnt, unsigned flags, cmData_t** ref );
  316. cmDtRC_t cmDataNewUShortArray( cmData_t* parent, unsigned short* v, unsigned eleCnt, unsigned flags, cmData_t** ref );
  317. cmDtRC_t cmDataNewIntArray( cmData_t* parent, int* v, unsigned eleCnt, unsigned flags, cmData_t** ref );
  318. cmDtRC_t cmDataNewUIntArray( cmData_t* parent, unsigned int* v, unsigned eleCnt, unsigned flags, cmData_t** ref );
  319. cmDtRC_t cmDataNewLongArray( cmData_t* parent, long* v, unsigned eleCnt, unsigned flags, cmData_t** ref );
  320. cmDtRC_t cmDataNewULongArray( cmData_t* parent, unsigned long* v, unsigned eleCnt, unsigned flags, cmData_t** ref );
  321. cmDtRC_t cmDataNewFloatArray( cmData_t* parent, float* v, unsigned eleCnt, unsigned flags, cmData_t** ref );
  322. cmDtRC_t cmDataNewDoubleArray( cmData_t* parent, double* v, unsigned eleCnt, unsigned flags, cmData_t** ref );
  323. cmDtRC_t cmDataNewStrArray( cmData_t* parent, cmChar_t** v, unsigned eleCnt, unsigned flags, cmData_t** ref );
  324. cmDtRC_t cmDataNewConstStrArray( cmData_t* parent, const cmChar_t** v,unsigned eleCnt, unsigned flags, cmData_t** ref );
  325. // Set the value and type of an existing scalar object.
  326. //
  327. // These functions begin by releasing any resources held by *p
  328. // prior to resetting the type and value of the object.
  329. // The 'flags' argument may include kConstValueDtFl, kConstObjDtFl,
  330. // kNoCopyDtFl and the kFreeValueDtFl.
  331. // Generic set array functions. 'vp' is assumed to point to an array
  332. // of the type defined by 'tid'.
  333. cmDtRC_t cmDataSetArrayValue( cmData_t* dt, cmDataTypeId_t tid, void* vp, unsigned eleCnt, unsigned flags );
  334. // Type sepctific set array functions.
  335. cmDtRC_t cmDataSetBoolArray( cmData_t* d, bool* v, unsigned eleCnt, unsigned flags );
  336. cmDtRC_t cmDataSetCharArray( cmData_t* d, char* v, unsigned eleCnt, unsigned flags );
  337. cmDtRC_t cmDataSetUCharArray( cmData_t* d, unsigned char* v, unsigned eleCnt, unsigned flags );
  338. cmDtRC_t cmDataSetShortArray( cmData_t* d, short* v, unsigned eleCnt, unsigned flags );
  339. cmDtRC_t cmDataSetUShortArray( cmData_t* d, unsigned short* v, unsigned eleCnt, unsigned flags );
  340. cmDtRC_t cmDataSetIntArray( cmData_t* d, int* v, unsigned eleCnt, unsigned flags );
  341. cmDtRC_t cmDataSetUIntArray( cmData_t* d, unsigned int* v, unsigned eleCnt, unsigned flags );
  342. cmDtRC_t cmDataSetLongArray( cmData_t* d, long* v, unsigned eleCnt, unsigned flags );
  343. cmDtRC_t cmDataSetULongArray( cmData_t* d, unsigned long* v, unsigned eleCnt, unsigned flags );
  344. cmDtRC_t cmDataSetFloatArray( cmData_t* d, float* v, unsigned eleCnt, unsigned flags );
  345. cmDtRC_t cmDataSetDoubleArray( cmData_t* d, double* v, unsigned eleCnt, unsigned flags );
  346. cmDtRC_t cmDataSetStrArray( cmData_t* d, cmChar_t** v, unsigned eleCnt, unsigned flags );
  347. cmDtRC_t cmDataSetConstStrArray(cmData_t* d,const cmChar_t** v,unsigned eleCnt, unsigned flags );
  348. // Return the count of elements in a n array.
  349. unsigned cmDataArrayEleCount( const cmData_t* d );
  350. // Get a pointer to the base of an array.
  351. // The type must match exactly or an error is generated.
  352. // Use cmDataEleCount() to determine the number of elements in the array.
  353. cmDtRC_t cmDataBoolArray( const cmData_t* d, bool** v );
  354. cmDtRC_t cmDataCharArray( const cmData_t* d, char** v );
  355. cmDtRC_t cmDataUCharArray( const cmData_t* d, unsigned char** v );
  356. cmDtRC_t cmDataShortArray( const cmData_t* d, short** v );
  357. cmDtRC_t cmDataUShortArray( const cmData_t* d, unsigned short** v );
  358. cmDtRC_t cmDataIntArray( const cmData_t* d, int** v );
  359. cmDtRC_t cmDataUIntArray( const cmData_t* d, unsigned int** v );
  360. cmDtRC_t cmDataLongArray( const cmData_t* d, long** v );
  361. cmDtRC_t cmDataULongArray( const cmData_t* d, unsigned long** v );
  362. cmDtRC_t cmDataFloatArray( const cmData_t* d, float** v );
  363. cmDtRC_t cmDataDoubleArray( const cmData_t* d, double** v );
  364. // This group of functions is a wrapper around calls to the same named
  365. // cmDataXXXArray() functions above. On error they return NULL.
  366. bool* cmDtBoolArray( const cmData_t* d );
  367. char* cmDtCharArray( const cmData_t* d );
  368. unsigned char* cmDtUCharArray( const cmData_t* d );
  369. short* cmDtShortArray( const cmData_t* d );
  370. unsigned short* cmDtUShortArray( const cmData_t* d );
  371. int* cmDtIntArray( const cmData_t* d );
  372. unsigned* cmDtUIntArray( const cmData_t* d );
  373. long* cmDtLongArray( const cmData_t* d );
  374. unsigned long* cmDtULongArray( const cmData_t* d );
  375. float* cmDtFloatArray( const cmData_t* d );
  376. double* cmDtDoubleArray( const cmData_t* d );
  377. //----------------------------------------------------------------------------
  378. // Structure related functions
  379. //
  380. // Release an object and any resources held by it.
  381. // Note the this function does not unlink the object
  382. // from it's parent. Use cmDataUnlinkAndFree()
  383. // to remove a object from it's parent list prior
  384. // to releasing it.
  385. void cmDataFree( cmData_t* p );
  386. // Unlink 'p' from its parents and siblings.
  387. // Asserts if parent is not a structure.
  388. // Returns 'p'.
  389. cmData_t* cmDataUnlink( cmData_t* p );
  390. // Wrapper function to cmDataUnlink() and cmDataFree().
  391. void cmDataUnlinkAndFree( cmData_t* p );
  392. // Replace the 'dst' node with the 'src' node and
  393. // return 'src'. This operation does not duplicate
  394. // 'src' it simply links in 'src' at the location of
  395. // 'dst' and then unlinks and free's 'dst'.
  396. cmData_t* cmDataReplace( cmData_t* dst, cmData_t* src );
  397. // Return the count of child nodes.
  398. // Scalars and arrays have no children.
  399. // Pairs have 2 children.
  400. // Lists have one child per element.
  401. // Records have one child per pair.
  402. unsigned cmDataChildCount( const cmData_t* p );
  403. // Returns the ith child of 'p'.
  404. // Returns NULL if p has no children or index is invalid.
  405. cmData_t* cmDataChild( cmData_t* p, unsigned index );
  406. // Prepend 'p' to 'parents' child list.
  407. // The source node 'p' is not duplicated it is simply linked in.
  408. // 'p' is automatically unlinked prior to being prepended.
  409. // Returns 'p'.
  410. cmData_t* cmDataPrependChild(cmData_t* parent, cmData_t* p );
  411. // Append 'p' to the end of 'parent' child list.
  412. // The source node 'p' is not duplicated it is simply linked in.
  413. // 'p' is automatically unlinked prior to being appended.
  414. // Returns 'p'.
  415. cmData_t* cmDataAppendChild( cmData_t* parent, cmData_t* p );
  416. // Insert 'p' at index. Index must be in the range:
  417. // 0 to cmDataChildCount(parent).
  418. // The source node 'p' is not duplicated it is simply linked in.
  419. // 'p' is automatically unlinked prior to being inserted.
  420. // Returns 'p'.
  421. cmData_t* cmDataInsertChild( cmData_t* parent, unsigned index, cmData_t* p );
  422. //----------------------------------------------------------------------------
  423. // Pair related functions
  424. //
  425. // Get the key/value of a pair
  426. cmData_t* cmDataPairKey( cmData_t* p );
  427. unsigned cmDataPairKeyId( cmData_t* p );
  428. const cmChar_t* cmDataPairKeyLabel( cmData_t* p );
  429. cmData_t* cmDataPairValue( cmData_t* p );
  430. // Set the value of an existing pair node.
  431. // 'value' is not duplicated it is simply linked in place of the
  432. // previous pair value node. The previous pair value node is
  433. // unlinked and freed.
  434. // Returns 'p'.
  435. cmData_t* cmDataPairSetValue( cmData_t* p, cmData_t* value );
  436. // Set the key of an existing pair node.
  437. // The previous key is unlinked and freed.
  438. cmData_t* cmDataPairSetKey( cmData_t* p, cmData_t* key );
  439. cmData_t* cmDataPairSetKeyId( cmData_t* p, unsigned id );
  440. // The data space for the 'label' string is dynamically allocated.
  441. cmData_t* cmDataPairSetKeyLabel( cmData_t* p, const cmChar_t* label );
  442. // Create a pair value by assigning a key and value to 'p'.
  443. // 'p' is unlinked and freed prior to the key value assignment.
  444. // 'key' and 'value' are simply linked in they are not duplicated or reallocated.
  445. cmData_t* cmDataPairMake( cmData_t* parent, cmData_t* p, cmData_t* key, cmData_t* value );
  446. // Dynamically allocate a pair node. Both the key and value nodes are reallocated.
  447. cmRC_t cmDataPairAlloc( cmData_t* parent, const cmData_t* key, const cmData_t* value, cmData_t** ref );
  448. // Dynamically allocate the id but link (w/o realloc) the value.
  449. cmRC_t cmDataPairAllocId( cmData_t* parent, unsigned keyId, cmData_t* value, cmData_t** ref );
  450. // Dynamically allocate the label but link (w/o realloc) the value.
  451. cmRC_t cmDataPairAllocLabelN(cmData_t* parent, const cmChar_t* label, unsigned charCnt, cmData_t* value, cmData_t** ref);
  452. cmRC_t cmDataPairAllocLabel( cmData_t* parent, const cmChar_t* label, cmData_t* value, cmData_t** ref );
  453. //----------------------------------------------------------------------------
  454. // List related functions
  455. //
  456. // Return the count of ele's in the list.
  457. unsigned cmDataListCount( const cmData_t* p );
  458. // Return the ith element in the list.
  459. cmData_t* cmDataListEle( cmData_t* p, unsigned index );
  460. //
  461. cmData_t* cmDataListMake( cmData_t* parent, cmData_t* p );
  462. cmData_t* cmDataListAlloc( cmData_t* parent);
  463. // Dynamically allocate a new list object and fill it with values
  464. // using a variable argument list.
  465. //
  466. // 1) Var-args fmt:
  467. // <typeId> {<value>} {<cnt>}
  468. //
  469. // 2) <typeId> is formed by OR-ing one of the container type flags with a
  470. // data type id. (e.g. kArrayDtId | kIntDtId). Note that if no
  471. // container is given then the type is assumed to be scalar.
  472. //
  473. // scalar types: <value> is literal, <cnt> should not be included
  474. // null scalar object should not include <value> or <cnt>
  475. // array types: <value> is pointer,<cnt> is element count
  476. // struct types: <value> is cmData_t pointer, <cnt> should not be included.
  477. // The struct object is appended to the child list of parent.
  478. //
  479. // 3) Indicate the end of argument list by setting <typeId> to kInvalidDtId.
  480. // 4) Scalar and array objects will be dynamically allocated.
  481. // 5) Data attribute flags (kXXXDtFl) make also be OR-ed into the <typeId>.
  482. // 6) Data attribute flags will only be used with scalar and array object and
  483. // will be ignored for all other object types.
  484. cmRC_t cmDataListAllocV( cmData_t* parent, cmErr_t* err, cmRC_t errRC, cmData_t** ref, va_list vl );
  485. cmRC_t cmDataListAllocA( cmData_t* parent, cmErr_t* err, cmRC_t errRC, cmData_t** ref, ... );
  486. // Returns a ptr to 'ele'.
  487. cmData_t* cmDataListAppendEle( cmData_t* p, cmData_t* ele );
  488. cmDtRC_t cmDataListAppendV( cmData_t* p, cmErr_t* err, cmRC_t errRC, va_list vl );
  489. cmDtRC_t cmDataListAppend( cmData_t* p, cmErr_t* err, cmRC_t errRC, ... );
  490. // Return 'p'.
  491. cmData_t* cmDataListInsertEle( cmData_t* p, unsigned index, cmData_t* ele );
  492. cmData_t* cmDataListInsertEleN(cmData_t* p, unsigned index, cmData_t* ele[], unsigned n );
  493. //----------------------------------------------------------------------------
  494. // Record related functions
  495. //
  496. // Return count of pairs.
  497. unsigned cmDataRecdCount( const cmData_t* p );
  498. // Return the ith pair.
  499. cmData_t* cmDataRecdEle( cmData_t* p, unsigned index );
  500. // Return the ith value.
  501. cmData_t* cmDataRecdValueFromIndex( cmData_t* p, unsigned index );
  502. cmData_t* cmDataRecdValueFromId( cmData_t* p, unsigned id );
  503. cmData_t* cmDataRecdValueFromLabel( cmData_t* p, const cmChar_t* label );
  504. // Return the ith key or NULL if it does not exist.
  505. cmData_t* cmDataRecdKey( cmData_t* p, unsigned index );
  506. // Returns cmInvalidId if the ith key does not exist or is not an integer.
  507. unsigned cmDataRecdKeyId( cmData_t* p, unsigned index );
  508. // Return NULL if the ith key does not exist or is not a string.
  509. const cmChar_t* cmDataRecdKeyLabel( cmData_t* p, unsigned index );
  510. cmData_t* cmDataRecdMake( cmData_t* parent, cmData_t* p );
  511. cmData_t* cmDataRecdAlloc( cmData_t* parent );
  512. // Append a pair node by linking the pair node 'pair' to the record node 'p'.
  513. // 'pair' is simply linked to 'p' via cmDataAppendChild() no
  514. // reallocation or duplicattion takes place.
  515. cmData_t* cmDataRecdAppendPair( cmData_t* p, cmData_t* pair );
  516. // Dynamically allocate a new record object and fill it with values
  517. // using a variable argument list.
  518. //
  519. // 1) Var-args format:
  520. // <label|id> <value>
  521. //
  522. // The <label|id> arg. gives the record pair label and the <value>
  523. // argument list gives the pair value.
  524. //
  525. // 2) The <value> argument has the same syntax as the cmDataListAllocLabelV()
  526. // call.
  527. // 3) The cmDataRecdAllocLabelV() arg. list should be terminated with NULL.
  528. // The cmDataRecdAllocIdV() arg. list should be terminated with 'kInvalidDtId'.
  529. cmDtRC_t cmDataRecdAllocLabelV( cmData_t* parent, cmErr_t* err, cmRC_t errRC, cmData_t** ref, va_list vl );
  530. cmDtRC_t cmDataRecdAllocLabelA( cmData_t* parent, cmErr_t* err, cmRC_t errRC, cmData_t** ref, ... );
  531. cmDtRC_t cmDataRecdAllocIdV( cmData_t* parent, cmErr_t* err, cmRC_t errRC, cmData_t** ref, va_list vl );
  532. cmDtRC_t cmDataRecdAllocIdA( cmData_t* parent, cmErr_t* err, cmRC_t errRC, cmData_t** ref, ... );
  533. // Extract the data in a record to C variables.
  534. // Var-args format:
  535. // (label | id) <cid> <typeId> <ptr> {cnt_ptr}
  536. // The var-args list must be NULL terminated.
  537. // The <'id' | 'label'> identify a pair.
  538. // The <cid> indicates the type of the target container.
  539. // The <typeId> indicates the C type of 'pointer'.
  540. // If <cid> is kArrayDtId then the <cnt_ptr} must be include to receive the
  541. // count of elements in the array.
  542. // The actual field type must be convertable into this pointer type or the
  543. // function will fail.
  544. // 'err' is an application supplied error object to be used if a required
  545. // field is missing. 'errRC' is the client result code to be passed with
  546. // the error report. See cmErrMsg(). Both 'err' and 'errRC' are optional.
  547. // Set kOptArgDtFl on 'typeId' to indicate that a field is optional.
  548. // <label|id> (<typeId> | kOptArgDtFl) <pointer>
  549. cmDtRC_t cmDataRecdParseLabelV(cmData_t* p, cmErr_t* err, unsigned errRC, va_list vl );
  550. cmDtRC_t cmDataRecdParseLabel( cmData_t* p, cmErr_t* err, unsigned errRC, ... );
  551. cmDtRC_t cmDataRecdParseIdV( cmData_t* p, cmErr_t* err, unsigned errRC, va_list vl );
  552. cmDtRC_t cmDataRecdParseId( cmData_t* p, cmErr_t* err, unsigned errRC, ... );
  553. //----------------------------------------------------------------------------
  554. // Serialization related functions
  555. //
  556. unsigned cmDataSerializeByteCount( const cmData_t* p );
  557. cmDtRC_t cmDataSerialize( const cmData_t* p, void* buf, unsigned bufByteCnt );
  558. cmDtRC_t cmDataDeserialize( const void* buf, unsigned bufByteCnt, cmData_t** pp );
  559. //----------------------------------------------------------------------------
  560. // Text to Data related functions
  561. //
  562. typedef cmHandle_t cmDataParserH_t;
  563. extern cmDataParserH_t cmDataParserNullHandle;
  564. cmDtRC_t cmDataParserCreate( cmCtx_t* ctx, cmDataParserH_t* hp );
  565. cmDtRC_t cmDataParserDestroy( cmDataParserH_t* hp );
  566. bool cmDataParserIsValid( cmDataParserH_t h );
  567. // Parse a text representation into a 'record' type.
  568. // Note that the text is wrapped with implied curly braces
  569. // (e.g. "{ text }"). The contents of the text should therefore
  570. // fit the record syntax (e.g. the first token should be a
  571. // 'pair' label.
  572. cmDtRC_t cmDataParserExec( cmDataParserH_t h, const cmChar_t* text, cmData_t** pp );
  573. //-----------------------------------------------------------------------------
  574. void cmDataPrint( const cmData_t* p, cmRpt_t* rpt );
  575. void cmDataTest( cmCtx_t* ctx );
  576. //)
  577. #ifdef __cplusplus
  578. }
  579. #endif
  580. #endif