Intro.3: New 'Allocators' module.
2001-12-19 Phil Edwards <pme@gcc.gnu.org>
* 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
diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog
index 916eae7..ee88500 100644
--- a/libstdc++-v3/ChangeLog
+++ b/libstdc++-v3/ChangeLog
@@ -1,5 +1,27 @@
2001-12-19 Phil Edwards <pme@gcc.gnu.org>
+ * 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 <pme@gcc.gnu.org>
+
* docs/html/configopts.html: Describe recent options.
* docs/html/documentation.html: Point to new doxygen tarballs.
* docs/html/install.html: Brief updates.
diff --git a/libstdc++-v3/docs/doxygen/Intro.3 b/libstdc++-v3/docs/doxygen/Intro.3
index 52998c9..1d0820c 100644
--- a/libstdc++-v3/docs/doxygen/Intro.3
+++ b/libstdc++-v3/docs/doxygen/Intro.3
@@ -29,6 +29,7 @@
.\" 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 20f7959..672513e 100644
--- a/libstdc++-v3/docs/doxygen/TODO
+++ b/libstdc++-v3/docs/doxygen/TODO
@@ -14,7 +14,7 @@
c17 FINISHED (Nothing in Clause 17 "exists" in terms of code.)
c18 <limits>, 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 de304f1..7d4e65d 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 78f2385..7ac2744 100644
--- a/libstdc++-v3/docs/doxygen/run_doxygen
+++ b/libstdc++-v3/docs/doxygen/run_doxygen
@@ -166,11 +166,12 @@
# 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 391ee25..d35b942 100644
--- a/libstdc++-v3/include/backward/iterator.h
+++ b/libstdc++-v3/include/backward/iterator.h
@@ -46,11 +46,54 @@
#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<typename _Tp, typename _Distance>
+ 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<typename _Tp, typename _Distance>
+ struct forward_iterator {
+ typedef forward_iterator_tag iterator_category;
+ typedef _Tp value_type;
+ typedef _Distance difference_type;
+ typedef _Tp* pointer;
+ typedef _Tp& reference;
+ };
+
+template<typename _Tp, typename _Distance>
+ struct bidirectional_iterator {
+ typedef bidirectional_iterator_tag iterator_category;
+ typedef _Tp value_type;
+ typedef _Distance difference_type;
+ typedef _Tp* pointer;
+ typedef _Tp& reference;
+ };
+
+template<typename _Tp, typename _Distance>
+ 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 d0b3696..c9a2e59 100644
--- a/libstdc++-v3/include/bits/std_memory.h
+++ b/libstdc++-v3/include/bits/std_memory.h
@@ -67,6 +67,9 @@
auto_ptr_ref(_Tp1* __p) : _M_ptr(__p) {}
};
+/**
+ * A simple smart pointer providing strict ownership semantics. (More later.)
+*/
template <class _Tp> class auto_ptr {
private:
_Tp* _M_ptr;
@@ -118,10 +121,6 @@
}
}
- // 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 b1dc11e..751dffe 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 @@
* 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 @@
* 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 <int __inst>
class __malloc_alloc_template
@@ -212,8 +214,8 @@
*
* 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 _Tp, class _Alloc>
class __simple_alloc
@@ -244,8 +246,8 @@
* "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 _Alloc>
class __debug_alloc
@@ -317,8 +319,8 @@
* 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 <bool __threads, int __inst>
class __default_alloc_template
@@ -674,12 +676,14 @@
/**
+ * @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 <class _Tp, class _Alloc>
@@ -822,9 +826,10 @@
* 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 <class _Tp, class _Allocator>
struct _Alloc_traits
@@ -844,6 +849,7 @@
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 605831f..984acbf 100644
--- a/libstdc++-v3/include/bits/stl_bvector.h
+++ b/libstdc++-v3/include/bits/stl_bvector.h
@@ -98,7 +98,7 @@
__y = __tmp;
}
-struct _Bit_iterator_base : public random_access_iterator<bool, ptrdiff_t>
+struct _Bit_iterator_base : public iterator<random_access_iterator_tag, bool>
{
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 28f79c2..992510d 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<typename _Tp, typename _Distance>
- 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<typename _Tp, typename _Distance>
- struct forward_iterator {
- typedef forward_iterator_tag iterator_category;
- typedef _Tp value_type;
- typedef _Distance difference_type;
- typedef _Tp* pointer;
- typedef _Tp& reference;
- };
-
- template<typename _Tp, typename _Distance>
- struct bidirectional_iterator {
- typedef bidirectional_iterator_tag iterator_category;
- typedef _Tp value_type;
- typedef _Distance difference_type;
- typedef _Tp* pointer;
- typedef _Tp& reference;
- };
-
- template<typename _Tp, typename _Distance>
- 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<typename _Category, typename _Tp, typename _Distance = ptrdiff_t,
typename _Pointer = _Tp*, typename _Reference = _Tp&>
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<typename _Iterator>
struct iterator_traits {
typedef typename _Iterator::iterator_category iterator_category;
@@ -163,9 +142,12 @@
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<typename _Iter>
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 58c45cd..59aa004 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 _ForwardIterator, class _Tp>
class raw_storage_iterator
: public iterator<output_iterator_tag, void, void, void, void>
diff --git a/libstdc++-v3/include/bits/stl_tempbuf.h b/libstdc++-v3/include/bits/stl_tempbuf.h
index 9d64c03..40cac1c 100644
--- a/libstdc++-v3/include/bits/stl_tempbuf.h
+++ b/libstdc++-v3/include/bits/stl_tempbuf.h
@@ -81,26 +81,23 @@
return pair<_Tp*, ptrdiff_t>((_Tp*)0, 0);
}
+/**
+ * This is a mostly-useless wrapper around malloc().
+*/
template <class _Tp>
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 <class _Tp>
-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 <class _Tp>
void return_temporary_buffer(_Tp* __p) {
free(__p);
}
+
template <class _ForwardIterator, class _Tp>
class _Temporary_buffer {
private:
diff --git a/libstdc++-v3/include/bits/stl_uninitialized.h b/libstdc++-v3/include/bits/stl_uninitialized.h
index 5c107a4..c51ba58 100644
--- a/libstdc++-v3/include/bits/stl_uninitialized.h
+++ b/libstdc++-v3/include/bits/stl_uninitialized.h
@@ -94,6 +94,15 @@
}
}
+ /**
+ * @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<typename _InputIter, typename _ForwardIter>
inline _ForwardIter
uninitialized_copy(_InputIter __first, _InputIter __last, _ForwardIter __result)
@@ -159,6 +168,15 @@
__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<typename _InputIter, typename _Size, typename _ForwardIter>
inline pair<_InputIter, _ForwardIter>
uninitialized_copy_n(_InputIter __first, _Size __count,
@@ -192,6 +210,15 @@
}
}
+ /**
+ * @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<typename _ForwardIter, typename _Tp>
inline void
uninitialized_fill(_ForwardIter __first, _ForwardIter __last, const _Tp& __x)
@@ -229,6 +256,15 @@
}
}
+ /**
+ * @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<typename _ForwardIter, typename _Size, typename _Tp>
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 23cc7e4..089561a 100644
--- a/libstdc++-v3/include/ext/stl_rope.h
+++ b/libstdc++-v3/include/ext/stl_rope.h
@@ -122,7 +122,8 @@
// little like containers.
template<class _Sequence, size_t _Buf_sz = 100>
-class sequence_buffer : public output_iterator {
+class sequence_buffer : public iterator<output_iterator_tag,void,void,void,void>
+{
public:
typedef typename _Sequence::value_type value_type;
protected:
@@ -837,7 +838,8 @@
template<class _CharT, class _Alloc>
class _Rope_iterator_base
- : public random_access_iterator<_CharT, ptrdiff_t> {
+ : public iterator<random_access_iterator_tag, _CharT>
+{
friend class rope<_CharT,_Alloc>;
public:
typedef _Alloc _allocator_type; // used in _Rope_rotate, VC++ workaround
