readdir_sequence.hpp

用STL的方式封装了WindowsAPI、COM调用、ACE、ATL、MFC、WTL等多种组件

/* /////////////////////////////////////////////////////////////////////////
 * File:        platformstl/filesystem/readdir_sequence.hpp
 *
 * Purpose:     Platform header for the readdir_sequence components.
 *
 * Created:     29th April 2006
 * Updated:     12th June 2006
 *
 * Home:        http://stlsoft.org/
 *
 * Copyright (c) 2006, Matthew Wilson and Synesis Software
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * - Redistributions of source code must retain the above copyright notice, this
 *   list of conditions and the following disclaimer.
 * - Redistributions in binary form must reproduce the above copyright notice,
 *   this list of conditions and the following disclaimer in the documentation
 *   and/or other materials provided with the distribution.
 * - Neither the name(s) of Matthew Wilson and Synesis Software nor the names of
 *   any contributors may be used to endorse or promote products derived from
 *   this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 *
 * ////////////////////////////////////////////////////////////////////// */


/** \file platformstl/filesystem/readdir_sequence.hpp
 *
 * \brief [C++ only] Definition of the platformstl::readdir_sequence
 *  type.
 *  (\ref group__library__file_system "File System" Library.)
 */

#ifndef PLATFORMSTL_INCL_PLATFORMSTL_FILESYSTEM_HPP_READDIR_SEQUENCE
#define PLATFORMSTL_INCL_PLATFORMSTL_FILESYSTEM_HPP_READDIR_SEQUENCE

/* File version */
#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION
# define PLATFORMSTL_VER_PLATFORMSTL_FILESYSTEM_HPP_READDIR_SEQUENCE_MAJOR      2
# define PLATFORMSTL_VER_PLATFORMSTL_FILESYSTEM_HPP_READDIR_SEQUENCE_MINOR      0
# define PLATFORMSTL_VER_PLATFORMSTL_FILESYSTEM_HPP_READDIR_SEQUENCE_REVISION   1
# define PLATFORMSTL_VER_PLATFORMSTL_FILESYSTEM_HPP_READDIR_SEQUENCE_EDIT       3
#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */

/* /////////////////////////////////////////////////////////////////////////
 * Includes
 */

#ifndef PLATFORMSTL_INCL_PLATFORMSTL_HPP_PLATFORMSTL
# include <platformstl/platformstl.hpp>
#endif /* !PLATFORMSTL_INCL_PLATFORMSTL_HPP_PLATFORMSTL */

#if defined(PLATFORMSTL_OS_IS_UNIX)
# ifndef UNIXSTL_INCL_UNIXSTL_HPP_READDIR_SEQUENCE
#  include <unixstl/readdir_sequence.hpp>
# endif /* !UNIXSTL_INCL_UNIXSTL_HPP_READDIR_SEQUENCE */
#elif defined(PLATFORMSTL_OS_IS_WIN32)
# ifndef WINSTL_INCL_WINSTL_FILESYSTEM_HPP_FINDFILE_SEQUENCE
#  include <winstl/filesystem/findfile_sequence.hpp>
# endif /* !WINSTL_INCL_WINSTL_FILESYSTEM_HPP_FINDFILE_SEQUENCE */
# ifndef WINSTL_INCL_WINSTL_FILESYSTEM_HPP_FILESYSTEM_TRAITS
#  include <winstl/filesystem/filesystem_traits.hpp>
# endif /* !WINSTL_INCL_WINSTL_FILESYSTEM_HPP_FILESYSTEM_TRAITS */
#else /* ? operating system */
# error Operating system not discriminated
#endif /* operating system */

/* /////////////////////////////////////////////////////////////////////////
 * Namespace
 */

#if defined(_STLSOFT_NO_NAMESPACE) || \
    defined(STLSOFT_DOCUMENTATION_SKIP_SECTION)
/* There is no stlsoft namespace, so must define ::platformstl */
namespace platformstl
{
#else
/* Define stlsoft::platformstl_project */

namespace stlsoft
{

namespace platformstl_project
{
#endif /* _STLSOFT_NO_NAMESPACE */

/* ////////////////////////////////////////////////////////////////////// */

#if defined(STLSOFT_DOCUMENTATION_SKIP_SECTION)

    /** \brief STL-like readonly sequence based on directory contents.
     *
     * \ingroup group__library__file_system
     *
     * The class is only defined in the \link ::platformstl platformstl\endlink
     * when the platform is not UNIX, in which case it uses the services
     * of another file-system enumeration type, e.g.
     * winstl::basic_findfile_sequence. For UNIX compilation, it
     * resolves to unixstl::readdir_sequence, relying on
     * \ref group__principle__intersecting_structural_conformance "Intersecting Structural Conformance"
     * of the resolved platform-specific types.
     */
    class readdir_sequence
    {};

#elif defined(PLATFORMSTL_OS_IS_UNIX)

# ifdef _UNIXSTL_NO_NAMESPACE
    using ::readdir_sequence;
# else /* ? _UNIXSTL_NO_NAMESPACE */
    using ::unixstl::readdir_sequence;
# endif /* _UNIXSTL_NO_NAMESPACE */

#elif defined(PLATFORMSTL_OS_IS_WIN32)

    class readdir_sequence
    {
    /// \name Member Types
    /// @{
    public:
        // This class
        typedef readdir_sequence                                    class_type;
    private:
        typedef winstl_ns_qual(ws_char_a_t)                         char_type;
        typedef winstl_ns_qual(basic_findfile_sequence)<char_type>  underlying_sequence_type;
        typedef winstl_ns_qual(filesystem_traits)<char_type>        traits_type;
    public:
        typedef underlying_sequence_type::const_iterator            underlying_sequence_const_iterator_type;
        typedef underlying_sequence_type::value_type                underlying_sequence_value_type;
    public:
        // The size type
        typedef winstl_ns_qual(ws_size_t)                           size_type;
        // The non-mutating (const) iterator type
        class                                                       const_iterator;
        // The value type
        typedef char_type const                                     *value_type;
        /// The flags type
        typedef winstl_ns_qual(ws_int_t)                            flags_type;
        /// The Boolean type
        typedef winstl_ns_qual(ws_bool_t)                           bool_type;

    public:
    /// @}

    /// \name Flags
    /// @{
    public:
        enum
        {
                includeDots     =   0x0008  /*!< Requests that dots directories be included in the returned sequence */
            ,   directories     =   0x0010  /*!< Causes the search to include directories */
            ,   files           =   0x0020  /*!< Causes the search to include files */
            ,   fullPath        =   0x0100  /*!< Each file entry is presented as a full path relative to the search directory. */
            ,   absolutePath    =   0x0200  /*!< The search directory is converted to an absolute path. */
        };
    /// @}

    /// \name Construction
    /// @{
    public:
        /// \brief Constructs a sequence according to the given criteria
        ///
        /// The constructor initialises a readdir_sequence instance on the given
        /// directory with the given flags.
        ///
        /// \param directory The directory whose contents are to be searched
        /// \param flags Flags to alter the behaviour of the search
        ///
        /// \note The \c flags parameter defaults to <code>directories | files</code> because
        /// this reflects the default behaviour of \c readdir(), and also because it is the
        /// most efficient.
        template <ss_typename_param_k S>
        readdir_sequence(S const &directory, flags_type flags = directories | files)
            : m_ffs(stlsoft_ns_qual(c_str_ptr)(directory), "*.*", translate_flags_(flags))
            , m_flags(validate_flags_(flags))
        {}
    /// @}

    /// \name Iteration
    /// @{
    public:
        /// Begins the iteration
        ///
        /// \return An iterator representing the start of the sequence
        const_iterator  begin() const;
        /// Ends the iteration
        ///
        /// \return An iterator representing the end of the sequence
        const_iterator  end() const;
    /// @}

    /// \name Attributes
    /// @{
    public:
        /// \brief Indicates whether the search sequence is empty
        bool_type           empty() const;

        /// \brief The search directory
        ///
        /// \note The value returned by this method always has a trailing path name separator, so
        /// you can safely concatenate this with the value returned by the iterator's operator *()
        /// with minimal fuss.
        char_type const     *get_directory() const;

        /// \brief The flags used by the sequence
        ///
        /// \note This value is the value used by the sequence, which may, as a result of the
        /// determination of defaults, be different from those specified in its constructor. In
        /// other words, if <code>includeDots</code> is specified, this function
        /// will return <code>includeDots | directories | files</code>
        flags_type          get_flags() const;
    /// @}

    /// \name Implementation
    /// @{
    private:
        /// \brief Ensures that the flags are correct
        static flags_type   validate_flags_(flags_type flags);