《STL原始碼剖析》-- stl_multiset.h

// Filename:    stl_multiset.h

// Comment By:  凝霜
// E-mail:      mdl2009@vip.qq.com
// Blog:        http://blog.csdn.net/mdl13412

/*
 *
 * Copyright (c) 1994
 * Hewlett-Packard Company
 *
 * Permission to use, copy, modify, distribute and sell this software
 * and its documentation for any purpose is hereby granted without fee,
 * provided that the above copyright notice appear in all copies and
 * that both that copyright notice and this permission notice appear
 * in supporting documentation.  Hewlett-Packard Company makes no
 * representations about the suitability of this software for any
 * purpose.  It is provided "as is" without express or implied warranty.
 *
 *
 * Copyright (c) 1996
 * Silicon Graphics Computer Systems, Inc.
 *
 * Permission to use, copy, modify, distribute and sell this software
 * and its documentation for any purpose is hereby granted without fee,
 * provided that the above copyright notice appear in all copies and
 * that both that copyright notice and this permission notice appear
 * in supporting documentation.  Silicon Graphics makes no
 * representations about the suitability of this software for any
 * purpose.  It is provided "as is" without express or implied warranty.
 */

/* NOTE: This is an internal header file, included by other STL headers.
 *   You should not attempt to use it directly.
 */

#ifndef __SGI_STL_INTERNAL_MULTISET_H
#define __SGI_STL_INTERNAL_MULTISET_H

__STL_BEGIN_NAMESPACE

#if defined(__sgi) && !defined(__GNUC__) && (_MIPS_SIM != _MIPS_SIM_ABI32)
#pragma set woff 1174
#endif

// 如果編譯器不能根據前面模板引數推匯出後面使用的預設引數型別,
// 那麼就需要手工指定, 本實作multiset內部元素預設使用less進行比較
// 內部維護的資料結構是紅黑樹, 具有非常優秀的最壞情況的時間複雜度
// 注意: 與set不同, multiset允許有重複的元素
#ifndef __STL_LIMITED_DEFAULT_TEMPLATES
template <class Key, class Compare = less<Key>, class Alloc = alloc>
#else
template <class Key, class Compare, class Alloc = alloc>
#endif
class multiset
{
public:
  // 這裡和set定義相同, 見<stl_set.h>
  typedef Key key_type;
  typedef Key value_type;
  typedef Compare key_compare;
  typedef Compare value_compare;

private:
  // 內部採用紅黑樹為資料結構, 其實現在<stl_tree.h>
  typedef rb_tree<key_type, value_type,
                  identity<value_type>, key_compare, Alloc> rep_type;
  rep_type t;  // red-black tree representing multiset

public:
  // 標記為'STL標準強制要求'的typedefs用於提供iterator_traits<I>支援
  // 注意: 迭代器, 引用型別都設計為const, 這是由multiset的性質決定的,
  //      如果使用者自行更改其數值, 可能會導致內部的紅黑樹出現問題
  typedef typename rep_type::const_pointer pointer;            // STL標準強制要求
  typedef typename rep_type::const_pointer const_pointer;
  typedef typename rep_type::const_reference reference;        // STL標準強制要求
  typedef typename rep_type::const_reference const_reference;
  typedef typename rep_type::const_iterator iterator;          // STL標準強制要求
  typedef typename rep_type::const_iterator const_iterator;
  typedef typename rep_type::const_reverse_iterator reverse_iterator;
  typedef typename rep_type::const_reverse_iterator const_reverse_iterator;
  typedef typename rep_type::size_type size_type;
  typedef typename rep_type::difference_type difference_type;  // STL標準強制要求

  multiset() : t(Compare()) {}
  explicit multiset(const Compare& comp) : t(comp) {}

#ifdef __STL_MEMBER_TEMPLATES
  template <class InputIterator>
  multiset(InputIterator first, InputIterator last)
    : t(Compare()) { t.insert_equal(first, last); }
  template <class InputIterator>
  multiset(InputIterator first, InputIterator last, const Compare& comp)
    : t(comp) { t.insert_equal(first, last); }
#else
  multiset(const value_type* first, const value_type* last)
    : t(Compare()) { t.insert_equal(first, last); }
  multiset(const value_type* first, const value_type* last,
           const Compare& comp)
    : t(comp) { t.insert_equal(first, last); }

  multiset(const_iterator first, const_iterator last)
    : t(Compare()) { t.insert_equal(first, last); }
  multiset(const_iterator first, const_iterator last, const Compare& comp)
    : t(comp) { t.insert_equal(first, last); }
#endif /* __STL_MEMBER_TEMPLATES */

  multiset(const multiset<Key, Compare, Alloc>& x) : t(x.t) {}
  multiset<Key, Compare, Alloc>&
  operator=(const multiset<Key, Compare, Alloc>& x)
  {
    t = x.t;
    return *this;
  }

  // 返回用於key比較的函式
  key_compare key_comp() const { return t.key_comp(); }

  // 由於multiset的性質, value比較和key使用同一個比較函式
  value_compare value_comp() const { return t.key_comp(); }

  iterator begin() const { return t.begin(); }
  iterator end() const { return t.end(); }
  reverse_iterator rbegin() const { return t.rbegin(); }
  reverse_iterator rend() const { return t.rend(); }
  bool empty() const { return t.empty(); }
  size_type size() const { return t.size(); }
  size_type max_size() const { return t.max_size(); }

  // 這裡呼叫的是專用的swap, 不是全域性的swap, 定於於<stl_tree.h>
  void swap(multiset<Key, Compare, Alloc>& x) { t.swap(x.t); }

  // 插入元素, 注意, 插入的元素key允許重複
  iterator insert(const value_type& x)
  {
    return t.insert_equal(x);
  }

  // 在position處插入元素, 但是position僅僅是個提示, 如果給出的位置不能進行插入,
  // STL會進行查詢, 這會導致很差的效率
  iterator insert(iterator position, const value_type& x)
  {
    typedef typename rep_type::iterator rep_iterator;
    return t.insert_equal((rep_iterator&)position, x);
  }

#ifdef __STL_MEMBER_TEMPLATES
  template <class InputIterator>
  void insert(InputIterator first, InputIterator last)
  {
    t.insert_equal(first, last);
  }
#else
  void insert(const value_type* first, const value_type* last) {
    t.insert_equal(first, last);
  }
  void insert(const_iterator first, const_iterator last) {
    t.insert_equal(first, last);
  }
#endif /* __STL_MEMBER_TEMPLATES */

  // 擦除指定位置的元素, 會導致內部的紅黑樹重新排列
  void erase(iterator position)
  {
    typedef typename rep_type::iterator rep_iterator;
    t.erase((rep_iterator&)position);
  }

  // 會返回擦除元素的個數
  size_type erase(const key_type& x)
  {
    return t.erase(x);
  }

  // 擦除指定區間的元素, 會導致紅黑樹有較大變化
  void erase(iterator first, iterator last)
  {
    typedef typename rep_type::iterator rep_iterator;
    t.erase((rep_iterator&)first, (rep_iterator&)last);
  }

  // 好吧, clear all, 再見吧紅黑樹
  void clear() { t.clear(); }

  // 查詢指定的元素
  iterator find(const key_type& x) const { return t.find(x); }

  // 返回指定元素的個數
  size_type count(const key_type& x) const { return t.count(x); }

  // 返回小於當前元素的第一個可插入的位置
  iterator lower_bound(const key_type& x) const
  {
    return t.lower_bound(x);
  }

  // 返回大於當前元素的第一個可插入的位置
  iterator upper_bound(const key_type& x) const
  {
    return t.upper_bound(x);
  }

  pair<iterator,iterator> equal_range(const key_type& x) const
  {
    return t.equal_range(x);
  }

  friend bool operator== __STL_NULL_TMPL_ARGS (const multiset&,
                                               const multiset&);
  friend bool operator< __STL_NULL_TMPL_ARGS (const multiset&,
                                              const multiset&);
};

// 比較兩個multiset比較的是其內部的紅黑樹, 會觸發紅黑樹的operator

template <class Key, class Compare, class Alloc>
inline bool operator==(const multiset<Key, Compare, Alloc>& x,
                       const multiset<Key, Compare, Alloc>& y)
{
  return x.t == y.t;
}

template <class Key, class Compare, class Alloc>
inline bool operator<(const multiset<Key, Compare, Alloc>& x,
                      const multiset<Key, Compare, Alloc>& y)
{
  return x.t < y.t;
}

// 如果編譯器支援模板函式特化優先順序
// 那麼將全域性的swap實現為使用multiset私有的swap以提高效率
#ifdef __STL_FUNCTION_TMPL_PARTIAL_ORDER

template <class Key, class Compare, class Alloc>
inline void swap(multiset<Key, Compare, Alloc>& x,
                 multiset<Key, Compare, Alloc>& y)
{
  x.swap(y);
}

#endif /* __STL_FUNCTION_TMPL_PARTIAL_ORDER */

#if defined(__sgi) && !defined(__GNUC__) && (_MIPS_SIM != _MIPS_SIM_ABI32)
#pragma reset woff 1174
#endif

__STL_END_NAMESPACE

#endif /* __SGI_STL_INTERNAL_MULTISET_H */

// Local Variables:
// mode:C++
// End: