Merge "Initial commit: cframework. Longbow and Libparc" into cframework/master

1 files changed, 253 insertions, 0 deletions

diff --git a/libparc/parc/testing/parc_ObjectTesting.h b/libparc/parc/testing/parc_ObjectTesting.h
new file mode 100644
index 00000000..557fee10
--- /dev/null
+++ b/libparc/parc/testing/parc_ObjectTesting.h
@@ -0,0 +1,253 @@
+/*
+ * Copyright (c) 2017 Cisco and/or its affiliates.
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at:
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * @file parc_ObjectTesting.h
+ * @brief Support for LongBow runtime and unit testing of PARCObject implementations.
+ *
+ */
+#ifndef PARC_Library_parc_ObjectTest_h
+#define PARC_Library_parc_ObjectTest_h
+
+#include <stdarg.h>
+#include <stdbool.h>
+
+#include <parc/algol/parc_Object.h>
+#include <parc/algol/parc_HashCode.h>
+
+/**
+ * Test if a PARCObject subclass behaves well as a PARCObject when passed to the various PARCObject functions.
+ *
+ * @param [in] inst1 A pointer to an instance that will be used as the base comparison for remaining parameters.
+ * @param [in] inst2 A pointer to an instance that is known to be equal to @p inst1, but is not @p inst1.
+ * @param [in] inst3 A pointer to an instance that is known to be equal to @p inst1 & @p inst2, but is not @p inst1 or @p inst2.
+ * @param [in] lesser A pointer to and instance that are known to be lesser than @p inst1.
+ * @param [in] greater A pointer to and instance that are known to be greater than @p inst1.
+ *
+ * @see parcObjectTesting_AssertEqualsFunction
+ * @see parcObjectTesting_AssertCompareTo
+ * @see parcObjectTesting_AssertAcquire
+ * @see parcObjectTesting_AssertHashCode
+ */
+
+void parcObjectTesting_AssertObjectConformance(const PARCObject *inst1,
+                                               const PARCObject *inst2,
+                                               const PARCObject *inst3,
+                                               const PARCObject *lesser,
+                                               const PARCObject *greater);
+
+/**
+ * Ensure that a function implements the Equals contract.
+ *
+ *   The equality function must implement the following equivalence relations on non-null instances:
+ *
+ *   * It is reflexive: for any non-null reference value x, equals(x, x) must return true.
+ *
+ *   * It is symmetric: for any non-null reference values x and y, equals(x, y) must return true if and only if
+ *        equals(y x) returns true.
+ *
+ *   * It is transitive: for any non-null reference values x, y, and z, if
+ *        equals(x, y) returns true and
+ *        equals(y, z) returns true,
+ *        then  equals(x, z) must return true.
+ *
+ *   * It is consistent: for any non-null reference values x and y, multiple invocations of equals(x, y)
+ *         consistently return true or consistently return false.
+ *
+ *   * For any non-null reference value x, equals(x, NULL)) must return false.
+ *
+ * @param [in] _function_ A pointer to a function that will be called to determine if it conforms to the Equals contract.
+ * @param [in] _x_ A pointer to a value that will be used as the base comparison for remaining parameters.
+ * @param [in] _y_ A pointer to a value that is known to be equal to @p x, but is not @p x.
+ * @param [in] _z_ A pointer to a value that is known to be equal to @p x and to @p y, but is neither @p x nor @p y.
+ * @param [in] ... A list of pointers to values that are known to be not equal to @p x, @p y, or @p z.
+ * @see parcObjectTesting_AssertEqualsImpl
+ */
+#define parcObjectTesting_AssertEqualsFunction(_function_, _x_, _y_, _z_, ...) \
+    parcObjectTesting_AssertEqualsFunctionImpl((bool (*)(const void *, const void *))_function_, _x_, _y_, _z_, __VA_ARGS__, NULL)
+
+/**
+ * Compares instance a known set of other instances for order.
+ *
+ * The comparison function that this evaluates <i>sgn(a - b)</i> required to return a negative integer,
+ * zero, or a positive integer as <code>a</code> is less than,
+ * equal to, or greater than <code>b</code>.
+ *
+ * The function must ensure that:
+ *   <ul>
+ *     <li>sgn(compareTo(a, b)) == -sgn(b, a) for all values of a and b.</li>
+ *     <li>the relation is transitive: (compareTo(x, y)>0 && compareTo(y, z)>0) implies compareTo(x, z)>0.</li>
+ *     <li>compareTo(x, y)== 0 implies that sgn(compareTo(x, z)) == sgn(compareTo(y, z)), for all values of z.</li>
+ *   </ul>
+ *
+ *   This also stipulates that
+ *   <code>compareTo(NULL, NULL)) == 0</code>,
+ *   <code>compareTo(not-NULL, NULL)) > 0</code>,
+ *   <code>compareTo(NULL, not-NULL)) < 0</code>.
+ *
+ * It is strongly recommended, but not strictly required that relation(compareTo(x, y)==0) == equals(x, y)) is true.
+ * Any module that implements the compareTo function and violates this condition
+ * should clearly indicate this fact.
+ * For example, "Note: this implementation has a natural ordering that is inconsistent with equals."
+ *
+ * @param [in] compareTo A pointer to a function implementing the CompareTo function signature.
+ * @param [in] exemplar The pivotal value under test.
+ * @param [in] equivalent A NULL terminated array of values that are all equivalent to <code>value</code>.
+ * @param [in] lesser A NULL terminated array of values that are all less than <code>value</code>.
+ * @param [in] greater A NULL terminated array of values that are all greater than <code>value</code>.
+ * @see parcObjectTesting_AssertCompareTo
+ */
+#define parcObjectTesting_AssertCompareTo(function, value, equality, lesser, greater) \
+    parcObjectTesting_AssertCompareToImpl((int (*)(const void *, const void *))function, (void *) value, (void *) equality, (void *) lesser, (void *) greater)
+
+#define parcObjectTesting_AssertAcquireReleaseContract(_function_, _instance_) \
+    parcObjectTesting_AssertAcquireReleaseContractImpl((void *(*)(const PARCObject *))_function_, _instance_)
+/**
+ * Assert the acquire/release contract given the Acquire function of a PARCObject implementation.
+ *
+ * Paragraphs Of Explanation
+ *
+ * @param [in] acquireFunction A pointer to the acquireFunction to invoke.
+ * @param [in] instance A pointer to a PARCObject implementation that will be used to acquire and release references.
+ */
+void parcObjectTesting_AssertAcquireReleaseContractImpl(void *(acquireFunction)(const PARCObject *),
+                                                        const PARCObject *instance);
+
+
+#define parcObjectTesting_AssertAcquire(_instance_) \
+    parcObjectTesting_AssertAcquireReleaseImpl((const PARCObject *) _instance_)
+
+/**
+ * Assert that the given PARCObject's Acquire/Release contract is correct.
+ *
+ * @param [in] instance A pointer to a PARCObject instance.
+ */
+void parcObjectTesting_AssertAcquireReleaseImpl(const PARCObject *instance);
+
+/**
+ * Ensure that a function implements the Equals contract.
+ *
+ *   The equality function must implement the following equivalence relations on non-null instances:
+ *
+ *   * It is reflexive: for any non-null reference value x, equals(x, x) must return true.
+ *
+ *   * It is symmetric: for any non-null reference values x and y, equals(x, y) must return true if and only if
+ *        equals(y x) returns true.
+ *
+ *   * It is transitive: for any non-null reference values x, y, and z, if
+ *        equals(x, y) returns true and
+ *        equals(y, z) returns true,
+ *        then  equals(x, z) must return true.
+ *
+ *   * It is consistent: for any non-null reference values x and y, multiple invocations of equals(x, y)
+ *         consistently return true or consistently return false.
+ *
+ *   * For any non-null reference value x, equals(x, NULL)) must return false.
+ *
+ * @param [in] equalsFunction A pointer to a function that will be called to determine if it conforms to the Equals contract.
+ * @param [in] x A pointer to a value that will be used as the base comparison for remaining parameters.
+ * @param [in] y A pointer to a value that is known to be equal to @p x, but is not @p x.
+ * @param [in] z A pointer to a value that is known to be equal to @p x and to @p y, but is neither @p x nor @p y.
+ * @param [in] ... A NULL terminated variable number of parameters consisting of pointers to values that are known to be not equal to @p x, @p y, or @p z.
+ * @see parcObjectTesting_AssertEquals
+ */
+void parcObjectTesting_AssertEqualsFunctionImpl(bool (*equalsFunction)(const void *a, const void *b), const void *x, const void *y, const void *z, ...);
+
+/**
+ * Ensure that a PARCObject implements the Equals contract.
+ *
+ *   The PARCObject's `Equals()` function must implement the following equivalence relations on non-null instances:
+ *
+ *   * It is reflexive: for any non-null reference value x, equals(x, x) must return true.
+ *
+ *   * It is symmetric: for any non-null reference values x and y, equals(x, y) must return true if and only if
+ *        equals(y x) returns true.
+ *
+ *   * It is transitive: for any non-null reference values x, y, and z, if
+ *        equals(x, y) returns true and
+ *        equals(y, z) returns true,
+ *        then  equals(x, z) must return true.
+ *
+ *   * It is consistent: for any non-null reference values x and y, multiple invocations of equals(x, y)
+ *         consistently return true or consistently return false.
+ *
+ *   * For any non-null reference value x, equals(x, NULL)) must return false.
+ *
+ * @param [in] object A pointer to a valid PARCObject instance.
+ * @param [in] y A pointer to a value that is known to be equal to @p object, but is not the same as @p object.
+ * @param [in] z A pointer to a value that is known to be equal to @p object and to @p y, but is neither the same as @p object nor @p y.
+ * @param [in] ... A NULL terminated variable number of parameters consisting of pointers to values that are known to be not equal to @p object, @p y, or @p z.
+ */
+void parcObjectTesting_AssertEquals(const PARCObject *object, const void *y, const void *z, ...);
+
+/**
+ * Compares instance <code>a</code> with instance <code>b</code> for order.
+ *
+ * The comparison function that this evaluates <i>sgn(a - b)</i> required to return a negative integer,
+ * zero, or a positive integer as <code>a</code> is less than,
+ * equal to, or greater than <code>b</code>.
+ *
+ * The function must ensure that:
+ *   <ul>
+ *     <li>sgn(compareTo(a, b)) == -sgn(b, a) for all values of a and b.</li>
+ *     <li>the relation is transitive: (compareTo(x, y)>0 && compareTo(y, z)>0) implies compareTo(x, z)>0.</li>
+ *     <li>compareTo(x, y)== 0 implies that sgn(compareTo(x, z)) == sgn(compareTo(y, z)), for all values of z.</li>
+ *   </ul>
+ *
+ *   This also stipulates that
+ *   <code>compareTo(NULL, NULL)) == 0</code>,
+ *   <code>compareTo(not-NULL, NULL)) > 0</code>,
+ *   <code>compareTo(NULL, not-NULL)) < 0</code>.
+ *
+ * It is strongly recommended, but not strictly required that relation(compareTo(x, y)==0) == equals(x, y)) is true.
+ * Any module that implements the compareTo function and violates this condition
+ * should clearly indicate this fact.
+ * For example, "Note: this implementation has a natural ordering that is inconsistent with equals."
+ *
+ * @param [in] compareTo A pointer to a function implementing the CompareTo function signature.
+ * @param [in] exemplar The pivotal value under test.
+ * @param [in] equivalent A NULL terminated array of values that are all equivalent to <code>value</code>.
+ * @param [in] lesser A NULL terminated array of values that are all less than <code>value</code>.
+ * @param [in] greater A NULL terminated array of values that are all greater than <code>value</code>.
+ * @see parcObjectTesting_AssertCompareTo
+ */
+bool parcObjectTesting_AssertCompareToImpl(int (*compareTo)(const void *a, const void *b),
+                                           const void *exemplar,
+                                           const void **equivalent,
+                                           const void **lesser,
+                                           const void **greater);
+
+/**
+ * Assert the HashCode contract on a PARCObject.
+ *
+ * @param [in] x A pointer to a valid PARCObject.
+ * @param [in] y A pointer to a valid PARCObject, that must be equal to @p x, but not the same.
+ *
+ * Example:
+ * @code
+ * {
+ *     <#example#>
+ * }
+ * @endcode
+ */
+void parcObjectTesting_AssertHashCode(const PARCObject *x, const void *y);
+
+/**
+ * Assert the HashCode function contract.
+ *
+ * @param [in] hashCode A pointer to a function implementing the hash code function.
+ */
+void parcObjectTesting_AssertHashCodeImpl(PARCHashCode (*hashCode)(const void *a), void *a);
+#endif