C++ stream buffer for GIO streams.
More...
#include <c++-gtk-utils/gstream.h>
|
| | basic_gstreambuf (const basic_gstreambuf &)=delete |
| |
| basic_gstreambuf & | operator= (const basic_gstreambuf &)=delete |
| |
| | basic_gstreambuf () |
| |
| | basic_gstreambuf (const GobjHandle< GInputStream > &input_stream_, bool manage_, const GobjHandle< GConverter > &converter_=GobjHandle< GConverter >()) |
| |
| | basic_gstreambuf (const GobjHandle< GOutputStream > &output_stream_, bool manage_, const GobjHandle< GConverter > &converter_=GobjHandle< GConverter >()) |
| |
| | basic_gstreambuf (const GobjHandle< GIOStream > &io_stream_, bool manage_, const GobjHandle< GConverter > &input_converter_=GobjHandle< GConverter >(), const GobjHandle< GConverter > &output_converter_=GobjHandle< GConverter >()) |
| |
| virtual | ~basic_gstreambuf () |
| |
| void | attach_stream (const GobjHandle< GInputStream > &input_stream_, bool manage_, const GobjHandle< GConverter > &converter_=GobjHandle< GConverter >()) |
| |
| void | attach_stream (const GobjHandle< GOutputStream > &output_stream_, bool manage_, const GobjHandle< GConverter > &converter_=GobjHandle< GConverter >()) |
| |
| void | attach_stream (const GobjHandle< GIOStream > &io_stream_, bool manage_, const GobjHandle< GConverter > &input_converter_=GobjHandle< GConverter >(), const GobjHandle< GConverter > &output_converter_=GobjHandle< GConverter >()) |
| |
| bool | close_stream () |
| |
| GobjHandle< GInputStream > | get_istream () const |
| |
| GobjHandle< GOutputStream > | get_ostream () const |
| |
| GobjHandle< GIOStream > | get_iostream () const |
| |
| void | set_byteswap (bool swap) |
| |
| void | set_output_buffered (bool buffered) |
| |
| bool | can_seek () const |
| |
| GError * | is_input_error () |
| |
| GError * | is_output_error () |
| |
template<class charT, class Traits = std::char_traits<charT>>
class Cgu::basic_gstreambuf< charT, Traits >
C++ stream buffer for GIO streams.
- See also
- gstreams
This class provides a stream buffer for interfacing with GIO streams. It does the buffering for the basic_gostream, basic_gistream and basic_giostream stream classes.
◆ char_type
template<class charT , class Traits = std::char_traits<charT>>
◆ int_type
template<class charT , class Traits = std::char_traits<charT>>
◆ off_type
template<class charT , class Traits = std::char_traits<charT>>
◆ pos_type
template<class charT , class Traits = std::char_traits<charT>>
◆ traits_type
template<class charT , class Traits = std::char_traits<charT>>
◆ basic_gstreambuf() [1/5]
template<class charT , class Traits = std::char_traits<charT>>
This class cannot be copied. The copy constructor is deleted.
◆ basic_gstreambuf() [2/5]
template<class charT , class Traits = std::char_traits<charT>>
The default constructor: the GIO stream is attached later using the attach_stream() method. It will not throw unless the default constructor of std::basic_streambuf 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.
◆ basic_gstreambuf() [3/5]
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
-
| input_stream_ | A GIO input stream to be attached to the streambuffer. If the caller wants the input stream to survive this class's destruction or a call to close_stream() or attach_stream(), the caller should keep a separate GobjHandle object which references the stream (obtained by, say, calling get_istream()) 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 this C++ streambuffer, and converting is controlled solely by the 'converter_' argument). |
| manage_ | Whether the streambuffer should call g_input_stream_close() on the stream in its 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_istream()). 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::gstreambuf 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 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_gstreambuf() [4/5]
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
-
| output_stream_ | A GIO output stream to be attached to the streambuffer. If the caller wants the output stream to survive this class's destruction or a call to close_stream() or attach_stream(), the caller should keep a separate GobjHandle object which references the stream (obtained by, say, calling get_ostream()) 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_output_buffered() method and 'converter_' argument). |
| manage_ | Whether the streambuffer should call g_output_stream_close() on the stream in its 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_ostream()). 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::gstreambuf 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 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_gstreambuf() [5/5]
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
-
| io_stream_ | A GIO input-output stream to be attached to the streambuffer. If the caller wants the stream to survive this class's destruction or a call to close_stream() or attach_stream(), the caller should keep a separate GobjHandle object which references the stream (obtained by, say, calling get_iostream()) and pass 'manage_' as false. |
| manage_ | Whether the streambuffer should call g_io_stream_close() on the stream in its 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_iostream()). 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::gstreambuf 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 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_gstreambuf()
template<class charT , class Traits = std::char_traits<charT>>
The destructor does not throw.
◆ attach_stream() [1/3]
template<class charT , class Traits = std::char_traits<charT>>
Attach a new GIO input stream to the streambuffer (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. 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
-
| input_stream_ | The GIO input stream to be attached to the streambuffer. If the caller wants the input stream to survive a subsequent call to close_stream() or attach_stream() or this class's destruction, the caller should keep a separate GobjHandle object which references the stream (obtained by, say, calling get_istream()) 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 this C++ streambuffer, and converting is controlled solely by the 'converter_' argument). |
| manage_ | Whether the streambuffer should call g_input_stream_close() on the stream in its 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_istream()). 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)).
◆ attach_stream() [2/3]
template<class charT , class Traits = std::char_traits<charT>>
Attach a new GIO input-output stream to the streambuffer (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. 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
-
| io_stream_ | The GIO input-output stream to be attached to the streambuffer. If the caller wants the stream to survive a subsequent call to close_stream() or attach_stream() or this class's destruction, the caller should keep a separate GobjHandle object which references the stream (obtained by, say, calling get_iostream()) and pass 'manage_' as false. |
| manage_ | Whether the streambuffer should call g_io_stream_close() on the stream in its 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_iostream()). 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.
◆ attach_stream() [3/3]
template<class charT , class Traits = std::char_traits<charT>>
Attach a new GIO output stream to the streambuffer (and close any GIO stream at present managed by it). If output buffering was previously switched off, it is switched back on again. 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
-
| output_stream_ | The GIO output stream to be attached to the streambuffer. If the caller wants the output stream to survive a subsequent call to close_stream() or attach_stream() or this class's destruction, the caller should keep a separate GobjHandle object which references the stream (obtained by, say, calling get_ostream()) 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_output_buffered() method and 'converter_' argument). |
| manage_ | Whether the streambuffer should call g_output_stream_close() on the stream in its 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_ostream()). 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 stream implements GSeekable, so that a call to seekoff() or seekpos() can succeed. 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 random access is supported, otherwise false. The result is only meaningful if a GIO stream has been attached to this streambuffer.
◆ close_stream()
template<class charT , class Traits = std::char_traits<charT>>
Call g_input_stream_close(), g_output_stream_close() or g_io_stream_close(), as the case may be, on the GIO stream at present attached to the streambuffer (if any), and release the streambuffer's reference to that stream (the reference will be released even if an error arose in closing the 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. 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 close succeeded, false if an error arose (including in a case where no GIO stream has been attached or it has already been closed).
◆ get_iostream()
template<class charT , class Traits = std::char_traits<charT>>
Get the GIOStream input-output stream at present attached to the streambuffer (if any), by GobjHandle. If a GInputStream or GOutputStream object rather than a GIOStream object has been attached (or no stream has been attached) or it has been closed, then this method will return an empty GobjHandle object. Retaining the return value will cause the stream to survive a subsequent call to attach_stream() or 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 GIOStream stream at present attached to the streambuffer, or an empty GobjHandle object if none has been attached
◆ get_istream()
template<class charT , class Traits = std::char_traits<charT>>
Get the GIO input stream at present attached to the streambuffer (if any), by GobjHandle. If a GOutputStream object rather than a GInputStream or GIOStream object has been attached (or no stream has been attached) or it has been closed, then this method will return an empty GobjHandle object. If a GIOStream object has been attached, this streambuffer's maintained GInputStream object will be returned, which may be a converting stream manufactured from the GInputStream object maintained by the GIOStream object. Retaining the return value will cause the stream to survive a subsequent call to attach_stream() or 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 to the streambuffer, or an empty GobjHandle object if none has been attached
◆ get_ostream()
template<class charT , class Traits = std::char_traits<charT>>
Get the GIO output stream at present attached to the streambuffer (if any), by GobjHandle. If a GInputStream object rather than a GOutputStream or GIOStream object has been attached (or no stream has been attached) or it has been closed, then this method will return an empty GobjHandle object. If a GIOStream object has been attached, this streambuffer's maintained GOutputStream object will be returned, which may be a converting stream manufactured from the GOutputStream object maintained by the GIOStream object. Retaining the return value will cause the stream to survive a subsequent call to attach_stream() or 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 to the streambuffer, or an empty GobjHandle object if none has been attached
◆ is_input_error()
template<class charT , class Traits = std::char_traits<charT>>
This method indicates whether any attached GIO input stream is in an error state. It can be useful for detecting conversion errors on converting streams. 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 indicates whether any attached GIO output stream is in an error state. It can be useful for detecting conversion errors on converting streams. 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.
◆ overflow()
template<class charT , class Traits = std::char_traits<charT>>
This method will not throw unless std::basic_streambuf<>::sputc() throws, which it would not do on any sane implementation. This means that the output functions of stream objects which have this streambuffer as a member will not throw unless the underlying functions of the std::basic_ostream class throw, which they would not normally do unless they have been required to do so on failbit, badbit or eofbit being set by an explicit call to the exceptions() method of that class. 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.
◆ seekoff()
template<class charT , class Traits = std::char_traits<charT>>
This method provides random access on GIO streams that implement GSeekable, so supporting the tellg(), tellp(), seekg() and seekp() methods of the basic_gostream, basic_gistream and basic_giostream classes. Any output buffers will be flushed and if the seek succeeds any input buffers will be reset. This method does not throw, but if it returns pos_type(off_type(-1)) to indicate failure, it will cause the tellg(), tellp(), seekg() or seekp() methods of the relevant stream class to throw std::ios_base::failure if such an exception has been required by an explicit call to the exceptions() method of that class (but not otherwise). 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
-
| off | The offset to be applied to the 'way' argument when seeking. It is a signed integer type, and on wide character streams 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)). |
| way | The file position to which the 'off' argument is to be applied (either std::ios_base::beg, std::ios_base::cur or std::ios_base::end). |
| m | The type of GIO stream which must have been attached to this streambuffer for this method to attempt a seek. For GInputStream the argument should have the std::ios_base::in bit set, for GOutputStream it should have the std::ios_base::out bit set and for GIOStream it should have either (or both) set. Provided the relevant bit is set, it doesn't matter if others are also set. However if, with a GIOStream object, both the std::ios_base::in and std::ios_base::out bits are set, a seek on both input and output streams will be attempted, unless the 'way' argument is std::ios_base::cur, in which case a seek on the output stream only will be attempted. (Note that the only GIOStream which at present supports seeking is GFileIOStream, and because filesystem files only have one file pointer, which is used for both input and output, both input seeking and output seeking have the same result and affect both streams.) As the tellg() and seekg() stream methods only pass std::ios_base::in, and the tellp() and seekp() methods only std::ios_base::out, these will always produce the expected result, and for GIOStream streams tellg() will be indistinguishable in effect from tellp(), and seekg() from seekp(). |
- Returns
- If the seek succeeds, a std::char_traits<T>::pos_type object representing the new stream position of the streambuffer after the seek. (This type is std::streampos for narrow character (char) streams, std::wstreampos for wide character (wchar_t) streams, std::u16streampos for the char16_t type and std::u32streampos for the char32_t type.) If the seek failed, pos_type(off_type(-1)) is returned. If a seek is made on a GIOStream object with both std::ios_base::in and std::ios_base::out set and a 'way' argument of std::ios_base::beg or std::ios_base::end, the result of the seek which succeeds is returned, or if both succeed, the result of the output seek is returned. (Note that the only GIOStream which at present supports seeking is GFileIOStream, and because files only have one file pointer, which is used for both input and output, both input seeking and output seeking have the same result and affect both streams.)
◆ seekpos()
template<class charT , class Traits = std::char_traits<charT>>
This method provides random access on GIO streams that implement GSeekable, so supporting the seekg() and seekp() methods of the basic_gostream, basic_gistream and basic_giostream classes. It is equivalent to seekoff(off_type(p), std::ios_base::beg, m). Any output buffers will be flushed and if the seek succeeds any input buffers will be reset. This method does not throw, but if it returns pos_type(off_type(-1)) to indicate failure, it will cause the seekg() or seekp() methods of the relevant stream class to throw std::ios_base::failure if such an exception has been required by an explicit call to the exceptions() method of that class (but not otherwise). 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
-
| p | The absolute position to which the seek is to be made, obtained by a previous call to seekoff() or to this method. |
| m | The type of GIO stream which must have been attached to this streambuffer for this method to attempt a seek. For GInputStream the argument should have the std::ios_base::in bit set, for GOutputStream it should have the std::ios_base::out bit set and for GIOStream it should have either (or both) set. Provided the relevant bit is set, it doesn't matter if others are also set. However if, with a GIOStream object, both the std::ios_base::in and std::ios_base::out bits are set, a seek on both input and output streams will be attempted. (Note that the only GIOStream which at present supports seeking is GFileIOStream, and because filesystem files only have one file pointer, which is used for both input and output, both input seeking and output seeking have the same result and affect both streams.) As the seekg() stream method only passes std::ios_base::in, and the seekp() method only std::ios_base::out, these will always produce the expected result, and seekg() will be indistinguishable in effect from seekp(). |
- Returns
- If the seek succeeds, a std::char_traits<T>::pos_type object representing the new stream position of the streambuffer after the seek. (This type is std::streampos for narrow character (char) streams, std::wstreampos for wide character (wchar_t) streams, std::u16streampos for the char16_t type and std::u32streampos for the char32_t type.) If the seek failed, pos_type(off_type(-1)) is returned.
◆ set_byteswap()
template<class charT , class Traits = std::char_traits<charT>>
Causes the streambuffer to swap bytes in 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 streambuffers for input (for example, a wgstreambuf to which a GInputStream or GIOStream object has been attached), and not the gstreambuf narrow character stream buffer. Note 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>>
If the GIO stream attached to this object is GOutputStream or GIOStream, this method converts it 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 gstreambuf object and any newly attached GIO output stream or 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 from this streambuffer may not appear in the destination until the GIO stream is closed). This method has no effect if no GIO output stream or input-output stream has yet been attached to this streambuffer. Switching output buffering off is similar in effect to setting the std::ios_base::unitbuf flag in the relevant gostream or giostream object, 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 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). |
◆ sync()
template<class charT , class Traits = std::char_traits<charT>>
This method will 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.
◆ underflow()
template<class charT , class Traits = std::char_traits<charT>>
This method will not throw. This means that the input functions of stream objects which have this streambuffer as a member will not throw unless the underlying functions of the std::basic_istream class throw, which they would not normally do unless they have been required to do so on failbit, badbit or eofbit being set by an explicit call to the exceptions() method of that class. 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.
◆ xsgetn()
template<class charT , class Traits = std::char_traits<charT>>
This method will not throw. This means that the input functions of stream objects which have this streambuffer as a member will not throw unless the underlying functions of the std::basic_istream class throw, which they would not normally do unless they have been required to do so on failbit, badbit or eofbit being set by an explicit call to the exceptions() method of that class. 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.
◆ xsputn()
template<class charT , class Traits = std::char_traits<charT>>
This method will not throw. This means that the output functions of stream objects which have this streambuffer as a member will not throw unless the underlying functions of the std::basic_ostream class throw, which they would not normally do unless they have been required to do so on failbit, badbit or eofbit being set by an explicit call to the exceptions() method of that class. 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.
The documentation for this class was generated from the following file:
