| api.md (268831) | api.md (279549) |
|---|---|
| 1# API documentation 2 3**Table of Contents** *generated with [DocToc](http://doctoc.herokuapp.com/)* 4 5- [Synopsis](#synopsis) 6- [Description](#description) 7 - [Parser functions](#parser-functions) 8 - [Emitting functions](#emitting-functions) --- 363 unchanged lines hidden (view full) --- 372- `UCL_STRING_PARSE_NUMBER` - parse passed string and detect number (both float, integer and time types) 373- `UCL_STRING_PARSE` - parse passed string (and detect booleans, numbers and time values) 374- `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 375 376If 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. 377 378# Iteration functions 379 | 1# API documentation 2 3**Table of Contents** *generated with [DocToc](http://doctoc.herokuapp.com/)* 4 5- [Synopsis](#synopsis) 6- [Description](#description) 7 - [Parser functions](#parser-functions) 8 - [Emitting functions](#emitting-functions) --- 363 unchanged lines hidden (view full) --- 372- `UCL_STRING_PARSE_NUMBER` - parse passed string and detect number (both float, integer and time types) 373- `UCL_STRING_PARSE` - parse passed string (and detect booleans, numbers and time values) 374- `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 375 376If 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. 377 378# Iteration functions 379 |
| 380Iteration 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`. | 380Iteration are used to iterate over UCL compound types: arrays and objects. Moreover, iterations could be performed over the keys with multiple values (implicit arrays). 381There are two types of iterators API: old and unsafe one via `ucl_iterate_object` and the proposed interface of safe iterators. |
| 381 | 382 |
| 383 |
|
| 382## ucl_iterate_object 383~~~C 384const ucl_object_t* ucl_iterate_object (const ucl_object_t *obj, 385 ucl_object_iter_t *iter, bool expand_values); 386~~~ 387 388This function accepts 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 through 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 is 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): 389 --- 7 unchanged lines hidden (view full) --- 397 /* Iterate over the values of a key */ 398 while ((cur = ucl_iterate_object (obj, &it_obj, false))) { 399 printf ("value: \"%s\"\n", 400 ucl_object_tostring_forced (cur)); 401 } 402} 403~~~ 404 | 384## ucl_iterate_object 385~~~C 386const ucl_object_t* ucl_iterate_object (const ucl_object_t *obj, 387 ucl_object_iter_t *iter, bool expand_values); 388~~~ 389 390This function accepts 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 through 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 is 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): 391 --- 7 unchanged lines hidden (view full) --- 399 /* Iterate over the values of a key */ 400 while ((cur = ucl_iterate_object (obj, &it_obj, false))) { 401 printf ("value: \"%s\"\n", 402 ucl_object_tostring_forced (cur)); 403 } 404} 405~~~ 406 |
| 407## Safe iterators API 408 409Safe iterators are defined to clarify iterating over UCL objects and simplify flattening of UCL objects in non-trivial cases. 410For example, if there is an implicit array that contains another array and a boolean value it is extremely unclear how to iterate over 411such an object. Safe iterators are desinged to define two sorts of iteration: 412 4131. Iteration over complex objects with expanding all values 4142. Iteration over complex objects without expanding of values 415 416The following example demonstrates the difference between these two types of iteration: 417 418~~~ 419key = 1; 420key = [2, 3, 4]; 421 422Iteration with expansion: 423 4241, 2, 3, 4 425 426Iteration without expansion: 427 4281, [2, 3, 4] 429~~~ 430 431UCL defines the following functions to manage safe iterators: 432 433- `ucl_object_iterate_new` - creates new safe iterator 434- `ucl_object_iterate_reset` - resets iterator to a new object 435- `ucl_object_iterate_safe` - safely iterate the object inside iterator 436- `ucl_object_iterate_free` - free memory associated with the safe iterator 437 438Please note that unlike unsafe iterators, safe iterators *must* be explicitly initialized and freed. 439An assert is likely generated if you use uninitialized or `NULL` iterator in all safe iterators functions. 440 441~~~C 442ucl_object_iter_t it; 443const ucl_object_t *cur; 444 445it = ucl_object_iterate_new (obj); 446 447while ((cur = ucl_object_iterate_safe (it, true)) != NULL) { 448 /* Do something */ 449} 450 451/* Switch to another object */ 452it = ucl_object_iterate_reset (it, another_obj); 453 454while ((cur = ucl_object_iterate_safe (it, true)) != NULL) { 455 /* Do something else */ 456} 457 458ucl_object_iterate_free (it); 459~~~ 460 |
|
| 405# Validation functions 406 407Currently, there is only one validation function called `ucl_object_validate`. It performs validation of object using the specified schema. This function is defined as following: 408 409## ucl_object_validate 410~~~C 411bool ucl_object_validate (const ucl_object_t *schema, 412 const ucl_object_t *obj, struct ucl_schema_error *err); --- 27 unchanged lines hidden --- | 461# Validation functions 462 463Currently, there is only one validation function called `ucl_object_validate`. It performs validation of object using the specified schema. This function is defined as following: 464 465## ucl_object_validate 466~~~C 467bool ucl_object_validate (const ucl_object_t *schema, 468 const ucl_object_t *obj, struct ucl_schema_error *err); --- 27 unchanged lines hidden --- |