Rename $assoc to $associative. Update API documentation.

Fill out the api documentation more in the README

Author: TysonAndre

README.md

@@ -108,47 +108,75 @@ var_dump($res) //int(5)
 <?php
 
 /**
+ * Takes a JSON encoded string and converts it into a PHP variable.
  * Similar to json_decode()
  *
+ * @param string $json The JSON string being decoded
+ * @param bool $associative When true, JSON objects will be returned as associative arrays.
+ *                          When false, JSON objects will be returned as objects.
+ * @param int $depth the maximum nesting depth of the structure being decoded.
  * @return array|stdClass|string|float|int|bool|null
  * @throws SimdJsonException for invalid JSON
- *                           (or document over 4GB, or out of range integer/float)
+ *                           (or $json over 4GB long, or out of range integer/float)
+ * @throws SimdJsonValueError for invalid $depth
  */
-function simdjson_decode(string $json, bool $assoc = false, int $depth = 512) {}
+function simdjson_decode(string $json, bool $associative = false, int $depth = 512) {}
 
 /**
  * Returns true if json is valid.
  *
- * @return ?bool (null if depth is invalid)
+ * @param string $json The JSON string being decoded
+ * @param int $depth the maximum nesting depth of the structure being decoded.
+ * @return bool
+ * @throws SimdJsonValueError for invalid $depth
  */
-function simdjson_is_valid(string $json, int $depth = 512) : ?bool {}
+function simdjson_is_valid(string $json, int $depth = 512) : bool {}
 
 /**
  * Parses $json and returns the number of keys in $json matching the JSON pointer $key
  *
- * @return ?int (null if depth is invalid)
- * @throws SimdJsonException for invalid JSON
+ * @param string $json The JSON string being decoded
+ * @param string $key The JSON pointer being requested
+ * @param int $depth The maximum nesting depth of the structure being decoded.
+ * @param bool $throw_if_uncountable If true, then throw SimdJsonException instead of returning 0 for JSON pointers
+                                     to values that are neither objects nor arrays.
+ * @return int
+ * @throws SimdJsonException for invalid JSON or invalid JSON pointer
  *                           (or document over 4GB, or out of range integer/float)
+ * @throws SimdJsonValueError for invalid $depth
+ * @see https://www.rfc-editor.org/rfc/rfc6901.html
  */
-function simdjson_key_count(string $json, string $key, int $depth = 512) : ?int {}
+function simdjson_key_count(string $json, string $key, int $depth = 512, bool $throw_if_uncountable = false) : int {}
 
 /**
  * Returns true if the JSON pointer $key could be found.
  *
- * @return ?bool (null if depth is invalid, false if json is invalid or key is not found)
- * @throws SimdJsonException for invalid JSON
+ * @param string $json The JSON string being decoded
+ * @param string $key The JSON pointer being requested
+ * @param int $depth the maximum nesting depth of the structure being decoded.
+ * @return bool (false if key is not found)
+ * @throws SimdJsonException for invalid JSON or invalid JSON pointer
  *                           (or document over 4GB, or out of range integer/float)
+ * @throws SimdJsonValueError for invalid $depth
+ * @see https://www.rfc-editor.org/rfc/rfc6901.html
  */
-function simdjson_key_exists(string $json, string $key, int $depth = 512) : ?bool {}
+function simdjson_key_exists(string $json, string $key, int $depth = 512) : bool {}
 
 /**
- * Returns the value at $key
+ * Returns the value at the json pointer $key
  *
+ * @param string $json The JSON string being decoded
+ * @param string $key The JSON pointer being requested
+ * @param int $depth the maximum nesting depth of the structure being decoded.
+ * @param bool $associative When true, JSON objects will be returned as associative arrays.
+ *                          When false, JSON objects will be returned as objects.
  * @return array|stdClass|string|float|int|bool|null the value at $key
- * @throws SimdJsonException for invalid JSON
+ * @throws SimdJsonException for invalid JSON or invalid JSON pointer
  *                           (or document over 4GB, or out of range integer/float)
+ * @throws SimdJsonValueError for invalid $depth
+ * @see https://www.rfc-editor.org/rfc/rfc6901.html
  */
-function simdjson_key_value(string $json, string $key, bool $assoc = unknown, int $depth = unknown) {}
+function simdjson_key_value(string $json, string $key, bool $associative = false, int $depth = 512) {}
 
 /**
  * An error thrown by simdjson when processing json.
@@ -160,12 +188,27 @@ function simdjson_key_value(string $json, string $key, bool $assoc = unknown, in
  */
 class SimdJsonException extends RuntimeException {
 }
+
+/**
+ * Thrown for error conditions on fields such as $depth that are not expected to be
+ * from user-provided JSON, with similar behavior to php 8.0.
+ *
+ * NOTE: https://www.php.net/valueerror was added in php 8.0.
+ * In older php versions, this extends Error instead.
+ *
+ * When support for php 8.0 is dropped completely,
+ * a major release of simdjson will likely switch to a standard ValueError.
+ */
+class SimdJsonValueError extends ValueError {
+}
 ```
 
 ## Edge cases
 
 There are some differences from `json_decode()` due to the implementation of the underlying simdjson library. This will throw a RuntimeException if simdjson rejects the JSON.
 
+Note that the simdjson PECL is using a fork of the simdjson C library to imitate php's handling of integers and floats in JSON.
+
 1) **Until simdjson 2.1.0,** `simdjson_decode()` differed in how out of range 64-bit integers and floats are handled.
 
 See https://github.com/simdjson/simdjson/blob/master/doc/basics.md#standard-compliance

package.xml

@@ -36,7 +36,7 @@
 * Throw a SimdJsonException in simdjson_key_exists on error conditions such as invalid json, to be consistent with other simdjson PHP functions.
 * Add an optional boolean `$throw_if_uncountable = false` to simdjson_key_count.
   When this is overridden to be true, simdjson_key_count will throw a SimdJsonException if the JSON pointer refers to a value that exists but is neither an array nor an object instead of returning 0.
-* Expose simdjson C APIs marked with PHP_SIMDJSON_API in php_simdjson.h to other C projects.
+* Rename the parameter $assoc to $associative in simdjson_decode and simdjson_key_value, to match naming practices used in json_decode()
  </notes>
  <contents>
   <dir name="/">

php_simdjson.cpp

@@ -60,14 +60,14 @@ ZEND_END_ARG_INFO()
 
 ZEND_BEGIN_ARG_INFO_EX(simdjson_decode_arginfo, 0, 0, 1)
         ZEND_ARG_TYPE_INFO(0, json, IS_STRING, 0)
-        ZEND_ARG_TYPE_INFO(0, assoc, _IS_BOOL, 0)
+        ZEND_ARG_TYPE_INFO(0, associative, _IS_BOOL, 0)
         ZEND_ARG_TYPE_INFO(0, depth, IS_LONG, 0)
 ZEND_END_ARG_INFO()
 
 ZEND_BEGIN_ARG_INFO_EX(simdjson_key_value_arginfo, 0, 0, 2)
         ZEND_ARG_TYPE_INFO(0, json, IS_STRING, 0)
         ZEND_ARG_TYPE_INFO(0, key, IS_STRING, 0)
-        ZEND_ARG_TYPE_INFO(0, assoc, _IS_BOOL, 0)
+        ZEND_ARG_TYPE_INFO(0, associative, _IS_BOOL, 0)
         ZEND_ARG_TYPE_INFO(0, depth, IS_LONG, 0)
 ZEND_END_ARG_INFO()
 
@@ -130,16 +130,16 @@ PHP_FUNCTION (simdjson_is_valid) {
 }
 
 PHP_FUNCTION (simdjson_decode) {
-    zend_bool assoc = 0;
+    zend_bool associative = 0;
     zend_long depth = SIMDJSON_PARSE_DEFAULT_DEPTH;
     zend_string *json = NULL;
-    if (zend_parse_parameters(ZEND_NUM_ARGS(), "S|bl", &json, &assoc, &depth) == FAILURE) {
+    if (zend_parse_parameters(ZEND_NUM_ARGS(), "S|bl", &json, &associative, &depth) == FAILURE) {
         RETURN_THROWS();
     }
     if (!simdjson_validate_depth(depth, "simdjson_decode", 2)) {
         RETURN_THROWS();
     }
-    simdjson_php_error_code error = php_simdjson_parse(simdjson_get_parser(), ZSTR_VAL(json), ZSTR_LEN(json), return_value, assoc, depth);
+    simdjson_php_error_code error = php_simdjson_parse(simdjson_get_parser(), ZSTR_VAL(json), ZSTR_LEN(json), return_value, associative, depth);
     if (error) {
         php_simdjson_throw_jsonexception(error);
         RETURN_THROWS();
@@ -149,15 +149,15 @@ PHP_FUNCTION (simdjson_decode) {
 PHP_FUNCTION (simdjson_key_value) {
     zend_string *json = NULL;
     zend_string *key = NULL;
-    zend_bool assoc = 0;
+    zend_bool associative = 0;
     zend_long depth = SIMDJSON_PARSE_DEFAULT_DEPTH;
-    if (zend_parse_parameters(ZEND_NUM_ARGS(), "SS|bl", &json, &key, &assoc, &depth) == FAILURE) {
+    if (zend_parse_parameters(ZEND_NUM_ARGS(), "SS|bl", &json, &key, &associative, &depth) == FAILURE) {
         RETURN_THROWS();
     }
     if (!simdjson_validate_depth(depth, "simdjson_key_value", 4)) {
         RETURN_THROWS();
     }
-    simdjson_php_error_code error = php_simdjson_key_value(simdjson_get_parser(), ZSTR_VAL(json), ZSTR_LEN(json), ZSTR_VAL(key), return_value, assoc, depth);
+    simdjson_php_error_code error = php_simdjson_key_value(simdjson_get_parser(), ZSTR_VAL(json), ZSTR_LEN(json), ZSTR_VAL(key), return_value, associative, depth);
     if (error) {
         php_simdjson_throw_jsonexception(error);
         RETURN_THROWS();