From ca33b868ea1fe9b7202647264b15a35afd1b32eb Mon Sep 17 00:00:00 2001 From: pme Date: Tue, 5 Feb 2002 00:14:37 +0000 Subject: [PATCH] 2002-02-04 Phil Edwards * docs/doxygen/TODO: Impl-defined behavior now documented... * docs/html/17_intro/howto.html: ...here. * docs/doxygen/mainpage.doxy: Remove, rename... * docs/doxygen/mainpage.html: ...to this. Tweak HTML, add license. * docs/doxygen/style.css: Add small text. * docs/doxygen/run_doxygen: Adjust for new mainpage. * docs/doxygen/user.cfg.in: Likewise. 2002-02-04 Stephan Buys * include/bits/stl_map.h: Initial doxygen markup. * include/std/std_fstream.h: Initial doxygen markup. git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@49502 138bc75d-0d04-0410-961f-82ee72b054a4 --- libstdc++-v3/ChangeLog | 15 ++ libstdc++-v3/docs/doxygen/TODO | 7 - .../docs/doxygen/{mainpage.doxy => mainpage.html} | 62 ++++- libstdc++-v3/docs/doxygen/run_doxygen | 1 + libstdc++-v3/docs/doxygen/style.css | 1 + libstdc++-v3/docs/doxygen/user.cfg.in | 3 +- libstdc++-v3/docs/html/17_intro/howto.html | 73 ++++-- libstdc++-v3/include/bits/stl_map.h | 270 +++++++++++++++++++-- libstdc++-v3/include/std/std_fstream.h | 258 +++++++++++++------- 9 files changed, 553 insertions(+), 137 deletions(-) rename libstdc++-v3/docs/doxygen/{mainpage.doxy => mainpage.html} (55%) diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index 6ca364e..4d7f104 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,18 @@ +2002-02-04 Phil Edwards + + * docs/doxygen/TODO: Impl-defined behavior now documented... + * docs/html/17_intro/howto.html: ...here. + * docs/doxygen/mainpage.doxy: Remove, rename... + * docs/doxygen/mainpage.html: ...to this. Tweak HTML, add license. + * docs/doxygen/style.css: Add small text. + * docs/doxygen/run_doxygen: Adjust for new mainpage. + * docs/doxygen/user.cfg.in: Likewise. + +2002-02-04 Stephan Buys + + * include/bits/stl_map.h: Initial doxygen markup. + * include/std/std_fstream.h: Initial doxygen markup. + 2002-02-04 Paolo Carlini libstdc++/5579 diff --git a/libstdc++-v3/docs/doxygen/TODO b/libstdc++-v3/docs/doxygen/TODO index 0a8cfbb..da2f25a 100644 --- a/libstdc++-v3/docs/doxygen/TODO +++ b/libstdc++-v3/docs/doxygen/TODO @@ -30,13 +30,6 @@ ext/* Some of the SGI algorithm/functional extensions. __gnu_cxx Tricky. Right now ext/* are in this namespace. -[1.3.5] "implementation-defined behavior: behavior ... that depends - on the implementation *and that each implementation shall - document*." [my emphasis] Not all implementation choices - have been thus described; doxygen is not necessarily the - appropriate place for such descriptions, either. I suggest - adding this list to the Chapter 17 HOWTO. - ----------------------------------------------------------- NOTES: diff --git a/libstdc++-v3/docs/doxygen/mainpage.doxy b/libstdc++-v3/docs/doxygen/mainpage.html similarity index 55% rename from libstdc++-v3/docs/doxygen/mainpage.doxy rename to libstdc++-v3/docs/doxygen/mainpage.html index b3a4d29..d7b1c43 100644 --- a/libstdc++-v3/docs/doxygen/mainpage.doxy +++ b/libstdc++-v3/docs/doxygen/mainpage.html @@ -1,7 +1,32 @@ -/*! \mainpage + + + +Main Page + + + + + + +

libstdc++-v3 Source Documentation

Documentation Overview

Generated 2002-02-04.

There are two types of documentation for libstdc++-v3. One is the distribution documentation, which can be read online at http://gcc.gnu.org/onlinedocs/libstdc++/documentation.html @@ -26,8 +51,12 @@ The Makefile rule 'make doxygen' in the libstdc++-v3 build directory generates these pages using a tool called, appropriately enough, Doxygen. To learn more about - Doxygen, take a look at the Doxygen - webpage. + Doxygen, take a look at + + + the Doxygen homepage +

The libstdc++-v3 configuration files needed to generate doxygen output @@ -71,6 +100,31 @@ href="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/C++STYLE">C++STYLE.

-*/ +

License, Copyright, and Other Lawyerly Verbosity

The libstdc++-v3 documentation is released under + + these terms. +

Part of the generated documentation involved comments + and notes from SGI, who says we gotta say this: +

+ Permission to use, copy, modify, distribute and sell this software and its + documentation for any purpose is hereby granted without fee, provided + that the below copyright notice appears in all copies and that both + the copyright notice and this permission notice appear in supporting + documentation. Silicon Graphics makes no representations about the + suitability of this software for any purpose. It is provided "as is" + without express or implied warranty. +

+ Copyright © 1994 + Hewlett-Packard Company +

+ + + diff --git a/libstdc++-v3/docs/doxygen/run_doxygen b/libstdc++-v3/docs/doxygen/run_doxygen index 18866da..e93c947 100644 --- a/libstdc++-v3/docs/doxygen/run_doxygen +++ b/libstdc++-v3/docs/doxygen/run_doxygen @@ -146,6 +146,7 @@ set -e set +e test $do_html = yes && { + cp ${srcdir}/docs/doxygen/mainpage.html ${outdir}/html_${mode}/index.html echo :: echo :: HTML pages begin with echo :: ${outdir}/html_${mode}/index.html diff --git a/libstdc++-v3/docs/doxygen/style.css b/libstdc++-v3/docs/doxygen/style.css index 5b03b69..5e43005 100644 --- a/libstdc++-v3/docs/doxygen/style.css +++ b/libstdc++-v3/docs/doxygen/style.css @@ -21,3 +21,4 @@ FONT.comment { color: #800000 } FONT.preprocessor { color: #806020 } FONT.stringliteral { color: #002080 } FONT.charliteral { color: #008080 } +.smallertext { font-size: smaller } diff --git a/libstdc++-v3/docs/doxygen/user.cfg.in b/libstdc++-v3/docs/doxygen/user.cfg.in index b6baf6d..430194b 100644 --- a/libstdc++-v3/docs/doxygen/user.cfg.in +++ b/libstdc++-v3/docs/doxygen/user.cfg.in @@ -296,8 +296,7 @@ WARN_LOGFILE = # directories like "/usr/src/myproject". Separate the files or directories # with spaces. -INPUT = @srcdir@/docs/doxygen/mainpage.doxy \ - @srcdir@/docs/doxygen/doxygroups.cc \ +INPUT = @srcdir@/docs/doxygen/doxygroups.cc \ @srcdir@/src \ @srcdir@/libsupc++/exception \ @srcdir@/libsupc++/new \ diff --git a/libstdc++-v3/docs/html/17_intro/howto.html b/libstdc++-v3/docs/html/17_intro/howto.html index e1823c9..7aa7430 100644 --- a/libstdc++-v3/docs/html/17_intro/howto.html +++ b/libstdc++-v3/docs/html/17_intro/howto.html @@ -165,26 +165,28 @@

Behavior specific to libstdc++-v3

The ISO standard defines the following: +

The ISO standard defines the following phrase:

[1.3.5] implementation-defined behavior
behavior, for a well-formed program construct and correct data, that depends on the implementation and that each implementation - shall document. + shall document.

We do so here, for the C++ library only. Behavior of the compiler, linker, runtime loader, and other elements of "the - implementation" are documented elsewhere. + implementation" are documented elsewhere. Everything listed in + Annex B, Implemenation Qualities, are also part of the compiler, not + the library.

For each entry, we give the section number of the standard, when - applicable. This list is known to be incomplet and inkorrekt. + applicable. This list is probably incomplet and inkorrekt.

[17.4.4.5] Non-reentrant functions are probably best discussed in the various sections on multithreading (see above).

[18.1]/4 The type of NULL is described here. @@ -200,27 +202,66 @@ [18.6.2.1]/5 (bad_exception): The what() member function of class std::exception, and these other classes publicly derived from it, simply returns the name of the - class. But they are the mangled names. - + class. But they are the mangled names; you will need to call + c++filt and pass the names as command-line parameters to + demangle them. (The classes in <stdexcept> have constructors which - require a string argument to use in what() calls, so the + require an argument to use later for what() calls, so the question does not arise in most user-defined exceptions.)

[18.5.1]/7 The return value of + std::type_info::name() is the mangled type name (see the + previous entry for more).

[20.1.5]/5 "Implementors are encouraged to + supply libraries that can accept allocators that encapsulate more + general memory models and that support non-equal instances. In such + implementations, any requirements imposed on allocators by containers + beyond those requirements that appear in Table 32, and the semantics + of containers and algorithms when allocator instances compare + non-equal, are implementation-defined." As yet we don't + have any allocators which compare non-equal, so we can't describe how + they behave.

[21.1.3.1]/3,4,
+ [21.1.3.2]/2,
+ [23.*]'s foo::iterator,
+ [27.*]'s foo::*_type,
+ others... + Nope, these types are called implementation-defined because you + shouldn't be taking advantage of their underlying types. Listing them + here would defeat the purpose. :-)

[21.1.3.1]/5 I don't really know about the mbstate_t + stuff... see the chapter 22 notes for what does exist.

[22.*] Anything and everything we have on locale + implemenation will be described + over here.

[26.2.8]/9 I have no idea what + complex<T>'s pow(0,0) returns.

[27.4.2.4]/2 Calling + std::ios_base::sync_with_stdio after I/O has already been + performed on the standard stream objects will + flush the buffers, and + destroy and recreate the underlying buffer instances. Whether or not + the previously-written I/O is destroyed in this process depends mostly + on the --enable-libio choice: for stdio, if the written data is + already in the stdio buffer, the data may be completely safe!

I/O sentry ctor/dtor They can perform additional work + than the minimum required. I don't think we're currently taking + advantage of this yet. +

[27.7.1.3]/16,
+ [27.8.1.4]/10 + The effects of pubsetbuf/setbuf are described + in this chapter. +

[27.8.1.4]/16 Calling fstream::sync when + a get area exists will... whatever fflush() does, I think.

Return to top of page or to the FAQ. diff --git a/libstdc++-v3/include/bits/stl_map.h b/libstdc++-v3/include/bits/stl_map.h index 7c00699..8ca6bed 100644 --- a/libstdc++-v3/include/bits/stl_map.h +++ b/libstdc++-v3/include/bits/stl_map.h @@ -1,6 +1,6 @@ // Map implementation -*- C++ -*- -// Copyright (C) 2001 Free Software Foundation, Inc. +// Copyright (C) 2001, 2002 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 @@ -66,6 +66,14 @@ namespace std { +/** + * @brief A standard container made up of pairs (see std::pair in ) + * which can be retrieved based on a key. + * + * This is an associative container. Values contained within it can be + * quickly retrieved through a key element. Example: MyMap["First"] would + * return the data associated with the key "First". +*/ template , class _Alloc = allocator > > class map @@ -81,7 +89,7 @@ public: typedef _Tp mapped_type; typedef pair value_type; typedef _Compare key_compare; - + class value_compare : public binary_function { friend class map<_Key,_Tp,_Compare,_Alloc>; @@ -95,7 +103,7 @@ public: }; private: - typedef _Rb_tree, key_compare, _Alloc> _Rep_type; _Rep_type _M_t; // red-black tree representing map public: @@ -133,7 +141,7 @@ public: operator=(const map<_Key, _Tp, _Compare, _Alloc>& __x) { _M_t = __x._M_t; - return *this; + return *this; } // accessors: @@ -142,17 +150,73 @@ public: value_compare value_comp() const { return value_compare(_M_t.key_comp()); } allocator_type get_allocator() const { return _M_t.get_allocator(); } + /** + * Returns a read/write iterator that points to the first pair in the map. + * Iteration is done in ascending order according to the keys. + */ iterator begin() { return _M_t.begin(); } + + /** + * Returns a read-only (constant) iterator that points to the first pair + * in the map. Iteration is done in ascending order according to the keys. + */ const_iterator begin() const { return _M_t.begin(); } + + /** + * Returns a read/write iterator that points one past the last pair in the + * map. Iteration is done in ascending order according to the keys. + */ iterator end() { return _M_t.end(); } + + /** + * Returns a read-only (constant) iterator that points one past the last + * pair in the map. Iteration is done in ascending order according to the + * keys. + */ const_iterator end() const { return _M_t.end(); } + + /** + * Returns a read/write reverse iterator that points to the last pair in + * the map. Iteration is done in descending order according to the keys. + */ reverse_iterator rbegin() { 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. + */ const_reverse_iterator rbegin() const { return _M_t.rbegin(); } + + /** + * Returns a read/write reverse iterator that points to one before the + * first pair in the map. Iteration is done in descending order according + * to the keys. + */ reverse_iterator rend() { return _M_t.rend(); } + + /** + * Returns a read-only (constant) reverse iterator that points to one + * before the first pair in the map. Iteration is done in descending order + * according to the keys. + */ const_reverse_iterator rend() const { return _M_t.rend(); } + + /** Returns true if the map is empty. (Thus begin() would equal end().) */ bool empty() const { return _M_t.empty(); } + /** Returns the size of the map. */ size_type size() const { return _M_t.size(); } + /** Returns the maximum size of the map. */ size_type max_size() const { return _M_t.max_size(); } + + /** + * @brief Subscript ( [] ) access to map data. + * @param k The key for which data should be retrieved. + * Allows for easy lookup with the subscript ( [] ) operator. Returns the + * data associated with the key specified in subscript. If the key does + * not exist a pair with that key is created with a default value, which + * is then returned. + */ _Tp& operator[](const key_type& __k) { iterator __i = lower_bound(__k); // __i->first is greater than or equivalent to __k. @@ -160,44 +224,216 @@ public: __i = insert(__i, value_type(__k, _Tp())); return (*__i).second; } + void swap(map<_Key,_Tp,_Compare,_Alloc>& __x) { _M_t.swap(__x._M_t); } // insert/erase - - pair insert(const value_type& __x) + /** + * @brief Attempts to insert a std::pair into the map. + * @param x Pair to be inserted (see std::make_pair for easy creation of + * pairs). + * @return A pair of which the first element is an iterator that points + * to the possibly inserted pair, a second element of type bool + * to show if the pair was actually inserted. + * + * This function attempts to insert a (key, value) pair into the map. A + * map relies on unique keys and thus a pair is only inserted if its first + * element (the key) is not already present in the map. + */ + pair insert(const value_type& __x) { return _M_t.insert_unique(__x); } + + /** + * @brief Attempts to insert a std::pair into the map. + * @param position An iterator that serves as a hint as to where the + * pair should be inserted. + * @param x Pair to be inserted (see std::make_pair for easy creation of + * pairs). + * @return An iterator that points to the inserted (key,value) pair. + * + * This function is not concerned about whether the insertion took place + * or not 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. + */ iterator insert(iterator position, const value_type& __x) { return _M_t.insert_unique(position, __x); } + + /** + * @brief A template function that attemps to insert elements from + * another range (possibly another map). + * @param first Iterator pointing to the start of the range to be inserted. + * @param last Iterator pointing to the end of the range. + */ template void insert(_InputIterator __first, _InputIterator __last) { _M_t.insert_unique(__first, __last); } + /** + * @brief Erases an element from a map. + * @param position An iterator pointing to the element to be erased. + * + * This function erases an element, pointed to by the given iterator, from + * a map. 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. That is the user's responsibilty. + */ void erase(iterator __position) { _M_t.erase(__position); } + + /** + * @brief Erases an element according to the provided key. + * @param x Key of element to be erased. + * @return Doc me! + * + * This function erases an element, located by the given key, from a map. + * 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. That 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 map. + * @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 map. + * 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. That is the user's responsibilty. + */ void erase(iterator __first, iterator __last) { _M_t.erase(__first, __last); } + + /** Erases all elements in a map. */ void clear() { _M_t.clear(); } // map operations: + /** + * @brief Tries to locate an element in a map. + * @param x Key of (key, value) pair 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 pair. If unsuccessful it returns the + * one past the end ( end() ) iterator. + */ iterator find(const key_type& __x) { return _M_t.find(__x); } + + /** + * @brief Tries to locate an element in a map. + * @param x Key of (key, value) pair to be located. + * @return Read-only (constant) 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 a constant iterator + * pointing to the sought after pair. If unsuccessful it returns the + * one past the end ( end() ) iterator. + */ const_iterator find(const key_type& __x) const { return _M_t.find(__x); } + + /** + * @brief Finds the number of elements with given key. + * @param x Key of (key, value) pairs to be located. + * @return Number of elements with specified key. + * + * This function only makes sense for multimaps. + */ size_type count(const key_type& __x) const { - return _M_t.find(__x) == _M_t.end() ? 0 : 1; + return _M_t.find(__x) == _M_t.end() ? 0 : 1; } + + /** + * @brief Finds the beginning of a subsequence matching given key. + * @param x Key of (key, value) pair to be located. + * @return Iterator pointing to first element matching given key, or + * end() if not found. + * + * This function is useful only with std::multimap. It 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); } + + /** + * @brief Finds the beginning of a subsequence matching given key. + * @param x Key of (key, value) pair to be located. + * @return Read-only (constant) iterator pointing to first element + * matching given key, or end() if not found. + * + * This function is useful only with std::multimap. It returns the first + * element of a subsequence of elements that matches the given key. If + * unsuccessful the iterator will point to the next greatest element or, + * if no such greater element exists, to end(). + */ const_iterator lower_bound(const key_type& __x) const { - return _M_t.lower_bound(__x); + return _M_t.lower_bound(__x); } + + /** + * @brief Finds the end of a subsequence matching given key. + * @param x Key of (key, value) pair to be located. + * @return Iterator pointing to last element matching given key. + * + * This function only makes sense with multimaps. + */ iterator upper_bound(const key_type& __x) {return _M_t.upper_bound(__x); } + + /** + * @brief Finds the end of a subsequence matching given key. + * @param x Key of (key, value) pair to be located. + * @return Read-only (constant) iterator pointing to last element matching + * given key. + * + * This function only makes sense with multimaps. + */ const_iterator upper_bound(const key_type& __x) const { - return _M_t.upper_bound(__x); + return _M_t.upper_bound(__x); } - + + /** + * @brief Finds a subsequence matching given key. + * @param x Key of (key, value) pairs to be located. + * @return Pair of iterators that possibly points to the subsequence + * matching given key. + * + * This function improves on lower_bound() and upper_bound() by giving a more + * elegant and efficient solution. It returns a pair of which the first + * element possibly points to the first element matching the given key + * and the second element possibly points to the last element matching the + * given key. If unsuccessful the first element of the returned pair will + * contain an iterator pointing to the next greatest element or, if no such + * greater element exists, to end(). + * + * This function only makes sense for multimaps. + */ pair equal_range(const key_type& __x) { return _M_t.equal_range(__x); } + + /** + * @brief Finds a subsequence matching given key. + * @param x Key of (key, value) pairs to be located. + * @return Pair of read-only (constant) iterators that possibly points to + * the subsequence matching given key. + * + * This function improves on lower_bound() and upper_bound() by giving a more + * elegant and efficient solution. It returns a pair of which the first + * element possibly points to the first element matching the given key + * and the second element possibly points to the last element matching the + * given key. If unsuccessful the first element of the returned pair will + * contain an iterator pointing to the next greatest element or, if no such + * a greater element exists, to end(). + * + * This function only makes sense for multimaps. + */ pair equal_range(const key_type& __x) const { return _M_t.equal_range(__x); } @@ -211,43 +447,43 @@ public: }; template -inline bool operator==(const map<_Key,_Tp,_Compare,_Alloc>& __x, +inline bool operator==(const map<_Key,_Tp,_Compare,_Alloc>& __x, const map<_Key,_Tp,_Compare,_Alloc>& __y) { return __x._M_t == __y._M_t; } template -inline bool operator<(const map<_Key,_Tp,_Compare,_Alloc>& __x, +inline bool operator<(const map<_Key,_Tp,_Compare,_Alloc>& __x, const map<_Key,_Tp,_Compare,_Alloc>& __y) { return __x._M_t < __y._M_t; } template -inline bool operator!=(const map<_Key,_Tp,_Compare,_Alloc>& __x, +inline bool operator!=(const map<_Key,_Tp,_Compare,_Alloc>& __x, const map<_Key,_Tp,_Compare,_Alloc>& __y) { return !(__x == __y); } template -inline bool operator>(const map<_Key,_Tp,_Compare,_Alloc>& __x, +inline bool operator>(const map<_Key,_Tp,_Compare,_Alloc>& __x, const map<_Key,_Tp,_Compare,_Alloc>& __y) { return __y < __x; } template -inline bool operator<=(const map<_Key,_Tp,_Compare,_Alloc>& __x, +inline bool operator<=(const map<_Key,_Tp,_Compare,_Alloc>& __x, const map<_Key,_Tp,_Compare,_Alloc>& __y) { return !(__y < __x); } template -inline bool operator>=(const map<_Key,_Tp,_Compare,_Alloc>& __x, +inline bool operator>=(const map<_Key,_Tp,_Compare,_Alloc>& __x, const map<_Key,_Tp,_Compare,_Alloc>& __y) { return !(__x < __y); } template -inline void swap(map<_Key,_Tp,_Compare,_Alloc>& __x, +inline void swap(map<_Key,_Tp,_Compare,_Alloc>& __x, map<_Key,_Tp,_Compare,_Alloc>& __y) { __x.swap(__y); } diff --git a/libstdc++-v3/include/std/std_fstream.h b/libstdc++-v3/include/std/std_fstream.h index 7de9f30..4483e3f 100644 --- a/libstdc++-v3/include/std/std_fstream.h +++ b/libstdc++-v3/include/std/std_fstream.h @@ -48,7 +48,7 @@ #include #include -namespace std +namespace std { template class basic_filebuf : public basic_streambuf<_CharT, _Traits> @@ -60,7 +60,7 @@ namespace std typedef typename traits_type::int_type int_type; typedef typename traits_type::pos_type pos_type; typedef typename traits_type::off_type off_type; - + // Non-standard Types: typedef basic_streambuf __streambuf_type; typedef basic_filebuf __filebuf_type; @@ -79,7 +79,7 @@ namespace std // Current and beginning state type for codecvt. __state_type _M_state_cur; - __state_type _M_state_beg; + __state_type _M_state_beg; // MT lock inherited from libio or other low-level io library. __c_lock _M_lock; @@ -87,46 +87,46 @@ namespace std // Set iff _M_buf is allocated memory from _M_allocate_internal_buffer.. bool _M_buf_allocated; - // XXX Needed? - bool _M_last_overflowed; - + // XXX Needed? + bool _M_last_overflowed; + public: // Constructors/destructor: basic_filebuf(); // Non-standard ctor: - basic_filebuf(__c_file_type* __f, ios_base::openmode __mode, + basic_filebuf(__c_file_type* __f, ios_base::openmode __mode, int_type __s = static_cast(BUFSIZ)); - + // Non-standard member: int fd(); - virtual - ~basic_filebuf() - { + virtual + ~basic_filebuf() + { this->close(); _M_last_overflowed = false; } // Members: - bool + bool is_open(void) const { return _M_file ? _M_file->is_open() : false; } - - __filebuf_type* + + __filebuf_type* open(const char* __s, ios_base::openmode __mode); - - __filebuf_type* + + __filebuf_type* close(void); protected: - void + void _M_allocate_internal_buffer(); - void + void _M_destroy_internal_buffer(); - void + void _M_allocate_pback_buffer(); // Create __file_type object and initialize it properly. @@ -134,17 +134,17 @@ namespace std _M_allocate_file(); // Overridden virtual functions: - virtual streamsize + virtual streamsize showmanyc(void); - - // Stroustrup, 1998, p. 628 + + // Stroustrup, 1998, p. 628 // underflow() and uflow() functions are called to get the next // charater from the real input source when the buffer is empty. // Buffered input uses underflow() - virtual int_type + virtual int_type underflow(void); - virtual int_type + virtual int_type pbackfail(int_type __c = _Traits::eof()); // NB: For what the standard expects of the overflow function, @@ -155,7 +155,7 @@ namespace std // this in actuality be a helper function that checks for the // eccentricities of this implementation, and then call // overflow() if indeed the buffer is full. - virtual int_type + virtual int_type overflow(int_type __c = _Traits::eof()); // Stroustrup, 1998, p 648 @@ -163,23 +163,23 @@ namespace std // real output destination when the buffer is full. A call to // overflow(c) outputs the contents of the buffer plus the // character c. - // 27.5.2.4.5 + // 27.5.2.4.5 // Consume some sequence of the characters in the pending sequence. - int_type + int_type _M_really_overflow(int_type __c = _Traits::eof()); - - virtual __streambuf_type* + + virtual __streambuf_type* setbuf(char_type* __s, streamsize __n); - - virtual pos_type + + virtual pos_type seekoff(off_type __off, ios_base::seekdir __way, ios_base::openmode __mode = ios_base::in | ios_base::out); - virtual pos_type + virtual pos_type seekpos(pos_type __pos, ios_base::openmode __mode = ios_base::in | ios_base::out); - virtual int + virtual int sync(void) { bool __testput = _M_out_cur && _M_out_beg < _M_out_end; @@ -197,14 +197,14 @@ namespace std _M_really_overflow(); _M_file->seekpos(__cur + __off); } - _M_last_overflowed = false; + _M_last_overflowed = false; return 0; } - - virtual void + + virtual void imbue(const locale& __loc); - virtual streamsize + virtual streamsize xsgetn(char_type* __s, streamsize __n) { streamsize __ret = 0; @@ -224,20 +224,24 @@ namespace std __ret += __streambuf_type::xsgetn(__s, __n - __ret); return __ret; } - - virtual streamsize + + virtual streamsize xsputn(const char_type* __s, streamsize __n) { _M_pback_destroy(); return __streambuf_type::xsputn(__s, __n); } - + void _M_output_unshift(); }; + // 27.8.1.5 Template class basic_ifstream + /** + * Derivation of general input streams, specific to files. + */ template class basic_ifstream : public basic_istream<_CharT, _Traits> { @@ -252,52 +256,69 @@ namespace std // Non-standard types: typedef basic_filebuf __filebuf_type; typedef basic_istream __istream_type; - + private: __filebuf_type _M_filebuf; public: // Constructors/Destructors: + /** Default constructor. Create an input file stream. */ basic_ifstream() : __istream_type(NULL), _M_filebuf() { this->init(&_M_filebuf); } - explicit + /** + * @brief Create an input file stream. + * @param s Null terminated string specifying filename. + * @param mode Open file in specified mode (see std::ios_base). + * + * Tip: When using std::string to hold the filename, you must use + * .c_str() before passing it to this constructor. + */ + explicit basic_ifstream(const char* __s, ios_base::openmode __mode = ios_base::in) : __istream_type(NULL), _M_filebuf() - { - this->init(&_M_filebuf); - this->open(__s, __mode); + { + this->init(&_M_filebuf); + this->open(__s, __mode); } - + ~basic_ifstream() { } // Members: - __filebuf_type* - rdbuf() const + /** + * @brief Get a pointer to the file stream's buffer. + * @return Pointer to basic_filebuf. + */ + __filebuf_type* + rdbuf() const { return const_cast<__filebuf_type*>(&_M_filebuf); } - bool + bool is_open(void) { return _M_filebuf.is_open(); } - void + void open(const char* __s, ios_base::openmode __mode = ios_base::in) - { + { if (_M_filebuf.open(__s, __mode | ios_base::in) == NULL) - this->setstate(ios_base::failbit); + this->setstate(ios_base::failbit); } - void + /** Close the file. */ + void close(void) - { + { if (!_M_filebuf.close()) - this->setstate(ios_base::failbit); + this->setstate(ios_base::failbit); } }; - + // 27.8.1.8 Template class basic_ofstream + /** + * Derivation of general output streams, specific to files. + */ template class basic_ofstream : public basic_ostream<_CharT,_Traits> { @@ -312,54 +333,83 @@ namespace std // Non-standard types: typedef basic_filebuf __filebuf_type; typedef basic_ostream __ostream_type; - + private: __filebuf_type _M_filebuf; public: // Constructors: + /** Default constructor for output file_stream. */ basic_ofstream() : __ostream_type(NULL), _M_filebuf() { this->init(&_M_filebuf); } - - explicit - basic_ofstream(const char* __s, + + /** + * @brief Create an output stream. + * @param s Null terminated string specifying filename. + * @param mode Open file in specified mode (see std::ios_base). + * + * Tip: When using std::string to hold the filename, you must use + * .c_str() before passing it to this constructor. + */ + explicit + basic_ofstream(const char* __s, ios_base::openmode __mode = ios_base::out|ios_base::trunc) : __ostream_type(NULL), _M_filebuf() - { - this->init(&_M_filebuf); - this->open(__s, __mode); + { + this->init(&_M_filebuf); + this->open(__s, __mode); } ~basic_ofstream() { } // Members: - __filebuf_type* + /** + * @brief Get a pointer to the file stream's buffer. + * @return Pointer to basic_filebuf. + */ + __filebuf_type* rdbuf(void) const { return const_cast<__filebuf_type*>(&_M_filebuf); } - - bool + + /** + * @brief Query to see if file stream is open. + * @return True if stream is open. + */ + bool is_open(void) { return _M_filebuf.is_open(); } - void - open(const char* __s, + /** + * @brief Specify a file to open for output. + * @param s Null terminated string specifying filename. + * @param mode Mode in which to open file (see std::ios_base). + * + * Tip: When using std::string to hold the filename, you must use + * .c_str() before passing it to this constructor. + */ + void + open(const char* __s, ios_base::openmode __mode = ios_base::out | ios_base::trunc) - { + { if (!_M_filebuf.open(__s, __mode | ios_base::out)) - this->setstate(ios_base::failbit); + this->setstate(ios_base::failbit); } - void + /** Close the file stream. */ + void close(void) - { + { if (!_M_filebuf.close()) - this->setstate(ios_base::failbit); + this->setstate(ios_base::failbit); } }; // 27.8.1.11 Template class basic_fstream + /** + * Derivation of general input/output streams, specific to files. + */ template class basic_fstream : public basic_iostream<_CharT, _Traits> { @@ -378,46 +428,72 @@ namespace std private: __filebuf_type _M_filebuf; - + public: // Constructors/destructor: + /** Default constructor. Create a file stream. */ basic_fstream() : __iostream_type(NULL), _M_filebuf() { this->init(&_M_filebuf); } - explicit + /** + * @brief Create an input/output stream. + * @param s Null terminated string specifying filename. + * @param mode Open file in specified mode (see std::ios_base). + * + * Tip: When using std::string to hold the filename, you must use + * .c_str() before passing it to this constructor. + */ + explicit basic_fstream(const char* __s, ios_base::openmode __mode = ios_base::in | ios_base::out) : __iostream_type(NULL), _M_filebuf() - { - this->init(&_M_filebuf); - this->open(__s, __mode); + { + this->init(&_M_filebuf); + this->open(__s, __mode); } - + ~basic_fstream() { } - + // Members: - __filebuf_type* - rdbuf(void) const + /** + * @brief Get a pointer to the file stream's buffer. + * @return Pointer to basic_filebuf. + */ + __filebuf_type* + rdbuf(void) const { return const_cast<__filebuf_type*>(&_M_filebuf); } - bool + /** + * @brief Query to see if file stream is open. + * @return True if stream is open. + */ + bool is_open(void) { return _M_filebuf.is_open(); } - void - open(const char* __s, + /** + * @brief Specify a file to open for input and/or output. + * @param s Null terminated string specifying filename. + * @param mode Mode in which to open file (see std::ios_base). + * + * Tip: When using std::string to hold the filename, you must use + * .c_str() before passing it to this constructor. + */ + void + open(const char* __s, ios_base::openmode __mode = ios_base::in | ios_base::out) - { + { if (!_M_filebuf.open(__s, __mode)) - setstate(ios_base::failbit); + setstate(ios_base::failbit); } - void + /** Close the file stream. */ + void close(void) - { + { if (!_M_filebuf.close()) - setstate(ios_base::failbit); + setstate(ios_base::failbit); } }; } // namespace std @@ -429,4 +505,4 @@ namespace std #endif #endif -#endif +#endif -- 2.7.4