Add a const qualified version of search (#69)

Author: dan4thewin

MISRA.md

@@ -9,14 +9,18 @@ Deviations from the MISRA standard are listed below:
 | :-: | :-: | :-: |
 | Directive 4.9 | Advisory | Allow inclusion of function like macros. |
 | Rule 3.1 | Required | Allow nested comments. C++ style `//` comments are used in example code within Doxygen documentation blocks. |
+| Rule 8.13 | Advisory | Allow one function to have a char * argument without const qualifier. |
 | Rule 15.4 | Advisory | Allow more then one `break` statement to terminate a loop. |
 | Rule 19.2 | Advisory | Allow a `union` of a signed and unsigned type of identical sizes. |
 | Rule 20.12 | Required | Allow use of `assert()`, which uses a parameter in both expanded and raw forms. |
 
 ### Flagged by Coverity
 | Deviation | Category | Justification |
 | :-: | :-: | :-: |
+| Rule 2.5 | Advisory | A macro is not used by the library; however, it exists to be used by an application. |
 | Rule 8.7 | Advisory | API functions are not used by the library; however, they must be externally visible in order to be used by an application. |
 
 ### Suppressed with Coverity Comments
-*None.*
+| Deviation | Category | Justification |
+| :-: | :-: | :-: |
+| Rule 11.3 | Required | False positive - the rule permits type qualifiers to be added. |

README.md

@@ -28,7 +28,7 @@ int main()
 
     if( result == JSONSuccess )
     {
-        result = JSON_Search( buffer, bufferLength, queryKey, queryKeyLength, '.',
+        result = JSON_Search( buffer, bufferLength, queryKey, queryKeyLength,
                               &value, &valueLength );
     }
 
@@ -47,11 +47,11 @@ int main()
     return 0;
 }
 ```
-A search may descend through nested objects when the `queryKey` contains matching key strings joined by a separator (e.g. `.`). In the example above, `bar` has the value `{"foo":"xyz"}`. Therefore, a search for query key `bar.foo` would output `xyz`.
+A search may descend through nested objects when the `queryKey` contains matching key strings joined by a separator, `.`. In the example above, `bar` has the value `{"foo":"xyz"}`. Therefore, a search for query key `bar.foo` would output `xyz`.
 
 ## Building coreJSON
 
-A compiler that supports **C89 or later** such as *gcc* is required to build the library.
+A compiler that supports **C90 or later** such as *gcc* is required to build the library.
 
 For instance, if the example above is copied to a file named `example.c`, *gcc* can be used like so:
 ```bash

docs/doxygen/pages.dox

@@ -60,6 +60,8 @@ are written to cover every path of execution and achieve 100% branch coverage.
 @brief Primary functions of the JSON library:<br><br>
 @subpage json_validate_function <br>
 @subpage json_search_function <br>
+@subpage json_searcht_function <br>
+@subpage json_searchconst_function <br>
 
 @page json_validate_function JSON_Validate
 @snippet core_json.h declare_json_validate
@@ -68,6 +70,14 @@ are written to cover every path of execution and achieve 100% branch coverage.
 @page json_search_function JSON_Search
 @snippet core_json.h declare_json_search
 @copydoc JSON_Search
+
+@page json_searcht_function JSON_SearchT
+@snippet core_json.h declare_json_searcht
+@copydoc JSON_SearchT
+
+@page json_searchconst_function JSON_SearchConst
+@snippet core_json.h declare_json_searchconst
+@copydoc JSON_SearchConst
 */
 
 <!-- We do not use doxygen ALIASes here because there have been issues in the past versions with "^^" newlines within the alias definition. -->

lexicon.txt

@@ -8,6 +8,7 @@ bufferlength
 cbmc
 com
 cond
+const
 corejson
 coverity
 dbff

source/core_json.c

@@ -1297,7 +1297,7 @@ static bool_ nextKeyValuePair( const char * buf,
  * @param[in] max  size of the buffer.
  * @param[in] query  The object keys and array indexes to search for.
  * @param[in] queryLength  Length of the key.
- * @param[out] outValue  A pointer to receive the address of the value found.
+ * @param[out] outValue  A pointer to receive the index of the value found.
  * @param[out] outValueLength  A pointer to receive the length of the value found.
  *
  * Iterate over the key-value pairs of an object, looking for a matching key.
@@ -1307,11 +1307,11 @@ static bool_ nextKeyValuePair( const char * buf,
  *
  * @note Parsing stops upon finding a match.
  */
-static bool_ objectSearch( char * buf,
+static bool_ objectSearch( const char * buf,
                            size_t max,
                            const char * query,
                            size_t queryLength,
-                           char ** outValue,
+                           size_t * outValue,
                            size_t * outValueLength )
 {
     bool_ ret = false;
@@ -1352,7 +1352,7 @@ static bool_ objectSearch( char * buf,
 
     if( ret == true )
     {
-        *outValue = &buf[ value ];
+        *outValue = value;
         *outValueLength = valueLength;
     }
 
@@ -1365,7 +1365,7 @@ static bool_ objectSearch( char * buf,
  * @param[in] buf  The buffer to search.
  * @param[in] max  size of the buffer.
  * @param[in] queryIndex  The index to search for.
- * @param[out] outValue  A pointer to receive the address of the value found.
+ * @param[out] outValue  A pointer to receive the index of the value found.
  * @param[out] outValueLength  A pointer to receive the length of the value found.
  *
  * Iterate over the values of an array, looking for a matching index.
@@ -1375,10 +1375,10 @@ static bool_ objectSearch( char * buf,
  *
  * @note Parsing stops upon finding a match.
  */
-static bool_ arraySearch( char * buf,
+static bool_ arraySearch( const char * buf,
                           size_t max,
                           uint32_t queryIndex,
-                          char ** outValue,
+                          size_t * outValue,
                           size_t * outValueLength )
 {
     bool_ ret = false;
@@ -1419,7 +1419,7 @@ static bool_ arraySearch( char * buf,
 
     if( ret == true )
     {
-        *outValue = &buf[ value ];
+        *outValue = value;
         *outValueLength = valueLength;
     }
 
@@ -1479,7 +1479,7 @@ static bool_ skipQueryPart( const char * buf,
  * @param[in] max  size of the buffer.
  * @param[in] query  The object keys and array indexes to search for.
  * @param[in] queryLength  Length of the key.
- * @param[out] outValue  A pointer to receive the address of the value found.
+ * @param[out] outValue  A pointer to receive the index of the value found.
  * @param[out] outValueLength  A pointer to receive the length of the value found.
  *
  * @return #JSONSuccess if the query is matched and the value output;
@@ -1489,17 +1489,15 @@ static bool_ skipQueryPart( const char * buf,
  *
  * @note Parsing stops upon finding a match.
  */
-static JSONStatus_t multiSearch( char * buf,
+static JSONStatus_t multiSearch( const char * buf,
                                  size_t max,
                                  const char * query,
                                  size_t queryLength,
-                                 char ** outValue,
+                                 size_t * outValue,
                                  size_t * outValueLength )
 {
     JSONStatus_t ret = JSONSuccess;
-    size_t i = 0, start = 0;
-    char * p = buf;
-    size_t tmp = max;
+    size_t i = 0, start = 0, queryStart = 0, value = 0, length = max;
 
     assert( ( buf != NULL ) && ( query != NULL ) );
     assert( ( outValue != NULL ) && ( outValueLength != NULL ) );
@@ -1525,13 +1523,13 @@ static JSONStatus_t multiSearch( char * buf,
 
             i++;
 
-            found = arraySearch( p, tmp, ( uint32_t ) queryIndex, &p, &tmp );
+            found = arraySearch( &buf[ start ], length, ( uint32_t ) queryIndex, &value, &length );
         }
         else
         {
             size_t keyLength = 0;
 
-            start = i;
+            queryStart = i;
 
             if( ( skipQueryPart( query, &i, queryLength, &keyLength ) != true ) ||
                 /* catch an empty key part or a trailing separator */
@@ -1541,7 +1539,7 @@ static JSONStatus_t multiSearch( char * buf,
                 break;
             }
 
-            found = objectSearch( p, tmp, &query[ start ], keyLength, &p, &tmp );
+            found = objectSearch( &buf[ start ], length, &query[ queryStart ], keyLength, &value, &length );
         }
 
         if( found == false )
@@ -1550,6 +1548,8 @@ static JSONStatus_t multiSearch( char * buf,
             break;
         }
 
+        start += value;
+
         if( ( i < queryLength ) && isSeparator_( query[ i ] ) )
         {
             i++;
@@ -1558,27 +1558,74 @@ static JSONStatus_t multiSearch( char * buf,
 
     if( ret == JSONSuccess )
     {
-        *outValue = p;
-        *outValueLength = tmp;
+        *outValue = start;
+        *outValueLength = length;
     }
 
     return ret;
 }
 
+/**
+ * @brief Return a JSON type based on a separator character or
+ * the first character of a value.
+ *
+ * @param[in] c  The character to classify.
+ *
+ * @return an enum of JSONTypes_t
+ */
+static JSONTypes_t getType( char c )
+{
+    JSONTypes_t t;
+
+    switch( c )
+    {
+        case '"':
+            t = JSONString;
+            break;
+
+        case '{':
+            t = JSONObject;
+            break;
+
+        case '[':
+            t = JSONArray;
+            break;
+
+        case 't':
+            t = JSONTrue;
+            break;
+
+        case 'f':
+            t = JSONFalse;
+            break;
+
+        case 'n':
+            t = JSONNull;
+            break;
+
+        default:
+            t = JSONNumber;
+            break;
+    }
+
+    return t;
+}
+
 /** @endcond */
 
 /**
  * See core_json.h for docs.
  */
-JSONStatus_t JSON_SearchT( char * buf,
-                           size_t max,
-                           const char * query,
-                           size_t queryLength,
-                           char ** outValue,
-                           size_t * outValueLength,
-                           JSONTypes_t * outType )
+JSONStatus_t JSON_SearchConst( const char * buf,
+                               size_t max,
+                               const char * query,
+                               size_t queryLength,
+                               const char ** outValue,
+                               size_t * outValueLength,
+                               JSONTypes_t * outType )
 {
     JSONStatus_t ret;
+    size_t value;
 
     if( ( buf == NULL ) || ( query == NULL ) ||
         ( outValue == NULL ) || ( outValueLength == NULL ) )
@@ -1591,47 +1638,22 @@ JSONStatus_t JSON_SearchT( char * buf,
     }
     else
     {
-        ret = multiSearch( buf, max, query, queryLength, outValue, outValueLength );
+        ret = multiSearch( buf, max, query, queryLength, &value, outValueLength );
     }
 
     if( ret == JSONSuccess )
     {
-        JSONTypes_t t;
+        JSONTypes_t t = getType( buf[ value ] );
 
-        switch( *outValue[ 0 ] )
+        if( t == JSONString )
         {
-            case '"':
-                /* strip the surrounding quotes */
-                ( *outValue )++;
-                *outValueLength -= 2U;
-                t = JSONString;
-                break;
-
-            case '{':
-                t = JSONObject;
-                break;
-
-            case '[':
-                t = JSONArray;
-                break;
-
-            case 't':
-                t = JSONTrue;
-                break;
-
-            case 'f':
-                t = JSONFalse;
-                break;
-
-            case 'n':
-                t = JSONNull;
-                break;
-
-            default:
-                t = JSONNumber;
-                break;
+            /* strip the surrounding quotes */
+            value++;
+            *outValueLength -= 2U;
         }
 
+        *outValue = &buf[ value ];
+
         if( outType != NULL )
         {
             *outType = t;
@@ -1640,3 +1662,22 @@ JSONStatus_t JSON_SearchT( char * buf,
 
     return ret;
 }
+
+/**
+ * See core_json.h for docs.
+ */
+JSONStatus_t JSON_SearchT( char * buf,
+                           size_t max,
+                           const char * query,
+                           size_t queryLength,
+                           char ** outValue,
+                           size_t * outValueLength,
+                           JSONTypes_t * outType )
+{
+    /* MISRA Rule 11.3 prohibits casting a pointer to a different type.
+     * This instance is a false positive, as the rule permits the
+     * addition of a type qualifier. */
+    /* coverity[misra_c_2012_rule_11_3_violation] */
+    return JSON_SearchConst( ( const char * ) buf, max, query, queryLength,
+                             ( const char ** ) outValue, outValueLength, outType );
+}

source/include/core_json.h

@@ -208,4 +208,26 @@ JSONStatus_t JSON_SearchT( char * buf,
                            JSONTypes_t * outType );
 /* @[declare_json_searcht] */
 
+/**
+ * @brief Same as JSON_SearchT(), but with const qualified buf and outValue arguments.
+ *
+ * See @ref JSON_Search for documentation of common behavior.
+ *
+ * @param[in] buf  The buffer to search.
+ * @param[in] max  size of the buffer.
+ * @param[in] query  The object keys and array indexes to search for.
+ * @param[in] queryLength  Length of the key.
+ * @param[out] outValue  A pointer to receive the address of the value found.
+ * @param[out] outValueLength  A pointer to receive the length of the value found.
+ * @param[out] outType  An enum indicating the JSON-specific type of the value.
+ */
+/* @[declare_json_searchconst] */
+JSONStatus_t JSON_SearchConst( const char * buf,
+                               size_t max,
+                               const char * query,
+                               size_t queryLength,
+                               const char ** outValue,
+                               size_t * outValueLength,
+                               JSONTypes_t * outType );
+/* @[declare_json_searchconst] */
 #endif /* ifndef CORE_JSON_H_ */

test/cbmc/proofs/JSON_Search/README.md

@@ -6,6 +6,7 @@ This directory contains a memory safety proof for JSON_Search and JSON_SearchT.
 The proof runs in 15 minutes on a t3.medium.  It provides complete coverage of:
 * JSON_Search()
 * JSON_SearchT()
+* JSON_SearchTc()
 * arraySearch()
 * multiSearch()
 * nextKeyValuePair()