LineageOS/android_external_json-c
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Clean up documentation and correct sample code

Browse Source
This commit is contained in:
Keith Derrick
2012-04-23 15:34:44 -07:00
parent 178a4b059c
commit ded667a612
2 changed files with 83 additions and 97 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
json_object_iterator.c
View File

@@ -1,16 +1,16 @@
/** /**
******************************************************************************* *******************************************************************************
* @file cjson_object_iterator.c * @file json_object_iterator.c
* *
* Copyright (c) 2009 Hewlett-Packard Development Company, L.P. * Copyright (c) 2009-2012 Hewlett-Packard Development Company, L.P.
* *
* This library is free software; you can redistribute it and/or modify * This library is free software; you can redistribute it and/or modify
* it under the terms of the MIT license. See COPYING for details. * it under the terms of the MIT license. See COPYING for details.
* *
* @brief cjson forces clients to use its private data * @brief json-c forces clients to use its private data
* structures for JSON Object iteration. This API * structures for JSON Object iteration. This API
* implementation corrects that by abstracting the * implementation corrects that by abstracting the
* private cjson details. * private json-c details.
* *
******************************************************************************* *******************************************************************************
*/ */
@@ -26,7 +26,7 @@
/** /**
* How It Works * How It Works
* *
* For each JSON Object, cjson maintains a linked list of zero * For each JSON Object, json-c maintains a linked list of zero
* or more lh_entry (link-hash entry) structures inside the * or more lh_entry (link-hash entry) structures inside the
* Object's link-hash table (lh_table). * Object's link-hash table (lh_table).
* *
@@ -39,7 +39,7 @@
* name/value pair via a pointer to the pair's lh_entry * name/value pair via a pointer to the pair's lh_entry
* structure set as the iterator's opaque_ field. * structure set as the iterator's opaque_ field.
* *
* We follow cjson's current pair list representation by * We follow json-c's current pair list representation by
* representing a valid "end" iterator (one that refers past the * representing a valid "end" iterator (one that refers past the
* last pair) with a NULL value in the iterator's opaque_ field. * last pair) with a NULL value in the iterator's opaque_ field.
* *

92
json_object_iterator.h
View File

@@ -2,24 +2,19 @@
******************************************************************************* *******************************************************************************
* @file json_object_iterator.h * @file json_object_iterator.h
* *
* Copyright (c) 2009 Hewlett-Packard Development Company, L.P. * Copyright (c) 2009-2012 Hewlett-Packard Development Company, L.P.
* *
* This library is free software; you can redistribute it and/or modify * This library is free software; you can redistribute it and/or modify
* it under the terms of the MIT license. See COPYING for details. * it under the terms of the MIT license. See COPYING for details.
* *
* @brief cjson forces clients to use its private data * @brief json-c forces clients to use its private data
* structures for JSON Object iteration. This API * structures for JSON Object iteration. This API
* corrects that by abstracting the private cjson * corrects that by abstracting the private json-c
* details. * details.
* *
* The intention is to add this API (and its * API attributes: <br>
* implementation) to Palm's version of the cjson * * Thread-safe: NO<br>
* library, at which point it can be removed from the * * Reentrant: NO
* Wireless System Framework library implementation.
*
* API attributes:
* * Thread-safe: NO
* * Re-entrant: NO
* *
******************************************************************************* *******************************************************************************
*/ */
@@ -42,7 +37,7 @@ struct json_object_iter_info_;
/** /**
* The opaque iterator that references a name/value pair within * The opaque iterator that references a name/value pair within
* a JSON Object intance or the "end" iterator value. * a JSON Object instance or the "end" iterator value.
*/ */
struct json_object_iterator { struct json_object_iterator {
const void* opaque_; const void* opaque_;
@@ -50,7 +45,7 @@ struct json_object_iterator {
/** /**
* forward declaration of cjson's JSON value instance structure * forward declaration of json-c's JSON value instance structure
*/ */
struct json_object; struct json_object;
@@ -68,7 +63,7 @@ struct json_object;
* *
* @note The initialized value doesn't reference any specific * @note The initialized value doesn't reference any specific
* pair, is considered an invalid iterator, and MUST NOT * pair, is considered an invalid iterator, and MUST NOT
* be passed to any cjson API that expects a valid * be passed to any json-c API that expects a valid
* iterator. * iterator.
* *
* @note User and internal code MUST NOT make any assumptions * @note User and internal code MUST NOT make any assumptions
@@ -82,11 +77,10 @@ json_object_iter_init_default(void);
/** Retrieves an iterator to the first pair of the JSON Object. /** Retrieves an iterator to the first pair of the JSON Object.
* *
* @note WARNING: Any modification of the underlying pair * @warning Any modification of the underlying pair invalidates all
* invalidates all iterators to that pair. * iterators to that pair.
* *
* @param obj JSON Object instance (MUST be of type * @param obj JSON Object instance (MUST be of type json_object)
* json_type_object)
* *
* @return json_object_iterator If the JSON Object has at * @return json_object_iterator If the JSON Object has at
* least one pair, on return, the iterator refers * least one pair, on return, the iterator refers
@@ -98,25 +92,18 @@ json_object_iter_init_default(void);
* @code * @code
* struct json_object_iterator it; * struct json_object_iterator it;
* struct json_object_iterator itEnd; * struct json_object_iterator itEnd;
* struct json_object* obj = json_tokener_parse( * struct json_object* obj;
* "{'first':'george', 'age':100}"); *
* json_object_iter_begin(obj, &it); * obj = json_tokener_parse("{'first':'george', 'age':100}");
* json_object_iter_end(obj, &itEnd); * it = json_object_iter_begin(obj);
* itEnd = json_object_iter_end(obj);
*
* while (!json_object_iter_equal(&it, &itEnd)) { * while (!json_object_iter_equal(&it, &itEnd)) {
* printf("%s\n", * printf("%s\n",
* json_object_iter_peek_name(&it)); * json_object_iter_peek_name(&it));
* json_object_iter_next(&it); * json_object_iter_next(&it);
* } * }
* *
* struct json_object* obj = json_tokener_parse(
* "{'first':'george', 'age':100}");
* struct json_object_iterator it;
* bool iterable = json_object_iter_begin(&it);
* if (iterable) {
* do {
* printf("%s\n", json_object_iter_peek_name(&it));
* } while (json_object_iter_next(&it));
* }
* @endcode * @endcode
*/ */
struct json_object_iterator struct json_object_iterator
@@ -125,7 +112,7 @@ json_object_iter_begin(struct json_object* obj);
/** Retrieves the iterator that represents the position beyond the /** Retrieves the iterator that represents the position beyond the
* last pair of the given JSON Object instance. * last pair of the given JSON Object instance.
* *
* @note WARNING: Do NOT write code that assumes that the "end" * @warning Do NOT write code that assumes that the "end"
* iterator value is NULL, even if it is so in a * iterator value is NULL, even if it is so in a
* particular instance of the implementation. * particular instance of the implementation.
* *
@@ -140,11 +127,10 @@ json_object_iter_begin(struct json_object* obj);
* representation without burdening the iterator * representation without burdening the iterator
* structure with unnecessary data. * structure with unnecessary data.
* *
* @note For performance reasons, memoize the "end" iterator prior * @note For performance reasons, memorize the "end" iterator prior
* to any loop. * to any loop.
* *
* @param obj JSON Object instance (MUST be of type * @param obj JSON Object instance (MUST be of type json_object)
* json_type_object)
* *
* @return json_object_iterator On return, the iterator refers * @return json_object_iterator On return, the iterator refers
* to the "end" of the Object instance's pairs * to the "end" of the Object instance's pairs
@@ -156,10 +142,8 @@ json_object_iter_end(const struct json_object* obj);
/** Returns an iterator to the next pair, if any /** Returns an iterator to the next pair, if any
* *
* @note WARNING: Any modification of the underlying pair * @warning Any modification of the underlying pair
* invalidates all iterators to that pair. * invalidates all iterators to that pair.
*
* @param iter Iterator that references a name/value pair;
* *
* @param iter [IN/OUT] Pointer to iterator that references a * @param iter [IN/OUT] Pointer to iterator that references a
* name/value pair; MUST be a valid, non-end iterator. * name/value pair; MUST be a valid, non-end iterator.
@@ -180,10 +164,11 @@ json_object_iter_next(struct json_object_iterator* iter);
* *
* @param iter pointer to iterator that references a name/value * @param iter pointer to iterator that references a name/value
* pair; MUST be a valid, non-end iterator. * pair; MUST be a valid, non-end iterator.
* WARNING: bad things will happen if invalid or
* "end" iterator is passed.
* *
* @return const char* Pointer to the name of the rerferenced * @warning bad things will happen if an invalid or
* "end" iterator is passed.
*
* @return const char* Pointer to the name of the referenced
* name/value pair. The name memory belongs to the * name/value pair. The name memory belongs to the
* name/value pair, will be freed when the pair is * name/value pair, will be freed when the pair is
* deleted or modified, and MUST NOT be modified or * deleted or modified, and MUST NOT be modified or
@@ -193,21 +178,22 @@ const char*
json_object_iter_peek_name(const struct json_object_iterator* iter); json_object_iter_peek_name(const struct json_object_iterator* iter);
/** Returns a pointer to the cjson instance representing the /** Returns a pointer to the json-c instance representing the
* value of the referenced name/value pair, without altering * value of the referenced name/value pair, without altering
* the instance's reference count. * the instance's reference count.
* *
* @param iter pointer to iterator that references a name/value * @param iter pointer to iterator that references a name/value
* pair; MUST be a valid, non-end iterator. * pair; MUST be a valid, non-end iterator.
* WARNING: bad things will happen if invalid or *
* @warning bad things will happen if invalid or
* "end" iterator is passed. * "end" iterator is passed.
* *
* @return struct json_object* Pointer to the cjson value * @return struct json_object* Pointer to the json-c value
* instance of the referenced name/value pair; the * instance of the referenced name/value pair; the
* value's reference count is not changed by this * value's reference count is not changed by this
* function: if you plan to hold on to this cjson node, * function: if you plan to hold on to this json-c node,
* take a look at json_object_get() and * take a look at json_object_get() and
* json_object_put(). IMPORTANT: cjson API represents * json_object_put(). IMPORTANT: json-c API represents
* the JSON Null value as a NULL json_object instance * the JSON Null value as a NULL json_object instance
* pointer. * pointer.
*/ */
@@ -232,10 +218,10 @@ json_object_iter_peek_value(const struct json_object_iterator* iter);
* @param iter1 Pointer to first valid, non-NULL iterator * @param iter1 Pointer to first valid, non-NULL iterator
* @param iter2 POinter to second valid, non-NULL iterator * @param iter2 POinter to second valid, non-NULL iterator
* *
* @note WARNING: if a NULL iterator pointer or an uninitialized * @warning if a NULL iterator pointer or an uninitialized
* or invalid iterator, or iterators derived from * or invalid iterator, or iterators derived from
* different JSON Object instances are passed, bad things * different JSON Object instances are passed, bad things
* will happen! * will happen!
* *
* @return bool non-zero if iterators are equal (i.e., both * @return bool non-zero if iterators are equal (i.e., both
* reference the same name/value pair or are both at * reference the same name/value pair or are both at