####################################
cmakepp_lang/utilities/compare_lists
####################################

.. module:: cmakepp_lang/utilities/compare_lists


.. function:: cpp_compare_lists(result lhs rhs)

   Encapsulates the process of comparing two CMake lists to one another.
   
   Two CMake lists are equal if they contain the same number of elements and if
   the :math:`i`-th element in ``lhs`` compares equal to the :math:`i`-th
   element of ``rhs`` under ``cpp_equal`` for all elements in the list. In
   particular this means that the lists must have the same order and that we
   compare the values of CMakePP objects, not their this-pointers.
   
   :param result: Name for variable which will hold the result.
   :type result: desc
   :param lhs: Identifier containing the first list to compare.
   :type lhs: list*
   :param rhs: Identifier containing the second list to comapre.
   :type rhs: list*
   :returns: ``result`` will be set to ``TRUE`` if the two lists are equal
             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 run in debug mode, this function will assert that the function
   is only provided three arguments (preventing the user from accidentally
   dereferencing one of the input lists in most cases) and that the arguments are
   all of type ``desc``.