summaryrefslogtreecommitdiff
path: root/libstdc++-v3
diff options
context:
space:
mode:
authorJerry Quinn <jlquinn@optonline.net>2003-07-11 14:25:09 +0000
committerJerry Quinn <jlquinn@gcc.gnu.org>2003-07-11 14:25:09 +0000
commite2fcbaa3e4dbd4eb5184bb03e570c44a5d0c52ab (patch)
treeb5db99e96736b15fbf1eeddb24fbe99aea8c8a4d /libstdc++-v3
parentfee226d25fc4af5f577cb05386e44e2dd0aa8fc6 (diff)
downloadgcc-e2fcbaa3e4dbd4eb5184bb03e570c44a5d0c52ab.tar.gz
basic_ios.h (copyfmt): Document.
2003-07-11 Jerry Quinn <jlquinn@optonline.net> * include/bits/basic_ios.h (copyfmt): Document. * include/bits/ios_base.h (event, event_callback, register_callback, xalloc, iword, pword): Document. (imbue, ~ios_base): Update docs on callbacks. From-SVN: r69235
Diffstat (limited to 'libstdc++-v3')
-rw-r--r--libstdc++-v3/ChangeLog7
-rw-r--r--libstdc++-v3/include/bits/basic_ios.h10
-rw-r--r--libstdc++-v3/include/bits/ios_base.h72
3 files changed, 78 insertions, 11 deletions
diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog
index 19354844a80..dc28eafa12a 100644
--- a/libstdc++-v3/ChangeLog
+++ b/libstdc++-v3/ChangeLog
@@ -1,3 +1,10 @@
+2003-07-11 Jerry Quinn <jlquinn@optonline.net>
+
+ * include/bits/basic_ios.h (copyfmt): Document.
+ * include/bits/ios_base.h (event, event_callback, register_callback,
+ xalloc, iword, pword): Document.
+ (imbue, ~ios_base): Update docs on callbacks.
+
2003-07-11 Phil Edwards <pme@gcc.gnu.org>
* acinclude.m4 (GLIBCC_ENABLE_SYMVERS): Tweak comments. Add
diff --git a/libstdc++-v3/include/bits/basic_ios.h b/libstdc++-v3/include/bits/basic_ios.h
index f2e468e6abf..e017ddc08c2 100644
--- a/libstdc++-v3/include/bits/basic_ios.h
+++ b/libstdc++-v3/include/bits/basic_ios.h
@@ -319,7 +319,15 @@ namespace std
rdbuf(basic_streambuf<_CharT, _Traits>* __sb);
/**
- * @doctodo
+ * @brief Copies fields of __rhs into this.
+ * @param __rhs The source values for the copies.
+ * @return Reference to this object.
+ *
+ * All fields of __rhs are copied into this object except that rdbuf()
+ * and rdstate() remain unchanged. All values in the pword and iword
+ * arrays are copied. Before copying, each callback is invoked with
+ * erase_event. After copying, each (new) callback is invoked with
+ * copyfmt_event. The final step is to copy exceptions().
*/
basic_ios&
copyfmt(const basic_ios& __rhs);
diff --git a/libstdc++-v3/include/bits/ios_base.h b/libstdc++-v3/include/bits/ios_base.h
index 3cc4ac1fd33..db8f9c92525 100644
--- a/libstdc++-v3/include/bits/ios_base.h
+++ b/libstdc++-v3/include/bits/ios_base.h
@@ -371,7 +371,10 @@ namespace std
// Callbacks;
/**
- * @doctodo
+ * @brief The set of events that may be passed to an event callback.
+ *
+ * erase_event is used during ~ios() and copyfmt(). imbue_event is used
+ * during imbue(). copyfmt_event is used during copyfmt().
*/
enum event
{
@@ -381,12 +384,26 @@ namespace std
};
/**
- * @doctodo
+ * @brief The type of an event callback function.
+ * @param event One of the members of the event enum.
+ * @param ios_base Reference to the ios_base object.
+ * @param int The integer provided when the callback was registered.
+ *
+ * Event callbacks are user defined functions that get called during
+ * several ios_base and basic_ios functions, specifically imbue(),
+ * copyfmt(), and ~ios().
*/
typedef void (*event_callback) (event, ios_base&, int);
/**
- * @doctodo
+ * @brief Add the callback __fn with parameter __index.
+ * @param __fn The function to add.
+ * @param __index The integer to pass to the function when invoked.
+ *
+ * Registers a function as an event callback with an integer parameter to
+ * be passed to the function when invoked. Multiple copies of the
+ * function are allowed. If there are multiple callbacks, they are
+ * invoked in the order they were registered.
*/
void
register_callback(event_callback __fn, int __index);
@@ -621,8 +638,8 @@ namespace std
* @param loc The new locale.
* @return The previous locale.
*
- * Sets the new locale for this stream, and
- * [XXX does something with callbacks].
+ * Sets the new locale for this stream, and then invokes each callback
+ * with imbue_event.
*/
locale
imbue(const locale& __loc);
@@ -650,13 +667,34 @@ namespace std
// [27.4.2.5] ios_base storage functions
/**
- * @doctodo
+ * @brief Access to unique indices.
+ * @return An integer different from all previous calls.
+ *
+ * This function returns a unique integer every time it is called. It
+ * can be used for any purpose, but is primarily intended to be a unique
+ * index for the iword and pword functions. The expectation is that an
+ * application calls xalloc in order to obtain an index in the iword and
+ * pword arrays that can be used without fear of conflict.
+ *
+ * The implementation maintains a static variable that is incremented and
+ * returned on each invocation. xalloc is guaranteed to return an index
+ * that is safe to use in the iword and pword arrays.
*/
static int
xalloc() throw();
/**
- * @doctodo
+ * @brief Access to integer array.
+ * @param __ix Index into the array.
+ * @return A reference to an integer associated with the index.
+ *
+ * The iword function provides access to an array of integers that can be
+ * used for any purpose. The array grows as required to hold the
+ * supplied index. All integers in the array are initialized to 0.
+ *
+ * The implementation reserves several indices. You should use xalloc to
+ * obtain an index that is safe to use. Also note that since the array
+ * can grow dynamically, it is not safe to hold onto the reference.
*/
inline long&
iword(int __ix)
@@ -667,7 +705,17 @@ namespace std
}
/**
- * @doctodo
+ * @brief Access to void pointer array.
+ * @param __ix Index into the array.
+ * @return A reference to a void* associated with the index.
+ *
+ * The pword function provides access to an array of pointers that can be
+ * used for any purpose. The array grows as required to hold the
+ * supplied index. All pointers in the array are initialized to 0.
+ *
+ * The implementation reserves several indices. You should use xalloc to
+ * obtain an index that is safe to use. Also note that since the array
+ * can grow dynamically, it is not safe to hold onto the reference.
*/
inline void*&
pword(int __ix)
@@ -679,8 +727,12 @@ namespace std
// Destructor
/**
- * Destroys local storage and
- * [XXX does something with callbacks].
+ * Invokes each callback with erase_event. Destroys local storage.
+ *
+ * Note that the ios_base object for the standard streams never gets
+ * destroyed. As a result, any callbacks registered with the standard
+ * streams will not get invoked with erase_event (unless copyfmt is
+ * used).
*/
virtual ~ios_base();