C++ input-output stream for GIO streams.
More...
#include <c++-gtk-utils/gstream.h>
template<class charT, class Traits = std::char_traits<charT>>
class Cgu::basic_giostream< charT, Traits >
C++ input-output stream for GIO streams.
- See also
- gstreams
This class provides standard iostream services for GIO streams.
◆ basic_giostream() [1/3]
template<class charT , class Traits = std::char_traits<charT>>
This class cannot be copied. The copy constructor is deleted.
◆ basic_giostream() [2/3]
template<class charT , class Traits = std::char_traits<charT>>
The constructor taking a GIO input-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 input-output stream to be attached. If the caller wants the GIO 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_io_stream()) and pass 'manage' as false. |
| manage | Whether the underlying streambuffer should call g_io_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_io_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_io_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 GIOStream* p, the construction "Cgu::giostream str(Cgu::GobjHandle<GIOStream>(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. |
| input_converter | A converter (if any) to be attached to the input stream (note that this does not affect the operation of set_byteswap()). The default value of an empty GobjHandle<GConverter> object indicates no converter. |
| output_converter | A converter (if any) to be attached to the 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_iostream throws. |
- Note
- If a converter is provided, the stream will no longer be seekable even if it otherwise would be, so tellg(), tellp(), seekg() and seekp() will no longer work (they will return pos_type(off_type(-1)). If the stream to which a converter has been attached represents a file on the file system (rather than a socket), after a read has been made, no further write may be made using the same GFileIOStream object. These restrictions do not apply to sockets (which are not seekable) so the use of converters with input-output streams (GIOStream) should generally be restricted to sockets.
◆ basic_giostream() [3/3]
template<class charT , class Traits = std::char_traits<charT>>
With this constructor, the GIO input-output stream must be attached later with the attach() method. It will not throw unless the constructor of std::basic_streambuf or std::basic_iostream 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 input-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. In the case of wide character input-output streams, it also switches off byte swapping on input, if it was previously on. 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 input-output stream to be attached. If the caller wants the GIO 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_io_stream()) and pass 'manage' as false. |
| manage | Whether the underlying streambuffer should call g_io_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_io_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_io_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. |
| input_converter | A converter (if any) to be attached to the input stream (note that this does not affect the operation of set_byteswap()). The default value of an empty GobjHandle<GConverter> object indicates no converter. |
| output_converter | A converter (if any) to be attached to the 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 tellg(), tellp(), seekg() and seekp() will no longer work (they will return pos_type(off_type(-1)). If the stream to which a converter has been attached represents a file on the file system (rather than a socket), after a read has been made, no further write may be made using the same GFileIOStream object. These restrictions do not apply to sockets (which are not seekable) so the use of converters with input-output streams (GIOStream) should generally be restricted to sockets.
◆ can_seek()
template<class charT , class Traits = std::char_traits<charT>>
This method indicates whether the attached GIO stream implements GSeekable, so that a call to tellg(), tellp(), seekg() or seekp() can succeed. Note that in the seekg(off_type off, ios_base::seekdir dir) and seekp(off_type off, ios_base::seekdir dir) variants, 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_io_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_input_stream()
template<class charT , class Traits = std::char_traits<charT>>
Get the GIO input stream at present attached (if any), by GobjHandle. If none has been attached, this method will return an empty GobjHandle object. Retaining the return value will cause the GIO input stream to survive the destruction of this object. The return value may be a different stream from the one kept by the GIOStream object 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 input stream at present attached, or an empty GobjHandle object if none has been attached
◆ get_gio_io_stream()
template<class charT , class Traits = std::char_traits<charT>>
Get the GIO input-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 input-output stream to survive the destruction of this object. 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 input-output stream at present attached, or an empty GobjHandle object if none has been attached
◆ get_gio_output_stream()
template<class charT , class Traits = std::char_traits<charT>>
Get the underlying GIO output stream at present attached (if any), by GobjHandle. If none 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 kept by the GIOStream object 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_input_error()
template<class charT , class Traits = std::char_traits<charT>>
This method reports the error status of any attached GIO input stream, and is intended to be called where failbit has been set. It can be useful for establishing, where that bit is set, whether failbit indicates normal end-of-file or a conversion error on a converting 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.
- Returns
- NULL if no input stream is attached, or it is not in an error state. If an attached input stream is in an error state, say because it is a converting input stream which has encountered a conversion error, the most recent GError object emitted by a read operation on it is returned. Ownership of the return value is retained, so if it is intended to be used after the next read operation, it should be copied using g_error_copy().
Since 2.0.5
◆ is_output_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_byteswap()
template<class charT , class Traits = std::char_traits<charT>>
Causes the underlying streambuffer to swap bytes in the incoming text, so as to convert big endian text to little endian text, or little endian text to big endian text. It is called by the user in response to finding a byte order marker (BOM) 0xfffe (UTF-16) or 0xfffe0000 (UTF-32) as the first character of a newly opened file/stream, or if the user knows by some other means that the native endianness of the machine doing the reading differs from the endianness of the file/stream being read. This only has effect on wide character streams for input (for example, a wgiostream object), and not the giostream narrow character stream. Note also that characters held for output are always outputted in native endian format unless a GConverter object has been attached, and this method does not affect that. 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.
- Parameters
-
| swap | 'true' if byte swapping for input is to be turned on, 'false' if it is to be turned off. This will affect all characters extracted from the underlying streambuffer after this call is made. If a previously extracted character is to be putback(), it must be put back before this function is called (or unget() should be called instead) to avoid a putback mismatch, because this call will byte-swap anything already in the buffers. (Characters extracted after the call to this method may be putback normally.) |
◆ set_output_buffered()
template<class charT , class Traits = std::char_traits<charT>>
This method converts the attached GIO input-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 giostream object and any newly attached GIO input-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 input-output stream has yet been attached. Switching output buffering off is similar in effect to setting the std::ios_base::unitbuf flag, except that switching buffering off is slightly more efficient, and setting the std::ios_base::unitbuf flag will not retain the automatic tying of logical and actual file positions that occurs when output buffering is switched off, as explained here. 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 for output 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:
