| | @@ -59,11 +59,11 @@ |
| 59 | 59 | #define CSON_INT_T_PFMT "I64d" |
| 60 | 60 | #elif (__STDC_VERSION__ >= 199901L) || (HAVE_LONG_LONG == 1) |
| 61 | 61 | typedef long long cson_int_t; |
| 62 | 62 | #define CSON_INT_T_SFMT "lld" |
| 63 | 63 | #define CSON_INT_T_PFMT "lld" |
| 64 | | -#else |
| 64 | +#else |
| 65 | 65 | typedef long cson_int_t; |
| 66 | 66 | #define CSON_INT_T_SFMT "ld" |
| 67 | 67 | #define CSON_INT_T_PFMT "ld" |
| 68 | 68 | #endif |
| 69 | 69 | |
| | @@ -215,11 +215,11 @@ |
| 215 | 215 | Convenience typedef. |
| 216 | 216 | */ |
| 217 | 217 | typedef struct cson_value cson_value; |
| 218 | 218 | |
| 219 | 219 | /** @struct cson_value |
| 220 | | - |
| 220 | + |
| 221 | 221 | The core value type of this API. It is opaque to clients, and |
| 222 | 222 | only the cson public API should be used for setting or |
| 223 | 223 | inspecting their values. |
| 224 | 224 | |
| 225 | 225 | This class is opaque because stack-based usage can easily cause |
| | @@ -231,11 +231,11 @@ |
| 231 | 231 | counting) as long as those insertions do not cause cycles. However, |
| 232 | 232 | be very aware that such value re-use uses a reference to the |
| 233 | 233 | original copy, meaning that if its value is changed once, it is |
| 234 | 234 | changed everywhere. Also beware that multi-threaded write |
| 235 | 235 | operations on such references leads to undefined behaviour. |
| 236 | | - |
| 236 | + |
| 237 | 237 | PLEASE read the ACHTUNGEN below... |
| 238 | 238 | |
| 239 | 239 | ACHTUNG #1: |
| 240 | 240 | |
| 241 | 241 | cson_values MUST NOT form cycles (e.g. via object or array |
| | @@ -244,33 +244,33 @@ |
| 244 | 244 | Not abiding th Holy Law Of No Cycles will lead to double-frees and |
| 245 | 245 | the like (i.e. undefined behaviour, likely crashes due to infinite |
| 246 | 246 | recursion or stepping on invalid (freed) pointers). |
| 247 | 247 | |
| 248 | 248 | ACHTUNG #2: |
| 249 | | - |
| 249 | + |
| 250 | 250 | ALL cson_values returned as non-const cson_value pointers from any |
| 251 | 251 | public functions in the cson API are to be treated as if they are |
| 252 | 252 | heap-allocated, and MUST be freed by client by doing ONE of: |
| 253 | | - |
| 253 | + |
| 254 | 254 | - Passing it to cson_value_free(). |
| 255 | | - |
| 255 | + |
| 256 | 256 | - Adding it to an Object or Array, in which case the object/array |
| 257 | 257 | takes over ownership. As of 20110323, a value may be inserted into |
| 258 | 258 | a single container multiple times, or into multiple containers, |
| 259 | 259 | in which case they all share ownership (via reference counting) |
| 260 | 260 | of the original value (meaning any changes to it are visible in |
| 261 | 261 | all references to it). |
| 262 | | - |
| 262 | + |
| 263 | 263 | Each call to cson_value_new_xxx() MUST eventually be followed up |
| 264 | 264 | by one of those options. |
| 265 | | - |
| 265 | + |
| 266 | 266 | Some cson_value_new_XXX() implementations do not actually allocate |
| 267 | 267 | memory, but this is an internal implementation detail. Client code |
| 268 | 268 | MUST NOT rely on this behaviour and MUST treat each object |
| 269 | 269 | returned by such a function as if it was a freshly-allocated copy |
| 270 | 270 | (even if their pointer addresses are the same). |
| 271 | | - |
| 271 | + |
| 272 | 272 | ACHTUNG #3: |
| 273 | 273 | |
| 274 | 274 | Note that ACHTUNG #2 tells us that we must always free (or transfer |
| 275 | 275 | ownership of) all pointers returned bycson_value_new_xxx(), but |
| 276 | 276 | that two calls to (e.g.) cson_value_new_bool(1) will (or might) |
| | @@ -315,11 +315,11 @@ |
| 315 | 315 | if( 0 == rc ) {...success...} |
| 316 | 316 | else if( cson_rc.ArgError == rc ) { ... some argument was wrong ... } |
| 317 | 317 | else if( cson_rc.AllocError == rc ) { ... allocation error ... } |
| 318 | 318 | ... |
| 319 | 319 | @endcode |
| 320 | | - |
| 320 | + |
| 321 | 321 | The entries named Parse_XXX are generally only returned by |
| 322 | 322 | cson_parse() and friends. |
| 323 | 323 | */ |
| 324 | 324 | |
| 325 | 325 | /** @struct cson_rc_ |
| | @@ -472,11 +472,11 @@ |
| 472 | 472 | |
| 473 | 473 | /** |
| 474 | 474 | Length, in bytes. |
| 475 | 475 | */ |
| 476 | 476 | unsigned int length; |
| 477 | | - |
| 477 | + |
| 478 | 478 | /** |
| 479 | 479 | Error code of the parse run (0 for no error). |
| 480 | 480 | */ |
| 481 | 481 | int errorCode; |
| 482 | 482 | |
| | @@ -523,11 +523,11 @@ |
| 523 | 523 | /** |
| 524 | 524 | Specifies how to indent (or not) output. The values |
| 525 | 525 | are: |
| 526 | 526 | |
| 527 | 527 | (0) == no extra indentation. |
| 528 | | - |
| 528 | + |
| 529 | 529 | (1) == 1 TAB character for each level. |
| 530 | 530 | |
| 531 | 531 | (>1) == that number of SPACES for each level. |
| 532 | 532 | */ |
| 533 | 533 | unsigned char indentation; |
| | @@ -536,11 +536,11 @@ |
| 536 | 536 | Maximum object/array depth to traverse. Traversing deeply can |
| 537 | 537 | be indicative of cycles in the object/array tree, and this |
| 538 | 538 | value is used to figure out when to abort the traversal. |
| 539 | 539 | */ |
| 540 | 540 | unsigned short maxDepth; |
| 541 | | - |
| 541 | + |
| 542 | 542 | /** |
| 543 | 543 | If true, a newline will be added to generated output, |
| 544 | 544 | else not. |
| 545 | 545 | */ |
| 546 | 546 | char addNewline; |
| | @@ -636,11 +636,11 @@ |
| 636 | 636 | |
| 637 | 637 | Must return 0 on success, non-0 on error (preferably a value from |
| 638 | 638 | cson_rc). |
| 639 | 639 | |
| 640 | 640 | These functions are called relatively often during the JSON-output |
| 641 | | - process, and should try to be fast. |
| 641 | + process, and should try to be fast. |
| 642 | 642 | */ |
| 643 | 643 | typedef int (*cson_data_dest_f)( void * state, void const * src, unsigned int n ); |
| 644 | 644 | |
| 645 | 645 | /** |
| 646 | 646 | Reads JSON-formatted string data (in ASCII, UTF8, or UTF16), using the |
| | @@ -664,15 +664,15 @@ |
| 664 | 664 | used. |
| 665 | 665 | |
| 666 | 666 | The info argument may be NULL. If it is not NULL then the parser |
| 667 | 667 | populates it with information which is useful in error |
| 668 | 668 | reporting. Namely, it contains the line/column of parse errors. |
| 669 | | - |
| 669 | + |
| 670 | 670 | The srcState argument is ignored by this function but is passed on to src, |
| 671 | 671 | so any output-destination-specific state can be stored there and accessed |
| 672 | 672 | via the src callback. |
| 673 | | - |
| 673 | + |
| 674 | 674 | Non-parse error conditions include: |
| 675 | 675 | |
| 676 | 676 | - (!tgt) or !src: cson_rc.ArgError |
| 677 | 677 | - cson_rc.AllocError can happen at any time during the input phase |
| 678 | 678 | |
| | @@ -725,11 +725,11 @@ |
| 725 | 725 | TODOs: |
| 726 | 726 | |
| 727 | 727 | - Buffer the input in larger chunks. We currently read |
| 728 | 728 | byte-by-byte, but i'm too tired to write/test the looping code for |
| 729 | 729 | the buffering. |
| 730 | | - |
| 730 | + |
| 731 | 731 | @see cson_parse_FILE() |
| 732 | 732 | @see cson_parse_string() |
| 733 | 733 | */ |
| 734 | 734 | int cson_parse( cson_value ** tgt, cson_data_source_f src, void * srcState, |
| 735 | 735 | cson_parse_opt const * opt, cson_parse_info * info ); |
| | @@ -786,11 +786,11 @@ |
| 786 | 786 | The destState parameter is ignored by this function and is passed |
| 787 | 787 | on to the dest function. |
| 788 | 788 | |
| 789 | 789 | Returns 0 on success. On error, any amount of output might have been |
| 790 | 790 | generated before the error was triggered. |
| 791 | | - |
| 791 | + |
| 792 | 792 | Example: |
| 793 | 793 | |
| 794 | 794 | @code |
| 795 | 795 | int rc = cson_output( myValue, cson_data_dest_FILE, stdout, NULL ); |
| 796 | 796 | // basically equivalent to: cson_output_FILE( myValue, stdout, NULL ); |
| | @@ -925,15 +925,15 @@ |
| 925 | 925 | /** |
| 926 | 926 | Converts the given value to a boolean, using JavaScript semantics depending |
| 927 | 927 | on the concrete type of val: |
| 928 | 928 | |
| 929 | 929 | undef or null: false |
| 930 | | - |
| 930 | + |
| 931 | 931 | boolean: same |
| 932 | | - |
| 932 | + |
| 933 | 933 | integer, double: 0 or 0.0 == false, else true |
| 934 | | - |
| 934 | + |
| 935 | 935 | object, array: true |
| 936 | 936 | |
| 937 | 937 | string: length-0 string is false, else true. |
| 938 | 938 | |
| 939 | 939 | Returns 0 on success and assigns *v (if v is not NULL) to either 0 or 1. |
| | @@ -945,18 +945,18 @@ |
| 945 | 945 | Similar to cson_value_fetch_bool(), but fetches an integer value. |
| 946 | 946 | |
| 947 | 947 | The conversion, if any, depends on the concrete type of val: |
| 948 | 948 | |
| 949 | 949 | NULL, null, undefined: *v is set to 0 and 0 is returned. |
| 950 | | - |
| 950 | + |
| 951 | 951 | string, object, array: *v is set to 0 and |
| 952 | 952 | cson_rc.TypeError is returned. The error may normally be safely |
| 953 | 953 | ignored, but it is provided for those wanted to know whether a direct |
| 954 | 954 | conversion was possible. |
| 955 | 955 | |
| 956 | 956 | integer: *v is set to the int value and 0 is returned. |
| 957 | | - |
| 957 | + |
| 958 | 958 | double: *v is set to the value truncated to int and 0 is returned. |
| 959 | 959 | */ |
| 960 | 960 | int cson_value_fetch_integer( cson_value const * val, cson_int_t * v ); |
| 961 | 961 | |
| 962 | 962 | /** |
| | @@ -1084,11 +1084,11 @@ |
| 1084 | 1084 | |
| 1085 | 1085 | - The maximum number of bytes compared is the lesser of rhsLen and |
| 1086 | 1086 | the length of lhs. If the strings do not match, but compare equal |
| 1087 | 1087 | up to the just-described comparison length, the shorter string is |
| 1088 | 1088 | considered to be less-than the longer one. |
| 1089 | | - |
| 1089 | + |
| 1090 | 1090 | - If lhs and rhs are both NULL, or both have a length of 0 then they will |
| 1091 | 1091 | compare equal. |
| 1092 | 1092 | |
| 1093 | 1093 | - If lhs is null/length-0 but rhs is not then lhs is considered to be less-than |
| 1094 | 1094 | rhs. |
| | @@ -1110,11 +1110,11 @@ |
| 1110 | 1110 | Returns the length, in bytes, of str, or 0 if str is NULL. This is |
| 1111 | 1111 | an O(1) operation. |
| 1112 | 1112 | |
| 1113 | 1113 | TODO: add cson_string_length_chars() (is O(N) unless we add another |
| 1114 | 1114 | member to store the char length). |
| 1115 | | - |
| 1115 | + |
| 1116 | 1116 | @see cson_string_cstr() |
| 1117 | 1117 | */ |
| 1118 | 1118 | unsigned int cson_string_length_bytes( cson_string const * str ); |
| 1119 | 1119 | |
| 1120 | 1120 | /** |
| | @@ -1207,11 +1207,11 @@ |
| 1207 | 1207 | ar is expanded, if needed, to be able to hold at least (ndx+1) |
| 1208 | 1208 | items, and any new entries created by that expansion are empty |
| 1209 | 1209 | (NULL values). |
| 1210 | 1210 | |
| 1211 | 1211 | On success, 0 is returned and ownership of v is transfered to ar. |
| 1212 | | - |
| 1212 | + |
| 1213 | 1213 | On error ownership of v is NOT modified, and the caller may still |
| 1214 | 1214 | need to clean it up. For example, the following code will introduce |
| 1215 | 1215 | a leak if this function fails: |
| 1216 | 1216 | |
| 1217 | 1217 | @code |
| | @@ -1240,11 +1240,11 @@ |
| 1240 | 1240 | |
| 1241 | 1241 | This is functionally equivalent to |
| 1242 | 1242 | cson_array_set(ar,cson_array_length_get(ar),v), but this |
| 1243 | 1243 | implementation has slightly different array-preallocation policy |
| 1244 | 1244 | (it grows more eagerly). |
| 1245 | | - |
| 1245 | + |
| 1246 | 1246 | Returns 0 on success, non-zero on error. Error cases include: |
| 1247 | 1247 | |
| 1248 | 1248 | - ar or v are NULL: cson_rc.ArgError |
| 1249 | 1249 | |
| 1250 | 1250 | - Array cannot be expanded to hold enough elements: cson_rc.AllocError. |
| | @@ -1283,11 +1283,11 @@ |
| 1283 | 1283 | cson_value * cson_new_bool(char v); |
| 1284 | 1284 | |
| 1285 | 1285 | /** |
| 1286 | 1286 | Returns the special JSON "null" value. When outputing JSON, |
| 1287 | 1287 | its string representation is "null" (without the quotes). |
| 1288 | | - |
| 1288 | + |
| 1289 | 1289 | See cson_value_new_bool() for notes regarding the returned |
| 1290 | 1290 | value's memory. |
| 1291 | 1291 | */ |
| 1292 | 1292 | cson_value * cson_value_null(); |
| 1293 | 1293 | |
| | @@ -1323,16 +1323,16 @@ |
| 1323 | 1323 | |
| 1324 | 1324 | /** |
| 1325 | 1325 | Semantically the same as cson_value_new_bool(), but for strings. |
| 1326 | 1326 | This creates a JSON value which copies the first n bytes of str. |
| 1327 | 1327 | The string will automatically be NUL-terminated. |
| 1328 | | - |
| 1328 | + |
| 1329 | 1329 | Note that if str is NULL or n is 0, this function still |
| 1330 | 1330 | returns non-NULL value representing that empty string. |
| 1331 | | - |
| 1331 | + |
| 1332 | 1332 | Returns NULL on allocation error. |
| 1333 | | - |
| 1333 | + |
| 1334 | 1334 | See cson_value_new_bool() for important information about the |
| 1335 | 1335 | returned memory. |
| 1336 | 1336 | */ |
| 1337 | 1337 | cson_value * cson_value_new_string( char const * str, unsigned int n ); |
| 1338 | 1338 | |
| | @@ -1354,11 +1354,11 @@ |
| 1354 | 1354 | This works like cson_value_new_object() but returns an Object |
| 1355 | 1355 | handle directly. |
| 1356 | 1356 | |
| 1357 | 1357 | The value handle for the returned object can be fetched with |
| 1358 | 1358 | cson_object_value(theObject). |
| 1359 | | - |
| 1359 | + |
| 1360 | 1360 | Ownership is transfered to the caller, who must eventually free it |
| 1361 | 1361 | by passing the Value handle (NOT the Object handle) to |
| 1362 | 1362 | cson_value_free() or passing ownership to a parent container. |
| 1363 | 1363 | |
| 1364 | 1364 | Returns NULL on error (out of memory). |
| | @@ -1419,11 +1419,11 @@ |
| 1419 | 1419 | cson_value_add_reference(). Even if this function does not |
| 1420 | 1420 | immediately destroy the value, the value must be considered, from |
| 1421 | 1421 | the perspective of that client code, to have been |
| 1422 | 1422 | destroyed/invalidated by this call. |
| 1423 | 1423 | |
| 1424 | | - |
| 1424 | + |
| 1425 | 1425 | @see cson_value_new_object() |
| 1426 | 1426 | @see cson_value_new_array() |
| 1427 | 1427 | @see cson_value_add_reference() |
| 1428 | 1428 | */ |
| 1429 | 1429 | void cson_value_free(cson_value * v); |
| | @@ -1445,11 +1445,11 @@ |
| 1445 | 1445 | case, the key is set to the special null value. |
| 1446 | 1446 | |
| 1447 | 1447 | The key may be encoded as ASCII or UTF8. Results are undefined |
| 1448 | 1448 | with other encodings, and the errors won't show up here, but may |
| 1449 | 1449 | show up later, e.g. during output. |
| 1450 | | - |
| 1450 | + |
| 1451 | 1451 | Returns 0 on success, non-0 on error. It has the following error |
| 1452 | 1452 | cases: |
| 1453 | 1453 | |
| 1454 | 1454 | - cson_rc.ArgError: obj or key are NULL or strlen(key) is 0. |
| 1455 | 1455 | |
| | @@ -1498,11 +1498,11 @@ |
| 1498 | 1498 | */ |
| 1499 | 1499 | int cson_object_set_s( cson_object * obj, cson_string * key, cson_value * v ); |
| 1500 | 1500 | |
| 1501 | 1501 | /** |
| 1502 | 1502 | Removes a property from an object. |
| 1503 | | - |
| 1503 | + |
| 1504 | 1504 | If obj contains the given key, it is removed and 0 is returned. If |
| 1505 | 1505 | it is not found, cson_rc.NotFoundError is returned (which can |
| 1506 | 1506 | normally be ignored by client code). |
| 1507 | 1507 | |
| 1508 | 1508 | cson_rc.ArgError is returned if obj or key are NULL or key has |
| | @@ -1569,33 +1569,33 @@ |
| 1569 | 1569 | |
| 1570 | 1570 | If it finds the given path, it returns the value by assiging *tgt |
| 1571 | 1571 | to it. If tgt is NULL then this function has no side-effects but |
| 1572 | 1572 | will return 0 if the given path is found within the object, so it can be used |
| 1573 | 1573 | to test for existence without fetching it. |
| 1574 | | - |
| 1574 | + |
| 1575 | 1575 | Returns 0 if it finds an entry, cson_rc.NotFoundError if it finds |
| 1576 | 1576 | no item, and any other non-zero error code on a "real" error. Errors include: |
| 1577 | 1577 | |
| 1578 | 1578 | - obj or path are NULL: cson_rc.ArgError |
| 1579 | | - |
| 1579 | + |
| 1580 | 1580 | - separator is 0, or path is an empty string or contains only |
| 1581 | 1581 | separator characters: cson_rc.RangeError |
| 1582 | 1582 | |
| 1583 | 1583 | - There is an upper limit on how long a single path component may |
| 1584 | 1584 | be (some "reasonable" internal size), and cson_rc.RangeError is |
| 1585 | 1585 | returned if that length is violated. |
| 1586 | 1586 | |
| 1587 | | - |
| 1587 | + |
| 1588 | 1588 | Limitations: |
| 1589 | 1589 | |
| 1590 | 1590 | - It has no way to fetch data from arrays this way. i could |
| 1591 | 1591 | imagine, e.g., a path of "subobj.subArray.0" for |
| 1592 | 1592 | subobj.subArray[0], or "0.3.1" for [0][3][1]. But i'm too |
| 1593 | 1593 | lazy/tired to add this. |
| 1594 | 1594 | |
| 1595 | 1595 | Example usage: |
| 1596 | | - |
| 1596 | + |
| 1597 | 1597 | |
| 1598 | 1598 | Assume we have a JSON structure which abstractly looks like: |
| 1599 | 1599 | |
| 1600 | 1600 | @code |
| 1601 | 1601 | {"subobj":{"subsubobj":{"myValue":[1,2,3]}}} |
| | @@ -1613,11 +1613,11 @@ |
| 1613 | 1613 | "subobj/subsubobj/myValue" with separator='/' is equivalent the |
| 1614 | 1614 | path "subobj.subsubobj.myValue" with separator='.'. The value of 0 |
| 1615 | 1615 | is not legal as a separator character because we cannot |
| 1616 | 1616 | distinguish that use from the real end-of-string without requiring |
| 1617 | 1617 | the caller to also pass in the length of the string. |
| 1618 | | - |
| 1618 | + |
| 1619 | 1619 | Multiple successive separators in the list are collapsed into a |
| 1620 | 1620 | single separator for parsing purposes. e.g. the path "a...b...c" |
| 1621 | 1621 | (separator='.') is equivalent to "a.b.c". |
| 1622 | 1622 | |
| 1623 | 1623 | @see cson_object_get_sub() |
| | @@ -1700,11 +1700,11 @@ |
| 1700 | 1700 | @see cson_object_iter_init() |
| 1701 | 1701 | @see cson_object_iter_next() |
| 1702 | 1702 | */ |
| 1703 | 1703 | struct cson_object_iterator |
| 1704 | 1704 | { |
| 1705 | | - |
| 1705 | + |
| 1706 | 1706 | /** @internal |
| 1707 | 1707 | The underlying object. |
| 1708 | 1708 | */ |
| 1709 | 1709 | cson_object const * obj; |
| 1710 | 1710 | /** @internal |
| | @@ -1771,11 +1771,11 @@ |
| 1771 | 1771 | ... |
| 1772 | 1772 | } |
| 1773 | 1773 | @endcode |
| 1774 | 1774 | |
| 1775 | 1775 | There is no need to clean up an iterator, as it holds no dynamic resources. |
| 1776 | | - |
| 1776 | + |
| 1777 | 1777 | @see cson_kvp_key() |
| 1778 | 1778 | @see cson_kvp_value() |
| 1779 | 1779 | */ |
| 1780 | 1780 | cson_kvp * cson_object_iter_next( cson_object_iterator * iter ); |
| 1781 | 1781 | |
| | @@ -1863,11 +1863,11 @@ |
| 1863 | 1863 | buf = cson_buffer_empty; |
| 1864 | 1864 | @endcode |
| 1865 | 1865 | |
| 1866 | 1866 | (You might also need to store buf.used and buf.capacity, |
| 1867 | 1867 | depending on what you want to do with the memory.) |
| 1868 | | - |
| 1868 | + |
| 1869 | 1869 | When doing so, the memory must eventually be passed to free() |
| 1870 | 1870 | to deallocate it. |
| 1871 | 1871 | */ |
| 1872 | 1872 | unsigned char * mem; |
| 1873 | 1873 | }; |
| | @@ -1894,11 +1894,11 @@ |
| 1894 | 1894 | On error non-zero is returned. Errors include: |
| 1895 | 1895 | |
| 1896 | 1896 | - Invalid arguments: cson_rc.ArgError |
| 1897 | 1897 | |
| 1898 | 1898 | - Buffer cannot be expanded (runs out of memory): cson_rc.AllocError |
| 1899 | | - |
| 1899 | + |
| 1900 | 1900 | Example usage: |
| 1901 | 1901 | |
| 1902 | 1902 | @code |
| 1903 | 1903 | cson_buffer buf = cson_buffer_empty; |
| 1904 | 1904 | // optional: cson_buffer_reserve(&buf, 1024 * 10); |
| | @@ -1918,13 +1918,13 @@ |
| 1918 | 1918 | buf = cson_buffer_empty; |
| 1919 | 1919 | ... |
| 1920 | 1920 | free(mem); |
| 1921 | 1921 | } |
| 1922 | 1922 | @endcode |
| 1923 | | - |
| 1923 | + |
| 1924 | 1924 | @see cson_output() |
| 1925 | | - |
| 1925 | + |
| 1926 | 1926 | */ |
| 1927 | 1927 | int cson_output_buffer( cson_value const * v, cson_buffer * buf, |
| 1928 | 1928 | cson_output_opt const * opt ); |
| 1929 | 1929 | |
| 1930 | 1930 | /** |
| | @@ -1993,11 +1993,11 @@ |
| 1993 | 1993 | calling cson_buffer_reserve(dest,0). |
| 1994 | 1994 | |
| 1995 | 1995 | dest->mem might (and possibly will) be (re)allocated by this |
| 1996 | 1996 | function, so any pointers to it held from before this call might be |
| 1997 | 1997 | invalidated by this call. |
| 1998 | | - |
| 1998 | + |
| 1999 | 1999 | On error non-0 is returned and dest has almost certainly been |
| 2000 | 2000 | modified but its state must be considered incomplete. |
| 2001 | 2001 | |
| 2002 | 2002 | Errors include: |
| 2003 | 2003 | |
| | @@ -2042,11 +2042,11 @@ |
| 2042 | 2042 | void * mem = buf.mem; |
| 2043 | 2043 | buf = cson_buffer_empty; |
| 2044 | 2044 | @endcode |
| 2045 | 2045 | |
| 2046 | 2046 | In which case the memory must eventually be passed to free() to |
| 2047 | | - free it. |
| 2047 | + free it. |
| 2048 | 2048 | */ |
| 2049 | 2049 | int cson_buffer_fill_from( cson_buffer * dest, cson_data_source_f src, void * state ); |
| 2050 | 2050 | |
| 2051 | 2051 | |
| 2052 | 2052 | /** |
| | @@ -2072,11 +2072,11 @@ |
| 2072 | 2072 | for other sharing points which added a reference. |
| 2073 | 2073 | |
| 2074 | 2074 | Normally any such value handles would be invalidated when the |
| 2075 | 2075 | parent container(s) is/are cleaned up, but this function can be |
| 2076 | 2076 | used to effectively delay the cleanup. |
| 2077 | | - |
| 2077 | + |
| 2078 | 2078 | This function, at its lowest level, increments the value's |
| 2079 | 2079 | reference count by 1. |
| 2080 | 2080 | |
| 2081 | 2081 | To decrement the reference count, pass the value to |
| 2082 | 2082 | cson_value_free(), after which the value must be considered, from |
| | @@ -2091,11 +2091,11 @@ |
| 2091 | 2091 | errors long before the reference count could overflow (assuming |
| 2092 | 2092 | those reference counts come from container insertions, as opposed |
| 2093 | 2093 | to via this function). |
| 2094 | 2094 | |
| 2095 | 2095 | Insider notes which clients really need to know: |
| 2096 | | - |
| 2096 | + |
| 2097 | 2097 | For shared/constant value instances, such as those returned by |
| 2098 | 2098 | cson_value_true() and cson_value_null(), this function has no side |
| 2099 | 2099 | effects - it does not actually modify the reference count because |
| 2100 | 2100 | (A) those instances are shared across all client code and (B) those |
| 2101 | 2101 | objects are static and never get cleaned up. However, that is an |
| | @@ -2173,11 +2173,11 @@ |
| 2173 | 2173 | returned object will be of the same logical type as orig. |
| 2174 | 2174 | |
| 2175 | 2175 | ACHTUNG: if orig contains any cyclic references at any depth level |
| 2176 | 2176 | this function will endlessly recurse. (Having _any_ cyclic |
| 2177 | 2177 | references violates this library's requirements.) |
| 2178 | | - |
| 2178 | + |
| 2179 | 2179 | Returns NULL if orig is NULL or if cloning fails. Assuming that |
| 2180 | 2180 | orig is in a valid state, the only "likely" error case is that an |
| 2181 | 2181 | allocation fails while constructing the clone. In other words, if |
| 2182 | 2182 | cloning fails due to something other than an allocation error then |
| 2183 | 2183 | either orig is in an invalid state or there is a bug. |
| | @@ -2278,11 +2278,11 @@ |
| 2278 | 2278 | --key=VAL : Treats VAL as either a double, integer, or string. |
| 2279 | 2279 | |
| 2280 | 2280 | --key= : Treats key as a JSON null (not literal NULL) value. |
| 2281 | 2281 | |
| 2282 | 2282 | Arguments not starting with a dash are skipped. |
| 2283 | | - |
| 2283 | + |
| 2284 | 2284 | Each key/value pair is inserted into an object. If a given key |
| 2285 | 2285 | appears more than once then only the final entry is actually |
| 2286 | 2286 | stored. |
| 2287 | 2287 | |
| 2288 | 2288 | argc and argv are expected to be values from main() (or similar, |
| | @@ -2434,22 +2434,22 @@ |
| 2434 | 2434 | Integer, double, null, or string (TEXT and BLOB data, though not |
| 2435 | 2435 | all blob data is legal for a JSON string). |
| 2436 | 2436 | |
| 2437 | 2437 | st must be a sqlite3_step()'d row and col must be a 0-based column |
| 2438 | 2438 | index within that result row. |
| 2439 | | - */ |
| 2439 | + */ |
| 2440 | 2440 | cson_value * cson_sqlite3_column_to_value( sqlite3_stmt * st, int col ); |
| 2441 | 2441 | |
| 2442 | 2442 | /** |
| 2443 | 2443 | Creates a JSON Array object containing the names of all columns |
| 2444 | | - of the given prepared statement handle. |
| 2445 | | - |
| 2444 | + of the given prepared statement handle. |
| 2445 | + |
| 2446 | 2446 | Returns a new array value on success, which the caller owns. Its elements |
| 2447 | 2447 | are in the same order as in the underlying query. |
| 2448 | 2448 | |
| 2449 | 2449 | On error NULL is returned. |
| 2450 | | - |
| 2450 | + |
| 2451 | 2451 | st is not traversed or freed by this function - only the column |
| 2452 | 2452 | count and names are read. |
| 2453 | 2453 | */ |
| 2454 | 2454 | cson_value * cson_sqlite3_column_names( sqlite3_stmt * st ); |
| 2455 | 2455 | |
| | @@ -2494,22 +2494,22 @@ |
| 2494 | 2494 | */ |
| 2495 | 2495 | cson_value * cson_sqlite3_row_to_array( sqlite3_stmt * st ); |
| 2496 | 2496 | /** |
| 2497 | 2497 | Converts the results of an sqlite3 SELECT statement to JSON, |
| 2498 | 2498 | in the form of a cson_value object tree. |
| 2499 | | - |
| 2499 | + |
| 2500 | 2500 | st must be a prepared, but not yet traversed, SELECT query. |
| 2501 | 2501 | tgt must be a pointer to NULL (see the example below). If |
| 2502 | 2502 | either of those arguments are NULL, cson_rc.ArgError is returned. |
| 2503 | | - |
| 2503 | + |
| 2504 | 2504 | This walks the query results and returns a JSON object which |
| 2505 | 2505 | has a different structure depending on the value of the 'fat' |
| 2506 | 2506 | argument. |
| 2507 | | - |
| 2508 | | - |
| 2507 | + |
| 2508 | + |
| 2509 | 2509 | If 'fat' is 0 then the structure is: |
| 2510 | | - |
| 2510 | + |
| 2511 | 2511 | @code |
| 2512 | 2512 | { |
| 2513 | 2513 | "columns":["colName1",..."colNameN"], |
| 2514 | 2514 | "rows":[ |
| 2515 | 2515 | [colVal0, ... colValN], |
| | @@ -2516,16 +2516,16 @@ |
| 2516 | 2516 | [colVal0, ... colValN], |
| 2517 | 2517 | ... |
| 2518 | 2518 | ] |
| 2519 | 2519 | } |
| 2520 | 2520 | @endcode |
| 2521 | | - |
| 2521 | + |
| 2522 | 2522 | In the "non-fat" format the order of the columns and row values is |
| 2523 | 2523 | guaranteed to be the same as that of the underlying query. |
| 2524 | | - |
| 2524 | + |
| 2525 | 2525 | If 'fat' is not 0 then the structure is: |
| 2526 | | - |
| 2526 | + |
| 2527 | 2527 | @code |
| 2528 | 2528 | { |
| 2529 | 2529 | "columns":["colName1",..."colNameN"], |
| 2530 | 2530 | "rows":[ |
| 2531 | 2531 | {"colName1":value1,..."colNameN":valueN}, |
| | @@ -2543,33 +2543,33 @@ |
| 2543 | 2543 | |
| 2544 | 2544 | On success it returns 0 and assigns *tgt to a newly-allocated |
| 2545 | 2545 | JSON object tree (using the above structure), which the caller owns. |
| 2546 | 2546 | If the query returns no rows, the "rows" value will be an empty |
| 2547 | 2547 | array, as opposed to null. |
| 2548 | | - |
| 2548 | + |
| 2549 | 2549 | On error non-0 is returned and *tgt is not modified. |
| 2550 | | - |
| 2550 | + |
| 2551 | 2551 | The error code cson_rc.IOError is used to indicate a db-level |
| 2552 | 2552 | error, and cson_rc.TypeError is returned if sqlite3_column_count(st) |
| 2553 | 2553 | returns 0 or less (indicating an invalid or non-SELECT statement). |
| 2554 | | - |
| 2554 | + |
| 2555 | 2555 | The JSON data types are determined by the column type as reported |
| 2556 | 2556 | by sqlite3_column_type(): |
| 2557 | | - |
| 2557 | + |
| 2558 | 2558 | SQLITE_INTEGER: integer |
| 2559 | | - |
| 2559 | + |
| 2560 | 2560 | SQLITE_FLOAT: double |
| 2561 | | - |
| 2561 | + |
| 2562 | 2562 | SQLITE_TEXT or SQLITE_BLOB: string, and this will only work if |
| 2563 | 2563 | the data is UTF8 compatible. |
| 2564 | | - |
| 2564 | + |
| 2565 | 2565 | If the db returns a literal or SQL NULL for a value it is converted |
| 2566 | 2566 | to a JSON null. If it somehow finds a column type it cannot handle, |
| 2567 | 2567 | the value is also converted to a NULL in the output. |
| 2568 | 2568 | |
| 2569 | 2569 | Example |
| 2570 | | - |
| 2570 | + |
| 2571 | 2571 | @code |
| 2572 | 2572 | cson_value * json = NULL; |
| 2573 | 2573 | int rc = cson_sqlite3_stmt_to_json( myStatement, &json, 1 ); |
| 2574 | 2574 | if( 0 != rc ) { ... error ... } |
| 2575 | 2575 | else { |
| | @@ -2603,14 +2603,14 @@ |
| 2603 | 2603 | TODO: add Object support for named parameters. |
| 2604 | 2604 | |
| 2605 | 2605 | Returns 0 on success, non-0 on error. |
| 2606 | 2606 | */ |
| 2607 | 2607 | int cson_sqlite3_bind_value( sqlite3_stmt * st, int ndx, cson_value const * v ); |
| 2608 | | - |
| 2608 | + |
| 2609 | 2609 | #if defined(__cplusplus) |
| 2610 | 2610 | } /*extern "C"*/ |
| 2611 | 2611 | #endif |
| 2612 | | - |
| 2612 | + |
| 2613 | 2613 | #endif /* CSON_ENABLE_SQLITE3 */ |
| 2614 | 2614 | #endif /* WANDERINGHORSE_NET_CSON_SQLITE3_H_INCLUDED */ |
| 2615 | 2615 | /* end file include/wh/cson/cson_sqlite3.h */ |
| 2616 | 2616 | #endif /* FOSSIL_ENABLE_JSON */ |
| 2617 | 2617 | |