From: Jerry Quinn Date: Tue, 27 Jan 2004 02:58:06 +0000 (+0000) Subject: codecvt.h, [...]: Document. X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=ffcec5c8324a55d5d0a3e80c08abfcee7b24df87;p=gcc.git codecvt.h, [...]: Document. 2003-01-26 Jerry Quinn * include/bits/codecvt.h, include/bits/locale_facets.h, include/bits/postypes.h, include/bits/stl_bvector.h, include/bits/stl_multiset.h, include/bits/stl_set.h, include/bits/stream_iterator.h, include/bits/streambuf_iterator.h, include/std/std_complex.h: Document. From-SVN: r76688 --- diff --git a/libstdc++-v3/include/bits/codecvt.h b/libstdc++-v3/include/bits/codecvt.h index 80f9cba0b35..33d2b95e35e 100644 --- a/libstdc++-v3/include/bits/codecvt.h +++ b/libstdc++-v3/include/bits/codecvt.h @@ -1,6 +1,6 @@ // Locale support (codecvt) -*- C++ -*- -// Copyright (C) 2000, 2001, 2002, 2003 Free Software Foundation, Inc. +// Copyright (C) 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc. // // This file is part of the GNU ISO C++ Library. This library is free // software; you can redistribute it and/or modify it under the @@ -44,6 +44,7 @@ #pragma GCC system_header // 22.2.1.5 Template class codecvt + /// Base class for codecvt facet providing conversion result enum. class codecvt_base { public: @@ -60,6 +61,15 @@ // NB: An abstract base class that fills in the public inlines, so // that the specializations don't have to re-copy the public // interface. + /** + * @brief Common base for codecvt facet + * + * This template class provides implementations of the public functions + * that forward to the protected virtual functions. + * + * This template also provides abstract stubs for the protected virtual + * functions. + */ template class __codecvt_abstract_base : public locale::facet, public codecvt_base @@ -72,6 +82,41 @@ typedef _StateT state_type; // 22.2.1.5.1 codecvt members + /** + * @brief Convert from internal to external character set. + * + * Converts input string of intern_type to output string of + * extern_type. This is analogous to wcsrtombs. It does this by + * calling codecvt::do_out. + * + * The source and destination character sets are determined by the + * facet's locale, internal and external types. + * + * The characters in [from,from_end) are converted and written to + * [to,to_end). from_next and to_next are set to point to the + * character following the last successfully converted character, + * respectively. If the result needed no conversion, from_next and + * to_next are not affected. + * + * The @a state argument should be intialized if the input is at the + * beginning and carried from a previous call if continuing + * conversion. There are no guarantees about how @a state is used. + * + * The result returned is a member of codecvt_base::result. If all the + * input is converted, returns codecvt_base::ok. If no conversion is + * necessary, returns codecvt_base::noconv. If the input ends early or + * there is insufficient space in the output, returns codecvt_base::partial. + * Otherwise the conversion failed and codecvt_base::error is returned. + * + * @param state Persistent conversion state data. + * @param from Start of input. + * @param from_end End of input. + * @param from_next Returns start of unconverted data. + * @param to Start of output buffer. + * @param to_end End of output buffer. + * @param to_next Returns start of unused output area. + * @return codecvt_base::result. + */ result out(state_type& __state, const intern_type* __from, const intern_type* __from_end, const intern_type*& __from_next, @@ -82,11 +127,75 @@ __to, __to_end, __to_next); } + /** + * @brief Reset conversion state. + * + * Writes characters to output that would restore @a state to initial + * conditions. The idea is that if a partial conversion occurs, then + * the converting the characters written by this function would leave + * the state in initial conditions, rather than partial conversion + * state. It does this by calling codecvt::do_unshift(). + * + * For example, if 4 external characters always converted to 1 internal + * character, and input to in() had 6 external characters with state + * saved, this function would write two characters to the output and + * set the state to initialized conditions. + * + * The source and destination character sets are determined by the + * facet's locale, internal and external types. + * + * The result returned is a member of codecvt_base::result. If the + * state could be reset and data written, returns codecvt_base::ok. If + * no conversion is necessary, returns codecvt_base::noconv. If the + * output has insufficient space, returns codecvt_base::partial. + * Otherwise the reset failed and codecvt_base::error is returned. + * + * @param state Persistent conversion state data. + * @param to Start of output buffer. + * @param to_end End of output buffer. + * @param to_next Returns start of unused output area. + * @return codecvt_base::result. + */ result unshift(state_type& __state, extern_type* __to, extern_type* __to_end, extern_type*& __to_next) const { return this->do_unshift(__state, __to,__to_end,__to_next); } + /** + * @brief Convert from external to internal character set. + * + * Converts input string of extern_type to output string of + * intern_type. This is analogous to mbsrtowcs. It does this by + * calling codecvt::do_in. + * + * The source and destination character sets are determined by the + * facet's locale, internal and external types. + * + * The characters in [from,from_end) are converted and written to + * [to,to_end). from_next and to_next are set to point to the + * character following the last successfully converted character, + * respectively. If the result needed no conversion, from_next and + * to_next are not affected. + * + * The @a state argument should be intialized if the input is at the + * beginning and carried from a previous call if continuing + * conversion. There are no guarantees about how @a state is used. + * + * The result returned is a member of codecvt_base::result. If all the + * input is converted, returns codecvt_base::ok. If no conversion is + * necessary, returns codecvt_base::noconv. If the input ends early or + * there is insufficient space in the output, returns codecvt_base::partial. + * Otherwise the conversion failed and codecvt_base::error is returned. + * + * @param state Persistent conversion state data. + * @param from Start of input. + * @param from_end End of input. + * @param from_next Returns start of unconverted data. + * @param to Start of output buffer. + * @param to_end End of output buffer. + * @param to_next Returns start of unused output area. + * @return codecvt_base::result. + */ result in(state_type& __state, const extern_type* __from, const extern_type* __from_end, const extern_type*& __from_next, @@ -121,6 +230,13 @@ virtual ~__codecvt_abstract_base() { } + /** + * @brief Convert from internal to external character set. + * + * Converts input string of intern_type to output string of + * extern_type. This function is a hook for derived classes to change + * the value returned. @see out for more information. + */ virtual result do_out(state_type& __state, const intern_type* __from, const intern_type* __from_end, const intern_type*& __from_next, diff --git a/libstdc++-v3/include/bits/locale_facets.h b/libstdc++-v3/include/bits/locale_facets.h index 6f212fe08ae..3b1315d3f27 100644 --- a/libstdc++-v3/include/bits/locale_facets.h +++ b/libstdc++-v3/include/bits/locale_facets.h @@ -4462,6 +4462,8 @@ namespace std // NB: These are inline because, when used in a loop, some compilers // can hoist the body out of the loop; then it's just as fast as the // C is*() function. + //@{ + /// Convenience interface to ctype.is(). template inline bool isspace(_CharT __c, const locale& __loc) @@ -4525,6 +4527,7 @@ namespace std inline _CharT tolower(_CharT __c, const locale& __loc) { return use_facet >(__loc).tolower(__c); } + //@} } // namespace std #endif diff --git a/libstdc++-v3/include/bits/postypes.h b/libstdc++-v3/include/bits/postypes.h index c9b46b1d171..cd0594c45c2 100644 --- a/libstdc++-v3/include/bits/postypes.h +++ b/libstdc++-v3/include/bits/postypes.h @@ -1,6 +1,6 @@ // Position types -*- C++ -*- -// Copyright (C) 1997, 1998, 1999, 2000, 2001, 2003 +// Copyright (C) 1997, 1998, 1999, 2000, 2001, 2003, 2004 // Free Software Foundation, Inc. // // This file is part of the GNU ISO C++ Library. This library is free @@ -64,6 +64,7 @@ namespace std typedef long long __streamoff_base_type; #endif + /// Integral type for I/O operation counts and buffer sizes. typedef ptrdiff_t streamsize; // Signed integral type template @@ -127,19 +128,30 @@ namespace std } }; - // In clauses 21.1.3.1 and 27.4.1 streamoff is described as an - // implementation defined type. In this implementation it is a - // distinct class type. - // Note: In versions of GCC up to and including GCC 3.3, streamoff - // was typedef long. + /** + * @brief Type used by fpos, char_traits, and char_traits. + * + * @if maint + * In clauses 21.1.3.1 and 27.4.1 streamoff is described as an + * implementation defined type. In this implementation it is a + * distinct class type. + * Note: In versions of GCC up to and including GCC 3.3, streamoff + * was typedef long. + * @endif + */ typedef class streamoff streamoff; - // The standard fails to place any requiremens on the template - // argument StateT. In this implementation StateT must be - // DefaultConstructible, CopyConstructible and Assignable. The - // standard only requires that fpos should contain a member of type - // StateT. In this implementation it also contains an offset stored - // as a signed integer. + /** + * @brief Class representing stream positions. + * + * The standard places no requirements upon the template parameter StateT. + * In this implementation StateT must be DefaultConstructible, + * CopyConstructible and Assignable. The standard only requires that fpos + * should contain a member of type StateT. In this implementation it also + * contains an offset stored as a signed integer. + * + * @param StateT Type passed to and returned from state(). + */ template class fpos { @@ -161,6 +173,7 @@ namespace std // fpos, but gives no meaningful semantics for this // conversion. In this implementation this constructor stores // the integer as the offset and default constructs the state. + /// Construct position from integer. fpos(__streamoff_base_type __off) : _M_off(__off), _M_state() { } @@ -170,13 +183,16 @@ namespace std // implementation implicit conversion is also allowed, and this // constructor stores the streamoff as the offset and default // constructs the state. + /// Construct position from offset. fpos(const streamoff& __off) : _M_off(__off), _M_state() { } + /// Remember the value of @a st. void state(_StateT __st) { _M_state = __st; } + /// Return the last set value of @a st. _StateT state() const { return _M_state; } @@ -185,10 +201,12 @@ namespace std // equivalence relation. In this implementation two fpos // objects belong to the same equivalence class if the contained // offsets compare equal. + /// Test if equivalent to another position. bool operator==(const fpos& __other) const { return _M_off == __other._M_off; } + /// Test if not equivalent to another position. bool operator!=(const fpos& __other) const { return _M_off != __other._M_off; } @@ -196,6 +214,7 @@ namespace std // The standard requires that this operator must be defined, but // gives no semantics. In this implemenation it just adds it's // argument to the stored offset and returns *this. + /// Add offset to this position. fpos& operator+=(const streamoff& __off) { @@ -206,6 +225,7 @@ namespace std // The standard requires that this operator must be defined, but // gives no semantics. In this implemenation it just subtracts // it's argument from the stored offset and returns *this. + /// Subtract offset from this position. fpos& operator-=(const streamoff& __off) { @@ -218,6 +238,7 @@ namespace std // implementation it constructs a copy of *this, adds the // argument to that copy using operator+= and then returns the // copy. + /// Add position and offset. fpos operator+(const streamoff& __off) const { @@ -231,6 +252,7 @@ namespace std // implementation it constructs a copy of *this, subtracts the // argument from that copy using operator-= and then returns the // copy. + /// Subtract offset from position. fpos operator-(const streamoff& __off) const { @@ -243,11 +265,13 @@ namespace std // defines it's semantics only in terms of operator+. In this // implementation it returns the difference between the offset // stored in *this and in the argument. + /// Subtract position to return offset. streamoff operator-(const fpos& __other) const { return _M_off - __other._M_off; } }; + /// Construct offset from position. template inline streamoff::streamoff(const fpos<_StateT>& __pos) @@ -256,7 +280,9 @@ namespace std // Clauses 21.1.3.1 and 21.1.3.2 describe streampos and wstreampos // as implementation defined types, but clause 27.2 requires that // they must both be typedefs for fpos + /// File position for char streams. typedef fpos streampos; + /// File position for wchar_t streams. typedef fpos wstreampos; } // namespace std diff --git a/libstdc++-v3/include/bits/stl_bvector.h b/libstdc++-v3/include/bits/stl_bvector.h index 884256151f4..34b1a87ad5d 100644 --- a/libstdc++-v3/include/bits/stl_bvector.h +++ b/libstdc++-v3/include/bits/stl_bvector.h @@ -1,6 +1,6 @@ // bit_vector and vector specialization -*- C++ -*- -// Copyright (C) 2001, 2002, 2003 Free Software Foundation, Inc. +// Copyright (C) 2001, 2002, 2003, 2004 Free Software Foundation, Inc. // // This file is part of the GNU ISO C++ Library. This library is free // software; you can redistribute it and/or modify it under the @@ -296,6 +296,24 @@ protected: #include namespace __gnu_norm { + + /** + * @brief A specialization of vector for booleans which offers fixed time + * access to individual elements in any order. + * + * Note that vector does not actually meet the requirements for being + * a container. This is because the reference and pointer types are not + * really references and pointers to bool. See DR96 for details. @see + * vector for function documentation. + * + * @ingroup Containers + * @ingroup Sequences + * + * In some terminology a %vector can be described as a dynamic C-style array, + * it offers fast and efficient access to individual elements in any order + * and saves the user from worrying about memory and size allocation. + * Subscripting ( @c [] ) access is also provided as with C-style arrays. + */ template class vector : public _Bvector_base<_Alloc> { diff --git a/libstdc++-v3/include/bits/stl_multiset.h b/libstdc++-v3/include/bits/stl_multiset.h index 515ef5c040e..2cd26d072e8 100644 --- a/libstdc++-v3/include/bits/stl_multiset.h +++ b/libstdc++-v3/include/bits/stl_multiset.h @@ -1,6 +1,6 @@ // Multiset implementation -*- C++ -*- -// Copyright (C) 2001, 2002 Free Software Foundation, Inc. +// Copyright (C) 2001, 2002, 2004 Free Software Foundation, Inc. // // This file is part of the GNU ISO C++ Library. This library is free // software; you can redistribute it and/or modify it under the @@ -80,181 +80,451 @@ template inline bool operator<(const multiset<_Key,_Compare,_Alloc>& __x, const multiset<_Key,_Compare,_Alloc>& __y); -template -class multiset -{ - // concept requirements - __glibcxx_class_requires(_Key, _SGIAssignableConcept) - __glibcxx_class_requires4(_Compare, bool, _Key, _Key, _BinaryFunctionConcept) - -public: - - // typedefs: - - typedef _Key key_type; - typedef _Key value_type; - typedef _Compare key_compare; - typedef _Compare value_compare; -private: - typedef _Rb_tree, key_compare, _Alloc> _Rep_type; - _Rep_type _M_t; // red-black tree representing multiset -public: - typedef typename _Alloc::pointer pointer; - typedef typename _Alloc::const_pointer const_pointer; - typedef typename _Alloc::reference reference; - typedef typename _Alloc::const_reference const_reference; - typedef typename _Rep_type::const_iterator iterator; - 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; - typedef typename _Rep_type::allocator_type allocator_type; - - // allocation/deallocation - - multiset() : _M_t(_Compare(), allocator_type()) {} - explicit multiset(const _Compare& __comp, - const allocator_type& __a = allocator_type()) - : _M_t(__comp, __a) {} - - template - multiset(_InputIterator __first, _InputIterator __last) - : _M_t(_Compare(), allocator_type()) + /** + * @brief A standard container made up of elements, which can be retrieved + * in logarithmic time. + * + * @ingroup Containers + * @ingroup Assoc_containers + * + * Meets the requirements of a container, a + * reversible container, and an + * associative container (using equivalent + * keys). For a @c multiset the key_type and value_type are Key. + * + * Multisets support bidirectional iterators. + * + * @if maint + * The private tree data is declared exactly the same way for set and + * multiset; the distinction is made entirely in how the tree functions are + * called (*_unique versus *_equal, same as the standard). + * @endif + */ + template + class multiset + { + // concept requirements + __glibcxx_class_requires(_Key, _SGIAssignableConcept) + __glibcxx_class_requires4(_Compare, bool, _Key, _Key, _BinaryFunctionConcept) + + public: + + // typedefs: + + typedef _Key key_type; + typedef _Key value_type; + typedef _Compare key_compare; + typedef _Compare value_compare; + + private: + /// @if maint This turns a red-black tree into a [multi]set. @endif + typedef _Rb_tree, key_compare, _Alloc> _Rep_type; + /// @if maint The actual tree structure. @endif + _Rep_type _M_t; + + public: + typedef typename _Alloc::pointer pointer; + typedef typename _Alloc::const_pointer const_pointer; + typedef typename _Alloc::reference reference; + typedef typename _Alloc::const_reference const_reference; + typedef typename _Rep_type::const_iterator iterator; + 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; + typedef typename _Rep_type::allocator_type allocator_type; + + // allocation/deallocation + + /** + * @brief Default constructor creates no elements. + */ + multiset() : _M_t(_Compare(), allocator_type()) {} + explicit multiset(const _Compare& __comp, + const allocator_type& __a = allocator_type()) + : _M_t(__comp, __a) {} + + /** + * @brief Builds a %multiset from a range. + * @param first An input iterator. + * @param last An input iterator. + * + * Create a %multiset consisting of copies of the elements from + * [first,last). This is linear in N if the range is already sorted, + * and NlogN otherwise (where N is distance(first,last)). + */ + template + multiset(_InputIterator __first, _InputIterator __last) + : _M_t(_Compare(), allocator_type()) { _M_t.insert_equal(__first, __last); } - template - multiset(_InputIterator __first, _InputIterator __last, - const _Compare& __comp, - const allocator_type& __a = allocator_type()) - : _M_t(__comp, __a) { _M_t.insert_equal(__first, __last); } - - multiset(const multiset<_Key,_Compare,_Alloc>& __x) : _M_t(__x._M_t) {} - - multiset<_Key,_Compare,_Alloc>& - operator=(const multiset<_Key,_Compare,_Alloc>& __x) { - _M_t = __x._M_t; - return *this; - } - - // accessors: - - key_compare key_comp() const { return _M_t.key_comp(); } - value_compare value_comp() const { return _M_t.key_comp(); } - allocator_type get_allocator() const { return _M_t.get_allocator(); } - - iterator begin() const { return _M_t.begin(); } - iterator end() const { return _M_t.end(); } - reverse_iterator rbegin() const { return _M_t.rbegin(); } - reverse_iterator rend() const { return _M_t.rend(); } - bool empty() const { return _M_t.empty(); } - size_type size() const { return _M_t.size(); } - size_type max_size() const { return _M_t.max_size(); } - void swap(multiset<_Key,_Compare,_Alloc>& __x) { _M_t.swap(__x._M_t); } - - // insert/erase - iterator insert(const value_type& __x) { - return _M_t.insert_equal(__x); - } - iterator insert(iterator __position, const value_type& __x) { - typedef typename _Rep_type::iterator _Rep_iterator; - return _M_t.insert_equal((_Rep_iterator&)__position, __x); - } - - template - void insert(_InputIterator __first, _InputIterator __last) { - _M_t.insert_equal(__first, __last); - } - void erase(iterator __position) { - typedef typename _Rep_type::iterator _Rep_iterator; - _M_t.erase((_Rep_iterator&)__position); - } - size_type erase(const key_type& __x) { - return _M_t.erase(__x); - } - void erase(iterator __first, iterator __last) { - typedef typename _Rep_type::iterator _Rep_iterator; - _M_t.erase((_Rep_iterator&)__first, (_Rep_iterator&)__last); - } - void clear() { _M_t.clear(); } - - // multiset operations: - - size_type count(const key_type& __x) const { return _M_t.count(__x); } - - // _GLIBCXX_RESOLVE_LIB_DEFECTS - // 214. set::find() missing const overload - iterator find(const key_type& __x) { return _M_t.find(__x); } - const_iterator find(const key_type& __x) const { return _M_t.find(__x); } - iterator lower_bound(const key_type& __x) { - return _M_t.lower_bound(__x); - } - const_iterator lower_bound(const key_type& __x) const { - return _M_t.lower_bound(__x); - } - iterator upper_bound(const key_type& __x) { - return _M_t.upper_bound(__x); - } - const_iterator upper_bound(const key_type& __x) const { - return _M_t.upper_bound(__x); - } - pair equal_range(const key_type& __x) { - return _M_t.equal_range(__x); - } - pair equal_range(const key_type& __x) const { - return _M_t.equal_range(__x); - } - - template - friend bool operator== (const multiset<_K1,_C1,_A1>&, - const multiset<_K1,_C1,_A1>&); - template - friend bool operator< (const multiset<_K1,_C1,_A1>&, - const multiset<_K1,_C1,_A1>&); -}; - -template -inline bool operator==(const multiset<_Key,_Compare,_Alloc>& __x, - const multiset<_Key,_Compare,_Alloc>& __y) { - return __x._M_t == __y._M_t; -} - -template -inline bool operator<(const multiset<_Key,_Compare,_Alloc>& __x, - const multiset<_Key,_Compare,_Alloc>& __y) { - return __x._M_t < __y._M_t; -} - -template -inline bool operator!=(const multiset<_Key,_Compare,_Alloc>& __x, - const multiset<_Key,_Compare,_Alloc>& __y) { - return !(__x == __y); -} - -template -inline bool operator>(const multiset<_Key,_Compare,_Alloc>& __x, - const multiset<_Key,_Compare,_Alloc>& __y) { - return __y < __x; -} - -template -inline bool operator<=(const multiset<_Key,_Compare,_Alloc>& __x, - const multiset<_Key,_Compare,_Alloc>& __y) { - return !(__y < __x); -} - -template -inline bool operator>=(const multiset<_Key,_Compare,_Alloc>& __x, - const multiset<_Key,_Compare,_Alloc>& __y) { - return !(__x < __y); -} - -template -inline void swap(multiset<_Key,_Compare,_Alloc>& __x, - multiset<_Key,_Compare,_Alloc>& __y) { - __x.swap(__y); -} + /** + * @brief Builds a %multiset from a range. + * @param first An input iterator. + * @param last An input iterator. + * @param comp A comparison functor. + * @param a An allocator object. + * + * Create a %multiset consisting of copies of the elements from + * [first,last). This is linear in N if the range is already sorted, + * and NlogN otherwise (where N is distance(first,last)). + */ + template + multiset(_InputIterator __first, _InputIterator __last, + const _Compare& __comp, + const allocator_type& __a = allocator_type()) + : _M_t(__comp, __a) { _M_t.insert_equal(__first, __last); } + + /** + * @brief %Multiset copy constructor. + * @param x A %multiset of identical element and allocator types. + * + * The newly-created %multiset uses a copy of the allocation object used + * by @a x. + */ + multiset(const multiset<_Key,_Compare,_Alloc>& __x) : _M_t(__x._M_t) {} + + /** + * @brief %Multiset assignment operator. + * @param x A %multiset of identical element and allocator types. + * + * All the elements of @a x are copied, but unlike the copy constructor, + * the allocator object is not copied. + */ + multiset<_Key,_Compare,_Alloc>& + operator=(const multiset<_Key,_Compare,_Alloc>& __x) { + _M_t = __x._M_t; + return *this; + } + + // accessors: + + /// Returns the comparison object. + key_compare key_comp() const { return _M_t.key_comp(); } + /// Returns the comparison object. + value_compare value_comp() const { return _M_t.key_comp(); } + /// Returns the memory allocation object. + allocator_type get_allocator() const { return _M_t.get_allocator(); } + + /** + * Returns a read/write iterator that points to the first element in the + * %multiset. Iteration is done in ascending order according to the + * keys. + */ + iterator begin() const { return _M_t.begin(); } + + /** + * Returns a read/write iterator that points one past the last element in + * the %multiset. Iteration is done in ascending order according to the + * keys. + */ + iterator end() const { return _M_t.end(); } + + /** + * Returns a read/write reverse iterator that points to the last element + * in the %multiset. Iteration is done in descending order according to + * the keys. + */ + reverse_iterator rbegin() const { return _M_t.rbegin(); } + + /** + * Returns a read/write reverse iterator that points to the last element + * in the %multiset. Iteration is done in descending order according to + * the keys. + */ + reverse_iterator rend() const { return _M_t.rend(); } + + /// Returns true if the %set is empty. + bool empty() const { return _M_t.empty(); } + + /// Returns the size of the %set. + size_type size() const { return _M_t.size(); } + + /// Returns the maximum size of the %set. + size_type max_size() const { return _M_t.max_size(); } + + /** + * @brief Swaps data with another %multiset. + * @param x A %multiset of the same element and allocator types. + * + * This exchanges the elements between two multisets in constant time. + * (It is only swapping a pointer, an integer, and an instance of the @c + * Compare type (which itself is often stateless and empty), so it should + * be quite fast.) + * Note that the global std::swap() function is specialized such that + * std::swap(s1,s2) will feed to this function. + */ + void swap(multiset<_Key,_Compare,_Alloc>& __x) { _M_t.swap(__x._M_t); } + + // insert/erase + /** + * @brief Inserts an element into the %multiset. + * @param x Element to be inserted. + * @return An iterator that points to the inserted element. + * + * This function inserts an element into the %multiset. Contrary + * to a std::set the %multiset does not rely on unique keys and thus + * multiple copies of the same element can be inserted. + * + * Insertion requires logarithmic time. + */ + iterator insert(const value_type& __x) { + return _M_t.insert_equal(__x); + } + + /** + * @brief Inserts an element into the %multiset. + * @param position An iterator that serves as a hint as to where the + * element should be inserted. + * @param x Element to be inserted. + * @return An iterator that points to the inserted element. + * + * This function inserts an element into the %multiset. Contrary + * to a std::set the %multiset does not rely on unique keys and thus + * multiple copies of the same element can be inserted. + * + * Note that the first parameter is only a hint and can potentially + * improve the performance of the insertion process. A bad hint would + * cause no gains in efficiency. + * + * See http://gcc.gnu.org/onlinedocs/libstdc++/23_containers/howto.html#4 + * for more on "hinting". + * + * Insertion requires logarithmic time (if the hint is not taken). + */ + iterator insert(iterator __position, const value_type& __x) { + typedef typename _Rep_type::iterator _Rep_iterator; + return _M_t.insert_equal((_Rep_iterator&)__position, __x); + } + + /** + * @brief A template function that attemps to insert a range of elements. + * @param first Iterator pointing to the start of the range to be + * inserted. + * @param last Iterator pointing to the end of the range. + * + * Complexity similar to that of the range constructor. + */ + template + void insert(_InputIterator __first, _InputIterator __last) { + _M_t.insert_equal(__first, __last); + } + + /** + * @brief Erases an element from a %multiset. + * @param position An iterator pointing to the element to be erased. + * + * This function erases an element, pointed to by the given iterator, + * from a %multiset. Note that this function only erases the element, + * and that if the element is itself a pointer, the pointed-to memory is + * not touched in any way. Managing the pointer is the user's + * responsibilty. + */ + void erase(iterator __position) { + typedef typename _Rep_type::iterator _Rep_iterator; + _M_t.erase((_Rep_iterator&)__position); + } + + /** + * @brief Erases elements according to the provided key. + * @param x Key of element to be erased. + * @return The number of elements erased. + * + * This function erases all elements located by the given key from a + * %multiset. + * Note that this function only erases the element, and that if + * the element is itself a pointer, the pointed-to memory is not touched + * in any way. Managing the pointer is the user's responsibilty. + */ + size_type erase(const key_type& __x) { + return _M_t.erase(__x); + } + + /** + * @brief Erases a [first,last) range of elements from a %multiset. + * @param first Iterator pointing to the start of the range to be erased. + * @param last Iterator pointing to the end of the range to be erased. + * + * This function erases a sequence of elements from a %multiset. + * Note that this function only erases the elements, and that if + * the elements themselves are pointers, the pointed-to memory is not + * touched in any way. Managing the pointer is the user's responsibilty. + */ + void erase(iterator __first, iterator __last) { + typedef typename _Rep_type::iterator _Rep_iterator; + _M_t.erase((_Rep_iterator&)__first, (_Rep_iterator&)__last); + } + + /** + * Erases all elements in a %multiset. Note that this function only + * erases the elements, and that if the elements themselves are pointers, + * the pointed-to memory is not touched in any way. Managing the pointer + * is the user's responsibilty. + */ + void clear() { _M_t.clear(); } + + // multiset operations: + + /** + * @brief Finds the number of elements with given key. + * @param x Key of elements to be located. + * @return Number of elements with specified key. + */ + size_type count(const key_type& __x) const { return _M_t.count(__x); } + + // _GLIBCXX_RESOLVE_LIB_DEFECTS + // 214. set::find() missing const overload + //@{ + /** + * @brief Tries to locate an element in a %set. + * @param x Element to be located. + * @return Iterator pointing to sought-after element, or end() if not + * found. + * + * This function takes a key and tries to locate the element with which + * the key matches. If successful the function returns an iterator + * pointing to the sought after element. If unsuccessful it returns the + * past-the-end ( @c end() ) iterator. + */ + iterator find(const key_type& __x) { return _M_t.find(__x); } + const_iterator find(const key_type& __x) const { return _M_t.find(__x); } + //@} + + //@{ + /** + * @brief Finds the beginning of a subsequence matching given key. + * @param x Key to be located. + * @return Iterator pointing to first element equal to or greater + * than key, or end(). + * + * This function returns the first element of a subsequence of elements + * that matches the given key. If unsuccessful it returns an iterator + * pointing to the first element that has a greater value than given key + * or end() if no such element exists. + */ + iterator lower_bound(const key_type& __x) { + return _M_t.lower_bound(__x); + } + const_iterator lower_bound(const key_type& __x) const { + return _M_t.lower_bound(__x); + } + //@} + + //@{ + /** + * @brief Finds the end of a subsequence matching given key. + * @param x Key to be located. + * @return Iterator pointing to the first element + * greater than key, or end(). + */ + iterator upper_bound(const key_type& __x) { + return _M_t.upper_bound(__x); + } + const_iterator upper_bound(const key_type& __x) const { + return _M_t.upper_bound(__x); + } + //@} + + //@{ + /** + * @brief Finds a subsequence matching given key. + * @param x Key to be located. + * @return Pair of iterators that possibly points to the subsequence + * matching given key. + * + * This function is equivalent to + * @code + * std::make_pair(c.lower_bound(val), + * c.upper_bound(val)) + * @endcode + * (but is faster than making the calls separately). + * + * This function probably only makes sense for multisets. + */ + pair equal_range(const key_type& __x) { + return _M_t.equal_range(__x); + } + pair equal_range(const key_type& __x) const { + return _M_t.equal_range(__x); + } + + template + friend bool operator== (const multiset<_K1,_C1,_A1>&, + const multiset<_K1,_C1,_A1>&); + template + friend bool operator< (const multiset<_K1,_C1,_A1>&, + const multiset<_K1,_C1,_A1>&); + }; + + /** + * @brief Multiset equality comparison. + * @param x A %multiset. + * @param y A %multiset of the same type as @a x. + * @return True iff the size and elements of the multisets are equal. + * + * This is an equivalence relation. It is linear in the size of the multisets. + * Multisets are considered equivalent if their sizes are equal, and if + * corresponding elements compare equal. + */ + template + inline bool + operator==(const multiset<_Key,_Compare,_Alloc>& __x, + const multiset<_Key,_Compare,_Alloc>& __y) + { return __x._M_t == __y._M_t; } + + /** + * @brief Multiset ordering relation. + * @param x A %multiset. + * @param y A %multiset of the same type as @a x. + * @return True iff @a x is lexicographically less than @a y. + * + * This is a total ordering relation. It is linear in the size of the + * maps. The elements must be comparable with @c <. + * + * See std::lexicographical_compare() for how the determination is made. + */ + template + inline bool + operator<(const multiset<_Key,_Compare,_Alloc>& __x, + const multiset<_Key,_Compare,_Alloc>& __y) + { return __x._M_t < __y._M_t; } + + /// Returns !(x == y). + template + inline bool + operator!=(const multiset<_Key,_Compare,_Alloc>& __x, + const multiset<_Key,_Compare,_Alloc>& __y) + { return !(__x == __y); } + + /// Returns y < x. + template + inline bool + operator>(const multiset<_Key,_Compare,_Alloc>& __x, + const multiset<_Key,_Compare,_Alloc>& __y) + { return __y < __x; } + + /// Returns !(y < x) + template + inline bool + operator<=(const multiset<_Key,_Compare,_Alloc>& __x, + const multiset<_Key,_Compare,_Alloc>& __y) + { return !(__y < __x); } + + /// Returns !(x < y) + template + inline bool + operator>=(const multiset<_Key,_Compare,_Alloc>& __x, + const multiset<_Key,_Compare,_Alloc>& __y) + { return !(__x < __y); } + + /// See std::multiset::swap(). + template + inline void + swap(multiset<_Key,_Compare,_Alloc>& __x, + multiset<_Key,_Compare,_Alloc>& __y) + { __x.swap(__y); } } // namespace __gnu_norm diff --git a/libstdc++-v3/include/bits/stl_set.h b/libstdc++-v3/include/bits/stl_set.h index 285d5ee2a85..a3f5472df7c 100644 --- a/libstdc++-v3/include/bits/stl_set.h +++ b/libstdc++-v3/include/bits/stl_set.h @@ -1,6 +1,6 @@ // Set implementation -*- C++ -*- -// Copyright (C) 2001, 2002 Free Software Foundation, Inc. +// Copyright (C) 2001, 2002, 2004 Free Software Foundation, Inc. // // This file is part of the GNU ISO C++ Library. This library is free // software; you can redistribute it and/or modify it under the @@ -80,6 +80,29 @@ namespace __gnu_norm operator<(const set<_Key,_Compare,_Alloc>& __x, const set<_Key,_Compare,_Alloc>& __y); + /** + * @brief A standard container made up of unique keys, which can be + * retrieved in logarithmic time. + * + * @ingroup Containers + * @ingroup Assoc_containers + * + * Meets the requirements of a container, a + * reversible container, and an + * associative container (using unique keys). + * + * Sets support bidirectional iterators. + * + * @param Key Type of key objects. + * @param Compare Comparison function object type, defaults to less. + * @param Alloc Allocator type, defaults to allocator. + * + * @if maint + * The private tree data is declared exactly the same way for set and + * multiset; the distinction is made entirely in how the tree functions are + * called (*_unique versus *_equal, same as the standard). + * @endif + */ template class set { @@ -89,168 +112,424 @@ namespace __gnu_norm public: // typedefs: + //@{ + /// Public typedefs. typedef _Key key_type; typedef _Key value_type; typedef _Compare key_compare; typedef _Compare value_compare; -private: - typedef _Rb_tree, key_compare, _Alloc> _Rep_type; - _Rep_type _M_t; // red-black tree representing set -public: - typedef typename _Alloc::pointer pointer; - typedef typename _Alloc::const_pointer const_pointer; - typedef typename _Alloc::reference reference; - typedef typename _Alloc::const_reference const_reference; - typedef typename _Rep_type::const_iterator iterator; - 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; - typedef typename _Rep_type::allocator_type allocator_type; - - // allocation/deallocation - - set() : _M_t(_Compare(), allocator_type()) {} - explicit set(const _Compare& __comp, - const allocator_type& __a = allocator_type()) - : _M_t(__comp, __a) {} - - template - set(_InputIterator __first, _InputIterator __last) - : _M_t(_Compare(), allocator_type()) - { _M_t.insert_unique(__first, __last); } - - template - set(_InputIterator __first, _InputIterator __last, const _Compare& __comp, - const allocator_type& __a = allocator_type()) - : _M_t(__comp, __a) { _M_t.insert_unique(__first, __last); } - - set(const set<_Key,_Compare,_Alloc>& __x) : _M_t(__x._M_t) {} - set<_Key,_Compare,_Alloc>& operator=(const set<_Key, _Compare, _Alloc>& __x) - { - _M_t = __x._M_t; - return *this; - } - - // accessors: - - key_compare key_comp() const { return _M_t.key_comp(); } - value_compare value_comp() const { return _M_t.key_comp(); } - allocator_type get_allocator() const { return _M_t.get_allocator(); } - - iterator begin() const { return _M_t.begin(); } - iterator end() const { return _M_t.end(); } - reverse_iterator rbegin() const { return _M_t.rbegin(); } - reverse_iterator rend() const { return _M_t.rend(); } - bool empty() const { return _M_t.empty(); } - size_type size() const { return _M_t.size(); } - size_type max_size() const { return _M_t.max_size(); } - void swap(set<_Key,_Compare,_Alloc>& __x) { _M_t.swap(__x._M_t); } - - // insert/erase - pair insert(const value_type& __x) { - pair __p = _M_t.insert_unique(__x); - return pair(__p.first, __p.second); - } - iterator insert(iterator __position, const value_type& __x) { - typedef typename _Rep_type::iterator _Rep_iterator; - return _M_t.insert_unique((_Rep_iterator&)__position, __x); - } - template - void insert(_InputIterator __first, _InputIterator __last) { - _M_t.insert_unique(__first, __last); - } - void erase(iterator __position) { - typedef typename _Rep_type::iterator _Rep_iterator; - _M_t.erase((_Rep_iterator&)__position); - } - size_type erase(const key_type& __x) { - return _M_t.erase(__x); - } - void erase(iterator __first, iterator __last) { - typedef typename _Rep_type::iterator _Rep_iterator; - _M_t.erase((_Rep_iterator&)__first, (_Rep_iterator&)__last); - } - void clear() { _M_t.clear(); } - - // set operations: - - size_type count(const key_type& __x) const { - return _M_t.find(__x) == _M_t.end() ? 0 : 1; - } - - // _GLIBCXX_RESOLVE_LIB_DEFECTS - // 214. set::find() missing const overload - iterator find(const key_type& __x) { return _M_t.find(__x); } - const_iterator find(const key_type& __x) const { return _M_t.find(__x); } - iterator lower_bound(const key_type& __x) { - return _M_t.lower_bound(__x); - } - const_iterator lower_bound(const key_type& __x) const { - return _M_t.lower_bound(__x); - } - iterator upper_bound(const key_type& __x) { - return _M_t.upper_bound(__x); - } - const_iterator upper_bound(const key_type& __x) const { - return _M_t.upper_bound(__x); - } - pair equal_range(const key_type& __x) { - return _M_t.equal_range(__x); - } - pair equal_range(const key_type& __x) const { - return _M_t.equal_range(__x); - } - - template - friend bool operator== (const set<_K1,_C1,_A1>&, const set<_K1,_C1,_A1>&); - template - friend bool operator< (const set<_K1,_C1,_A1>&, const set<_K1,_C1,_A1>&); -}; - -template -inline bool operator==(const set<_Key,_Compare,_Alloc>& __x, - const set<_Key,_Compare,_Alloc>& __y) { - return __x._M_t == __y._M_t; -} - -template -inline bool operator<(const set<_Key,_Compare,_Alloc>& __x, - const set<_Key,_Compare,_Alloc>& __y) { - return __x._M_t < __y._M_t; -} - -template -inline bool operator!=(const set<_Key,_Compare,_Alloc>& __x, - const set<_Key,_Compare,_Alloc>& __y) { - return !(__x == __y); -} - -template -inline bool operator>(const set<_Key,_Compare,_Alloc>& __x, - const set<_Key,_Compare,_Alloc>& __y) { - return __y < __x; -} - -template -inline bool operator<=(const set<_Key,_Compare,_Alloc>& __x, - const set<_Key,_Compare,_Alloc>& __y) { - return !(__y < __x); -} - -template -inline bool operator>=(const set<_Key,_Compare,_Alloc>& __x, - const set<_Key,_Compare,_Alloc>& __y) { - return !(__x < __y); -} - -template -inline void swap(set<_Key,_Compare,_Alloc>& __x, - set<_Key,_Compare,_Alloc>& __y) { - __x.swap(__y); -} + //@} + + private: + typedef _Rb_tree, key_compare, _Alloc> _Rep_type; + _Rep_type _M_t; // red-black tree representing set + public: + //@{ + /// Iterator-related typedefs. + typedef typename _Alloc::pointer pointer; + typedef typename _Alloc::const_pointer const_pointer; + typedef typename _Alloc::reference reference; + typedef typename _Alloc::const_reference const_reference; + typedef typename _Rep_type::const_iterator iterator; + 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; + typedef typename _Rep_type::allocator_type allocator_type; + //@} + + // allocation/deallocation + /// Default constructor creates no elements. + set() : _M_t(_Compare(), allocator_type()) {} + + /** + * @brief Default constructor creates no elements. + * + * @param comp Comparator to use. + * @param a Allocator to use. + */ + explicit set(const _Compare& __comp, + const allocator_type& __a = allocator_type()) + : _M_t(__comp, __a) {} + + /** + * @brief Builds a %set from a range. + * @param first An input iterator. + * @param last An input iterator. + * + * Create a %set consisting of copies of the elements from [first,last). + * This is linear in N if the range is already sorted, and NlogN + * otherwise (where N is distance(first,last)). + */ + template + set(_InputIterator __first, _InputIterator __last) + : _M_t(_Compare(), allocator_type()) + { _M_t.insert_unique(__first, __last); } + + /** + * @brief Builds a %set from a range. + * @param first An input iterator. + * @param last An input iterator. + * @param comp A comparison functor. + * @param a An allocator object. + * + * Create a %set consisting of copies of the elements from [first,last). + * This is linear in N if the range is already sorted, and NlogN + * otherwise (where N is distance(first,last)). + */ + template + set(_InputIterator __first, _InputIterator __last, const _Compare& __comp, + const allocator_type& __a = allocator_type()) + : _M_t(__comp, __a) + { _M_t.insert_unique(__first, __last); } + + /** + * @brief Set copy constructor. + * @param x A %set of identical element and allocator types. + * + * The newly-created %set uses a copy of the allocation object used + * by @a x. + */ + set(const set<_Key,_Compare,_Alloc>& __x) : _M_t(__x._M_t) {} + + /** + * @brief Set assignment operator. + * @param x A %set of identical element and allocator types. + * + * All the elements of @a x are copied, but unlike the copy constructor, + * the allocator object is not copied. + */ + set<_Key,_Compare,_Alloc>& operator=(const set<_Key, _Compare, _Alloc>& __x) + { + _M_t = __x._M_t; + return *this; + } + + // accessors: + + /// Returns the comparison object with which the %set was constructed. + key_compare key_comp() const { return _M_t.key_comp(); } + /// Returns the comparison object with which the %set was constructed. + value_compare value_comp() const { return _M_t.key_comp(); } + /// Returns the allocator object with which the %set was constructed. + allocator_type get_allocator() const { return _M_t.get_allocator(); } + + /** + * Returns a read/write iterator that points to the first element in the + * %set. Iteration is done in ascending order according to the keys. + */ + iterator begin() const { return _M_t.begin(); } + + /** + * Returns a read/write iterator that points one past the last element in + * the %set. Iteration is done in ascending order according to the keys. + */ + iterator end() const { return _M_t.end(); } + + /** + * Returns a read/write reverse iterator that points to the last element in + * the %set. Iteration is done in descending order according to the keys. + */ + reverse_iterator rbegin() const { return _M_t.rbegin(); } + + /** + * Returns a read-only (constant) reverse iterator that points to the last + * pair in the %map. Iteration is done in descending order according to + * the keys. + */ + reverse_iterator rend() const { return _M_t.rend(); } + + /// Returns true if the %set is empty. + bool empty() const { return _M_t.empty(); } + + /// Returns the size of the %set. + size_type size() const { return _M_t.size(); } + + /// Returns the maximum size of the %set. + size_type max_size() const { return _M_t.max_size(); } + + /** + * @brief Swaps data with another %set. + * @param x A %set of the same element and allocator types. + * + * This exchanges the elements between two sets in constant time. + * (It is only swapping a pointer, an integer, and an instance of + * the @c Compare type (which itself is often stateless and empty), so it + * should be quite fast.) + * Note that the global std::swap() function is specialized such that + * std::swap(s1,s2) will feed to this function. + */ + void swap(set<_Key,_Compare,_Alloc>& __x) { _M_t.swap(__x._M_t); } + + // insert/erase + /** + * @brief Attempts to insert an element into the %set. + * @param x Element to be inserted. + * @return A pair, of which the first element is an iterator that points + * to the possibly inserted element, and the second is a bool that + * is true if the element was actually inserted. + * + * This function attempts to insert an element into the %set. A %set + * relies on unique keys and thus an element is only inserted if it is + * not already present in the %set. + * + * Insertion requires logarithmic time. + */ + pair insert(const value_type& __x) + { + pair __p = _M_t.insert_unique(__x); + return pair(__p.first, __p.second); + } + + /** + * @brief Attempts to insert an element into the %set. + * @param position An iterator that serves as a hint as to where the + * element should be inserted. + * @param x Element to be inserted. + * @return An iterator that points to the element with key of @a x (may + * or may not be the element passed in). + * + * This function is not concerned about whether the insertion took place, + * and thus does not return a boolean like the single-argument insert() + * does. Note that the first parameter is only a hint and can + * potentially improve the performance of the insertion process. A bad + * hint would cause no gains in efficiency. + * + * See http://gcc.gnu.org/onlinedocs/libstdc++/23_containers/howto.html#4 + * for more on "hinting". + * + * Insertion requires logarithmic time (if the hint is not taken). + */ + iterator insert(iterator __position, const value_type& __x) + { + typedef typename _Rep_type::iterator _Rep_iterator; + return _M_t.insert_unique((_Rep_iterator&)__position, __x); + } + + /** + * @brief A template function that attemps to insert a range of elements. + * @param first Iterator pointing to the start of the range to be + * inserted. + * @param last Iterator pointing to the end of the range. + * + * Complexity similar to that of the range constructor. + */ + template + void insert(_InputIterator __first, _InputIterator __last) + { _M_t.insert_unique(__first, __last); } + + /** + * @brief Erases an element from a %set. + * @param position An iterator pointing to the element to be erased. + * + * This function erases an element, pointed to by the given iterator, + * from a %set. Note that this function only erases the element, and + * that if the element is itself a pointer, the pointed-to memory is not + * touched in any way. Managing the pointer is the user's responsibilty. + */ + void erase(iterator __position) + { + typedef typename _Rep_type::iterator _Rep_iterator; + _M_t.erase((_Rep_iterator&)__position); + } + + /** + * @brief Erases elements according to the provided key. + * @param x Key of element to be erased. + * @return The number of elements erased. + * + * This function erases all the elements located by the given key from + * a %set. + * Note that this function only erases the element, and that if + * the element is itself a pointer, the pointed-to memory is not touched + * in any way. Managing the pointer is the user's responsibilty. + */ + size_type erase(const key_type& __x) { return _M_t.erase(__x); } + + /** + * @brief Erases a [first,last) range of elements from a %set. + * @param first Iterator pointing to the start of the range to be erased. + * @param last Iterator pointing to the end of the range to be erased. + * + * This function erases a sequence of elements from a %set. + * Note that this function only erases the element, and that if + * the element is itself a pointer, the pointed-to memory is not touched + * in any way. Managing the pointer is the user's responsibilty. + */ + void erase(iterator __first, iterator __last) + { + typedef typename _Rep_type::iterator _Rep_iterator; + _M_t.erase((_Rep_iterator&)__first, (_Rep_iterator&)__last); + } + + /** + * Erases all elements in a %set. Note that this function only erases + * the elements, and that if the elements themselves are pointers, the + * pointed-to memory is not touched in any way. Managing the pointer is + * the user's responsibilty. + */ + void clear() { _M_t.clear(); } + + // set operations: + + /** + * @brief Finds the number of elements. + * @param x Element to located. + * @return Number of elements with specified key. + * + * This function only makes sense for multisets; for set the result will + * either be 0 (not present) or 1 (present). + */ + size_type count(const key_type& __x) const + { return _M_t.find(__x) == _M_t.end() ? 0 : 1; } + + // _GLIBCXX_RESOLVE_LIB_DEFECTS + // 214. set::find() missing const overload + //@{ + /** + * @brief Tries to locate an element in a %set. + * @param x Element to be located. + * @return Iterator pointing to sought-after element, or end() if not + * found. + * + * This function takes a key and tries to locate the element with which + * the key matches. If successful the function returns an iterator + * pointing to the sought after element. If unsuccessful it returns the + * past-the-end ( @c end() ) iterator. + */ + iterator find(const key_type& __x) { return _M_t.find(__x); } + const_iterator find(const key_type& __x) const { return _M_t.find(__x); } + //@} + + //@{ + /** + * @brief Finds the beginning of a subsequence matching given key. + * @param x Key to be located. + * @return Iterator pointing to first element equal to or greater + * than key, or end(). + * + * This function returns the first element of a subsequence of elements + * that matches the given key. If unsuccessful it returns an iterator + * pointing to the first element that has a greater value than given key + * or end() if no such element exists. + */ + iterator lower_bound(const key_type& __x) + { return _M_t.lower_bound(__x); } + const_iterator lower_bound(const key_type& __x) const + { return _M_t.lower_bound(__x); } + //@} + + //@{ + /** + * @brief Finds the end of a subsequence matching given key. + * @param x Key to be located. + * @return Iterator pointing to the first element + * greater than key, or end(). + */ + iterator upper_bound(const key_type& __x) + { return _M_t.upper_bound(__x); } + const_iterator upper_bound(const key_type& __x) const + { return _M_t.upper_bound(__x); } + //@} + + //@{ + /** + * @brief Finds a subsequence matching given key. + * @param x Key to be located. + * @return Pair of iterators that possibly points to the subsequence + * matching given key. + * + * This function is equivalent to + * @code + * std::make_pair(c.lower_bound(val), + * c.upper_bound(val)) + * @endcode + * (but is faster than making the calls separately). + * + * This function probably only makes sense for multisets. + */ + pair equal_range(const key_type& __x) + { return _M_t.equal_range(__x); } + pair equal_range(const key_type& __x) const + { return _M_t.equal_range(__x); } + //@} + + template + friend bool operator== (const set<_K1,_C1,_A1>&, const set<_K1,_C1,_A1>&); + template + friend bool operator< (const set<_K1,_C1,_A1>&, const set<_K1,_C1,_A1>&); + }; + + + /** + * @brief Set equality comparison. + * @param x A %set. + * @param y A %set of the same type as @a x. + * @return True iff the size and elements of the sets are equal. + * + * This is an equivalence relation. It is linear in the size of the sets. + * Sets are considered equivalent if their sizes are equal, and if + * corresponding elements compare equal. + */ + template + inline bool + operator==(const set<_Key,_Compare,_Alloc>& __x, + const set<_Key,_Compare,_Alloc>& __y) + { return __x._M_t == __y._M_t; } + + /** + * @brief Set ordering relation. + * @param x A %set. + * @param y A %set of the same type as @a x. + * @return True iff @a x is lexicographically less than @a y. + * + * This is a total ordering relation. It is linear in the size of the + * maps. The elements must be comparable with @c <. + * + * See std::lexicographical_compare() for how the determination is made. + */ + template + inline bool + operator<(const set<_Key,_Compare,_Alloc>& __x, + const set<_Key,_Compare,_Alloc>& __y) + { return __x._M_t < __y._M_t; } + + /// Returns !(x == y). + template + inline bool + operator!=(const set<_Key,_Compare,_Alloc>& __x, + const set<_Key,_Compare,_Alloc>& __y) + { return !(__x == __y); } + + /// Returns y < x. + template + inline bool + operator>(const set<_Key,_Compare,_Alloc>& __x, + const set<_Key,_Compare,_Alloc>& __y) + { return __y < __x; } + + + /// Returns !(y < x) + template + inline bool + operator<=(const set<_Key,_Compare,_Alloc>& __x, + const set<_Key,_Compare,_Alloc>& __y) + { return !(__y < __x); } + + /// Returns !(x < y) + template + inline bool + operator>=(const set<_Key,_Compare,_Alloc>& __x, + const set<_Key,_Compare,_Alloc>& __y) + { return !(__x < __y); } + + /// See std::set::swap(). + template + inline void + swap(set<_Key,_Compare,_Alloc>& __x, set<_Key,_Compare,_Alloc>& __y) + { __x.swap(__y); } } // namespace __gnu_norm diff --git a/libstdc++-v3/include/bits/stream_iterator.h b/libstdc++-v3/include/bits/stream_iterator.h index cc67505dd69..a8bc0565a90 100644 --- a/libstdc++-v3/include/bits/stream_iterator.h +++ b/libstdc++-v3/include/bits/stream_iterator.h @@ -1,6 +1,6 @@ // Stream iterators -// Copyright (C) 2001 Free Software Foundation, Inc. +// Copyright (C) 2001, 2004 Free Software Foundation, Inc. // // This file is part of the GNU ISO C++ Library. This library is free // software; you can redistribute it and/or modify it under the @@ -41,6 +41,7 @@ namespace std { + /// Provides input iterator semantics for streams. template, typename _Dist = ptrdiff_t> class istream_iterator @@ -56,9 +57,11 @@ namespace std _Tp _M_value; bool _M_ok; - public: + public: + /// Construct end of input stream iterator. istream_iterator() : _M_stream(0), _M_ok(false) {} + /// Construct start of input stream iterator. istream_iterator(istream_type& __s) : _M_stream(&__s) { _M_read(); } istream_iterator(const istream_iterator& __obj) @@ -116,12 +119,14 @@ namespace std } }; + /// Return true if x and y are both end or not end, or x and y are the same. template inline bool operator==(const istream_iterator<_Tp, _CharT, _Traits, _Dist>& __x, const istream_iterator<_Tp, _CharT, _Traits, _Dist>& __y) { return __x._M_equal(__y); } + /// Return false if x and y are both end or not end, or x and y are the same. template inline bool operator!=(const istream_iterator<_Tp, _CharT, _Traits, _Dist>& __x, @@ -129,29 +134,57 @@ namespace std { return !__x._M_equal(__y); } + /** + * @brief Provides output iterator semantics for streams. + * + * This class provides an iterator to write to an ostream. The type Tp is + * the only type written by this iterator and there must be an + * operator<<(Tp) defined. + * + * @param Tp The type to write to the ostream. + * @param CharT The ostream char_type. + * @param Traits The ostream char_traits. + */ template > class ostream_iterator : public iterator { public: + //@{ + /// Public typedef typedef _CharT char_type; typedef _Traits traits_type; typedef basic_ostream<_CharT, _Traits> ostream_type; + //@} private: ostream_type* _M_stream; const _CharT* _M_string; public: + /// Construct from an ostream. ostream_iterator(ostream_type& __s) : _M_stream(&__s), _M_string(0) {} + /** + * Construct from an ostream. + * + * The delimiter string @a c is written to the stream after every Tp + * written to the stream. The delimiter is not copied, and thus must + * not be destroyed while this iterator is in use. + * + * @param s Underlying ostream to write to. + * @param c CharT delimiter string to insert. + */ ostream_iterator(ostream_type& __s, const _CharT* __c) : _M_stream(&__s), _M_string(__c) { } + /// Copy constructor. ostream_iterator(const ostream_iterator& __obj) : _M_stream(__obj._M_stream), _M_string(__obj._M_string) { } + /// Writes @a value to underlying ostream using operator<<. If + /// constructed with delimiter string, writes delimiter to ostream. ostream_iterator& operator=(const _Tp& __value) { diff --git a/libstdc++-v3/include/bits/streambuf_iterator.h b/libstdc++-v3/include/bits/streambuf_iterator.h index 027cc891d99..908b8ddf33a 100644 --- a/libstdc++-v3/include/bits/streambuf_iterator.h +++ b/libstdc++-v3/include/bits/streambuf_iterator.h @@ -1,6 +1,6 @@ // Streambuf iterators -// Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003 +// Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004 // Free Software Foundation, Inc. // // This file is part of the GNU ISO C++ Library. This library is free @@ -46,6 +46,7 @@ namespace std { // 24.5.3 Template class istreambuf_iterator + /// Provides input iterator semantics for streambufs. template class istreambuf_iterator : public iterator streambuf_type; typedef basic_istream<_CharT, _Traits> istream_type; + //@} private: // 24.5.3 istreambuf_iterator @@ -71,16 +75,21 @@ namespace std int_type _M_c; public: + /// Construct end of input stream iterator. istreambuf_iterator() throw() : _M_sbuf(0), _M_c(traits_type::eof()) { } + /// Construct start of input stream iterator. istreambuf_iterator(istream_type& __s) throw() : _M_sbuf(__s.rdbuf()), _M_c(traits_type::eof()) { } + /// Construct start of streambuf iterator. istreambuf_iterator(streambuf_type* __s) throw() : _M_sbuf(__s), _M_c(traits_type::eof()) { } - // NB: The result of operator*() on an end of stream is undefined. + /// Return the current character pointed to by iterator. This returns + /// streambuf.sgetc(). It cannot be assigned. NB: The result of + /// operator*() on an end of stream is undefined. char_type operator*() const { @@ -93,7 +102,8 @@ namespace std #endif return traits_type::to_char_type(_M_get()); } - + + /// Advance the iterator. Calls streambuf.sbumpc(). istreambuf_iterator& operator++() { @@ -108,6 +118,7 @@ namespace std return *this; } + /// Advance the iterator. Calls streambuf.sbumpc(). istreambuf_iterator operator++(int) { @@ -129,6 +140,7 @@ namespace std // _GLIBCXX_RESOLVE_LIB_DEFECTS // 110 istreambuf_iterator::equal not const // NB: there is also number 111 (NAD, Future) pending on this function. + /// Return true both iterators are end or both are not end. bool equal(const istreambuf_iterator& __b) const { @@ -174,28 +186,35 @@ namespace std const istreambuf_iterator<_CharT, _Traits>& __b) { return !__a.equal(__b); } + /// Provides output iterator semantics for streambufs. template class ostreambuf_iterator : public iterator { public: // Types: + //@{ + /// Public typedefs typedef _CharT char_type; typedef _Traits traits_type; typedef basic_streambuf<_CharT, _Traits> streambuf_type; typedef basic_ostream<_CharT, _Traits> ostream_type; + //@} private: streambuf_type* _M_sbuf; bool _M_failed; public: + /// Construct output iterator from ostream. ostreambuf_iterator(ostream_type& __s) throw () : _M_sbuf(__s.rdbuf()), _M_failed(!_M_sbuf) { } + /// Construct output iterator from streambuf. ostreambuf_iterator(streambuf_type* __s) throw () : _M_sbuf(__s), _M_failed(!_M_sbuf) { } + /// Write character to streambuf. Calls streambuf.sputc(). ostreambuf_iterator& operator=(_CharT __c) { @@ -205,18 +224,22 @@ namespace std return *this; } + /// Return *this. ostreambuf_iterator& operator*() { return *this; } + /// Return *this. ostreambuf_iterator& operator++(int) { return *this; } + /// Return *this. ostreambuf_iterator& operator++() { return *this; } + /// Return true if previous operator=() failed. bool failed() const throw() { return _M_failed; } diff --git a/libstdc++-v3/include/std/std_complex.h b/libstdc++-v3/include/std/std_complex.h index 4fe80a55769..25c657f2701 100644 --- a/libstdc++-v3/include/std/std_complex.h +++ b/libstdc++-v3/include/std/std_complex.h @@ -58,67 +58,113 @@ namespace std template<> class complex; template<> class complex; + /// Return magnitude of @a z. template _Tp abs(const complex<_Tp>&); + /// Return phase angle of @a z. template _Tp arg(const complex<_Tp>&); + /// Return @a z magnitude squared. template _Tp norm(const complex<_Tp>&); + /// Return complex conjugate of @a z. template complex<_Tp> conj(const complex<_Tp>&); + /// Return complex with magnitude @a rho and angle @a theta. template complex<_Tp> polar(const _Tp&, const _Tp& = 0); // Transcendentals: + /// Return complex cosine of @a z. template complex<_Tp> cos(const complex<_Tp>&); + /// Return complex hyperbolic cosine of @a z. template complex<_Tp> cosh(const complex<_Tp>&); + /// Return complex base e exponential of @a z. template complex<_Tp> exp(const complex<_Tp>&); + /// Return complex natural logarithm of @a z. template complex<_Tp> log(const complex<_Tp>&); + /// Return complex base 10 logarithm of @a z. template complex<_Tp> log10(const complex<_Tp>&); + /// Return complex cosine of @a z. template complex<_Tp> pow(const complex<_Tp>&, int); + /// Return @a x to the @a y'th power. template complex<_Tp> pow(const complex<_Tp>&, const _Tp&); + /// Return @a x to the @a y'th power. template complex<_Tp> pow(const complex<_Tp>&, const complex<_Tp>&); + /// Return @a x to the @a y'th power. template complex<_Tp> pow(const _Tp&, const complex<_Tp>&); + /// Return complex sine of @a z. template complex<_Tp> sin(const complex<_Tp>&); + /// Return complex hyperbolic sine of @a z. template complex<_Tp> sinh(const complex<_Tp>&); + /// Return complex square root of @a z. template complex<_Tp> sqrt(const complex<_Tp>&); + /// Return complex tangent of @a z. template complex<_Tp> tan(const complex<_Tp>&); + /// Return complex hyperbolic tangent of @a z. template complex<_Tp> tanh(const complex<_Tp>&); + //@} // 26.2.2 Primary template class complex + /** + * Template to represent complex numbers. + * + * Specializations for float, double, and long double are part of the + * library. Results with any other type are not guaranteed. + * + * @param Tp Type of real and imaginary values. + */ template class complex { public: + /// Value typedef. typedef _Tp value_type; + /// Default constructor. First parameter is x, second parameter is y. + /// Unspecified parameters default to 0. complex(const _Tp& = _Tp(), const _Tp & = _Tp()); - // Let's the compiler synthetize the copy constructor + // Lets the compiler synthesize the copy constructor // complex (const complex<_Tp>&); + /// Copy constructor. template complex(const complex<_Up>&); + /// Return real part of complex number. _Tp& real(); + /// Return real part of complex number. const _Tp& real() const; + /// Return imaginary part of complex number. _Tp& imag(); + /// Return imaginary part of complex number. const _Tp& imag() const; + /// Assign this complex number to scalar @a t. complex<_Tp>& operator=(const _Tp&); + /// Add @a t to this complex number. complex<_Tp>& operator+=(const _Tp&); + /// Subtract @a t from this complex number. complex<_Tp>& operator-=(const _Tp&); + /// Multiply this complex number by @a t. complex<_Tp>& operator*=(const _Tp&); + /// Divide this complex number by @a t. complex<_Tp>& operator/=(const _Tp&); - // Let's the compiler synthetize the + // Lets the compiler synthesize the // copy and assignment operator // complex<_Tp>& operator= (const complex<_Tp>&); + /// Assign this complex number to complex @a z. template complex<_Tp>& operator=(const complex<_Up>&); + /// Add @a z to this complex number. template complex<_Tp>& operator+=(const complex<_Up>&); + /// Subtract @a z from this complex number. template complex<_Tp>& operator-=(const complex<_Up>&); + /// Multiply this complex number by @a z. template complex<_Tp>& operator*=(const complex<_Up>&); + /// Divide this complex number by @a z. template complex<_Tp>& operator/=(const complex<_Up>&); @@ -261,6 +307,8 @@ namespace std } // Operators: + //@{ + /// Return new complex value @a x plus @a y. template inline complex<_Tp> operator+(const complex<_Tp>& __x, const complex<_Tp>& __y) @@ -287,7 +335,10 @@ namespace std __r.real() += __x; return __r; } + //@} + //@{ + /// Return new complex value @a x minus @a y. template inline complex<_Tp> operator-(const complex<_Tp>& __x, const complex<_Tp>& __y) @@ -314,7 +365,10 @@ namespace std __r.real() -= __y.real(); return __r; } + //@} + //@{ + /// Return new complex value @a x times @a y. template inline complex<_Tp> operator*(const complex<_Tp>& __x, const complex<_Tp>& __y) @@ -341,7 +395,10 @@ namespace std __r *= __x; return __r; } + //@} + //@{ + /// Return new complex value @a x divided by @a y. template inline complex<_Tp> operator/(const complex<_Tp>& __x, const complex<_Tp>& __y) @@ -368,17 +425,22 @@ namespace std __r /= __y; return __r; } + //@} + /// Return @a x. template inline complex<_Tp> operator+(const complex<_Tp>& __x) { return __x; } + /// Return complex negation of @a x. template inline complex<_Tp> operator-(const complex<_Tp>& __x) { return complex<_Tp>(-__x.real(), -__x.imag()); } + //@{ + /// Return true if @a x is equal to @a y. template inline bool operator==(const complex<_Tp>& __x, const complex<_Tp>& __y) @@ -393,7 +455,10 @@ namespace std inline bool operator==(const _Tp& __x, const complex<_Tp>& __y) { return __x == __y.real() && _Tp() == __y.imag(); } + //@} + //@{ + /// Return false if @a x is equal to @a y. template inline bool operator!=(const complex<_Tp>& __x, const complex<_Tp>& __y) @@ -408,7 +473,9 @@ namespace std inline bool operator!=(const _Tp& __x, const complex<_Tp>& __y) { return __x != __y.real() || _Tp() != __y.imag(); } + //@} + /// Extraction operator for complex values. template basic_istream<_CharT, _Traits>& operator>>(basic_istream<_CharT, _Traits>& __is, complex<_Tp>& __x) @@ -441,6 +508,7 @@ namespace std return __is; } + /// Insertion operator for complex values. template basic_ostream<_CharT, _Traits>& operator<<(basic_ostream<_CharT, _Traits>& __os, const complex<_Tp>& __x)