environment_map.hpp

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

/* /////////////////////////////////////////////////////////////////////////
 * File:        platformstl/system/environment_map.hpp
 *
 * Purpose:     Definition of the environment_map class.
 *
 * Created:     14th November 2005
 * Updated:     11th June 2006
 *
 * Home:        http://stlsoft.org/
 *
 * Copyright (c) 2005-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/system/environment_map.hpp
 *
 * \brief [C++ only] Definition of the platformstl::environment_map class.
 *  (\reg group__library__system "System" Library.)
 */

#ifndef PLATFORMSTL_INCL_PLATFORMSTL_SYSTEM_HPP_ENVIRONMENT_MAP
#define PLATFORMSTL_INCL_PLATFORMSTL_SYSTEM_HPP_ENVIRONMENT_MAP

/* File version */
#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION
# define PLATFORMSTL_VER_PLATFORMSTL_SYSTEM_HPP_ENVIRONMENT_MAP_MAJOR       2
# define PLATFORMSTL_VER_PLATFORMSTL_SYSTEM_HPP_ENVIRONMENT_MAP_MINOR       0
# define PLATFORMSTL_VER_PLATFORMSTL_SYSTEM_HPP_ENVIRONMENT_MAP_REVISION    2
# define PLATFORMSTL_VER_PLATFORMSTL_SYSTEM_HPP_ENVIRONMENT_MAP_EDIT        35
#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */

/* /////////////////////////////////////////////////////////////////////////
 * Auto-generation and compatibility
 */

/*
[Incompatibilies-start]
STLSOFT_COMPILER_IS_WATCOM:
[Incompatibilies-end]
*/

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

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

#if defined(PLATFORMSTL_OS_IS_UNIX)

#elif defined(PLATFORMSTL_OS_IS_WIN32)

#else /* ? operating system */
# error Operating system not discriminated
#endif /* operating system */

#ifndef STLSOFT_INCL_STLSOFT_HPP_SCOPED_HANDLE
# include <stlsoft/scoped_handle.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_HPP_SCOPED_HANDLE */
#ifndef STLSOFT_INCL_STLSOFT_HPP_SHARED_PTR
# include <stlsoft/shared_ptr.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_HPP_SHARED_PTR */
#ifndef STLSOFT_INCL_STLSOFT_HPP_STRING_ACCESS
# include <stlsoft/string_access.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_HPP_STRING_ACCESS */
#ifndef STLSOFT_INCL_STLSOFT_STRING_HPP_SPLIT_FUNCTIONS
# include <stlsoft/string/split_functions.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_STRING_HPP_SPLIT_FUNCTIONS */
#ifndef STLSOFT_INCL_STLSOFT_HPP_ITERATOR
# include <stlsoft/iterator.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_HPP_ITERATOR */
#ifndef STLSOFT_INCL_STLSOFT_COLLECTIONS_HPP_COLLECTIONS
# include <stlsoft/collections/collections.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_COLLECTIONS_HPP_COLLECTIONS */
#include <map>
#include <utility>

/* /////////////////////////////////////////////////////////////////////////
 * 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 */

/* /////////////////////////////////////////////////////////////////////////
 * Classes
 */

/** \brief Provides an associative STL-collection interface to the current
 *   process's system environment.
 *
 * \note The design and implementation of this class is documented in Part 2
 *  of the forthcoming book
 *  <a href = "http://extendedstl.com">Extended STL</a>.
 */
class environment_map
    : public stlsoft_ns_qual(stl_collection_tag)
{
/// \name Member Types
/// @{
private:
    typedef environment_variable_traits                     traits_type;
    typedef stlsoft_ns_qual_std(string)                     string_type;
public:
    /// \brief The string type used for variable name, and lookup
    ///
    /// \note This is the association "key" type
    typedef string_type                                     first_type;
    /// \brief The string type used for variable value, and retrieval
    ///
    /// \note This is the association "value" type
    typedef string_type                                     second_type;
    /// \brief Value type of the class: a pair of first_type and second_type
    typedef std::pair<  const first_type
                    ,   second_type
                    >                                       value_type;
    /// \brief The size type
    typedef ss_size_t                                       size_type;
    /// \brief The difference type
    typedef ss_ptrdiff_t                                    difference_type;
    /// \brief The non-mutating (const) reference type
    typedef const value_type                                const_reference;    // BVT
    /// \brief The non-mutating (const) iterator type
    class                                                   const_iterator;
#if defined(STLSOFT_CF_BIDIRECTIONAL_ITERATOR_SUPPORT) && \
    !defined(STLSOFT_COMPILER_IS_BORLAND)
    typedef const_reverse_bidirectional_iterator_base<  const_iterator
                                                    ,   value_type
                                                    ,   const_reference
                                                    ,   void            // By-Value Temporary reference category
                                                    ,   difference_type
                                                    >       const_reverse_iterator;
#endif /* STLSOFT_CF_BIDIRECTIONAL_ITERATOR_SUPPORT */
    /// \brief The type of the class
    typedef environment_map                                 class_type;

private:
    friend class const_iterator;
    class snapshot
    {
    public: // Member Types
        typedef stlsoft_ns_qual(shared_ptr)<snapshot>   ref_type;
        typedef stlsoft_ns_qual_std(map)<   const first_type
                                        ,   second_type
                                        >               variables_type_;
        typedef variables_type_::iterator               iterator;

    public: // Construction
        snapshot();

    public: // Operations
        ss_bool_t erase(    first_type const    &name) throw();
        void erase(         iterator            it) throw();
        void insert(        first_type const    &name
                        ,   second_type const   &value);
        void set(           first_type const    &name
                        ,   second_type const   &value);
        ss_bool_t lookup(   first_type const    &name
                        ,   second_type         *&pvalue) throw();

    public: // Iteration
        iterator    begin();
        iterator    end();

    private: // Members
        variables_type_   m_variables;
    };
/// @}

/// \name Construction
/// @{
public:
    /// \brief Constructs an instance of the type
    ///
    /// \note This instance does <b>not</b> store a snapshot of the
    ///  environment at the time of its construction. All lookup and
    ///  iteration is carried out 'live' at the time of invocation.
    environment_map();
/// @}

/// \name Element Access
/// @{
public:
    /// \brief Returns the value of the given environment variable, or throws
    ///  std::out_of_range if it does not exist.
    ///
    /// \param name The name of the environment variable whose value is to be
    ///  retrieved
    ///
    /// \exception std::out_of_range If no variable exists with the given name
    second_type operator [](char const *name) const;
    /// \brief Returns the value of the given environment variable, or throws
    ///  std::out_of_range if it does not exist.
    ///
    /// \param name The name of the environment variable whose value is to be
    ///  retrieved
    ///
    /// \exception std::out_of_range If no variable exists with the given name
    second_type operator [](first_type const &name) const;

    /// \brief Looks for the variable of the given name in the current
    ///  process environment.
    ///
    /// \return A Boolean value indicating whether the variable was found
    ss_bool_t   lookup(char const *name, second_type &value) const;
    /// \brief Looks for the variable of the given name in the current
    ///  process environment.
    ///
    /// \return A Boolean value indicating whether the variable was found
    ss_bool_t   lookup(first_type const &name, second_type &value) const;
/// @}

/// \name Operations
/// @{
public:
    /// \brief Discard any current enumeration snapshots.
    ///
    /// Used to force the collection instance to discard any currently snapshotd
    /// snapshot it may be holding on behalf of extant iterator instances, so
    /// that new iterator instances will receive a refreshed view of the
    /// underlying environment.
    void refresh();
/// @}

/// \name Modifiers
/// @{
public:
#ifdef PLATFORMSTL_ENVVAR_SET_SUPPORTED
    /// \brief Inserts or updates and environment variable
    ///
    /// \note This method is strongly exception-safe. The insertion into the
    /// snapshot is done first. If that does not throw an exception, but the
    /// insertion into the process' environment fails, it is removed from
    /// the snapshot. The only way that could fail would be if the element
    /// already exists, in which case
    void insert(first_type const &name, second_type const &value);

    /// \brief The semantics of this function are identical to the string object overload
    ///
    /// \param name The name of the variable to insert/update
    /// \param value The new value of the variable
    void insert(char const *name, char const *value);
#endif /* PLATFORMSTL_ENVVAR_SET_SUPPORTED */
#ifdef PLATFORMSTL_ENVVAR_ERASE_SUPPORTED
    /// \brief Removes the entry of the given name
    ///
    /// \note If the given entry does not exist
    size_type erase(first_type const &name);

    /// \brief Removes the entry of the given name
    ///
    /// \note If the given entry does not exist
    size_type erase(char const *name);

    /// \brief Removes the entry corresponding to the given iterator
    void erase(const_iterator it);
#endif /* PLATFORMSTL_ENVVAR_ERASE_SUPPORTED */
/// @}

/// \name Iteration
/// @{
public:
#ifdef PLATFORMSTL_ENVVAR_HAS_ENVIRON
    /// \brief Begins the iteration
    ///
    /// \return A non-mutating (const) iterator representing the start of the sequence
    const_iterator  begin() const;
    /// \brief Ends the iteration
    ///
    /// \return A non-mutating (const) iterator representing (one past) the end of the sequence
    const_iterator  end() const;
# if defined(STLSOFT_CF_BIDIRECTIONAL_ITERATOR_SUPPORT) && \
     !defined(STLSOFT_COMPILER_IS_BORLAND)
    /// \brief Begins the reverse iteration
    ///
    /// \return A non-mutating (const) iterator representing the start of the reverse sequence
    const_reverse_iterator  rbegin() const;
    /// \brief Ends the reverse iteration
    ///
    /// \return A non-mutating (const) iterator representing (one past) the end of the reverse sequence
    const_reverse_iterator  rend() const;
# endif /* STLSOFT_CF_BIDIRECTIONAL_ITERATOR_SUPPORT */
#endif /* PLATFORMSTL_ENVVAR_HAS_ENVIRON */
/// @}

/// \name Iteration
/// @{
public:
#ifdef PLATFORMSTL_ENVVAR_HAS_ENVIRON
    /// \brief const_iterator class
    ///
    /// \note Even though the const_iterator class, in and of itself, supports Invalidatable
    /// References, the collection as a whole supports only By-Value Temporary (BVT) References
    /// because that is the highest model that the subscript operations can support. (See XSTL
    /// for details.)
    class const_iterator
        : public stlsoft_ns_qual(iterator_base)<stlsoft_ns_qual_std(bidirectional_iterator_tag)
                                            ,   value_type
                                            ,   ss_ptrdiff_t
                                            ,   void                // By-Value Temporary reference
                                            ,   const value_type    // By-Value Temporary reference
                                            >
    {
    /// \name Member Types
    /// @{
    public:
        typedef const_iterator  class_type;
    /// @}

    /// \name Construction
    /// @{
    private:
        friend class environment_map;
        const_iterator(snapshot::iterator it, snapshot::ref_type snapshot);
    public:
        const_iterator();
        const_iterator(class_type const &rhs);
    /// @}

    /// \name Forward Iterator Operations
    /// @{
    public:
        class_type &operator ++();
        class_type operator ++(int);
        const_reference operator *() const;
    /// @}

    /// \name BiDirectional Iterator Operations
    /// @{
    public:
        class_type &operator --();
        class_type operator --(int);
    /// @}

    /// \name Comparison
    /// @{
    public:
        ss_bool_t equal(class_type const &rhs) const;
    /// @}

    /// \name Members
    /// @{
    private:
        snapshot::iterator     m_it;
        snapshot::ref_type     m_snapshot;
    /// @}
    };
#endif /* PLATFORMSTL_ENVVAR_HAS_ENVIRON */
/// @}

/// \name Implementation
/// @{
private:
#ifdef PLATFORMSTL_ENVVAR_HAS_ENVIRON
    void check_refresh_snapshot_() const;
#endif /* PLATFORMSTL_ENVVAR_HAS_ENVIRON */
/// @}

/// \name Members
/// @{
private:
#ifdef PLATFORMSTL_ENVVAR_HAS_ENVIRON
    mutable snapshot::ref_type     m_snapshot;
#endif /* PLATFORMSTL_ENVVAR_HAS_ENVIRON */
/// @}

/// \name Not to be defined
/// @{
private:
    environment_map(environment_map const &rhs);
    environment_map &operator =(environment_map const &rhs);
/// @}
};

/* /////////////////////////////////////////////////////////////////////////
 * Operators
 */

// NOTE: Neither Borland (5.6+) nor DMC++ correctly handle ADL for (comparison)
//       operators of types within a namespace, so we temporarily skip out into
//       the global namespace.

#if (   defined(STLSOFT_COMPILER_IS_BORLAND) && \
        __BORLANDC__ >= 0x0560) || \
    defined(STLSOFT_COMPILER_IS_DMC)

# if defined(_STLSOFT_NO_NAMESPACE) || \
     defined(STLSOFT_DOCUMENTATION_SKIP_SECTION)
} // namespace platformstl
# else
} // namespace platformstl_project
} // namespace stlsoft
# endif /* _STLSOFT_NO_NAMESPACE */

#endif /* compiler */

inline stlsoft_ns_qual(ss_bool_t) operator ==(  platformstl_ns_qual(environment_map)::const_iterator const  &lhs
                                            ,   platformstl_ns_qual(environment_map)::const_iterator const  &rhs)
{
    return lhs.equal(rhs);
}
inline stlsoft_ns_qual(ss_bool_t) operator !=(  platformstl_ns_qual(environment_map)::const_iterator const  &lhs
                                            ,   platformstl_ns_qual(environment_map)::const_iterator const  &rhs)
{
    return !lhs.equal(rhs);
}

// TODO: Make this a discriminated feature declared in the cccap files
#if (   defined(STLSOFT_COMPILER_IS_BORLAND) && \