Adjust the behavior of the args passed to json_patch_apply to make it easier to do in place modifications, and add a struct json_patch_error to report more details on failures.

json_patch.h

@@ -19,25 +19,59 @@
 extern "C" {
 #endif
 
+/**
+ * Details of an error that occurred during json_patch_apply()
+ */
+struct json_patch_error {
+	/**
+	 * An errno value indicating what kind of error occurred.
+	 * Possible values include:
+	 * - ENOENT - A path referenced in the operation does not exist.
+	 * - EINVAL - An invalid operation or with invalid path was attempted
+	 * - ENOMEM - Unable to allocate memory
+	 * - EFAULT - Invalid arguments were passed to json_patch_apply()
+	 *             (i.e. a C API error, vs. a data error like EINVAL)
+	 */
+	int errno_code;
+
+	/**
+	 * The index into the patch array of the operation that failed,
+	 * or SIZE_T_MAX for overall errors.
+	 */
+	size_t patch_failure_idx;
+
+	/**
+	 * A human readable error message.
+	 * Allocated from static storage, does not need to be freed.
+	 */
+	const char *errmsg;
+};
+
 /**
  * Apply the JSON patch to the base object.
- * The patch object must be formatted as per RFC 6902.
+ * The patch object must be formatted as per RFC 6902, i.e.
+ * a json_type_array containing patch operations.
  * If the patch is not correctly formatted, an error will
  * be returned.
  *
- * The original `base` object will first be copied, and then
- * the patch will be applied.
- * If anything fails during patching, the `res` object will be
- * NULL and the function will return a negative result.
+ * The json_object at *base will be modified in place.
+ * Exactly one of *base or copy_from must be non-NULL.
+ * If *base is NULL, a new copy of copy_from will allocated and populated
+ * using json_object_deep_copy().  In this case json_object_put() _must_ be 
+ * used to free *base even if the overall patching operation fails.
  *
- * @param base the JSON object which to patch
+ * If anything fails during patching a negative value will be returned,
+ * and patch_error (if non-NULL) will be populated with error details.
+ *
+ * @param base a pointer to the JSON object which to patch
  * @param patch the JSON object that describes the patch to be applied
- * @param the resulting patched JSON object
+ * @param copy_from a JSON object to copy to *base
+ * @param patch_error optional, details about errors
  *
- * @return negative if an error (or not found), or 0 if succeeded
+ * @return negative if an error (or not found), or 0 if patch completely applied
  */
-JSON_EXPORT int json_patch_apply(struct json_object *base, struct json_object *patch,
-                                 struct json_object **res);
+JSON_EXPORT int json_patch_apply(struct json_object *copy_from, struct json_object *patch,
+                                 struct json_object **base, struct json_patch_error *patch_error);
 
 #ifdef __cplusplus
 }