C++ input stream for GIO streams.
More...
#include <c++-gtk-utils/gstream.h>
template<class charT, class Traits = std::char_traits<charT>>
class Cgu::basic_gistream< charT, Traits >
C++ input stream for GIO streams.
- See also
- gstreams
This class provides standard istream services for GIO input streams.
◆ basic_gistream() [1/3]
template<class charT , class Traits = std::char_traits<charT>>
This class cannot be copied. The copy constructor is deleted.
◆ basic_gistream() [2/3]
template<class charT , class Traits = std::char_traits<charT>>
The constructor taking a GIO input 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 stream to be attached. If the caller wants the GIO input 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 GFilterInputStream object (that is, a GBufferedInputStream or GConverterInputStream stream), only the underlying base input stream will be attached and the other higher level streams will be closed (buffering of input streams is always provided by the underlying C++ streambuffer, and converting is controlled solely by the 'converter' argument). |
| manage | Whether the underlying streambuffer should call g_input_stream_close() on the GIO stream in the streambuffer's destructor or when another stream is attached. Passing 'true' is usually what is wanted - '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 GInputStream* p, the construction "Cgu::gistream str(Cgu::GobjHandle<GInputStream>(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 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. |
- 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_istream throws. |
- Note
- If a converter is provided, the stream will no longer be seekable even if it otherwise would be, so tellg() and seekg() will no longer work (they will return pos_type(off_type(-1)).
◆ basic_gistream() [3/3]
template<class charT , class Traits = std::char_traits<charT>>
With this constructor, the GIO input stream must be attached later with the attach() method. It will not throw unless the default constructor of std::basic_streambuf or std::basic_istream 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 stream to this object (and close any GIO stream at present managed by it). In the case of wide character input streams, it also switches off byte swapping, 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 stream to be attached. If the caller wants the GIO input 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 GFilterInputStream object (that is, a GBufferedInputStream or GConverterInputStream stream), only the underlying base input stream will be attached and the other higher level streams will be closed (buffering of input streams is always provided by the underlying C++ streambuffer, and converting is controlled solely by the 'converter' argument). |
| manage | Whether the underlying streambuffer should call g_input_stream_close() on the GIO stream in the streambuffer's destructor or when another stream is attached. Passing 'true' is usually what is wanted - '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 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. |
- 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() and seekg() 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 input stream implements GSeekable, so that a call to tellg() or seekg() can succeed. Note that in the seekg(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_input_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 input 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 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 input 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 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
◆ 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 example, a wgistream object), and not the gistream narrow character stream. 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 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.) |
The documentation for this class was generated from the following file:
