Update the json_tokener_parse_ex() docs to clarify that the final '\0' character...

diff --git a/json_tokener.h b/json_tokener.h
index 8afa6ec4649e816fd1e38ba8d35488d26615dad4..4e17dffcc30bf280969d7cf38d46c42751c6aae5 100644 (file)
--- a/json_tokener.h
+++ b/json_tokener.h
@@ -220,8 +220,8 @@ JSON_EXPORT void json_tokener_set_flags(struct json_tokener *tok, int flags);
  *
  * If json_tokener_parse_ex() returns NULL and the error is anything other than
  * json_tokener_continue, a fatal error has occurred and parsing must be
- * halted.  Then, the tok object must not be reused until json_tokener_reset() is
- * called.
+ * halted.  Then, the tok object must not be reused until json_tokener_reset()
+ * is called.
  *
  * When a valid JSON value is parsed, a non-NULL json_object will be
  * returned, with a reference count of one which belongs to the caller.  Also,
@@ -234,13 +234,18 @@ JSON_EXPORT void json_tokener_set_flags(struct json_tokener *tok, int flags);
  * error or to handle the additional characters, perhaps by parsing another
  * json value starting from that point.
  *
+ * If the caller knows that they are at the end of their input, the length
+ * passed MUST include the final '\0' character, so values with no inherent
+ * end (i.e. numbers) can be properly parsed, rather than just returning
+ * json_tokener_continue.
+ *
  * Extra characters can be detected by comparing the value returned by
  * json_tokener_get_parse_end() against
  * the length of the last len parameter passed in.
  *
  * The tokener does \b not maintain an internal buffer so the caller is
- * responsible for calling json_tokener_parse_ex with an appropriate str
- * parameter starting with the extra characters.
+ * responsible for a subsequent call to json_tokener_parse_ex with an 
+ * appropriate str parameter starting with the extra characters.
  *
  * This interface is presently not 64-bit clean due to the int len argument
  * so the function limits the maximum string size to INT32_MAX (2GB).
@@ -256,6 +261,8 @@ enum json_tokener_error jerr;
 do {
        mystring = ...  // get JSON string, e.g. read from file, etc...
        stringlen = strlen(mystring);
+       if (end_of_input)
+               stringlen++;  // Include the '\0' if we know we're at the end of input
        jobj = json_tokener_parse_ex(tok, mystring, stringlen);
 } while ((jerr = json_tokener_get_error(tok)) == json_tokener_continue);
 if (jerr != json_tokener_success)