Fix value comparison and sorting semantics

engine/api.c

@@ -886,6 +886,25 @@ void *ph7_value_to_resource(ph7_value *pValue) {
 /*
  * [CAPIREF: ph7_value_compare()]
  * Please refer to the official documentation for function purpose and expected parameters.
+ *
+ * The comparison core does NOT mutate its operands [copy-on-compare], so the
+ * caller's values keep their type and contents after this call.
+ * If either pLeft or pRight is a NULL pointer, the call is harmless
+ * [legacy ticket 1433-24] and returns 1 [not equal] without inspecting
+ * the other value.
+ * Return 0 when both values are equal. For the ordered categories [numbers,
+ * strings] the result is exactly -1 or +1 [the comparison core normalizes
+ * ordering results to the 3-way value; a raw SyMemcmp byte delta such as
+ * -26 is never handed out]. The equality-only categories [arrays, objects,
+ * resources, callbacks] never return < 0: a positive result simply means
+ * "not equal", NOT "greater".
+ * SXERR_NOMATCH (-26) is returned when no 3-way ordering result exists:
+ * different comparison categories [e.g: string vs int, or any pair
+ * involving the incomparable void value], a NaN operand
+ * [unordered], an instantiated object against NULL [equality is known to be
+ * false, but the pair has no ordering], or, when bStrict is non-zero, values
+ * whose types are not identical. It is not an ordering result; test it before
+ * interpreting the sign.
  */
 int ph7_value_compare(ph7_value *pLeft, ph7_value *pRight, int bStrict) {
 	int rc;
@@ -893,8 +912,9 @@ int ph7_value_compare(ph7_value *pLeft, ph7_value *pRight, int bStrict) {
 		/* TICKET 1433-24: NULL values is harmless operation */
 		return 1;
 	}
-	/* Perform the comparison */
-	rc = PH7_MemObjCmp(&(*pLeft), &(*pRight), bStrict, 0);
+	/* Perform the comparison [non-erroring flavor: a host application
+	 * must be able to probe values without risking a process exit] */
+	rc = PH7_MemObjCmpSafe(&(*pLeft), &(*pRight), bStrict, 0, 0);
 	/* Comparison result */
 	return rc;
 }