environment_sequence.hpp

新版本TR1的stl

/* /////////////////////////////////////////////////////////////////////////
 * File:        winstl/system/environment_sequence.hpp
 *
 * Purpose:     basic_environment_sequence class.
 *
 * Created:     31st December 2002
 * Updated:     12th March 2007
 *
 * Home:        http://stlsoft.org/
 *
 * Copyright (c) 2002-2007, 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 winstl/system/environment_sequence.hpp
 *
 * \brief [C++ only] Definition of the winstl::basic_environment_sequence
 *  class template
 *   (\ref group__library__system "System" Library).
 */

#ifndef WINSTL_INCL_WINSTL_SYSTEM_HPP_ENVIRONMENT_SEQUENCE
#define WINSTL_INCL_WINSTL_SYSTEM_HPP_ENVIRONMENT_SEQUENCE

#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION
# define WINSTL_VER_WINSTL_SYSTEM_HPP_ENVIRONMENT_SEQUENCE_MAJOR    4
# define WINSTL_VER_WINSTL_SYSTEM_HPP_ENVIRONMENT_SEQUENCE_MINOR    0
# define WINSTL_VER_WINSTL_SYSTEM_HPP_ENVIRONMENT_SEQUENCE_REVISION 3
# define WINSTL_VER_WINSTL_SYSTEM_HPP_ENVIRONMENT_SEQUENCE_EDIT     75
#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */

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

#ifndef WINSTL_INCL_WINSTL_H_WINSTL
# include <winstl/winstl.h>
#endif /* !WINSTL_INCL_WINSTL_H_WINSTL */
#ifndef STLSOFT_INCL_STLSOFT_UTIL_STD_HPP_ITERATOR_HELPER
# include <stlsoft/util/std/iterator_helper.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_UTIL_STD_HPP_ITERATOR_HELPER */
#ifndef STLSOFT_INCL_STLSOFT_MEMORY_HPP_AUTO_BUFFER
# include <stlsoft/memory/auto_buffer.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_MEMORY_HPP_AUTO_BUFFER */
#ifndef STLSOFT_INCL_STLSOFT_UTIL_STD_HPP_ITERATOR_GENERATORS
# include <stlsoft/util/std/iterator_generators.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_UTIL_STD_HPP_ITERATOR_GENERATORS */
#ifndef WINSTL_INCL_WINSTL_MEMORY_HPP_PROCESSHEAP_ALLOCATOR
# include <winstl/memory/processheap_allocator.hpp>
#endif /* !WINSTL_INCL_WINSTL_MEMORY_HPP_PROCESSHEAP_ALLOCATOR */
#ifndef STLSOFT_INCL_STLSOFT_COLLECTIONS_UTIL_HPP_COLLECTIONS
# include <stlsoft/collections/util/collections.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_COLLECTIONS_UTIL_HPP_COLLECTIONS */
#include <algorithm>
#ifndef _WINSTL_WINDOW_FUNCTIONALS_NO_STD
# include <functional>
#else /* ? _WINSTL_WINDOW_FUNCTIONALS_NO_STD */
# error Now need to write that std_binary_function stuff!!
#endif /* _WINSTL_WINDOW_FUNCTIONALS_NO_STD */

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

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

namespace stlsoft
{

namespace winstl_project
{

# endif /* _STLSOFT_NO_NAMESPACE */
#endif /* !_WINSTL_NO_NAMESPACE */

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

/** \brief STL-like sequence for the system environment variables
 *
 * \ingroup group__library__system
 *
 * \param C The character type
 *
 * \note Even though Win32 treats environment variables in a case-insensitive
 * manner, it is possible for the raw environment information (access via the
 * GetEnvironmentStrings() function) to contain multiple entries whose names
 * differ only by case. Thus, later versions of the sequence class support the
 * \c ignoreCase member constant, which is passed by default to the
 * constructor, in order to facilitate "normal" Win32 operation while
 * supporting all possible modes.
 */
template <ss_typename_param_k C>
class basic_environment_sequence
    : public stlsoft_ns_qual(stl_collection_tag)
{
/// \name Member Types
/// @{
public:
    /// The character type
    typedef C                                                   char_type;
    /// Structure representing the items
    struct symbol
    {
        /// The symbol name
        char_type const* name;
        /// The symbol value
        char_type const* value;
    };
    /// The value type
    typedef symbol                                              value_type;
    /// The current parameterisation of the type
    typedef basic_environment_sequence<C>                       class_type;
    /// The non-mutable (const) pointer type
    typedef value_type const                                    *const_pointer;
    /// The non-mutable (const) reference type
    typedef value_type const                                    &const_reference;
    /// The size type
    typedef ws_size_t                                           size_type;
    /// The difference type
    typedef ws_ptrdiff_t                                        difference_type;
    /// The non-mutating (const) iterator type
    typedef
#if !defined(STLSOFT_COMPILER_IS_BORLAND)
      ss_typename_type_k
#endif /* compiler */
        stlsoft_ns_qual(pointer_iterator)   <   value_type
                                            ,   const_pointer
                                            ,   const_reference
                                            >::type             const_iterator;
#if defined(STLSOFT_CF_BIDIRECTIONAL_ITERATOR_SUPPORT)
    /// The non-mutating (const) reverse iterator type
    typedef
#if !defined(STLSOFT_COMPILER_IS_BORLAND)
            ss_typename_type_k
#endif /* compiler */
                               stlsoft_ns_qual(const_reverse_iterator_generator)<   const_iterator
                                                                                ,   value_type
                                                                                ,   const_reference
                                                                                ,   const_pointer
                                                                                ,   difference_type
                                                                                >::type     const_reverse_iterator;
#endif /* STLSOFT_CF_BIDIRECTIONAL_ITERATOR_SUPPORT */
/// @}

/// \name Member Constants
/// @{
public:
    enum
    {
            showHidden  =   0x0001  //!< Include the hidden environment variables (those beginning with '=') in the sequence
        ,   noSort      =   0x0002  //!< Do not explicitly sort the contents
        ,   ignoreCase  =   0x0004  //!< Ignore case in when comparing names / values in find() methods
    };
/// @}

// Construction
public:
    /// Construct a sequence of the current process's environment entries, according
    /// to the given criteria
    ///
    /// \param flags One or more of the member constants
    ss_explicit_k basic_environment_sequence(ws_int_t flags = ignoreCase);
    /// Destructor, which releases any resources acquired
    ~basic_environment_sequence() stlsoft_throw_0();

/// \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;

#if defined(STLSOFT_CF_BIDIRECTIONAL_ITERATOR_SUPPORT)
    /// Begins the reverse iteration
    ///
    /// \return An iterator representing the start of the reverse sequence
    const_reverse_iterator  rbegin() const;
    /// Ends the reverse iteration
    ///
    /// \return An iterator representing the end of the reverse sequence
    const_reverse_iterator  rend() const;
#endif /* STLSOFT_CF_BIDIRECTIONAL_ITERATOR_SUPPORT */

    /// Searches for an entry holding the given name
    ///
    /// \param name The name of the entry. Must not be NULL
    const_iterator  find(char_type const* name) const;

    /// Searches for an entry holding the given name and value
    ///
    /// \param name The name of the entry. Must not be NULL
    /// \param value The value of the entry. Must not be NULL
    const_iterator  find(char_type const* name, char_type const* value) const;
/// @}

/** \brief Size
 * @{
 *
 * \ingroup group__library__system
 */
public:
    /// Returns the number of elements in the enviroment sequence
    size_type size() const;
    /// Indicates whether the enviroment sequence is empty
    ws_bool_t empty() const;
/// @}

// Accessors
public:
    /// Returns the name-value item for the given index
    value_type operator [](size_type index) const;

// TODO: Add ARV to this class

// Implementation
private:
    typedef stlsoft_ns_qual(auto_buffer_old)<   char_type
                                            ,   processheap_allocator<char_type>
                                            >           environment_buffer_type;
    typedef stlsoft_ns_qual(auto_buffer_old)<   symbol
                                            ,   processheap_allocator<symbol>
                                            >           symbols_buffer_type;

    static ws_size_t    calc_items_(char_type const* p, char_type const** q, ws_int_t flags);
    static void         prepare_items_(symbols_buffer_type &symbols, environment_buffer_type &environment, char_type *p, char_type *q, ws_int_t flags);
private:
    static ws_int_t     compare_strings_(char_type const* s1, char_type const* s2, ws_int_t flags);

public:
    /// A function class that compares environment symbols for the basic_environment_sequence class
    // [[synesis:class:binary-functor: compare_symbol]]
    struct compare_symbol
        : stlsoft_ns_qual_std(binary_function)<symbol, symbol, ws_bool_t>
//      , stlsoft_ns_qual(base_property)<ws_bool_t, 0>
    {
    public:
        ss_explicit_k compare_symbol(ws_bool_t bIgnoreCase = true)
            : m_bIgnoreCase(bIgnoreCase)
//          , stlsoft_ns_qual(base_property)<ws_bool_t, 0>(b
        {}

    public:
        /// Function call operator, which returns \c true if \c lhs is lexicographically less than \c rhs
        ws_bool_t operator ()(symbol const& lhs, symbol const& rhs)
        {
            return compare_strings_(lhs.name, rhs.name, m_bIgnoreCase ? ignoreCase : 0) < 0;
        }

    private:
        ws_bool_t   m_bIgnoreCase;
    };

    friend struct compare_symbol; // This is needed by Borland, CodeWarrior, DMC++ and Visual C++

private:
    static ws_int_t         validate_flags_(ws_int_t flags);
    static char_type const* get_environment_strings_();
    static void             free_environment_strings_(char_type *);

private:
    const ws_int_t          m_flags;        // The flags as specified to the ctor
    C const                 *m_p;           // Pointer to the start of the raw environment block
    C const                 *m_q;           // Pointer to the (one off the) end of the raw environment block
    symbols_buffer_type     m_symbols;      // Array of symbols representing the parsed environment block
    environment_buffer_type m_environment;  // The editable (and edited) copy of the environment block