#######################
cmakepp_lang/types/path
#######################

.. module:: cmakepp_lang/types/path


.. function:: cpp_is_path(result str2check)

   Determines if a string is lexically convertible to an absolute filepath.
   
   This function wraps a call to CMake's ``if(IS_ABSOLUTE ...)`` in order to
   determine if the provided string is lexically convertible to an absolute
   filepath.
   
   :param result: An identifier to hold the result.
   :type result: identifier
   :param str2check: The string which may be an absolute filepath.
   :type str: str
   :returns: ``TRUE`` if ``str2check`` is an absolute filepath and
             ``FALSE`` otherwise. The result is returned via ``result``.
   :rtype: bool
   
   Example Usage
   =============
   
   The following code snippet checks whether ${CMAKE_BINARY_DIR} is a relative
   directory (it always is by default):
   
   .. code-block:: cmake
   
      include(cmakepp_lang/types/filepath)
      cpp_is_path(result "${CMAKE_BINARY_DIR}")
      message("Is a filepath: ${result}")  # Prints TRUE
   
   Error Checking
   ==============
   
   ``cpp_is_path`` will assert that the caller has provided exactly two
   arguments. If this is not the case an error will be raised.