| api.md (262398) | api.md (262975) |
|---|---|
| 1Synopsis 2======== 3 4`#include <ucl.h>` 5 6Description 7=========== 8 --- 247 unchanged lines hidden (view full) --- 256- `ucl_object_toint` - returns `int64_t` of UCL object 257- `ucl_object_todouble` - returns `double` of UCL object 258- `ucl_object_toboolean` - returns `bool` of UCL object 259- `ucl_object_tostring` - returns `const char *` of UCL object (this string is NULL terminated) 260- `ucl_object_tolstring` - returns `const char *` and `size_t` len of UCL object (string can be not NULL terminated) 261- `ucl_object_tostring_forced` - returns string representation of any UCL object 262 263Strings returned by these pointers are associated with the UCL object and exist over its lifetime. A caller should not free this memory. | 1Synopsis 2======== 3 4`#include <ucl.h>` 5 6Description 7=========== 8 --- 247 unchanged lines hidden (view full) --- 256- `ucl_object_toint` - returns `int64_t` of UCL object 257- `ucl_object_todouble` - returns `double` of UCL object 258- `ucl_object_toboolean` - returns `bool` of UCL object 259- `ucl_object_tostring` - returns `const char *` of UCL object (this string is NULL terminated) 260- `ucl_object_tolstring` - returns `const char *` and `size_t` len of UCL object (string can be not NULL terminated) 261- `ucl_object_tostring_forced` - returns string representation of any UCL object 262 263Strings returned by these pointers are associated with the UCL object and exist over its lifetime. A caller should not free this memory. |
| 264 265# Generation functions 266 267It is possible to generate UCL objects from C primitive types. Moreover, libucl permits to create and modify complex UCL objects, such as arrays or associative objects. 268 269## ucl_object_new 270~~~C 271ucl_object_t * ucl_object_new (void) 272~~~ 273 274Creates new object of type `UCL_NULL`. This object should be released by caller. 275 276## ucl_object_typed_new 277~~~C 278ucl_object_t * ucl_object_typed_new (unsigned int type) 279~~~ 280 281Create an object of a specified type: 282- `UCL_OBJECT` - UCL object - key/value pairs 283- `UCL_ARRAY` - UCL array 284- `UCL_INT` - integer number 285- `UCL_FLOAT` - floating point number 286- `UCL_STRING` - NULL terminated string 287- `UCL_BOOLEAN` - boolean value 288- `UCL_TIME` - time value (floating point number of seconds) 289- `UCL_USERDATA` - opaque userdata pointer (may be used in macros) 290- `UCL_NULL` - null value 291 292This object should be released by caller. 293 294## Primitive objects generation 295Libucl provides the functions similar to inverse conversion functions called with the specific C type: 296- `ucl_object_fromint` - converts `int64_t` to UCL object 297- `ucl_object_fromdouble` - converts `double` to UCL object 298- `ucl_object_fromboolean` - converts `bool` to UCL object 299- `ucl_object_fromstring` - converts `const char *` to UCL object (this string is NULL terminated) 300- `ucl_object_fromlstring` - converts `const char *` and `size_t` len to UCL object (string can be not NULL terminated) 301 302Also there is a function to generate UCL object from a string performing various parsing or conversion operations called `ucl_object_fromstring_common`. 303 304## ucl_object_fromstring_common 305~~~C 306ucl_object_t * ucl_object_fromstring_common (const char *str, 307 size_t len, enum ucl_string_flags flags) 308~~~ 309 310This function is used to convert a string `str` of size `len` to an UCL objects applying `flags` conversions. If `len` is equal to zero then a `str` is assumed as NULL-terminated. This function supports the following flags (a set of flags can be specified using logical `OR` operation): 311 312- `UCL_STRING_ESCAPE` - perform JSON escape 313- `UCL_STRING_TRIM` - trim leading and trailing whitespaces 314- `UCL_STRING_PARSE_BOOLEAN` - parse passed string and detect boolean 315- `UCL_STRING_PARSE_INT` - parse passed string and detect integer number 316- `UCL_STRING_PARSE_DOUBLE` - parse passed string and detect integer or float number 317- `UCL_STRING_PARSE_NUMBER` - parse passed string and detect number (both float or integer types) 318- `UCL_STRING_PARSE` - parse passed string (and detect booleans and numbers) 319- `UCL_STRING_PARSE_BYTES` - assume that numeric multipliers are in bytes notation, for example `10k` means `10*1024` and not `10*1000` as assumed without this flag 320 321If parsing operations fail then the resulting UCL object will be a `UCL_STRING`. A caller should always check the type of the returned object and release it after using. 322 323# Iteration function 324 325Iteration are used to iterate over UCL compound types: arrays and objects. Moreover, iterations could be performed over the keys with multiple values (implicit arrays). To iterate over an object, an array or a key with multiple values there is a function `ucl_iterate_object`. 326 327## ucl_iterate_object 328~~~C 329ucl_object_t* ucl_iterate_object (ucl_object_t *obj, 330 ucl_object_iter_t *iter, bool expand_values); 331~~~ 332 333This function accept opaque iterator pointer `iter`. In the first call this iterator *must* be initialized to `NULL`. Iterator is changed by this function call. `ucl_iterate_object` returns the next UCL object in the compound object `obj` or `NULL` if all objects have been iterated. The reference count of the object returned is not increased, so a caller should not unref the object or modify its content (e.g. by inserting to another compound object). The object `obj` should not be changed during the iteration process as well. `expand_values` flag speicifies whether `ucl_iterate_object` should expand keys with multiple values. The general rule is that if you need to iterate throught the *object* or *explicit array*, then you always need to set this flag to `true`. However, if you get some key in the object and want to extract all its values then you should set `expand_values` to `false`. Mixing of iteration types are not permitted since the iterator is set according to the iteration type and cannot be reused. Here is an example of iteration over the objects using libucl API (assuming that `top` is `UCL_OBJECT` in this example): 334 335~~~C 336ucl_object_iter_t it = NULL, it_obj = NULL; 337ucl_object_t *cur, *tmp; 338 339/* Iterate over the object */ 340while ((obj = ucl_iterate_object (top, &it, true))) { 341 printf ("key: \"%s\"\n", ucl_object_key (obj)); 342 /* Iterate over the values of a key */ 343 while ((cur = ucl_iterate_object (obj, &it_obj, false))) { 344 printf ("value: \"%s\"\n", 345 ucl_object_tostring_forced (cur)); 346 } 347} 348~~~ |
|