C++ output stream for GIO streams.
More...
#include <c++-gtk-utils/gstream.h>
template<class charT, class Traits = std::char_traits<charT>>
class Cgu::basic_gostream< charT, Traits >
C++ output stream for GIO streams.
- See also
- gstreams
This class provides standard ostream services for GIO output streams.
◆ basic_gostream() [1/3]
template<class charT , class Traits = std::char_traits<charT>>
This class cannot be copied. The copy constructor is deleted.
◆ basic_gostream() [2/3]
template<class charT , class Traits = std::char_traits<charT>>
The constructor taking a GIO output stream. This class does not offer concurrent access from multiple threads to the same stream object, and if that is required users should provide their own synchronisation.
- Parameters
-
| stream | A GIO output stream to be attached. If the caller wants the output stream to survive this class's destruction or a call to close() or attach(), the caller should keep a separate GobjHandle object which references the stream (obtained by, say, calling get_gio_stream()) and pass 'manage' as false. If this is a GFilterOutputStream object (that is, a GBufferedOutputStream, GConverterOutputStream or GDataOutputStream stream), only the underlying base output stream will be attached and the other higher level streams will be closed (buffering and converting are controlled solely by the set_buffered() method and 'converter' argument). |
| manage | Whether the underlying streambuffer should call g_output_stream_close() on the GIO stream in the streambuffer's destructor or when another stream is attached. Passing 'true' is usually what is wanted, and is particularly relevant on output streams because unless g_output_stream_close() is called, GIO may not commit to disk - 'false' only makes sense if the caller keeps a separate GobjHandle object which references the stream to keep it alive (obtained by, say, calling get_gio_stream()). Unlike its fdstreams equivalent, this parameter does not have a default value of 'true': this is partly to make it less likely that a converter is passed to this argument by mistake (that would not normally cause a compiler warning because GobjHandle has a type conversion operator providing the underlying C object by pointer, so GobjHandles are type convertible to pointers, and such a pointer will in turn provide a type match with a bool argument); and partly because, given a GOutputStream* p, the construction "Cgu::gostream str(Cgu::GobjHandle<GOutputStream>(p));" without an additional argument or additional parentheses (or the use of uniform initializer syntax using braces) would cause a compiler error as it would be interpreted as a function declaration. |
| converter | A converter (if any) to be attached to the GIO output stream. The default value of an empty GobjHandle<GConverter> object indicates no converter. |
- Exceptions
-
| std::bad_alloc | This constructor will throw std::bad_alloc if memory is exhausted and the system throws on such exhaustion (unless the library has been installed using the --with-glib-memory-slices-compat or --with-glib-memory-slices-no-compat configuration option, in which case glib will terminate the program if it is unable to obtain memory from the operating system). No other exception will be thrown unless the constructor of std::basic_streambuf or std::basic_ostream throws. |
- Note
- If a converter is provided, the stream will no longer be seekable even if it otherwise would be, so tellp() and seekp() will no longer work (they will return pos_type(off_type(-1)).
◆ basic_gostream() [3/3]
template<class charT , class Traits = std::char_traits<charT>>
With this constructor, the GIO output stream must be attached later with the attach() method. It will not throw unless the default constructor of std::basic_streambuf or std::basic_ostream throws. This class does not offer concurrent access from multiple threads to the same stream object, and if that is required users should provide their own synchronisation.
◆ attach()
template<class charT , class Traits = std::char_traits<charT>>
Attach a new GIO output stream to this object (and close any GIO stream at present managed by it). If output buffering was previously switched off, it is switched back on again. If any stream state flags were set (eofbit, failbit or badbit), they will be cleared by a call to clear(). If this method closes a stream at present managed by it and the close fails, failbit is not set and no exception will be thrown. Accordingly, if the user needs to know whether there was an error in this method closing any managed stream, she should call close() explicitly before calling this method. This class does not offer concurrent access from multiple threads to the same stream object, and if that is required users should provide their own synchronisation.
- Parameters
-
| stream | A GIO output stream to be attached. If the caller wants the GIO output stream to survive a subsequent call to close() or attach() or this class's destruction, the caller should keep a separate GobjHandle object which references the stream (obtained by, say, calling get_gio_stream()) and pass 'manage' as false. If this is a GFilterOutputStream object (that is, a GBufferedOutputStream, GConverterOutputStream or GDataOutputStream stream), only the underlying base output stream will be attached and the other higher level streams will be closed (buffering and converting are controlled solely by the set_buffered() method and 'converter' argument). |
| manage | Whether the underlying streambuffer should call g_output_stream_close() on the GIO stream in the streambuffer's destructor or when another stream is attached. Passing 'true' is usually what is wanted, and is particularly relevant on output streams because unless g_output_stream_close() is called, GIO may not commit to disk - 'false' only makes sense if the caller keeps a separate GobjHandle object which references the stream to keep it alive (obtained by, say, calling get_gio_stream()). Unlike its fdstreams equivalent, this parameter does not have a default value of 'true': this is partly to make it less likely that a converter is passed to this argument by mistake (that would not normally cause a compiler warning because GobjHandle has a type conversion operator providing the underlying C object by pointer, so GobjHandles are type convertible to pointers, and such a pointer will in turn provide a type match with a bool argument); and partly to maintain compatibility with the constructor's interface, which has separate syntactic constraints. |
| converter | A converter (if any) to be attached to the GIO output stream. The default value of an empty GobjHandle<GConverter> object indicates no converter. |
- Exceptions
-
| std::bad_alloc | This method will throw std::bad_alloc if memory is exhausted and the system throws on such exhaustion (unless the library has been installed using the --with-glib-memory-slices-compat or --with-glib-memory-slices-no-compat configuration option, in which case glib will terminate the program if it is unable to obtain memory from the operating system). |
- Note
- If a converter is provided, the stream will no longer be seekable even if it otherwise would be, so tellp() and seekp() will no longer work (they will return pos_type(off_type(-1)).
◆ can_seek()
template<class charT , class Traits = std::char_traits<charT>>
This method indicates whether the attached GIO output stream implements GSeekable, so that a call to tellp() or seekp() can succeed. Note that in the seekp(off_type off, ios_base::seekdir dir) variant, on wide character streams the 'off' argument is dimensioned as the number of wchar_t/char32_t/char16_t units not the number of bytes (that is, it is bytes/sizeof(char_type)). This method does not throw. This class does not offer concurrent access from multiple threads to the same stream object, and if that is required users should provide their own synchronisation.
- Returns
- true if the attached GIO stream implements GSeekable, otherwise false. The result is only meaningful if a GIO stream has been attached to this C++ stream object.
◆ close()
template<class charT , class Traits = std::char_traits<charT>>
Call g_output_stream_close() on the GIO stream at present attached (if any), and release the underlying C++ streambuffer's reference to that stream. If the caller wants the GIO stream to survive the call to this method (albeit in a closed state), the caller should, before the call is made, keep a separate GobjHandle object which references the stream. If the close fails, the failbit will be set with setstate(std::ios_base::failbit). This class does not offer concurrent access from multiple threads to the same stream object, and if that is required users should provide their own synchronisation.
- Exceptions
-
| std::ios_base::failure | This exception will be thrown if an error arises on closing the stream and such an exception has been required by a call to the exceptions() method of this class (inherited from std::basic_ios<>). No exception will be thrown if exceptions() has not been called. |
◆ get_gio_stream()
template<class charT , class Traits = std::char_traits<charT>>
Get the GIO output stream at present attached (if any), by GobjHandle. If no stream has been attached, this method will return an empty GobjHandle object. Retaining the return value will cause the GIO output stream to survive the destruction of this object. The return value may be a different stream from the one originally passed to this object's constructor or to attach(). It will be different if a converter has been attached to it. This method does not throw. This class does not offer concurrent access from multiple threads to the same stream object, and if that is required users should provide their own synchronisation.
- Returns
- The GIO output stream at present attached, or an empty GobjHandle object if none has been attached
◆ is_error()
template<class charT , class Traits = std::char_traits<charT>>
This method reports the error status of any attached GIO output stream, and is intended to be called where failbit or badbit has been set. It can be useful for interpreting conversion errors on converting streams where one of those bits is set. This class does not offer concurrent access from multiple threads to the same stream object, and if that is required users should provide their own synchronisation.
- Returns
- NULL if no output stream is attached, or it is not in an error state. If an attached output stream is in an error state, say because it is a converting output stream which has encountered a conversion error, the most recent GError object emitted by a write operation on it is returned. Ownership of the return value is retained, so if it is intended to be used after the next write operation, it should be copied using g_error_copy().
Since 2.0.5
◆ operator=()
template<class charT , class Traits = std::char_traits<charT>>
This class cannot be copied. The copy assignment operator is deleted.
◆ set_buffered()
template<class charT , class Traits = std::char_traits<charT>>
This method converts the attached GIO output stream to an unbuffered stream for output if 'buffered' is false, or back to a buffered stream if buffering has previously been switched off and 'buffered' is true. Buffering is on by default for any newly created gostream object and any newly attached GIO output stream. If buffering is turned off, all characters at present in the buffers which are stored for output are flushed (but if writing to a file which is being written over/replaced, output may not appear in the destination until the GIO stream is closed). This method has no effect if no GIO output stream has yet been attached. Switching output buffering off is similar in effect to setting the std::ios_base::unitbuf flag, but is slightly more efficient. This class does not offer concurrent access from multiple threads to the same stream object, and if that is required users should provide their own synchronisation.
- Parameters
-
| buffered | 'false' if buffering is to be turned off, 'true' if it is to be turned back on. |
- Exceptions
-
| std::bad_alloc | This method will throw std::bad_alloc if 'buffered' is true, output buffering had previously been switched off, memory is exhausted and the system throws on such exhaustion (unless the library has been installed using the --with-glib-memory-slices-compat or --with-glib-memory-slices-no-compat configuration option, in which case glib will terminate the program if it is unable to obtain memory from the operating system). |
The documentation for this class was generated from the following file:
