From 82b61df521d17a96f60e56ede06a55a8894b1c2e Mon Sep 17 00:00:00 2001 From: Phil Edwards Date: Wed, 19 Dec 2001 21:57:43 +0000 Subject: [PATCH] Intro.3: New 'Allocators' module. 2001-12-19 Phil Edwards * docs/doxygen/Intro.3: New 'Allocators' module. * docs/doxygen/TODO: Update. * docs/doxygen/doxygroups.cc: Update. * docs/doxygen/run_doxygen: Update. * include/bits/stl_alloc.h: Tweak doxygen hooks in comments. * include/bits/std_memory.h: Doxygenate. * include/bits/stl_iterator_base_types.h: Likewise. * include/bits/stl_raw_storage_iter.h: Likewise. * include/bits/stl_tempbuf.h: Likewise. (get_temporary_buffer): Remove unused nonstandard overload. * include/bits/stl_uninitialized.h: Likewise. * include/bits/stl_iterator_base_types.h (input_iterator, output_iterator, forward_iterator, bidirectional_iterator, random_access_iterator): Move old names... * include/backward/iterator.h: ...to here. * include/bits/stl_bvector.h: Update. * include/ext/stl_rope.h: Update. From-SVN: r48185 --- libstdc++-v3/ChangeLog | 22 +++++ libstdc++-v3/docs/doxygen/Intro.3 | 1 + libstdc++-v3/docs/doxygen/TODO | 2 +- libstdc++-v3/docs/doxygen/doxygroups.cc | 14 +-- libstdc++-v3/docs/doxygen/run_doxygen | 3 +- libstdc++-v3/include/backward/iterator.h | 53 +++++++++- libstdc++-v3/include/bits/std_memory.h | 7 +- libstdc++-v3/include/bits/stl_alloc.h | 22 +++-- libstdc++-v3/include/bits/stl_bvector.h | 2 +- .../include/bits/stl_iterator_base_types.h | 96 ++++++++----------- .../include/bits/stl_raw_storage_iter.h | 4 + libstdc++-v3/include/bits/stl_tempbuf.h | 17 ++-- libstdc++-v3/include/bits/stl_uninitialized.h | 36 +++++++ libstdc++-v3/include/ext/stl_rope.h | 6 +- 14 files changed, 190 insertions(+), 95 deletions(-) diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index 916eae772b0..ee885008a97 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,25 @@ +2001-12-19 Phil Edwards + + * docs/doxygen/Intro.3: New 'Allocators' module. + * docs/doxygen/TODO: Update. + * docs/doxygen/doxygroups.cc: Update. + * docs/doxygen/run_doxygen: Update. + + * include/bits/stl_alloc.h: Tweak doxygen hooks in comments. + * include/bits/std_memory.h: Doxygenate. + * include/bits/stl_iterator_base_types.h: Likewise. + * include/bits/stl_raw_storage_iter.h: Likewise. + * include/bits/stl_tempbuf.h: Likewise. + (get_temporary_buffer): Remove unused nonstandard overload. + * include/bits/stl_uninitialized.h: Likewise. + + * include/bits/stl_iterator_base_types.h (input_iterator, + output_iterator, forward_iterator, bidirectional_iterator, + random_access_iterator): Move old names... + * include/backward/iterator.h: ...to here. + * include/bits/stl_bvector.h: Update. + * include/ext/stl_rope.h: Update. + 2001-12-19 Phil Edwards * docs/html/configopts.html: Describe recent options. diff --git a/libstdc++-v3/docs/doxygen/Intro.3 b/libstdc++-v3/docs/doxygen/Intro.3 index 52998c9fdd4..1d0820cdb42 100644 --- a/libstdc++-v3/docs/doxygen/Intro.3 +++ b/libstdc++-v3/docs/doxygen/Intro.3 @@ -29,6 +29,7 @@ or Austern's.) These category pages are: .\" These are separated by ONE TAB. Nothing else. I don't like it either. .TS lB l. +Allocators Classes encapsulating memory allocation schemes. Arithmetic_functors Functors for basic math. Assoc_containers Key-based containers. Binder_functors Functors which "remember" an argument. diff --git a/libstdc++-v3/docs/doxygen/TODO b/libstdc++-v3/docs/doxygen/TODO index 20f79593e4f..672513e624c 100644 --- a/libstdc++-v3/docs/doxygen/TODO +++ b/libstdc++-v3/docs/doxygen/TODO @@ -14,7 +14,7 @@ haven't gotten to it yet. It /will/ be done (by somebody, eventually.) c17 FINISHED (Nothing in Clause 17 "exists" in terms of code.) c18 , Note A c19 Note A -c20 std_memory.h[20.4], rel_ops (should they be doc'd?), Note A +c20 rel_ops (should they be doc'd?), Note A c21 Untouched, Note B c22 Untouched c23 See doxygroups.cc and Note B. diff --git a/libstdc++-v3/docs/doxygen/doxygroups.cc b/libstdc++-v3/docs/doxygen/doxygroups.cc index de304f13382..7d4e65dd760 100644 --- a/libstdc++-v3/docs/doxygen/doxygroups.cc +++ b/libstdc++-v3/docs/doxygen/doxygroups.cc @@ -1,10 +1,12 @@ -// This just provides documentation for stuff that doesn't need to be in the -// source headers themselves. It is a ".cc" file for the sole cheesy reason -// that it triggers many different text editors into doing Nice Things when -// typing comments. However, it is mentioned nowhere except the *cfg.in files. -// Pieces separated by '// //' lines will usually not be presented to the -// user on the same page. +/* + This just provides documentation for stuff that doesn't need to be in the + source headers themselves. It is a ".cc" file for the sole cheesy reason + that it triggers many different text editors into doing Nice Things when + typing comments. However, it is mentioned nowhere except the *cfg.in files. + Pieces separated by '// //' lines will usually not be presented to the + user on the same page. +*/ // // // // // // // // // // // // // // // // // // // // // // // // /** @addtogroup SGIextensions STL extensions from SGI diff --git a/libstdc++-v3/docs/doxygen/run_doxygen b/libstdc++-v3/docs/doxygen/run_doxygen index 78f23854974..7ac27447d4c 100644 --- a/libstdc++-v3/docs/doxygen/run_doxygen +++ b/libstdc++-v3/docs/doxygen/run_doxygen @@ -166,11 +166,12 @@ rm stdheader # implementations of man(1), e.g., Linux's. We need to have another top-level # *roff tag to /stop/ the .SH NAME entry. #problematic=`egrep --files-without-match '^\.SH SYNOPSIS' [A-Z]*.3` -problematic='Containers.3 Sequences.3 Assoc_containers.3' +problematic='Containers.3 Sequences.3 Assoc_containers.3 Allocators.3' for f in $problematic; do sed '/^\.SH NAME/{ n a\ +\ .SH SYNOPSIS }' $f > TEMP mv TEMP $f diff --git a/libstdc++-v3/include/backward/iterator.h b/libstdc++-v3/include/backward/iterator.h index 391ee2566c0..d35b9420a86 100644 --- a/libstdc++-v3/include/backward/iterator.h +++ b/libstdc++-v3/include/backward/iterator.h @@ -46,11 +46,54 @@ using std::random_access_iterator_tag; #if 0 using std::iterator; #endif -using std::input_iterator; -using std::output_iterator; -using std::forward_iterator; -using std::bidirectional_iterator; -using std::random_access_iterator; + +// The base classes input_iterator, output_iterator, forward_iterator, +// bidirectional_iterator, and random_access_iterator are not part of +// the C++ standard. (They have been replaced by struct iterator.) +// They are included for backward compatibility with the HP STL. +template + struct input_iterator { + typedef input_iterator_tag iterator_category; + typedef _Tp value_type; + typedef _Distance difference_type; + typedef _Tp* pointer; + typedef _Tp& reference; + }; + +struct output_iterator { + typedef output_iterator_tag iterator_category; + typedef void value_type; + typedef void difference_type; + typedef void pointer; + typedef void reference; +}; + +template + struct forward_iterator { + typedef forward_iterator_tag iterator_category; + typedef _Tp value_type; + typedef _Distance difference_type; + typedef _Tp* pointer; + typedef _Tp& reference; + }; + +template + struct bidirectional_iterator { + typedef bidirectional_iterator_tag iterator_category; + typedef _Tp value_type; + typedef _Distance difference_type; + typedef _Tp* pointer; + typedef _Tp& reference; + }; + +template + struct random_access_iterator { + typedef random_access_iterator_tag iterator_category; + typedef _Tp value_type; + typedef _Distance difference_type; + typedef _Tp* pointer; + typedef _Tp& reference; + }; using std::iterator_traits; diff --git a/libstdc++-v3/include/bits/std_memory.h b/libstdc++-v3/include/bits/std_memory.h index d0b36965384..c9a2e59e48e 100644 --- a/libstdc++-v3/include/bits/std_memory.h +++ b/libstdc++-v3/include/bits/std_memory.h @@ -67,6 +67,9 @@ namespace std auto_ptr_ref(_Tp1* __p) : _M_ptr(__p) {} }; +/** + * A simple smart pointer providing strict ownership semantics. (More later.) +*/ template class auto_ptr { private: _Tp* _M_ptr; @@ -118,10 +121,6 @@ public: } } - // According to the C++ standard, these conversions are required. Most - // present-day compilers, however, do not enforce that requirement---and, - // in fact, most present-day compilers do not support the language - // features that these conversions rely on. public: auto_ptr(auto_ptr_ref<_Tp> __ref) throw() : _M_ptr(__ref._M_ptr) {} diff --git a/libstdc++-v3/include/bits/stl_alloc.h b/libstdc++-v3/include/bits/stl_alloc.h index b1dc11e8af0..751dffece77 100644 --- a/libstdc++-v3/include/bits/stl_alloc.h +++ b/libstdc++-v3/include/bits/stl_alloc.h @@ -49,8 +49,8 @@ #define __GLIBCPP_INTERNAL_ALLOC_H /** + * @defgroup Allocators Memory Allocators * @maint - * @addtogroup Allocators * stl_alloc.h implements some node allocators. These are NOT the same as * allocators in the C++ standard, nor in the original H-P STL. They do not * encapsulate different pointer types; we assume that there is only one @@ -72,8 +72,10 @@ * * "SGI" allocators may be wrapped in __allocator to convert the interface * into a "standard" one. - * * @endmaint + * + * The canonical description of these classes is in docs/html/ext/howto.html + * or online at http://gcc.gnu.org/onlinedocs/libstdc++/ext/howto.html#3 */ @@ -91,8 +93,8 @@ namespace std * A new-based allocator, as required by the standard. Allocation and * deallocation forward to global new and delete. "SGI" style, minus * reallocate(). - * (See @link Allocators allocators info @endlink for more.) * @endmaint + * (See @link Allocators allocators info @endlink for more.) */ class __new_alloc { @@ -114,8 +116,8 @@ namespace std * storage efficient. The template argument is unused and is only present * to permit multiple instantiations (but see __default_alloc_template * for caveats). "SGI" style, plus __set_malloc_handler for OOM conditions. - * (See @link Allocators allocators info @endlink for more.) * @endmaint + * (See @link Allocators allocators info @endlink for more.) */ template class __malloc_alloc_template @@ -212,8 +214,8 @@ namespace std * * This is neither "standard"-conforming nor "SGI". The _Alloc parameter * must be "SGI" style. - * (See @link Allocators allocators info @endlink for more.) * @endmaint + * (See @link Allocators allocators info @endlink for more.) */ template class __simple_alloc @@ -244,8 +246,8 @@ namespace std * "There is some evidence that this can confuse Purify." - SGI comment * * This adaptor is "SGI" style. The _Alloc parameter must also be "SGI". - * (See @link Allocators allocators info @endlink for more.) * @endmaint + * (See @link Allocators allocators info @endlink for more.) */ template class __debug_alloc @@ -317,8 +319,8 @@ typedef __mem_interface __single_client_alloc; * approach. If you do not wish to share the free lists with the main * default_alloc instance, instantiate this with a non-zero __inst. * - * (See @link Allocators allocators info @endlink for more.) * @endmaint + * (See @link Allocators allocators info @endlink for more.) */ template class __default_alloc_template @@ -674,12 +676,14 @@ inline bool operator!=(const allocator<_T1>&, const allocator<_T2>&) /** + * @maint * Allocator adaptor to turn an "SGI" style allocator (e.g., __alloc, * __malloc_alloc_template) into a "standard" conforming allocator. Note * that this adaptor does *not* assume that all objects of the underlying * alloc class are identical, nor does it assume that all of the underlying * alloc's member functions are static member functions. Note, also, that * __allocator<_Tp, __alloc> is essentially the same thing as allocator<_Tp>. + * @endmaint * (See @link Allocators allocators info @endlink for more.) */ template @@ -822,9 +826,10 @@ inline bool operator!=(const __debug_alloc<_Alloc>&, * The size_t parameters are "standard" style (see top of stl_alloc.h) in * that they take counts, not sizes. * - * (See @link Allocators allocators info @endlink for more.) * @endmaint + * (See @link Allocators allocators info @endlink for more.) */ +//@{ // The fully general version. template struct _Alloc_traits @@ -844,6 +849,7 @@ struct _Alloc_traits<_Tp, allocator<_Tp1> > typedef __simple_alloc<_Tp, __alloc> _Alloc_type; typedef allocator<_Tp> allocator_type; }; +//@} //@{ /// Versions for the predefined "SGI" style allocators. diff --git a/libstdc++-v3/include/bits/stl_bvector.h b/libstdc++-v3/include/bits/stl_bvector.h index 605831fdf97..984acbfd5c1 100644 --- a/libstdc++-v3/include/bits/stl_bvector.h +++ b/libstdc++-v3/include/bits/stl_bvector.h @@ -98,7 +98,7 @@ inline void swap(_Bit_reference __x, _Bit_reference __y) __y = __tmp; } -struct _Bit_iterator_base : public random_access_iterator +struct _Bit_iterator_base : public iterator { unsigned int* _M_p; unsigned int _M_offset; diff --git a/libstdc++-v3/include/bits/stl_iterator_base_types.h b/libstdc++-v3/include/bits/stl_iterator_base_types.h index 28f79c27a90..992510d139e 100644 --- a/libstdc++-v3/include/bits/stl_iterator_base_types.h +++ b/libstdc++-v3/include/bits/stl_iterator_base_types.h @@ -56,86 +56,65 @@ /** @file stl_iterator_base_types.h * This is an internal header file, included by other library headers. * You should not attempt to use it directly. + * + * This file contains all of the general iterator-related utility types, + * such as iterator_traits and struct iterator. */ #ifndef __GLIBCPP_INTERNAL_ITERATOR_BASE_TYPES_H #define __GLIBCPP_INTERNAL_ITERATOR_BASE_TYPES_H -// This file contains all of the general iterator-related utility -// types, such as iterator_traits and struct iterator. -// The internal file stl_iterator.h contains predefined iterators, -// such as front_insert_iterator and istream_iterator. - #pragma GCC system_header namespace std { - + /** + * @defgroup iterator_tags Iterator Tags + * These are empty types, used to distinguish different iterators. The + * distinction is not made by what they contain, but simply by what they + * are. Different underlying algorithms can then be used based on the + * different operations supporetd by different iterator types. + * @{ + */ + /// Marking input iterators. struct input_iterator_tag {}; + /// Marking output iterators. struct output_iterator_tag {}; + /// Forward iterators support a superset of input iterator operations. struct forward_iterator_tag : public input_iterator_tag {}; + /// Bidirectional iterators support a superset of forward iterator operations. struct bidirectional_iterator_tag : public forward_iterator_tag {}; + /// Random-access iterators support a superset of bidirectional iterator operations. struct random_access_iterator_tag : public bidirectional_iterator_tag {}; + //@} - // The base classes input_iterator, output_iterator, forward_iterator, - // bidirectional_iterator, and random_access_iterator are not part of - // the C++ standard. (They have been replaced by struct iterator.) - // They are included for backward compatibility with the HP STL. - - template - struct input_iterator { - typedef input_iterator_tag iterator_category; - typedef _Tp value_type; - typedef _Distance difference_type; - typedef _Tp* pointer; - typedef _Tp& reference; - }; - - struct output_iterator { - typedef output_iterator_tag iterator_category; - typedef void value_type; - typedef void difference_type; - typedef void pointer; - typedef void reference; - }; - - template - struct forward_iterator { - typedef forward_iterator_tag iterator_category; - typedef _Tp value_type; - typedef _Distance difference_type; - typedef _Tp* pointer; - typedef _Tp& reference; - }; - - template - struct bidirectional_iterator { - typedef bidirectional_iterator_tag iterator_category; - typedef _Tp value_type; - typedef _Distance difference_type; - typedef _Tp* pointer; - typedef _Tp& reference; - }; - - template - struct random_access_iterator { - typedef random_access_iterator_tag iterator_category; - typedef _Tp value_type; - typedef _Distance difference_type; - typedef _Tp* pointer; - typedef _Tp& reference; - }; + /** + * This class does nothing but define nested typedefs. Iterator classes + * can inherit from this class to save some work. The typedefs are then + * used in specializations and overloading. + */ template struct iterator { + /// One of the @link iterator_tags tag types@endlink. typedef _Category iterator_category; + /// The type "pointed to" by the iterator. typedef _Tp value_type; + /// Distance between iterators is represented as this type. typedef _Distance difference_type; + /// This type represents a pointer-to-value_type. typedef _Pointer pointer; + /// This type represents a reference-to-value_type. typedef _Reference reference; }; + /** + * This class does nothing but define nested typedefs. The general + * version simply "forwards" the nested typedefs from the Iterator + * argument. Specialized versions for pointers and pointers-to-const + * provide tighter, more correct semantics. + */ template struct iterator_traits { typedef typename _Iterator::iterator_category iterator_category; @@ -163,9 +142,12 @@ namespace std typedef const _Tp& reference; }; - // This function is not a part of the C++ standard but is syntactic - // sugar for internal library use only. - + /** + * @maint + * This function is not a part of the C++ standard but is syntactic + * sugar for internal library use only. + * @endmaint + */ template inline typename iterator_traits<_Iter>::iterator_category __iterator_category(const _Iter&) diff --git a/libstdc++-v3/include/bits/stl_raw_storage_iter.h b/libstdc++-v3/include/bits/stl_raw_storage_iter.h index 58c45cd3f0c..59aa004296e 100644 --- a/libstdc++-v3/include/bits/stl_raw_storage_iter.h +++ b/libstdc++-v3/include/bits/stl_raw_storage_iter.h @@ -63,6 +63,10 @@ namespace std { + /** + * This iterator class lets algorithms store their results into + * uninitialized memory. + */ template class raw_storage_iterator : public iterator diff --git a/libstdc++-v3/include/bits/stl_tempbuf.h b/libstdc++-v3/include/bits/stl_tempbuf.h index 9d64c0333a8..40cac1cdd18 100644 --- a/libstdc++-v3/include/bits/stl_tempbuf.h +++ b/libstdc++-v3/include/bits/stl_tempbuf.h @@ -81,26 +81,23 @@ __get_temporary_buffer(ptrdiff_t __len, _Tp*) return pair<_Tp*, ptrdiff_t>((_Tp*)0, 0); } +/** + * This is a mostly-useless wrapper around malloc(). +*/ template inline pair<_Tp*, ptrdiff_t> get_temporary_buffer(ptrdiff_t __len) { return __get_temporary_buffer(__len, (_Tp*) 0); } -// This overload is not required by the standard; it is an extension. -// It is supported for backward compatibility with the HP STL, and -// because not all compilers support the language feature (explicit -// function template arguments) that is required for the standard -// version of get_temporary_buffer. -template -inline pair<_Tp*, ptrdiff_t> get_temporary_buffer(ptrdiff_t __len, _Tp*) { - return __get_temporary_buffer(__len, (_Tp*) 0); -} - +/** + * The companion to get_temporary_buffer(). +*/ template void return_temporary_buffer(_Tp* __p) { free(__p); } + template class _Temporary_buffer { private: diff --git a/libstdc++-v3/include/bits/stl_uninitialized.h b/libstdc++-v3/include/bits/stl_uninitialized.h index 5c107a4600c..c51ba58c079 100644 --- a/libstdc++-v3/include/bits/stl_uninitialized.h +++ b/libstdc++-v3/include/bits/stl_uninitialized.h @@ -94,6 +94,15 @@ namespace std } } + /** + * @brief Copies the range [first,last) into result. + * @param first An input iterator. + * @param last An input iterator. + * @param result An output iterator. + * @return result + (first - last) + * + * Like copy(), but does not require an initialized output range. + */ template inline _ForwardIter uninitialized_copy(_InputIter __first, _InputIter __last, _ForwardIter __result) @@ -159,6 +168,15 @@ namespace std __iterator_category(__first)); } + /** + * @brief Copies the range [first,last) into result. + * @param first An input iterator. + * @param last An input iterator. + * @param result An output iterator. + * @return result + (first - last) + * + * Like copy(), but does not require an initialized output range. + */ template inline pair<_InputIter, _ForwardIter> uninitialized_copy_n(_InputIter __first, _Size __count, @@ -192,6 +210,15 @@ namespace std } } + /** + * @brief Copies the value x into the range [first,last). + * @param first An input iterator. + * @param last An input iterator. + * @param x The source value. + * @return Nothing. + * + * Like fill(), but does not require an initialized output range. + */ template inline void uninitialized_fill(_ForwardIter __first, _ForwardIter __last, const _Tp& __x) @@ -229,6 +256,15 @@ namespace std } } + /** + * @brief Copies the value x into the range [first,first+n). + * @param first An input iterator. + * @param n The number of copies to make. + * @param x The source value. + * @return first+n + * + * Like fill_n(), but does not require an initialized output range. + */ template inline _ForwardIter uninitialized_fill_n(_ForwardIter __first, _Size __n, const _Tp& __x) diff --git a/libstdc++-v3/include/ext/stl_rope.h b/libstdc++-v3/include/ext/stl_rope.h index 23cc7e40f72..089561a80bf 100644 --- a/libstdc++-v3/include/ext/stl_rope.h +++ b/libstdc++-v3/include/ext/stl_rope.h @@ -122,7 +122,8 @@ class char_producer { // little like containers. template -class sequence_buffer : public output_iterator { +class sequence_buffer : public iterator +{ public: typedef typename _Sequence::value_type value_type; protected: @@ -837,7 +838,8 @@ class _Rope_char_ptr_proxy { template class _Rope_iterator_base - : public random_access_iterator<_CharT, ptrdiff_t> { + : public iterator +{ friend class rope<_CharT,_Alloc>; public: typedef _Alloc _allocator_type; // used in _Rope_rotate, VC++ workaround