/*
 * 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