    // Copyright (C) 2009  Davis E. King (davis@dlib.net)
    // License: Boost Software License   See LICENSE.txt for the full license.
    #undef DLIB_DIR_NAV_EXTENSIONs_ABSTRACT_
    #ifdef DLIB_DIR_NAV_EXTENSIONs_ABSTRACT_

    #include <string>
    #include <vector>
    #include "dir_nav_kernel_abstract.h"

    namespace dlib
    {

    // ----------------------------------------------------------------------------------------

        bool file_exists (
            const std::string& filename
        );
        /*!
            ensures
                - if (a file with the given filename exists) then
                    - returns true
                - else
                    - returns false
        !*/

    // ----------------------------------------------------------------------------------------

        bool directory_exists (
            const std::string& dirname
        );
        /*!
            ensures
                - if (a directory with the given dirname exists) then
                    - returns true
                - else
                    - returns false
        !*/

    // ----------------------------------------------------------------------------------------

        template <typename T>
        const std::vector<file> get_files_in_directory_tree (
            const directory& top_of_tree,
            const T& add_file,
            unsigned long max_depth = 30
        );
        /*!
            requires
                - add_file must be a function object with the following prototype:
                    bool add_file (file f);
            ensures
                - performs a recursive search through the directory top_of_tree and all
                  its sub-directories (up to the given max depth).  All files in these
                  directories are examined by passing them to add_file() and if it
                  returns true then they will be included in the returned std::vector<file>
                  object.
                - Note that a max_depth of 0 means that only the files in the directory
                  top_of_tree will be considered.  A depth of 1 means that only files in
                  top_of_tree and its immediate sub-directories will be considered.  And
                  so on...
        !*/

    // ----------------------------------------------------------------------------------------

        class match_ending
        {
            /*!
                WHAT THIS OBJECT REPRESENTS
                    This is a simple function object that can be used with the
                    above get_files_in_directory_tree() function.  This object
                    just looks for files with a certain ending.
            !*/

        public:
            match_ending (
                const std::string& ending
            );
            /*!
                ensures
                    - this object will be a function that checks if a file has a
                      name that ends with the given ending string.
            !*/

            bool operator() (
                const file& f
            ) const;
            /*!
                ensures
                    - if (the file f has a name that ends with the ending string given
                      to this object's constructor) then
                        - returns true
                    - else
                        - returns false
            !*/
        };

    // ----------------------------------------------------------------------------------------

        class match_endings
        {
            /*!
                WHAT THIS OBJECT REPRESENTS
                    This is a simple function object that can be used with the
                    above get_files_in_directory_tree() function.  This object
                    allows you to look for files with a number of different
                    endings.
            !*/

        public:
            match_endings (
                const std::string& ending_list
            );
            /*!
                ensures
                    - ending_list is interpreted as a whitespace separated list
                      of file endings.
                    - this object will be a function that checks if a file has a
                      name that ends with one of the strings in ending_list.
            !*/

            bool operator() (
                const file& f
            ) const;
            /*!
                ensures
                    - if (the file f has a name that ends with one of the ending strings
                      given to this object's constructor) then
                        - returns true
                    - else
                        - returns false
            !*/
        };

    // ----------------------------------------------------------------------------------------

        class match_all
        {
            /*!
                WHAT THIS OBJECT REPRESENTS
                    This is a simple function object that can be used with the
                    above get_files_in_directory_tree() function.  This object
                    matches all files.
            !*/

        public:
            bool operator() (
                const file& f
            ) const;
            /*!
                ensures
                    - returns true
                      (i.e. this function doesn't do anything.  It just says it
                      matches all files no matter what)
            !*/
        };

    // ----------------------------------------------------------------------------------------

        directory get_parent_directory (
            const directory& dir
        );
        /*!
            ensures
                - returns the parent directory of dir.  In particular, this
                  function returns the value of dir.get_parent()
        !*/

    // ----------------------------------------------------------------------------------------

        directory get_parent_directory (
            const file& f
        );
        /*!
            ensures
                - if (f.full_name() != "") then
                    - returns the directory which contains the given file
                - else
                    - returns a default initialized directory (i.e. directory())
        !*/

    // ----------------------------------------------------------------------------------------

        std::string select_oldest_file (
            const std::string& filename1,
            const std::string& filename2
        );
        /*!
            ensures
                - Checks the last modification times of the two given files and returns the
                  filename of the oldest file, i.e., the file that has gone longest since being
                  modified.  Ties are broken arbitrarily.
                - For the purpose of comparison, a file that doesn't exist is presumed to have
                  a last modification time of -infinity (i.e. very far in the past).
        !*/

    // ----------------------------------------------------------------------------------------

        std::string select_newest_file (
            const std::string& filename1,
            const std::string& filename2
        );
        /*!
            ensures
                - Checks the last modification times of the two given files and returns the
                  filename that was most recently modified.  Ties are broken arbitrarily.
                - For the purpose of comparison, a file that doesn't exist is presumed to have
                  a last modification time of -infinity (i.e. very far in the past).
        !*/

    // ----------------------------------------------------------------------------------------

    }

    #endif // DLIB_DIR_NAV_EXTENSIONs_ABSTRACT_