############################
cmakepp_lang/algorithm/equal
############################

.. module:: cmakepp_lang/algorithm/equal


.. function:: cpp_equal(result lhs rhs)

   Compares two values for equivalency.
   
   This function can be used to compare any two CMakePP objects for equality. For
   native CMake types, like booleans and integers, equality is defined as being
   the same string. ``cpp_equal`` will also compare objects like CMakePP maps or
   instances of user-defined classes to ensure they have the same state. If two
   objects have different types they are defined to be unequal.
   
   :param result: The name to use for variable holding the result.
   :type result: desc
   :param lhs: One of the two values involved in the comparison.
   :type lhs: str
   :param rhs: The other value involved in the comparison
   :type rhs: str
   :returns: ``result`` will be set to ``TRUE`` if ``lhs`` compares equal
             to ``rhs`` and ``FALSE`` otherwise.
   :rtype: bool
   
   :var CMAKEPP_LANG_DEBUG_MODE: Used to determine if CMakePP is being run in
                                 debug mode or not.
   :vartype CMAKEPP_LANG_DEBUG_MODE: bool
   
   Error Checking
   ==============
   
   If CMakePP is being run in debug mode this function will assert that it is
   being called with exactly three arguments and that those arguments are of the
   correct types. If any of these asserts fail an error will be raised. These
   errors are only checked for in debug mode.