c++-gtk-utils
gstream.h
Go to the documentation of this file.
1 /* Copyright (C) 2010 to 2012 Chris Vine
2 
3 
4 The library comprised in this file or of which this file is part is
5 distributed by Chris Vine under the GNU Lesser General Public
6 License as follows:
7 
8  This library is free software; you can redistribute it and/or
9  modify it under the terms of the GNU Lesser General Public License
10  as published by the Free Software Foundation; either version 2.1 of
11  the License, or (at your option) any later version.
12 
13  This library is distributed in the hope that it will be useful, but
14  WITHOUT ANY WARRANTY; without even the implied warranty of
15  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16  Lesser General Public License for more details.
17 
18  You should have received a copy of the GNU Lesser General Public
19  License, version 2.1, along with this library (see the file LGPL.TXT
20  which came with this source code package in the c++-gtk-utils
21  sub-directory); if not, write to the Free Software Foundation, Inc.,
22  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
23 
24 However, it is not intended that the object code of a program whose
25 source code instantiates a template from this file or uses macros or
26 inline functions (of any length) should by reason only of that
27 instantiation or use be subject to the restrictions of use in the GNU
28 Lesser General Public License. With that in mind, the words "and
29 macros, inline functions and instantiations of templates (of any
30 length)" shall be treated as substituted for the words "and small
31 macros and small inline functions (ten lines or less in length)" in
32 the fourth paragraph of section 5 of that licence. This does not
33 affect any other reason why object code may be subject to the
34 restrictions in that licence (nor for the avoidance of doubt does it
35 affect the application of section 2 of that licence to modifications
36 of the source code in this file).
37 */
38 
39 /**
40  * @defgroup gstreams gstreams
41  *
42  * \#include <c++-gtk-utils/gstream.h>
43  *
44  * The c++-gtk-utils library contains C++ classes providing a
45  * streambuffer and stream objects interfacing with GIO streams.
46  *
47  * Normally 'true' would be passed as the second (manage) argument of
48  * the gostream/gistream/giostream constructors or of the attach()
49  * methods, so that the destructors of these classes close the GIO
50  * streams concerned, which helps exception safety (the attach()
51  * method will also close any previous GIO stream). If this behaviour
52  * is not wanted, pass 'false' instead to that argument.
53  *
54  * C++ stream objects are not suitable for asynchronous input and
55  * output. On sockets and pipes or other special devices, they may
56  * block on a read or write until the read or write request has been
57  * satisfied. In circumstances where asynchronous input and output is
58  * wanted, it will be necessary to start a new thread in which to
59  * carry out the input and output operations (which is what GIO does
60  * behind the scenes on its asynchronous operations) or use the GIO
61  * interfaces directly.
62  *
63  * Here are some examples of use:
64  *
65  * @code
66  * // open file for input, another for output, and make the
67  * // output file a gzipped copy of the input (gzipping a
68  * // file doesn't get much easier than this)
69  * Cgu::gistream input;
70  * Cgu::gostream output;
71  * Cgu::GobjHandle<GFile> file_in(g_file_new_for_path("filename"));
72  * GFileInputStream* is = g_file_read(file_in, 0, 0);
73  * if (is)
74  * input.attach(Cgu::GobjHandle<GInputStream>(G_INPUT_STREAM(is)), // takes ownership of 'is'
75  * true);
76  * else {
77  * std::cerr << "Can't open file 'filename'" << std::endl;
78  * return;
79  * }
80  * Cgu::GobjHandle<GFile> file_out(g_file_new_for_path("filename.gz"));
81  * GFileOutputStream* os = g_file_replace(file_out, 0, false,
82  * G_FILE_CREATE_REPLACE_DESTINATION,
83  * 0, 0);
84  * if (os) {
85  * output.attach(Cgu::GobjHandle<GOutputStream>(G_OUTPUT_STREAM(os)), // takes ownership of 'os'
86  * true,
87  * Cgu::GobjHandle<GConverter>(
88  * G_CONVERTER(g_zlib_compressor_new(G_ZLIB_COMPRESSOR_FORMAT_GZIP, -1)))
89  * );
90  * }
91  * else {
92  * std::cerr << "Can't create file 'filename.gz'" << std::endl;
93  * return;
94  * }
95  * // this does the copying, and is shorthand for creating your own buffer
96  * // and calling std::istream::read() and std::ostream::write() on it
97  * output << input.rdbuf();
98  *
99  * --------------------------------------------------------------------
100  *
101  * // establish a TCP socket on localhost, listen for connections on port
102  * // 1200 and receive whitespace-separated words for processing
103  * using Cgu::GobjHandle;
104  * GobjHandle<GInetAddress> i(g_inet_address_new_loopback(G_SOCKET_FAMILY_IPV4));
105  * GobjHandle<GSocketAddress> a(g_inet_socket_address_new(i, 1200));
106  * GobjHandle<GSocketListener> l(g_socket_listener_new());
107  *
108  * gboolean success = g_socket_listener_add_address(l,
109  * a,
110  * G_SOCKET_TYPE_STREAM,
111  * G_SOCKET_PROTOCOL_TCP,
112  * 0, 0, 0);
113  * if (!success) {
114  * std::cerr << "Can't bind socket on localhost" << std::endl;
115  * return;
116  * }
117  *
118  * GSocketConnection* c = g_socket_listener_accept(l, 0, 0, 0);
119  * if (!c) {
120  * std::cerr << "Can't listen on localhost" << std::endl;
121  * return;
122  * }
123  *
124  * Cgu::giostream sock_strm(GobjHandle<GIOStream>(G_IO_STREAM(c)), true); // takes ownership of c
125  * sock_strm.set_output_buffered(false);
126  * std::cout << "Connection accepted" << std::endl;
127  *
128  * std::string str;
129  * while (sock_strm >> str) {
130  * [ ... do something with the word in str ... ]
131  * // acknowledge the client
132  * sock_strm << "ACK\n";
133  * }
134  *
135  * --------------------------------------------------------------------
136  *
137  * // read line delimited text from a pipe until it is closed by the
138  * // writer: assume 'fd' is the read file descriptor of the pipe
139  * // (in real life you would probably want to use a Cgu::fdistream
140  * // object in this usage and bypass GIO)
141  * Cgu::gistream istrm(Cgu::GobjHandle<GInputStream>(g_unix_input_stream_new(fd, true)), true);
142  * if (!istrm.get_gio_stream().get()) {
143  * std::cerr << "Can't create gio file-descriptor input stream" << std::endl;
144  * return;
145  * }
146  * std::string line;
147  * while (std::getline(istrm, line)) {
148  * [ ... do something with the read text ... ]
149  * }
150  * @endcode
151  *
152  *
153  * @note 1. Users cannot (except by derivation) use the virtual
154  * protected methods of the streambuffer classes, including xsgetn()
155  * and xsputn(). Instead, if they want direct access to the
156  * streambuffer other than through the gostream/gistream/giostream
157  * methods (or their wide stream equivalents), they should use the
158  * public forwarding functions provided by std::streambuf base class.
159  * @note 2. These streambuffers and stream objects are not copiable.
160  * @note 3. The base glib requirement for the c++-gtk-utils library is
161  * glib >= 2.10.0, but the gstreams component will only be available
162  * if glib >= 2.16.0 is installed.
163  *
164  * @b Buffering
165  *
166  * The classes implement buffering on input streams and (unless output
167  * buffering is switched off) on output streams. They implement the
168  * buffering internally and do not use GBufferedInputStream and
169  * GBufferedOutputStream. This has a number of efficiency advantages
170  * and also retains random access, on devices that support it, for
171  * buffered streams (GBufferedInputStream and GBufferedOutputStream do
172  * not do so). So far as concerns random access on GIOStream objects,
173  * which are opened for both read and write, see
174  * @ref GioRandomAccessAnchor "giostream and random access"
175  *
176  * The streambuf class provides a block read and write in xsgetn() and
177  * xsputn(), which will be called by the read() and write() methods
178  * (and some other output operators) inherited by (w)gistream,
179  * (w)gostream and (w)giostream from std::basic_istream and
180  * std::basic_ostream. They operate (after appropriately vacating and
181  * resetting the buffers) by doing a block read and write directly to
182  * and from the target, and are very efficient for large block reads
183  * (those significantly exceeding the buffer size). If users want all
184  * reads and writes to go through the buffers, by using
185  * std::basic_streambuf<>::xsputn() and
186  * std::basic_streambuf<>::xsgetn() then the symbol
187  * CGU_GSTREAM_USE_STD_N_READ_WRITE can be defined for the purpose
188  * before gstream.h is \#include'd. (libstdc++-3 provides efficient
189  * inbuilt versions of these std::basic_streambuf functions for block
190  * reads not significantly larger than the buffer size, provided
191  * output buffering has not been turned off by the
192  * set_output_buffered() method of these classes.)
193  *
194  * One possible case for defining that symbol is where the user wants
195  * to use the tie() method of (w)gistream or (w)giostream (inherited
196  * from std::basic_ios) to procure flushing of an output stream before
197  * extraction from an input stream is made by (w)gistream::read() or
198  * (w)giostream::read(). Such flushing might not occur where a call
199  * to read() is made unless CGU_GSTREAM_USE_STD_N_READ_WRITE is
200  * defined, because an implementation is permitted to defer such
201  * flushing until underflow() occurs, and the block read by read(), as
202  * forwarded to xsgetn(), will never invoke underflow() if that symbol
203  * is not defined. (Having said that, any basic_istream
204  * implementation which does defer output flushing until underflow()
205  * is called makes tie() unusable anyway for a number of purposes,
206  * because the time of flushing would become dependent on whether a
207  * read request can be satisfied by what is already in the buffers.)
208  *
209  * 4 characters are stored and available for putback. However, if the
210  * symbol CGU_GSTREAM_USE_STD_N_READ_WRITE is not defined, then a call
211  * to (w)gstreambuf::xsgetn() via (w)gistream::read() or
212  * (w)giostream::read() with a request for less than 4 characters will
213  * result in less than 4 characters available for putback (if these
214  * block read methods obtain some characters but less than 4, only the
215  * number of characters obtained by them is guaranteed to be available
216  * for putback).
217  *
218  * @anchor GioRandomAccessAnchor
219  * @b giostream @b and @b random @b access
220  *
221  * For GIO objects which implement GSeekable (which are GFileIOStream,
222  * GFileInputStream, GFileOutputStream, GMemoryInputStream and
223  * GMemoryOutputStream), the classes in this c++-gtk-utils library
224  * implement the tellg(), tellp(), seekg() and seekp() random access
225  * methods.
226  *
227  * The presence of buffering does not impede this where a stream is
228  * only opened for reading or only opened for writing. However, it
229  * presents complications if the giostream or wgiostream classes are
230  * used with a GFIleIOStream object (GFileIOStream objects are opened
231  * for both read and write). Because the classes employ buffering of
232  * input, and optional buffering of output, the logical file position
233  * (the file position expected by the user from the reads and writes
234  * she has made) will usually differ from the actual file position
235  * seen by the underlying operating system. The gstreambuf class
236  * provided by this library implements intelligent tying between input
237  * and output streams for GFileIOStream objects which means that if
238  * output has been made unbuffered by a call to
239  * set_output_buffered(false) and no converter has been attached, all
240  * reads and writes onto the file system from the same giostream
241  * object will be made at the expected logical position.
242  *
243  * This cannot be done by the gstreambuf class where the output stream
244  * is set as buffered (the default). In that case, if the last
245  * operation on a giostream or wgiostream object 'strm' was a read,
246  * before the first write operation thereafter is made on it, the user
247  * should call strm.seekg(strm.tellg()) or strm.seekp(strm.tellp())
248  * (the two have the same effect), in order to synchronise the logical
249  * and actual file positions, or if the user does not want to maintain
250  * the current logical file position, make some other call to seekg()
251  * or seekp() which does not comprise only seekg(0,
252  * std::ios_base::cur) or seekp(0, std::ios_base::cur). Many
253  * std::basic_iostream implementations, as inherited by
254  * Cgu::giostream, will synchronise positions automatically on
255  * seekable streams via their sentry objects in order to provide
256  * support for buffered random access on their std::basic_fstream
257  * class (gcc's libstdc++ library does this, for example), making
258  * these steps unnecessary, but following these steps will provide
259  * maximum portability. The same applies to the equivalent wide
260  * stream classes.
261  *
262  * If a GFileIOStream object attached to a giostream or wgiostream
263  * object is not seekable (that is, can_seek() returns false), say
264  * because an input or output converter has been attached or the
265  * filesystem is a network file system, no random access may be
266  * attempted. In particular, the tellg(), tellp(), seekg() and
267  * seekp() methods will not work (they will return
268  * pos_type(off_type(-1))). Furthermore, if a giostream or wgiostream
269  * object which manages a GFileIOStream object (as opposed to a
270  * socket) has a converter attached or is not seekable for some other
271  * reason, then after a read has been made no further write may be
272  * made using the same GFileIOStream object, so the use of converters
273  * with giostream or wgiostream objects should generally be restricted
274  * to use with sockets (GSocketConnection objects) only. Where
275  * converters are used with files on a filesystem, it is best to use
276  * the gostream and gistream classes (or their wide stream
277  * equivalents), and to close one stream before opening the other
278  * where they address the same file.
279  *
280  * None of these restrictions applies to GSocketConnection objects
281  * obtained by a call to g_socket_listener_accept() or
282  * g_socket_client_connect(), or obtained in some other way, as these
283  * do not maintain file pointers. They can be attached to a giostream
284  * or wgiostream object (with or without a converter) without any
285  * special precautions being taken, other than the normal step of
286  * calling giostream::flush() (or using the std::flush manipulator) to
287  * flush the output buffer to the socket if the user needs to know
288  * that that has happened (or setting output buffering off with the
289  * set_output_buffered() method). In summary, on a socket, a read
290  * does not automatically flush the output buffer: it is for the user
291  * to do that.
292  *
293  * @b Wide @b streams @b and @b endianness
294  *
295  * This library provides typedef'ed instances of the template classes
296  * for wchar_t, char16_t and char32_t characters. Unless a converter
297  * is attached (for, say, UTF-32LE to UTF-32BE, or vice versa), with
298  * these wide character classes wide characters are written out in the
299  * native endian format of the writing machine. Whether or not a
300  * converter from one endianness to another is attached, special steps
301  * need to be taken if the text which is sent for output might be read
302  * by machines of unknown endianness.
303  *
304  * No such special steps are required where the wide character classes
305  * are used with temporary files, pipes, fifos, unix domain sockets
306  * and network sockets on localhost, because in those cases they will
307  * be read by the same machine that writes; but they are required
308  * where sockets communicate with other computers over a network or
309  * when writing to files which may be distributed to and read by other
310  * computers with different endianness.
311  *
312  * Where wide characters are to be exported to other machines, one
313  * useful approach is to convert to and from UTF-8 with
314  * Utf8::uniwide_from_utf8(), Utf8::uniwide_to_utf8(),
315  * Utf8::wide_from_utf8() or Utf8::wide_to_utf8(), and to use
316  * gostream/gistream/giostream with the converted text, or to attach a
317  * converter for UTF-8, generated by GIO's g_charset_converter_new(),
318  * directly to a wgostream, wgistream or wgiostream object (or their
319  * char16_t and char32_t equivalents).
320  *
321  * Instead of converting exported text to UTF-8, another approach is
322  * to use a byte order marker (BOM) as the first character of the wide
323  * stream output. UCS permits a BOM character to be inserted,
324  * comprising static_cast<wchar_t>(0xfeff),
325  * static_cast<char16_t>(0xfeff) or static_cast<char32_t>(0xfeff), at
326  * the beginning of the output to the wide character stream. At the
327  * receiving end, this will appear as 0xfffe (UTF-16) or 0xfffe0000
328  * (UTF-32) to a big endian machine with 8 bit char type if the text
329  * is little endian, or to a little endian machine with big endian
330  * text, so signaling a need to undertake byte swapping of text read
331  * from the stream. Another alternative is to label the physical
332  * medium conveying the file as UTF-16LE, UTF-16BE, UTF-32LE or
333  * UTF-32BE, as the case may be, in which case a BOM character should
334  * not be prepended.
335  *
336  * Where it is established by either means that the input stream
337  * requires byte swapping, the wide character input stream and wide
338  * character input streambuffer classes have a set_byteswap() member
339  * function which should be called on opening the input stream as soon
340  * as it has been established that byte swapping is required. Once
341  * this function has been called with an argument of 'true', all
342  * further calls to stream functions which provide characters will
343  * provide those characters with the correct native endianness.
344  * Calling set_byteswap() on the narrow stream gistream, giostream and
345  * gstreambuf objects has no effect (byte order is irrelevant to
346  * narrow streams).
347  *
348  * Here is an example of such use in a case where sizeof(wchar_t) is
349  * 4:
350  *
351  * @code
352  * using Cgu::GobjHandle;
353  * Cgu::wgistream input;
354  * GobjHandle<GFile> file_in(g_file_new_for_path("filename"));
355  * GFileInputStream* is = g_file_read(file_in, 0, 0);
356  * if (is)
357  * input.attach(GobjHandle<GInputStream>(G_INPUT_STREAM(is)), true); // takes ownership of 'is'
358  * else {
359  * std::cerr << "Can't open file 'filename'"
360  * << std::endl;
361  * return;
362  * }
363  * wchar_t item;
364  * input.get(item);
365  * if (!input) {
366  * std::cerr << "File 'filename' is empty" << std::endl;
367  * return;
368  * }
369  * if (item == static_cast<wchar_t>(0xfffe0000))
370  * input.set_byteswap(true);
371  * else if (item != static_cast<wchar_t>(0xfeff)) {
372  * // calling set_byteswap() will manipulate the buffers, so
373  * // either call putback() before we call set_byteswap(), or
374  * // call unget() instead
375  * input.putback(item);
376  * // the first character is not a BOM character so assume big endian
377  * // format, and byte swap if the local machine is little endian
378  * #if G_BYTE_ORDER == G_LITTLE_ENDIAN
379  * input.set_byteswap(true);
380  * #endif
381  * }
382  * [ ... do something with the input file ... ]
383  * @endcode
384  *
385  * @b Other @b wide @b stream @b issues
386  *
387  * basic_gostream, basic_gistream, basic_giostream and
388  * basic_gstreambuf objects can be instantiated for any integer type
389  * which has an appropriate traits class provided for it which has
390  * the copy(), eof(), eq_int_type(), move(), not_eof() and
391  * to_int_type() static member functions. The integer type could in
392  * fact have any size, but the set_byteswap() methods for
393  * basic_gistream, basic_giostream and basic_gstreambuf will only
394  * have an effect if its size is either 2 or 4. Typedef'ed instances
395  * of the classes are provided by the library for characters of type
396  * wchar_t, char16_t and char32_t.
397  *
398  * @b gtkmm @b users
399  *
400  * gtkmm/giomm does not provide C++ streams for GIO objects: instead,
401  * it provides a literal function-for-function wrapping. However,
402  * giomm users can use the stream classes provided by this library by
403  * converting the relevant Glib::RefPtr object to a Cgu::GobjHandle
404  * object. This can be done as follows:
405  *
406  * @code
407  * // Glib::RefPtr<Gio::InputStream> to Cgu::GobjHandle<GInputStream>
408  * inline
409  * Cgu::GobjHandle<GInputStream> giomm_input_convert(const Glib::RefPtr<Gio::InputStream>& in) {
410  * return Cgu::GobjHandle<GInputStream>(static_cast<GInputStream*>(g_object_ref(in.operator->()->gobj())));
411  * }
412  *
413  * // Glib::RefPtr<Gio::OutputStream> to Cgu::GobjHandle<GOutputStream>
414  * inline
415  * Cgu::GobjHandle<GOutputStream> giomm_output_convert(const Glib::RefPtr<Gio::OutputStream>& out) {
416  * return Cgu::GobjHandle<GOutputStream>(static_cast<GOutputStream*>(g_object_ref(out.operator->()->gobj())));
417  * }
418  *
419  * // Glib::RefPtr<Gio::IOStream> to Cgu::GobjHandle<GIOStream>
420  * inline
421  * Cgu::GobjHandle<GIOStream> giomm_io_convert(const Glib::RefPtr<Gio::IOStream>& io) {
422  * return Cgu::GobjHandle<GIOStream>(static_cast<GIOStream*>(g_object_ref(io.operator->()->gobj())));
423  * }
424  *
425  * // example printing a text file to stdout with file opened with giomm
426  * Glib::RefPtr<Gio::File> file = Gio::File::create_for_path("filename");
427  * Glib::RefPtr<Gio::InputStream> is = file->read();
428  *
429  * Cgu::gistream filein(giomm_input_convert(is), true);
430  *
431  * std::string line;
432  * while (std::getline(filein, line)) {
433  * std::cout << line << '\n';
434  * }
435  * @endcode
436  */
437 
438 #ifndef CGU_GSTREAM_H
439 #define CGU_GSTREAM_H
440 
441 #include <glib.h>
442 
443 #if defined(DOXYGEN_PARSING) || GLIB_CHECK_VERSION(2,16,0)
444 
445 // see above for what this does
446 //#define CGU_GSTREAM_USE_STD_N_READ_WRITE 1
447 
448 #include <istream>
449 #include <ostream>
450 #include <streambuf>
451 #include <algorithm>
452 #include <string>
453 #include <cstddef>
454 
455 #include <glib.h>
456 #include <glib-object.h>
457 #include <gio/gio.h>
458 
463 
464 namespace Cgu {
465 
466 /*
467 The following convenience typedefs appear at the end of this file:
468 typedef basic_gstreambuf<char> gstreambuf;
469 typedef basic_gistream<char> gistream;
470 typedef basic_gostream<char> gostream;
471 typedef basic_giostream<char> giostream;
472 typedef basic_gstreambuf<wchar_t> wgstreambuf;
473 typedef basic_gistream<wchar_t> wgistream;
474 typedef basic_gostream<wchar_t> wgostream;
475 typedef basic_giostream<wchar_t> wgiostream;
476 typedef basic_gstreambuf<char16_t> u16gstreambuf;
477 typedef basic_gistream<char16_t> u16gistream;
478 typedef basic_gostream<char16_t> u16gostream;
479 typedef basic_giostream<char16_t> u16giostream;
480 typedef basic_gstreambuf<char32_t> u32gstreambuf;
481 typedef basic_gistream<char32_t> u32gistream;
482 typedef basic_gostream<char32_t> u32gostream;
483 typedef basic_giostream<char32_t> u32giostream;
484 */
485 
486 
487 /**
488  * @headerfile gstream.h c++-gtk-utils/gstream.h
489  * @brief C++ stream buffer for GIO streams
490  * @sa gstreams
491  * @ingroup gstreams
492  *
493  * This class provides a stream buffer for interfacing with GIO
494  * streams. It does the buffering for the basic_gostream,
495  * basic_gistream and basic_giostream stream classes.
496  */
497 
498 template <class charT , class Traits = std::char_traits<charT> >
499 class basic_gstreambuf: public std::basic_streambuf<charT, Traits> {
500 
501 public:
502  typedef charT char_type;
503  typedef Traits traits_type;
504  typedef typename traits_type::int_type int_type;
505  typedef typename traits_type::pos_type pos_type;
506  typedef typename traits_type::off_type off_type;
507 
508 private:
509  GobjHandle<GInputStream> input_stream;
510  GobjHandle<GOutputStream> output_stream;
511  GobjHandle<GIOStream> io_stream;
512 
513  bool manage;
514  bool byteswap;
515  bool seek_mismatch;
516  bool seekable;
517 
518  static const int output_buf_size = 1024; // size of the data write buffer
519  static const int putback_size = 4; // size of read putback area
520  static const int input_buf_size = 1024; // size of the data read buffer
521 
522 #if defined(CGU_USE_GLIB_MEMORY_SLICES_COMPAT) || defined(CGU_USE_GLIB_MEMORY_SLICES_NO_COMPAT)
527 #else
528  ScopedHandle<char_type*> input_buffer;
529  ScopedHandle<char_type*> output_buffer;
530 #endif
531 
532  static void swap_element(char_type&);
533  GobjHandle<GInputStream> find_base_input_stream(const GobjHandle<GInputStream>&);
534  GobjHandle<GOutputStream> find_base_output_stream(const GobjHandle<GOutputStream>&);
535  void reset_input_buffer_pointers();
536  int flush_buffer();
537  bool wind_back_input_buffer();
538  bool is_input_stored();
539  bool is_output_stored();
540  void set_input_error(GError*);
541  void set_output_error(GError*);
542 
543 protected:
544 /**
545  * This method will not throw. This means that the input functions of
546  * stream objects which have this streambuffer as a member will not
547  * throw unless the underlying functions of the std::basic_istream
548  * class throw, which they would not normally do unless they have been
549  * required to do so on failbit, badbit or eofbit being set by an
550  * explicit call to the exceptions() method of that class. This class
551  * does not offer concurrent access from multiple threads to the same
552  * stream object, and if that is required users should provide their
553  * own synchronisation.
554  */
555  virtual int_type underflow();
556 
557 /**
558  * This method will not throw. This class does not offer concurrent
559  * access from multiple threads to the same stream object, and if that
560  * is required users should provide their own synchronisation.
561  */
562  virtual int sync();
563 
564 /**
565  * This method will not throw unless std::basic_streambuf<>::sputc()
566  * throws, which it would not do on any sane implementation. This
567  * means that the output functions of stream objects which have this
568  * streambuffer as a member will not throw unless the underlying
569  * functions of the std::basic_ostream class throw, which they would
570  * not normally do unless they have been required to do so on failbit,
571  * badbit or eofbit being set by an explicit call to the exceptions()
572  * method of that class. This class does not offer concurrent access
573  * from multiple threads to the same stream object, and if that is
574  * required users should provide their own synchronisation.
575  */
576  virtual int_type overflow(int_type);
577 #ifndef CGU_GSTREAM_USE_STD_N_READ_WRITE
578 /**
579  * This method will not throw. This means that the input functions of
580  * stream objects which have this streambuffer as a member will not
581  * throw unless the underlying functions of the std::basic_istream
582  * class throw, which they would not normally do unless they have been
583  * required to do so on failbit, badbit or eofbit being set by an
584  * explicit call to the exceptions() method of that class. This class
585  * does not offer concurrent access from multiple threads to the same
586  * stream object, and if that is required users should provide their
587  * own synchronisation.
588  */
589  virtual std::streamsize xsgetn(char_type*, std::streamsize);
590 
591 /**
592  * This method will not throw. This means that the output functions
593  * of stream objects which have this streambuffer as a member will not
594  * throw unless the underlying functions of the std::basic_ostream
595  * class throw, which they would not normally do unless they have been
596  * required to do so on failbit, badbit or eofbit being set by an
597  * explicit call to the exceptions() method of that class. This class
598  * does not offer concurrent access from multiple threads to the same
599  * stream object, and if that is required users should provide their
600  * own synchronisation.
601  */
602  virtual std::streamsize xsputn(const char_type*, std::streamsize);
603 #endif
604 /**
605  * This method provides random access on GIO streams that implement
606  * GSeekable, so supporting the tellg(), tellp(), seekg() and seekp()
607  * methods of the basic_gostream, basic_gistream and basic_giostream
608  * classes. Any output buffers will be flushed and if the seek
609  * succeeds any input buffers will be reset. This method does not
610  * throw, but if it returns pos_type(off_type(-1)) to indicate
611  * failure, it will cause the tellg(), tellp(), seekg() or seekp()
612  * methods of the relevant stream class to throw
613  * std::ios_base::failure if such an exception has been required by an
614  * explicit call to the exceptions() method of that class (but not
615  * otherwise). This class does not offer concurrent access from
616  * multiple threads to the same stream object, and if that is required
617  * users should provide their own synchronisation.
618  *
619  * @param off The offset to be applied to the 'way' argument when
620  * seeking. It is a signed integer type, and on wide character
621  * streams is dimensioned as the number of wchar_t/char32_t/char16_t
622  * units not the number of bytes (that is, it is
623  * bytes/sizeof(char_type)).
624  *
625  * @param way The file position to which the 'off' argument is to be
626  * applied (either std::ios_base::beg, std::ios_base::cur or
627  * std::ios_base::end).
628  *
629  * @param m The type of GIO stream which must have been attached to
630  * this streambuffer for this method to attempt a seek. For
631  * GInputStream the argument should have the std::ios_base::in bit
632  * set, for GOutputStream it should have the std::ios_base::out bit
633  * set and for GIOStream it should have either (or both) set.
634  * Provided the relevant bit is set, it doesn't matter if others are
635  * also set. However if, with a GIOStream object, both the
636  * std::ios_base::in and std::ios_base::out bits are set, a seek on
637  * both input and output streams will be attempted, unless the 'way'
638  * argument is std::ios_base::cur, in which case a seek on the output
639  * stream only will be attempted. (Note that the only GIOStream which
640  * at present supports seeking is GFileIOStream, and because
641  * filesystem files only have one file pointer, which is used for both
642  * input and output, both input seeking and output seeking have the
643  * same result and affect both streams.) As the tellg() and seekg()
644  * stream methods only pass std::ios_base::in, and the tellp() and
645  * seekp() methods only std::ios_base::out, these will always produce
646  * the expected result, and for GIOStream streams tellg() will be
647  * indistinguishable in effect from tellp(), and seekg() from seekp().
648  *
649  * @return If the seek succeeds, a std::char_traits<T>::pos_type
650  * object representing the new stream position of the streambuffer
651  * after the seek. (This type is std::streampos for narrow character
652  * (char) streams, std::wstreampos for wide character (wchar_t)
653  * streams, std::u16streampos for the char16_t type and
654  * std::u32streampos for the char32_t type.) If the seek failed,
655  * pos_type(off_type(-1)) is returned. If a seek is made on a
656  * GIOStream object with both std::ios_base::in and std::ios_base::out
657  * set and a 'way' argument of std::ios_base::beg or
658  * std::ios_base::end, the result of the seek which succeeds is
659  * returned, or if both succeed, the result of the output seek is
660  * returned. (Note that the only GIOStream which at present supports
661  * seeking is GFileIOStream, and because files only have one file
662  * pointer, which is used for both input and output, both input
663  * seeking and output seeking have the same result and affect both
664  * streams.)
665  */
666  virtual pos_type seekoff(off_type off,
667  std::ios_base::seekdir way,
668  std::ios_base::openmode m = std::ios_base::in | std::ios_base::out);
669 
670 /**
671  * This method provides random access on GIO streams that implement
672  * GSeekable, so supporting the seekg() and seekp() methods of the
673  * basic_gostream, basic_gistream and basic_giostream classes. It is
674  * equivalent to seekoff(off_type(p), std::ios_base::beg, m). Any
675  * output buffers will be flushed and if the seek succeeds any input
676  * buffers will be reset. This method does not throw, but if it
677  * returns pos_type(off_type(-1)) to indicate failure, it will cause
678  * the seekg() or seekp() methods of the relevant stream class to
679  * throw std::ios_base::failure if such an exception has been required
680  * by an explicit call to the exceptions() method of that class (but
681  * not otherwise). This class does not offer concurrent access from
682  * multiple threads to the same stream object, and if that is required
683  * users should provide their own synchronisation.
684  *
685  * @param p The absolute position to which the seek is to be made,
686  * obtained by a previous call to seekoff() or to this method.
687  *
688  * @param m The type of GIO stream which must have been attached to
689  * this streambuffer for this method to attempt a seek. For
690  * GInputStream the argument should have the std::ios_base::in bit
691  * set, for GOutputStream it should have the std::ios_base::out bit
692  * set and for GIOStream it should have either (or both) set.
693  * Provided the relevant bit is set, it doesn't matter if others are
694  * also set. However if, with a GIOStream object, both the
695  * std::ios_base::in and std::ios_base::out bits are set, a seek on
696  * both input and output streams will be attempted. (Note that the
697  * only GIOStream which at present supports seeking is GFileIOStream,
698  * and because filesystem files only have one file pointer, which is
699  * used for both input and output, both input seeking and output
700  * seeking have the same result and affect both streams.) As the
701  * seekg() stream method only passes std::ios_base::in, and the
702  * seekp() method only std::ios_base::out, these will always produce
703  * the expected result, and seekg() will be indistinguishable in
704  * effect from seekp().
705  *
706  * @return If the seek succeeds, a std::char_traits<T>::pos_type
707  * object representing the new stream position of the streambuffer
708  * after the seek. (This type is std::streampos for narrow character
709  * (char) streams, std::wstreampos for wide character (wchar_t)
710  * streams, std::u16streampos for the char16_t type and
711  * std::u32streampos for the char32_t type.) If the seek failed,
712  * pos_type(off_type(-1)) is returned.
713  */
714  virtual pos_type seekpos(pos_type p,
715  std::ios_base::openmode m = std::ios_base::in | std::ios_base::out);
716 
717 public:
718 /**
719  * This class cannot be copied. The copy constructor is deleted.
720  */
721  basic_gstreambuf(const basic_gstreambuf&) = delete;
722 
723 /**
724  * This class cannot be copied. The assignment operator is deleted.
725  */
726  basic_gstreambuf& operator=(const basic_gstreambuf&) = delete;
727 
728 /**
729  * The default constructor: the GIO stream is attached later using the
730  * attach_stream() method. It will not throw unless the constructor
731  * of std::basic_streambuf throws. This class does not offer
732  * concurrent access from multiple threads to the same stream object,
733  * and if that is required users should provide their own
734  * synchronisation.
735  */
737 
738  /**
739  * The constructor taking a GIO input stream. This class does not
740  * offer concurrent access from multiple threads to the same stream
741  * object, and if that is required users should provide their own
742  * synchronisation.
743  *
744  * @param input_stream_ A GIO input stream to be attached to the
745  * streambuffer. If the caller wants the input stream to survive
746  * this class's destruction or a call to close_stream() or
747  * attach_stream(), the caller should keep a separate GobjHandle
748  * object which references the stream (obtained by, say, calling
749  * get_istream()) and pass 'manage_' as false. If this is a
750  * GFilterInputStream object (that is, a GBufferedInputStream or
751  * GConverterInputStream stream), only the underlying base input
752  * stream will be attached and the other higher level streams will be
753  * closed (buffering of input streams is always provided by this C++
754  * streambuffer, and converting is controlled solely by the
755  * 'converter_' argument).
756  *
757  * @param manage_ Whether the streambuffer should call
758  * g_input_stream_close() on the stream in its destructor or when
759  * another stream is attached. Passing 'true' is usually what is
760  * wanted - 'false' only makes sense if the caller keeps a separate
761  * GobjHandle object which references the stream to keep it alive
762  * (obtained by, say, calling get_istream()). Unlike its fdstreams
763  * equivalent, this parameter does not have a default value of
764  * 'true': this is partly to make it less likely that a converter is
765  * passed to this argument by mistake (that would not normally cause
766  * a compiler warning because GobjHandle has a type conversion
767  * operator providing the underlying C object by pointer, so
768  * GobjHandles are type convertible to pointers, and such a pointer
769  * will in turn provide a type match with a bool argument); and
770  * partly because, given a GInputStream* p, the construction
771  * \"Cgu::gstreambuf str(Cgu::GobjHandle<GInputStream>(p));\"
772  * without an additional argument or additional parentheses (or the
773  * use of uniform initializer syntax using braces) would cause a
774  * compiler error as it would be interpreted as a function
775  * declaration.
776  *
777  * @param converter_ A converter (if any) to be attached to the GIO
778  * input stream (note that this does not affect the operation of
779  * set_byteswap()). The default value of an empty
780  * GobjHandle<GConverter> object indicates no converter.
781  *
782  * @exception std::bad_alloc This constructor will throw
783  * std::bad_alloc if memory is exhausted and the system throws on
784  * such exhaustion (unless the library has been installed using the
785  * --with-glib-memory-slices-compat or
786  * --with-glib-memory-slices-no-compat configuration option, in which
787  * case glib will terminate the program if it is unable to obtain
788  * memory from the operating system). No other exception will be
789  * thrown unless the constructor of std::basic_streambuf throws.
790  *
791  * @note If a converter is provided, the stream will no longer be
792  * seekable even if it otherwise would be, so tellg() and seekg()
793  * will no longer work (they will return pos_type(off_type(-1)).
794  */
795  basic_gstreambuf(const GobjHandle<GInputStream>& input_stream_,
796  bool manage_,
797  const GobjHandle<GConverter>& converter_ = GobjHandle<GConverter>());
798 
799  /**
800  * The constructor taking a GIO output stream. This class does not
801  * offer concurrent access from multiple threads to the same stream
802  * object, and if that is required users should provide their own
803  * synchronisation.
804  *
805  * @param output_stream_ A GIO output stream to be attached to the
806  * streambuffer. If the caller wants the output stream to survive
807  * this class's destruction or a call to close_stream() or
808  * attach_stream(), the caller should keep a separate GobjHandle
809  * object which references the stream (obtained by, say, calling
810  * get_ostream()) and pass 'manage_' as false. If this is a
811  * GFilterOutputStream object (that is, a GBufferedOutputStream,
812  * GConverterOutputStream or GDataOutputStream stream), only the
813  * underlying base output stream will be attached and the other
814  * higher level streams will be closed (buffering and converting are
815  * controlled solely by the set_output_buffered() method and
816  * 'converter_' argument).
817  *
818  * @param manage_ Whether the streambuffer should call
819  * g_output_stream_close() on the stream in its destructor or when
820  * another stream is attached. Passing 'true' is usually what is
821  * wanted, and is particularly relevant on output streams because
822  * unless g_output_stream_close() is called, GIO may not commit to
823  * disk - 'false' only makes sense if the caller keeps a separate
824  * GobjHandle object which references the stream to keep it alive
825  * (obtained by, say, calling get_ostream()). Unlike its fdstreams
826  * equivalent, this parameter does not have a default value of
827  * 'true': this is partly to make it less likely that a converter is
828  * passed to this argument by mistake (that would not normally cause
829  * a compiler warning because GobjHandle has a type conversion
830  * operator providing the underlying C object by pointer, so
831  * GobjHandles are type convertible to pointers, and such a pointer
832  * will in turn provide a type match with a bool argument); and
833  * partly because, given a GOutputStream* p, the construction
834  * \"Cgu::gstreambuf str(Cgu::GobjHandle<GOutputStream>(p));\"
835  * without an additional argument or additional parentheses (or the
836  * use of uniform initializer syntax using braces) would cause a
837  * compiler error as it would be interpreted as a function
838  * declaration.
839  *
840  * @param converter_ A converter (if any) to be attached to the GIO
841  * output stream. The default value of an empty
842  * GobjHandle<GConverter> object indicates no converter.
843  *
844  * @exception std::bad_alloc This constructor will throw
845  * std::bad_alloc if memory is exhausted and the system throws on
846  * such exhaustion (unless the library has been installed using the
847  * --with-glib-memory-slices-compat or
848  * --with-glib-memory-slices-no-compat configuration option, in which
849  * case glib will terminate the program if it is unable to obtain
850  * memory from the operating system). No other exception will be
851  * thrown unless the constructor of std::basic_streambuf throws.
852  *
853  * @note If a converter is provided, the stream will no longer be
854  * seekable even if it otherwise would be, so tellp() and seekp()
855  * will no longer work (they will return pos_type(off_type(-1)).
856  */
857  basic_gstreambuf(const GobjHandle<GOutputStream>& output_stream_,
858  bool manage_,
859  const GobjHandle<GConverter>& converter_ = GobjHandle<GConverter>());
860 
861  /**
862  * The constructor taking a GIO input-output stream. This class does
863  * not offer concurrent access from multiple threads to the same
864  * stream object, and if that is required users should provide their
865  * own synchronisation.
866  *
867  * @param io_stream_ A GIO input-output stream to be attached to the
868  * streambuffer. If the caller wants the stream to survive this
869  * class's destruction or a call to close_stream() or
870  * attach_stream(), the caller should keep a separate GobjHandle
871  * object which references the stream (obtained by, say, calling
872  * get_iostream()) and pass 'manage_' as false.
873  *
874  * @param manage_ Whether the streambuffer should call
875  * g_io_stream_close() on the stream in its destructor or when
876  * another stream is attached. Passing 'true' is usually what is
877  * wanted, and is particularly relevant on output streams because
878  * unless g_io_stream_close() is called, GIO may not commit to disk -
879  * 'false' only makes sense if the caller keeps a separate GobjHandle
880  * object which references the stream to keep it alive (obtained by,
881  * say, calling get_iostream()). Unlike its fdstreams equivalent,
882  * this parameter does not have a default value of 'true': this is
883  * partly to make it less likely that a converter is passed to this
884  * argument by mistake (that would not normally cause a compiler
885  * warning because GobjHandle has a type conversion operator
886  * providing the underlying C object by pointer, so GobjHandles are
887  * type convertible to pointers, and such a pointer will in turn
888  * provide a type match with a bool argument); and partly because,
889  * given a GIOStream* p, the construction \"Cgu::gstreambuf
890  * str(Cgu::GobjHandle<GIOStream>(p));\" without an additional
891  * argument or additional parentheses (or the use of uniform
892  * initializer syntax using braces) would cause a compiler error as
893  * it would be interpreted as a function declaration.
894  *
895  * @param input_converter_ A converter (if any) to be attached to the
896  * input stream (note that this does not affect the operation of
897  * set_byteswap()). The default value of an empty
898  * GobjHandle<GConverter> object indicates no converter.
899  *
900  * @param output_converter_ A converter (if any) to be attached to the
901  * output stream. The default value of an empty
902  * GobjHandle<GConverter> object indicates no converter.
903  *
904  * @exception std::bad_alloc This constructor will throw
905  * std::bad_alloc if memory is exhausted and the system throws on
906  * such exhaustion (unless the library has been installed using the
907  * --with-glib-memory-slices-compat or
908  * --with-glib-memory-slices-no-compat configuration option, in which
909  * case glib will terminate the program if it is unable to obtain
910  * memory from the operating system). No other exception will be
911  * thrown unless the constructor of std::basic_streambuf throws.
912  *
913  * @note If a converter is provided, the stream will no longer be
914  * seekable even if it otherwise would be, so tellg(), tellp(),
915  * seekg() and seekp() will no longer work (they will return
916  * pos_type(off_type(-1)). If the stream to which a converter has
917  * been attached represents a file on the file system (rather than a
918  * socket), after a read has been made, no further write may be made
919  * using the same GFileIOStream object. These restrictions do not
920  * apply to sockets (which are not seekable) so the use of converters
921  * with input-output streams (GIOStream) should generally be
922  * restricted to sockets.
923  */
924  basic_gstreambuf(const GobjHandle<GIOStream>& io_stream_,
925  bool manage_,
926  const GobjHandle<GConverter>& input_converter_ = GobjHandle<GConverter>(),
927  const GobjHandle<GConverter>& output_converter_ = GobjHandle<GConverter>());
928 
929 /**
930  * The destructor does not throw.
931  */
932  virtual ~basic_gstreambuf();
933 
934  /**
935  * Attach a new GIO input stream to the streambuffer (and close any
936  * GIO stream at present managed by it). In the case of wide
937  * character input streams, it also switches off byte swapping, if it
938  * was previously on. This class does not offer concurrent access
939  * from multiple threads to the same stream object, and if that is
940  * required users should provide their own synchronisation.
941  *
942  * @param input_stream_ The GIO input stream to be attached to the
943  * streambuffer. If the caller wants the input stream to survive a
944  * subsequent call to close_stream() or attach_stream() or this
945  * class's destruction, the caller should keep a separate GobjHandle
946  * object which references the stream (obtained by, say, calling
947  * get_istream()) and pass 'manage_' as false. If this is a
948  * GFilterInputStream object (that is, a GBufferedInputStream or
949  * GConverterInputStream stream), only the underlying base input
950  * stream will be attached and the other higher level streams will be
951  * closed (buffering of input streams is always provided by this C++
952  * streambuffer, and converting is controlled solely by the
953  * 'converter_' argument).
954  *
955  * @param manage_ Whether the streambuffer should call
956  * g_input_stream_close() on the stream in its destructor or when
957  * another stream is attached. Passing 'true' is usually what is
958  * wanted - 'false' only makes sense if the caller keeps a separate
959  * GobjHandle object which references the stream to keep it alive
960  * (obtained by, say, calling get_istream()). Unlike its fdstreams
961  * equivalent, this parameter does not have a default value of
962  * 'true': this is partly to make it less likely that a converter is
963  * passed to this argument by mistake (that would not normally cause
964  * a compiler warning because GobjHandle has a type conversion
965  * operator providing the underlying C object by pointer, so
966  * GobjHandles are type convertible to pointers, and such a pointer
967  * will in turn provide a type match with a bool argument); and
968  * partly to maintain compatibility with the constructor's interface,
969  * which has separate syntactic constraints.
970  *
971  * @param converter_ A converter (if any) to be attached to the GIO
972  * input stream (note that this does not affect the operation of
973  * set_byteswap()). The default value of an empty
974  * GobjHandle<GConverter> object indicates no converter.
975  *
976  * @exception std::bad_alloc This method will throw std::bad_alloc if
977  * memory is exhausted and the system throws on such exhaustion
978  * (unless the library has been installed using the
979  * --with-glib-memory-slices-compat or
980  * --with-glib-memory-slices-no-compat configuration option, in which
981  * case glib will terminate the program if it is unable to obtain
982  * memory from the operating system).
983  *
984  * @note If a converter is provided, the stream will no longer be
985  * seekable even if it otherwise would be, so tellg() and seekg()
986  * will no longer work (they will return pos_type(off_type(-1)).
987  */
988  void attach_stream(const GobjHandle<GInputStream>& input_stream_,
989  bool manage_,
990  const GobjHandle<GConverter>& converter_ = GobjHandle<GConverter>());
991 
992  /**
993  * Attach a new GIO output stream to the streambuffer (and close any
994  * GIO stream at present managed by it). If output buffering was
995  * previously switched off, it is switched back on again. This class
996  * does not offer concurrent access from multiple threads to the same
997  * stream object, and if that is required users should provide their
998  * own synchronisation.
999  *
1000  * @param output_stream_ The GIO output stream to be attached to the
1001  * streambuffer. If the caller wants the output stream to survive a
1002  * subsequent call to close_stream() or attach_stream() or this
1003  * class's destruction, the caller should keep a separate GobjHandle
1004  * object which references the stream (obtained by, say, calling
1005  * get_ostream()) and pass 'manage_' as false. If this is a
1006  * GFilterOutputStream object (that is, a GBufferedOutputStream,
1007  * GConverterOutputStream or GDataOutputStream stream), only the
1008  * underlying base output stream will be attached and the other
1009  * higher level streams will be closed (buffering and converting are
1010  * controlled solely by the set_output_buffered() method and
1011  * 'converter_' argument).
1012  *
1013  * @param manage_ Whether the streambuffer should call
1014  * g_output_stream_close() on the stream in its destructor or when
1015  * another stream is attached. Passing 'true' is usually what is
1016  * wanted, and is particularly relevant on output streams because
1017  * unless g_output_stream_close() is called, GIO may not commit to
1018  * disk - 'false' only makes sense if the caller keeps a separate
1019  * GobjHandle object which references the stream to keep it alive
1020  * (obtained by, say, calling get_ostream()). Unlike its fdstreams
1021  * equivalent, this parameter does not have a default value of
1022  * 'true': this is partly to make it less likely that a converter is
1023  * passed to this argument by mistake (that would not normally cause
1024  * a compiler warning because GobjHandle has a type conversion
1025  * operator providing the underlying C object by pointer, so
1026  * GobjHandles are type convertible to pointers, and such a pointer
1027  * will in turn provide a type match with a bool argument); and
1028  * partly to maintain compatibility with the constructor's interface,
1029  * which has separate syntactic constraints.
1030  *
1031  * @param converter_ A converter (if any) to be attached to the GIO
1032  * output stream. The default value of an empty
1033  * GobjHandle<GConverter> object indicates no converter.
1034  *
1035  * @exception std::bad_alloc This method will throw std::bad_alloc if
1036  * memory is exhausted and the system throws on such exhaustion
1037  * (unless the library has been installed using the
1038  * --with-glib-memory-slices-compat or
1039  * --with-glib-memory-slices-no-compat configuration option, in which
1040  * case glib will terminate the program if it is unable to obtain
1041  * memory from the operating system).
1042  *
1043  * @note If a converter is provided, the stream will no longer be
1044  * seekable even if it otherwise would be, so tellp() and seekp()
1045  * will no longer work (they will return pos_type(off_type(-1)).
1046  */
1047  void attach_stream(const GobjHandle<GOutputStream>& output_stream_,
1048  bool manage_,
1049  const GobjHandle<GConverter>& converter_ = GobjHandle<GConverter>());
1050 
1051  /**
1052  * Attach a new GIO input-output stream to the streambuffer (and
1053  * close any GIO stream at present managed by it). If output
1054  * buffering was previously switched off, it is switched back on
1055  * again. In the case of wide character input-output streams, it
1056  * also switches off byte swapping on input, if it was previously on.
1057  * This class does not offer concurrent access from multiple threads
1058  * to the same stream object, and if that is required users should
1059  * provide their own synchronisation.
1060  *
1061  * @param io_stream_ The GIO input-output stream to be attached to
1062  * the streambuffer. If the caller wants the stream to survive a
1063  * subsequent call to close_stream() or attach_stream() or this
1064  * class's destruction, the caller should keep a separate GobjHandle
1065  * object which references the stream (obtained by, say, calling
1066  * get_iostream()) and pass 'manage_' as false.
1067  *
1068  * @param manage_ Whether the streambuffer should call
1069  * g_io_stream_close() on the stream in its destructor or when
1070  * another stream is attached. Passing 'true' is usually what is
1071  * wanted, and is particularly relevant on output streams because
1072  * unless g_io_stream_close() is called, GIO may not commit to disk -
1073  * 'false' only makes sense if the caller keeps a separate GobjHandle
1074  * object which references the stream to keep it alive (obtained by,
1075  * say, calling get_iostream()). Unlike its fdstreams equivalent,
1076  * this parameter does not have a default value of 'true': this is
1077  * partly to make it less likely that a converter is passed to this
1078  * argument by mistake (that would not normally cause a compiler
1079  * warning because GobjHandle has a type conversion operator
1080  * providing the underlying C object by pointer, so GobjHandles are
1081  * type convertible to pointers, and such a pointer will in turn
1082  * provide a type match with a bool argument); and partly to maintain
1083  * compatibility with the constructor's interface, which has separate
1084  * syntactic constraints.
1085  *
1086  * @param input_converter_ A converter (if any) to be attached to the
1087  * input stream (note that this does not affect the operation of
1088  * set_byteswap()). The default value of an empty
1089  * GobjHandle<GConverter> object indicates no converter.
1090  *
1091  * @param output_converter_ A converter (if any) to be attached to the
1092  * output stream. The default value of an empty
1093  * GobjHandle<GConverter> object indicates no converter.
1094  *
1095  * @exception std::bad_alloc This method will throw std::bad_alloc if
1096  * memory is exhausted and the system throws on such exhaustion
1097  * (unless the library has been installed using the
1098  * --with-glib-memory-slices-compat or
1099  * --with-glib-memory-slices-no-compat configuration option, in which
1100  * case glib will terminate the program if it is unable to obtain
1101  * memory from the operating system).
1102  *
1103  * @note If a converter is provided, the stream will no longer be
1104  * seekable even if it otherwise would be, so tellg(), tellp(),
1105  * seekg() and seekp() will no longer work (they will return
1106  * pos_type(off_type(-1)). If the stream to which a converter has
1107  * been attached represents a file on the file system (rather than a
1108  * socket), after a read has been made, no further write may be made
1109  * using the same GFileIOStream object. These restrictions do not
1110  * apply to sockets (which are not seekable) so the use of converters
1111  * with input-output streams (GIOStream) should generally be
1112  * restricted to sockets.
1113  */
1114  void attach_stream(const GobjHandle<GIOStream>& io_stream_,
1115  bool manage_,
1116  const GobjHandle<GConverter>& input_converter_ = GobjHandle<GConverter>(),
1117  const GobjHandle<GConverter>& output_converter_ = GobjHandle<GConverter>());
1118 
1119 
1120  /**
1121  * Call g_input_stream_close(), g_output_stream_close() or
1122  * g_io_stream_close(), as the case may be, on the GIO stream at
1123  * present attached to the streambuffer (if any), and release the
1124  * streambuffer's reference to that stream (the reference will be
1125  * released even if an error arose in closing the stream). If the
1126  * caller wants the GIO stream to survive the call to this method
1127  * (albeit in a closed state), the caller should, before the call is
1128  * made, keep a separate GobjHandle object which references the
1129  * stream. This method does not throw. This class does not offer
1130  * concurrent access from multiple threads to the same stream object,
1131  * and if that is required users should provide their own
1132  * synchronisation.
1133  *
1134  * @return true if the close succeeded, false if an error arose
1135  * (including in a case where no GIO stream has been attached or it
1136  * has already been closed).
1137  */
1138  bool close_stream();
1139 
1140  /**
1141  * Get the GIO input stream at present attached to the streambuffer
1142  * (if any), by GobjHandle. If a GOutputStream object rather than a
1143  * GInputStream or GIOStream object has been attached (or no stream
1144  * has been attached) or it has been closed, then this method will
1145  * return an empty GobjHandle object. If a GIOStream object has been
1146  * attached, this streambuffer's maintained GInputStream object will
1147  * be returned, which may be a converting stream manufactured from
1148  * the GInputStream object maintained by the GIOStream object.
1149  * Retaining the return value will cause the stream to survive a
1150  * subsequent call to attach_stream() or the destruction of this
1151  * object. The return value may be a different stream from the one
1152  * originally passed to this object's constructor or to attach(). It
1153  * will be different if a converter has been attached to it. This
1154  * method does not throw. This class does not offer concurrent
1155  * access from multiple threads to the same stream object, and if
1156  * that is required users should provide their own synchronisation.
1157  *
1158  * @return The GIO input stream at present attached to the
1159  * streambuffer, or an empty GobjHandle object if none has been
1160  * attached
1161  */
1163 
1164  /**
1165  * Get the GIO output stream at present attached to the streambuffer
1166  * (if any), by GobjHandle. If a GInputStream object rather than a
1167  * GOutputStream or GIOStream object has been attached (or no stream
1168  * has been attached) or it has been closed, then this method will
1169  * return an empty GobjHandle object. If a GIOStream object has been
1170  * attached, this streambuffer's maintained GOutputStream object will
1171  * be returned, which may be a converting stream manufactured from
1172  * the GOutputStream object maintained by the GIOStream object.
1173  * Retaining the return value will cause the stream to survive a
1174  * subsequent call to attach_stream() or the destruction of this
1175  * object. The return value may be a different stream from the one
1176  * originally passed to this object's constructor or to attach(). It
1177  * will be different if a converter has been attached to it. This
1178  * method does not throw. This class does not offer concurrent
1179  * access from multiple threads to the same stream object, and if
1180  * that is required users should provide their own synchronisation.
1181  *
1182  * @return The GIO output stream at present attached to the
1183  * streambuffer, or an empty GobjHandle object if none has been
1184  * attached
1185  */
1187 
1188  /**
1189  * Get the GIOStream input-output stream at present attached to the
1190  * streambuffer (if any), by GobjHandle. If a GInputStream or
1191  * GOutputStream object rather than a GIOStream object has been
1192  * attached (or no stream has been attached) or it has been closed,
1193  * then this method will return an empty GobjHandle object.
1194  * Retaining the return value will cause the stream to survive a
1195  * subsequent call to attach_stream() or the destruction of this
1196  * object. This method does not throw. This class does not offer
1197  * concurrent access from multiple threads to the same stream object,
1198  * and if that is required users should provide their own
1199  * synchronisation.
1200  *
1201  * @return The GIOStream stream at present attached to the
1202  * streambuffer, or an empty GobjHandle object if none has been
1203  * attached
1204  */
1206 
1207  /**
1208  * Causes the streambuffer to swap bytes in incoming text, so as to
1209  * convert big endian text to little endian text, or little endian
1210  * text to big endian text. It is called by the user in response to
1211  * finding a byte order marker (BOM) 0xfffe (UTF-16) or 0xfffe0000
1212  * (UTF-32) as the first character of a newly opened file/stream, or
1213  * if the user knows by some other means that the native endianness
1214  * of the machine doing the reading differs from the endianness of
1215  * the file/stream being read. This only has effect on wide
1216  * character streambuffers for input (for example, a wgstreambuf to
1217  * which a GInputStream or GIOStream object has been attached), and
1218  * not the gstreambuf narrow character stream buffer. Note that
1219  * characters held for output are always outputted in native endian
1220  * format unless a GConverter object has been attached, and this
1221  * method does not affect that. This method does not throw. This
1222  * class does not offer concurrent access from multiple threads to
1223  * the same stream object, and if that is required users should
1224  * provide their own synchronisation.
1225  *
1226  * @param swap 'true' if byte swapping for input is to be turned on,
1227  * 'false' if it is to be turned off. This will affect all
1228  * characters extracted from the underlying streambuffer after this
1229  * call is made. If a previously extracted character is to be
1230  * putback(), it must be put back before this function is called (or
1231  * unget() should be called instead) to avoid a putback mismatch,
1232  * because this call will byte-swap anything already in the buffers.
1233  * (Characters extracted after the call to this method may be putback
1234  * normally.)
1235  */
1236  void set_byteswap(bool swap);
1237 
1238 /**
1239  * If the GIO stream attached to this object is GOutputStream or
1240  * GIOStream, this method converts it to an unbuffered stream for
1241  * output if 'buffered' is false, or back to a buffered stream if
1242  * buffering has previously been switched off and 'buffered' is true.
1243  * Buffering is on by default for any newly created gstreambuf object
1244  * and any newly attached GIO output stream or input-output stream.
1245  * If buffering is turned off, all characters at present in the
1246  * buffers which are stored for output are flushed (but if writing to
1247  * a file which is being written over/replaced, output from this
1248  * streambuffer may not appear in the destination until the GIO stream
1249  * is closed). This method has no effect if no GIO output stream or
1250  * input-output stream has yet been attached to this streambuffer.
1251  * Switching output buffering off is similar in effect to setting the
1252  * std::ios_base::unitbuf flag in the relevant gostream or giostream
1253  * object, except that switching buffering off is slightly more
1254  * efficient, and setting the std::ios_base::unitbuf flag will not
1255  * retain the automatic tying of logical and actual file positions
1256  * that occurs when output buffering is switched off, as explained
1257  * @ref GioRandomAccessAnchor "here". This class does not offer
1258  * concurrent access from multiple threads to the same stream object,
1259  * and if that is required users should provide their own
1260  * synchronisation.
1261  *
1262  * @param buffered 'false' if buffering is to be turned off, 'true' if
1263  * it is to be turned back on.
1264  *
1265  * @exception std::bad_alloc This method will throw std::bad_alloc if
1266  * 'buffered' is true, output buffering had previously been switched
1267  * off, memory is exhausted and the system throws on such exhaustion
1268  * (unless the library has been installed using the
1269  * --with-glib-memory-slices-compat or
1270  * --with-glib-memory-slices-no-compat configuration option, in which
1271  * case glib will terminate the program if it is unable to obtain
1272  * memory from the operating system).
1273  */
1274  void set_output_buffered(bool buffered);
1275 
1276 /**
1277  * This method indicates whether the attached GIO stream implements
1278  * GSeekable, so that a call to seekoff() or seekpos() can succeed.
1279  * This method does not throw. This class does not offer concurrent
1280  * access from multiple threads to the same stream object, and if that
1281  * is required users should provide their own synchronisation.
1282  *
1283  * @return true if random access is supported, otherwise false. The
1284  * result is only meaningful if a GIO stream has been attached to this
1285  * streambuffer.
1286  */
1287  bool can_seek() const {return seekable;}
1288 
1289 /**
1290  * This method indicates whether any attached GIO input stream is in
1291  * an error state. It can be useful for detecting conversion errors
1292  * on converting streams. This class does not offer concurrent access
1293  * from multiple threads to the same stream object, and if that is
1294  * required users should provide their own synchronisation.
1295  *
1296  * @return NULL if no input stream is attached, or it is not in an
1297  * error state. If an attached input stream is in an error state, say
1298  * because it is a converting input stream which has encountered a
1299  * conversion error, the most recent GError object emitted by a read
1300  * operation on it is returned. Ownership of the return value is
1301  * retained, so if it is intended to be used after the next read
1302  * operation, it should be copied using g_error_copy().
1303  *
1304  * Since 2.0.5
1305  */
1306  GError* is_input_error();
1307 
1308 /**
1309  * This method indicates whether any attached GIO output stream is in
1310  * an error state. It can be useful for detecting conversion errors
1311  * on converting streams. This class does not offer concurrent access
1312  * from multiple threads to the same stream object, and if that is
1313  * required users should provide their own synchronisation.
1314  *
1315  * @return NULL if no output stream is attached, or it is not in an
1316  * error state. If an attached output stream is in an error state,
1317  * say because it is a converting output stream which has encountered
1318  * a conversion error, the most recent GError object emitted by a
1319  * write operation on it is returned. Ownership of the return value
1320  * is retained, so if it is intended to be used after the next write
1321  * operation, it should be copied using g_error_copy().
1322  *
1323  * Since 2.0.5
1324  */
1325  GError* is_output_error();
1326 
1327 /* Only has effect if --with-glib-memory-slices-compat or
1328  * --with-glib-memory-slices-no-compat option picked */
1330 };
1331 
1332 /**
1333  * @headerfile gstream.h c++-gtk-utils/gstream.h
1334  * @brief C++ output stream for GIO streams
1335  * @sa gstreams
1336  * @ingroup gstreams
1337  *
1338  * This class provides standard ostream services for GIO output
1339  * streams.
1340  */
1341 template <class charT , class Traits = std::char_traits<charT> >
1342 class basic_gostream: public std::basic_ostream<charT, Traits> {
1343 
1345 
1346 public:
1347 /**
1348  * This class cannot be copied. The copy constructor is deleted.
1349  */
1350  basic_gostream(const basic_gostream&) = delete;
1351 
1352 /**
1353  * This class cannot be copied. The assignment operator is deleted.
1354  */
1355  basic_gostream& operator=(const basic_gostream&) = delete;
1356 
1357  /**
1358  * The constructor taking a GIO output stream. This class does not
1359  * offer concurrent access from multiple threads to the same stream
1360  * object, and if that is required users should provide their own
1361  * synchronisation.
1362  *
1363  * @param stream A GIO output stream to be attached. If the caller
1364  * wants the output stream to survive this class's destruction or a
1365  * call to close() or attach(), the caller should keep a separate
1366  * GobjHandle object which references the stream (obtained by, say,
1367  * calling get_gio_stream()) and pass 'manage' as false. If this is
1368  * a GFilterOutputStream object (that is, a GBufferedOutputStream,
1369  * GConverterOutputStream or GDataOutputStream stream), only the
1370  * underlying base output stream will be attached and the other
1371  * higher level streams will be closed (buffering and converting are
1372  * controlled solely by the set_buffered() method and 'converter'
1373  * argument).
1374  *
1375  * @param manage Whether the underlying streambuffer should call
1376  * g_output_stream_close() on the GIO stream in the streambuffer's
1377  * destructor or when another stream is attached. Passing 'true' is
1378  * usually what is wanted, and is particularly relevant on output
1379  * streams because unless g_output_stream_close() is called, GIO may
1380  * not commit to disk - 'false' only makes sense if the caller keeps
1381  * a separate GobjHandle object which references the stream to keep
1382  * it alive (obtained by, say, calling get_gio_stream()). Unlike its
1383  * fdstreams equivalent, this parameter does not have a default value
1384  * of 'true': this is partly to make it less likely that a converter
1385  * is passed to this argument by mistake (that would not normally
1386  * cause a compiler warning because GobjHandle has a type conversion
1387  * operator providing the underlying C object by pointer, so
1388  * GobjHandles are type convertible to pointers, and such a pointer
1389  * will in turn provide a type match with a bool argument); and
1390  * partly because, given a GOutputStream* p, the construction
1391  * \"Cgu::gostream str(Cgu::GobjHandle<GOutputStream>(p));\"
1392  * without an additional argument or additional parentheses (or the
1393  * use of uniform initializer syntax using braces) would cause a
1394  * compiler error as it would be interpreted as a function
1395  * declaration.
1396  *
1397  * @param converter A converter (if any) to be attached to the GIO
1398  * output stream. The default value of an empty
1399  * GobjHandle<GConverter> object indicates no converter.
1400  *
1401  * @exception std::bad_alloc This constructor will throw
1402  * std::bad_alloc if memory is exhausted and the system throws on
1403  * such exhaustion (unless the library has been installed using the
1404  * --with-glib-memory-slices-compat or
1405  * --with-glib-memory-slices-no-compat configuration option, in which
1406  * case glib will terminate the program if it is unable to obtain
1407  * memory from the operating system). No other exception will be
1408  * thrown unless the constructor of std::basic_streambuf,
1409  * std::basic_ostream or std::basic_istream throws.
1410  *
1411  * @note If a converter is provided, the stream will no longer be
1412  * seekable even if it otherwise would be, so tellp() and seekp()
1413  * will no longer work (they will return pos_type(off_type(-1)).
1414  */
1415  // using uniform initializer syntax here confuses doxygen
1417  bool manage,
1418  const GobjHandle<GConverter>& converter = GobjHandle<GConverter>()):
1419  std::basic_ostream<charT, Traits>(0),
1420  buf(stream, manage, converter) {
1421  this->rdbuf(&buf);
1422  }
1423 
1424  /**
1425  * With this constructor, the GIO output stream must be attached
1426  * later with the attach() method. It will not throw unless the
1427  * constructor of std::basic_streambuf, std::basic_ostream or
1428  * std::basic_istream throws. This class does not offer concurrent
1429  * access from multiple threads to the same stream object, and if
1430  * that is required users should provide their own synchronisation.
1431  */
1432  // using uniform initializer syntax here confuses doxygen
1433  basic_gostream(): std::basic_ostream<charT, Traits>(0) {
1434  this->rdbuf(&buf);
1435  }
1436 
1437  /**
1438  * Attach a new GIO output stream to this object (and close any GIO
1439  * stream at present managed by it). If output buffering was
1440  * previously switched off, it is switched back on again. If any
1441  * stream state flags were set (eofbit, failbit or badbit), they will
1442  * be cleared by a call to clear(). If this method closes a stream
1443  * at present managed by it and the close fails, failbit is not set
1444  * and no exception will be thrown. Accordingly, if the user needs
1445  * to know whether there was an error in this method closing any
1446  * managed stream, she should call close() explicitly before calling
1447  * this method. This class does not offer concurrent access from
1448  * multiple threads to the same stream object, and if that is
1449  * required users should provide their own synchronisation.
1450  *
1451  * @param stream A GIO output stream to be attached. If the caller
1452  * wants the GIO output stream to survive a subsequent call to
1453  * close() or attach() or this class's destruction, the caller should
1454  * keep a separate GobjHandle object which references the stream
1455  * (obtained by, say, calling get_gio_stream()) and pass 'manage' as
1456  * false. If this is a GFilterOutputStream object (that is, a
1457  * GBufferedOutputStream, GConverterOutputStream or GDataOutputStream
1458  * stream), only the underlying base output stream will be attached
1459  * and the other higher level streams will be closed (buffering and
1460  * converting are controlled solely by the set_buffered() method and
1461  * 'converter' argument).
1462  *
1463  * @param manage Whether the underlying streambuffer should call
1464  * g_output_stream_close() on the GIO stream in the streambuffer's
1465  * destructor or when another stream is attached. Passing 'true' is
1466  * usually what is wanted, and is particularly relevant on output
1467  * streams because unless g_output_stream_close() is called, GIO may
1468  * not commit to disk - 'false' only makes sense if the caller keeps
1469  * a separate GobjHandle object which references the stream to keep
1470  * it alive (obtained by, say, calling get_gio_stream()). Unlike its
1471  * fdstreams equivalent, this parameter does not have a default value
1472  * of 'true': this is partly to make it less likely that a converter
1473  * is passed to this argument by mistake (that would not normally
1474  * cause a compiler warning because GobjHandle has a type conversion
1475  * operator providing the underlying C object by pointer, so
1476  * GobjHandles are type convertible to pointers, and such a pointer
1477  * will in turn provide a type match with a bool argument); and
1478  * partly to maintain compatibility with the constructor's interface,
1479  * which has separate syntactic constraints.
1480  *
1481  * @param converter A converter (if any) to be attached to the GIO
1482  * output stream. The default value of an empty
1483  * GobjHandle<GConverter> object indicates no converter.
1484  *
1485  * @exception std::bad_alloc This method will throw std::bad_alloc if
1486  * memory is exhausted and the system throws on such exhaustion
1487  * (unless the library has been installed using the
1488  * --with-glib-memory-slices-compat or
1489  * --with-glib-memory-slices-no-compat configuration option, in which
1490  * case glib will terminate the program if it is unable to obtain
1491  * memory from the operating system).
1492  *
1493  * @note If a converter is provided, the stream will no longer be
1494  * seekable even if it otherwise would be, so tellp() and seekp()
1495  * will no longer work (they will return pos_type(off_type(-1)).
1496  */
1497  void attach(const GobjHandle<GOutputStream>& stream,
1498  bool manage,
1499  const GobjHandle<GConverter>& converter = GobjHandle<GConverter>())
1500  {buf.attach_stream(stream, manage, converter); this->clear();}
1501 
1502  /**
1503  * Call g_output_stream_close() on the GIO stream at present attached
1504  * (if any), and release the underlying C++ streambuffer's reference
1505  * to that stream. If the caller wants the GIO stream to survive the
1506  * call to this method (albeit in a closed state), the caller should,
1507  * before the call is made, keep a separate GobjHandle object which
1508  * references the stream. If the close fails, the failbit will be
1509  * set with setstate(std::ios_base::failbit). This class does not
1510  * offer concurrent access from multiple threads to the same stream
1511  * object, and if that is required users should provide their own
1512  * synchronisation.
1513  *
1514  * @exception std::ios_base::failure This exception will be thrown if
1515  * an error arises on closing the stream and such an exception has
1516  * been required by a call to the exceptions() method of this class
1517  * (inherited from std::basic_ios<>). No exception will be thrown if
1518  * exceptions() has not been called.
1519  */
1520  void close() {if (!buf.close_stream()) this->setstate(std::ios_base::failbit);}
1521 
1522  /**
1523  * Get the GIO output stream at present attached (if any), by
1524  * GobjHandle. If no stream has been attached, this method will
1525  * return an empty GobjHandle object. Retaining the return value
1526  * will cause the GIO output stream to survive the destruction of
1527  * this object. The return value may be a different stream from the
1528  * one originally passed to this object's constructor or to attach().
1529  * It will be different if a converter has been attached to it. This
1530  * method does not throw. This class does not offer concurrent
1531  * access from multiple threads to the same stream object, and if
1532  * that is required users should provide their own synchronisation.
1533  *
1534  * @return The GIO output stream at present attached, or an empty
1535  * GobjHandle object if none has been attached
1536  */
1537  GobjHandle<GOutputStream> get_gio_stream() const {return buf.get_ostream();}
1538 
1539 /**
1540  * This method converts the attached GIO output stream to an
1541  * unbuffered stream for output if 'buffered' is false, or back to a
1542  * buffered stream if buffering has previously been switched off and
1543  * 'buffered' is true. Buffering is on by default for any newly
1544  * created gostream object and any newly attached GIO output stream.
1545  * If buffering is turned off, all characters at present in the
1546  * buffers which are stored for output are flushed (but if writing to
1547  * a file which is being written over/replaced, output may not appear
1548  * in the destination until the GIO stream is closed). This method
1549  * has no effect if no GIO output stream has yet been attached.
1550  * Switching output buffering off is similar in effect to setting the
1551  * std::ios_base::unitbuf flag, but is slightly more efficient. This
1552  * class does not offer concurrent access from multiple threads to the
1553  * same stream object, and if that is required users should provide
1554  * their own synchronisation.
1555  *
1556  * @param buffered 'false' if buffering is to be turned off, 'true' if
1557  * it is to be turned back on.
1558  *
1559  * @exception std::bad_alloc This method will throw std::bad_alloc if
1560  * 'buffered' is true, output buffering had previously been switched
1561  * off, memory is exhausted and the system throws on such exhaustion
1562  * (unless the library has been installed using the
1563  * --with-glib-memory-slices-compat or
1564  * --with-glib-memory-slices-no-compat configuration option, in which
1565  * case glib will terminate the program if it is unable to obtain
1566  * memory from the operating system).
1567  */
1568  void set_buffered(bool buffered) {buf.set_output_buffered(buffered);}
1569 
1570 /**
1571  * This method indicates whether the attached GIO output stream
1572  * implements GSeekable, so that a call to tellp() or seekp() can
1573  * succeed. Note that in the seekp(off_type off, ios_base::seekdir
1574  * dir) variant, on wide character streams the 'off' argument is
1575  * dimensioned as the number of wchar_t/char32_t/char16_t units not
1576  * the number of bytes (that is, it is bytes/sizeof(char_type)). This
1577  * method does not throw. This class does not offer concurrent access
1578  * from multiple threads to the same stream object, and if that is
1579  * required users should provide their own synchronisation.
1580  *
1581  * @return true if the attached GIO stream implements GSeekable,
1582  * otherwise false. The result is only meaningful if a GIO stream has
1583  * been attached to this C++ stream object.
1584  */
1585  bool can_seek() const {return buf.can_seek();}
1586 
1587 /**
1588  * This method reports the error status of any attached GIO output
1589  * stream, and is intended to be called where failbit or badbit has
1590  * been set. It can be useful for interpreting conversion errors on
1591  * converting streams where one of those bits is set. This class does
1592  * not offer concurrent access from multiple threads to the same
1593  * stream object, and if that is required users should provide their
1594  * own synchronisation.
1595  *
1596  * @return NULL if no output stream is attached, or it is not in an
1597  * error state. If an attached output stream is in an error state,
1598  * say because it is a converting output stream which has encountered
1599  * a conversion error, the most recent GError object emitted by a
1600  * write operation on it is returned. Ownership of the return value
1601  * is retained, so if it is intended to be used after the next write
1602  * operation, it should be copied using g_error_copy().
1603  *
1604  * Since 2.0.5
1605  */
1606  GError* is_error() {return buf.is_output_error();}
1607 
1608 /* Only has effect if --with-glib-memory-slices-compat or
1609  * --with-glib-memory-slices-no-compat option picked */
1611 };
1612 
1613 
1614 /**
1615  * @headerfile gstream.h c++-gtk-utils/gstream.h
1616  * @brief C++ input stream for GIO streams
1617  * @sa gstreams
1618  * @ingroup gstreams
1619  *
1620  * This class provides standard istream services for GIO input
1621  * streams.
1622  */
1623 template <class charT , class Traits = std::char_traits<charT> >
1624 class basic_gistream : public std::basic_istream<charT, Traits> {
1625 
1627 
1628 public:
1629 /**
1630  * This class cannot be copied. The copy constructor is deleted.
1631  */
1632  basic_gistream(const basic_gistream&) = delete;
1633 
1634 /**
1635  * This class cannot be copied. The assignment operator is deleted.
1636  */
1637  basic_gistream& operator=(const basic_gistream&) = delete;
1638 
1639  /**
1640  * The constructor taking a GIO input stream. This class does not
1641  * offer concurrent access from multiple threads to the same stream
1642  * object, and if that is required users should provide their own
1643  * synchronisation.
1644  *
1645  * @param stream A GIO input stream to be attached. If the caller
1646  * wants the GIO input stream to survive this class's destruction or
1647  * a call to close() or attach(), the caller should keep a separate
1648  * GobjHandle object which references the stream (obtained by, say,
1649  * calling get_gio_stream()) and pass 'manage' as false. If this is
1650  * a GFilterInputStream object (that is, a GBufferedInputStream or
1651  * GConverterInputStream stream), only the underlying base input
1652  * stream will be attached and the other higher level streams will be
1653  * closed (buffering of input streams is always provided by the
1654  * underlying C++ streambuffer, and converting is controlled solely
1655  * by the 'converter' argument).
1656  *
1657  * @param manage Whether the underlying streambuffer should call
1658  * g_input_stream_close() on the GIO stream in the streambuffer's
1659  * destructor or when another stream is attached. Passing 'true' is
1660  * usually what is wanted - 'false' only makes sense if the caller
1661  * keeps a separate GobjHandle object which references the stream to
1662  * keep it alive (obtained by, say, calling get_gio_stream()).
1663  * Unlike its fdstreams equivalent, this parameter does not have a
1664  * default value of 'true': this is partly to make it less likely
1665  * that a converter is passed to this argument by mistake (that would
1666  * not normally cause a compiler warning because GobjHandle has a
1667  * type conversion operator providing the underlying C object by
1668  * pointer, so GobjHandles are type convertible to pointers, and such
1669  * a pointer will in turn provide a type match with a bool argument);
1670  * and partly because, given a GInputStream* p, the construction
1671  * \"Cgu::gistream str(Cgu::GobjHandle<GInputStream>(p));\" without
1672  * an additional argument or additional parentheses (or the use of
1673  * uniform initializer syntax using braces) would cause a compiler
1674  * error as it would be interpreted as a function declaration.
1675  *
1676  * @param converter A converter (if any) to be attached to the GIO
1677  * input stream (note that this does not affect the operation of
1678  * set_byteswap()). The default value of an empty
1679  * GobjHandle<GConverter> object indicates no converter.
1680  *
1681  * @exception std::bad_alloc This constructor will throw
1682  * std::bad_alloc if memory is exhausted and the system throws on
1683  * such exhaustion (unless the library has been installed using the
1684  * --with-glib-memory-slices-compat or
1685  * --with-glib-memory-slices-no-compat configuration option, in which
1686  * case glib will terminate the program if it is unable to obtain
1687  * memory from the operating system). No other exception will be
1688  * thrown unless the constructor of std::basic_streambuf,
1689  * std::basic_ostream or std::basic_istream throws.
1690  *
1691  * @note If a converter is provided, the stream will no longer be
1692  * seekable even if it otherwise would be, so tellg() and seekg()
1693  * will no longer work (they will return pos_type(off_type(-1)).
1694  */
1695  // using uniform initializer syntax here confuses doxygen
1697  bool manage,
1698  const GobjHandle<GConverter>& converter = GobjHandle<GConverter>()):
1699  std::basic_istream<charT, Traits>(0),
1700  buf(stream, manage, converter) {
1701  this->rdbuf(&buf);
1702  }
1703 
1704  /**
1705  * With this constructor, the GIO input stream must be attached later
1706  * with the attach() method. It will not throw unless the
1707  * constructor of std::basic_streambuf, std::basic_ostream or
1708  * std::basic_istream throws. This class does not offer concurrent
1709  * access from multiple threads to the same stream object, and if
1710  * that is required users should provide their own synchronisation.
1711  */
1712  // using uniform initializer syntax here confuses doxygen
1713  basic_gistream(): std::basic_istream<charT, Traits>(0) {
1714  this->rdbuf(&buf);
1715  }
1716 
1717  /**
1718  * Attach a new GIO input stream to this object (and close any GIO
1719  * stream at present managed by it). In the case of wide character
1720  * input streams, it also switches off byte swapping, if it was
1721  * previously on. If any stream state flags were set (eofbit,
1722  * failbit or badbit), they will be cleared by a call to clear(). If
1723  * this method closes a stream at present managed by it and the close
1724  * fails, failbit is not set and no exception will be thrown.
1725  * Accordingly, if the user needs to know whether there was an error
1726  * in this method closing any managed stream, she should call close()
1727  * explicitly before calling this method. This class does not offer
1728  * concurrent access from multiple threads to the same stream object,
1729  * and if that is required users should provide their own
1730  * synchronisation.
1731  *
1732  * @param stream A GIO input stream to be attached. If the caller
1733  * wants the GIO input stream to survive a subsequent call to close()
1734  * or attach() or this class's destruction, the caller should keep a
1735  * separate GobjHandle object which references the stream (obtained
1736  * by, say, calling get_gio_stream()) and pass 'manage' as false. If
1737  * this is a GFilterInputStream object (that is, a
1738  * GBufferedInputStream or GConverterInputStream stream), only the
1739  * underlying base input stream will be attached and the other higher
1740  * level streams will be closed (buffering of input streams is always
1741  * provided by the underlying C++ streambuffer, and converting is
1742  * controlled solely by the 'converter' argument).
1743  *
1744  * @param manage Whether the underlying streambuffer should call
1745  * g_input_stream_close() on the GIO stream in the streambuffer's
1746  * destructor or when another stream is attached. Passing 'true' is
1747  * usually what is wanted - 'false' only makes sense if the caller
1748  * keeps a separate GobjHandle object which references the stream to
1749  * keep it alive (obtained by, say, calling get_gio_stream()).
1750  * Unlike its fdstreams equivalent, this parameter does not have a
1751  * default value of 'true': this is partly to make it less likely
1752  * that a converter is passed to this argument by mistake (that would
1753  * not normally cause a compiler warning because GobjHandle has a
1754  * type conversion operator providing the underlying C object by
1755  * pointer, so GobjHandles are type convertible to pointers, and such
1756  * a pointer will in turn provide a type match with a bool argument);
1757  * and partly to maintain compatibility with the constructor's
1758  * interface, which has separate syntactic constraints.
1759  *
1760  * @param converter A converter (if any) to be attached to the GIO
1761  * input stream (note that this does not affect the operation of
1762  * set_byteswap()). The default value of an empty
1763  * GobjHandle<GConverter> object indicates no converter.
1764  *
1765  * @exception std::bad_alloc This method will throw std::bad_alloc if
1766  * memory is exhausted and the system throws on such exhaustion
1767  * (unless the library has been installed using the
1768  * --with-glib-memory-slices-compat or
1769  * --with-glib-memory-slices-no-compat configuration option, in which
1770  * case glib will terminate the program if it is unable to obtain
1771  * memory from the operating system).
1772  *
1773  * @note If a converter is provided, the stream will no longer be
1774  * seekable even if it otherwise would be, so tellg() and seekg()
1775  * will no longer work (they will return pos_type(off_type(-1)).
1776  */
1777  void attach(const GobjHandle<GInputStream>& stream,
1778  bool manage,
1779  const GobjHandle<GConverter>& converter = GobjHandle<GConverter>())
1780  {buf.attach_stream(stream, manage, converter); this->clear();}
1781 
1782  /**
1783  * Call g_input_stream_close() on the GIO stream at present attached
1784  * (if any), and release the underlying C++ streambuffer's reference
1785  * to that stream. If the caller wants the GIO stream to survive the
1786  * call to this method (albeit in a closed state), the caller should,
1787  * before the call is made, keep a separate GobjHandle object which
1788  * references the stream. If the close fails, the failbit will be
1789  * set with setstate(std::ios_base::failbit). This class does not
1790  * offer concurrent access from multiple threads to the same stream
1791  * object, and if that is required users should provide their own
1792  * synchronisation.
1793  *
1794  * @exception std::ios_base::failure This exception will be thrown if
1795  * an error arises on closing the stream and such an exception has
1796  * been required by a call to the exceptions() method of this class
1797  * (inherited from std::basic_ios<>). No exception will be thrown if
1798  * exceptions() has not been called.
1799  */
1800  void close() {if (!buf.close_stream()) this->setstate(std::ios_base::failbit);}
1801 
1802  /**
1803  * Get the GIO input stream at present attached (if any), by
1804  * GobjHandle. If no stream has been attached, this method will
1805  * return an empty GobjHandle object. Retaining the return value
1806  * will cause the GIO input stream to survive the destruction of this
1807  * object. The return value may be a different stream from the one
1808  * originally passed to this object's constructor or to attach(). It
1809  * will be different if a converter has been attached to it. This
1810  * method does not throw. This class does not offer concurrent
1811  * access from multiple threads to the same stream object, and if
1812  * that is required users should provide their own synchronisation.
1813  *
1814  * @return The GIO input stream at present attached, or an empty
1815  * GobjHandle object if none has been attached
1816  */
1817  GobjHandle<GInputStream> get_gio_stream() const {return buf.get_istream();}
1818 
1819  /**
1820  * Causes the underlying streambuffer to swap bytes in the incoming
1821  * text, so as to convert big endian text to little endian text, or
1822  * little endian text to big endian text. It is called by the user
1823  * in response to finding a byte order marker (BOM) 0xfffe (UTF-16)
1824  * or 0xfffe0000 (UTF-32) as the first character of a newly opened
1825  * file/stream, or if the user knows by some other means that the
1826  * native endianness of the machine doing the reading differs from
1827  * the endianness of the file/stream being read. This only has
1828  * effect on wide character streams (for example, a wgistream
1829  * object), and not the gistream narrow character stream. This
1830  * method does not throw. This class does not offer concurrent
1831  * access from multiple threads to the same stream object, and if
1832  * that is required users should provide their own synchronisation.
1833  *
1834  * @param swap 'true' if byte swapping is to be turned on, 'false' if
1835  * it is to be turned off. This will affect all characters extracted
1836  * from the underlying streambuffer after this call is made. If a
1837  * previously extracted character is to be putback(), it must be put
1838  * back before this function is called (or unget() should be called
1839  * instead) to avoid a putback mismatch, because this call will
1840  * byte-swap anything already in the buffers. (Characters extracted
1841  * after the call to this method may be putback normally.)
1842  */
1843  void set_byteswap(bool swap) {buf.set_byteswap(swap);}
1844 
1845 /**
1846  * This method indicates whether the attached GIO input stream
1847  * implements GSeekable, so that a call to tellg() or seekg() can
1848  * succeed. Note that in the seekg(off_type off, ios_base::seekdir
1849  * dir) variant, on wide character streams the 'off' argument is
1850  * dimensioned as the number of wchar_t/char32_t/char16_t units not
1851  * the number of bytes (that is, it is bytes/sizeof(char_type)). This
1852  * method does not throw. This class does not offer concurrent access
1853  * from multiple threads to the same stream object, and if that is
1854  * required users should provide their own synchronisation.
1855  *
1856  * @return true if the attached GIO stream implements GSeekable,
1857  * otherwise false. The result is only meaningful if a GIO stream has
1858  * been attached to this C++ stream object.
1859  */
1860  bool can_seek() const {return buf.can_seek();}
1861 
1862 /**
1863  * This method reports the error status of any attached GIO input
1864  * stream, and is intended to be called where failbit has been set.
1865  * It can be useful for establishing, where that bit is set, whether
1866  * failbit indicates normal end-of-file or a conversion error on a
1867  * converting stream. This class does not offer concurrent access
1868  * from multiple threads to the same stream object, and if that is
1869  * required users should provide their own synchronisation.
1870  *
1871  * @return NULL if no input stream is attached, or it is not in an
1872  * error state. If an attached input stream is in an error state, say
1873  * because it is a converting input stream which has encountered a
1874  * conversion error, the most recent GError object emitted by a read
1875  * operation on it is returned. Ownership of the return value is
1876  * retained, so if it is intended to be used after the next read
1877  * operation, it should be copied using g_error_copy().
1878  *
1879  * Since 2.0.5
1880  */
1881  GError* is_error() {return buf.is_input_error();}
1882 
1883 /* Only has effect if --with-glib-memory-slices-compat or
1884  * --with-glib-memory-slices-no-compat option picked */
1886 };
1887 
1888 
1889 
1890 /**
1891  * @headerfile gstream.h c++-gtk-utils/gstream.h
1892  * @brief C++ input-output stream for GIO streams
1893  * @sa gstreams
1894  * @ingroup gstreams
1895  *
1896  * This class provides standard iostream services for GIO streams.
1897  */
1898 template <class charT , class Traits = std::char_traits<charT> >
1899 class basic_giostream : public std::basic_iostream<charT, Traits> {
1900 
1902 
1903 public:
1904 /**
1905  * This class cannot be copied. The copy constructor is deleted.
1906  */
1907  basic_giostream(const basic_giostream&) = delete;
1908 
1909 /**
1910  * This class cannot be copied. The assignment operator is deleted.
1911  */
1912  basic_giostream& operator=(const basic_giostream&) = delete;
1913 
1914  /**
1915  * The constructor taking a GIO input-output stream. This class does
1916  * not offer concurrent access from multiple threads to the same
1917  * stream object, and if that is required users should provide their
1918  * own synchronisation.
1919  *
1920  * @param stream A GIO input-output stream to be attached. If the
1921  * caller wants the GIO stream to survive this class's destruction or
1922  * a call to close() or attach(), the caller should keep a separate
1923  * GobjHandle object which references the stream (obtained by, say,
1924  * calling get_gio_io_stream()) and pass 'manage' as false.
1925  *
1926  * @param manage Whether the underlying streambuffer should call
1927  * g_io_stream_close() on the GIO stream in the streambuffer's
1928  * destructor or when another stream is attached. Passing 'true' is
1929  * usually what is wanted, and is particularly relevant on output
1930  * streams because unless g_io_stream_close() is called, GIO may not
1931  * commit to disk - 'false' only makes sense if the caller keeps a
1932  * separate GobjHandle object which references the stream to keep it
1933  * alive (obtained by, say, calling get_gio_io_stream()). Unlike its
1934  * fdstreams equivalent, this parameter does not have a default value
1935  * of 'true': this is partly to make it less likely that a converter
1936  * is passed to this argument by mistake (that would not normally
1937  * cause a compiler warning because GobjHandle has a type conversion
1938  * operator providing the underlying C object by pointer, so
1939  * GobjHandles are type convertible to pointers, and such a pointer
1940  * will in turn provide a type match with a bool argument); and
1941  * partly because, given a GIOStream* p, the construction
1942  * \"Cgu::giostream str(Cgu::GobjHandle<GIOStream>(p));\" without
1943  * an additional argument or additional parentheses (or the use of
1944  * uniform initializer syntax using braces) would cause a compiler
1945  * error as it would be interpreted as a function declaration.
1946  *
1947  * @param input_converter A converter (if any) to be attached to the
1948  * input stream (note that this does not affect the operation of
1949  * set_byteswap()). The default value of an empty
1950  * GobjHandle<GConverter> object indicates no converter.
1951  *
1952  * @param output_converter A converter (if any) to be attached to the
1953  * output stream. The default value of an empty
1954  * GobjHandle<GConverter> object indicates no converter.
1955  *
1956  * @exception std::bad_alloc This constructor will throw
1957  * std::bad_alloc if memory is exhausted and the system throws on
1958  * such exhaustion (unless the library has been installed using the
1959  * --with-glib-memory-slices-compat or
1960  * --with-glib-memory-slices-no-compat configuration option, in which
1961  * case glib will terminate the program if it is unable to obtain
1962  * memory from the operating system). No other exception will be
1963  * thrown unless the constructor of std::basic_streambuf,
1964  * std::basic_ostream or std::basic_istream throws.
1965  *
1966  * @note If a converter is provided, the stream will no longer be
1967  * seekable even if it otherwise would be, so tellg(), tellp(),
1968  * seekg() and seekp() will no longer work (they will return
1969  * pos_type(off_type(-1)). If the stream to which a converter has
1970  * been attached represents a file on the file system (rather than a
1971  * socket), after a read has been made, no further write may be made
1972  * using the same GFileIOStream object. These restrictions do not
1973  * apply to sockets (which are not seekable) so the use of converters
1974  * with input-output streams (GIOStream) should generally be
1975  * restricted to sockets.
1976  */
1977  // using uniform initializer syntax here confuses doxygen
1979  bool manage,
1980  const GobjHandle<GConverter>& input_converter = GobjHandle<GConverter>(),
1981  const GobjHandle<GConverter>& output_converter = GobjHandle<GConverter>()):
1982  std::basic_iostream<charT, Traits>(0),
1983  buf(stream, manage, input_converter, output_converter) {
1984  this->rdbuf(&buf); // std::basic_ios is a virtual base class
1985  }
1986 
1987  /**
1988  * With this constructor, the GIO input-output stream must be
1989  * attached later with the attach() method. It will not throw unless
1990  * the constructor of std::basic_streambuf, std::basic_ostream or
1991  * std::basic_istream throws. This class does not offer concurrent
1992  * access from multiple threads to the same stream object, and if
1993  * that is required users should provide their own synchronisation.
1994  */
1995  // using uniform initializer syntax here confuses doxygen
1996  basic_giostream() : std::basic_iostream<charT, Traits>(0) {
1997  this->rdbuf(&buf); // std::basic_ios is a virtual base class
1998  }
1999 
2000  /**
2001  * Attach a new GIO input-output stream to this object (and close any
2002  * GIO stream at present managed by it). If output buffering was
2003  * previously switched off, it is switched back on again. In the
2004  * case of wide character input-output streams, it also switches off
2005  * byte swapping on input, if it was previously on. If any stream
2006  * state flags were set (eofbit, failbit or badbit), they will be
2007  * cleared by a call to clear(). If this method closes a stream at
2008  * present managed by it and the close fails, failbit is not set and
2009  * no exception will be thrown. Accordingly, if the user needs to
2010  * know whether there was an error in this method closing any managed
2011  * stream, she should call close() explicitly before calling this
2012  * method. This class does not offer concurrent access from multiple
2013  * threads to the same stream object, and if that is required users
2014  * should provide their own synchronisation.
2015  *
2016  * @param stream A GIO input-output stream to be attached. If the
2017  * caller wants the GIO stream to survive a subsequent call to
2018  * close() or attach() or this class's destruction, the caller should
2019  * keep a separate GobjHandle object which references the stream
2020  * (obtained by, say, calling get_gio_io_stream()) and pass 'manage'
2021  * as false.
2022  *
2023  * @param manage Whether the underlying streambuffer should call
2024  * g_io_stream_close() on the GIO stream in the streambuffer's
2025  * destructor or when another stream is attached. Passing 'true' is
2026  * usually what is wanted, and is particularly relevant on output
2027  * streams because unless g_io_stream_close() is called, GIO may not
2028  * commit to disk - 'false' only makes sense if the caller keeps a
2029  * separate GobjHandle object which references the stream to keep it
2030  * alive (obtained by, say, calling get_gio_io_stream()). Unlike its
2031  * fdstreams equivalent, this parameter does not have a default value
2032  * of 'true': this is partly to make it less likely that a converter
2033  * is passed to this argument by mistake (that would not normally
2034  * cause a compiler warning because GobjHandle has a type conversion
2035  * operator providing the underlying C object by pointer, so
2036  * GobjHandles are type convertible to pointers, and such a pointer
2037  * will in turn provide a type match with a bool argument); and
2038  * partly to maintain compatibility with the constructor's interface,
2039  * which has separate syntactic constraints.
2040  *
2041  * @param input_converter A converter (if any) to be attached to the
2042  * input stream (note that this does not affect the operation of
2043  * set_byteswap()). The default value of an empty
2044  * GobjHandle<GConverter> object indicates no converter.
2045  *
2046  * @param output_converter A converter (if any) to be attached to the
2047  * output stream. The default value of an empty
2048  * GobjHandle<GConverter> object indicates no converter.
2049  *
2050  * @exception std::bad_alloc This method will throw std::bad_alloc if
2051  * memory is exhausted and the system throws on such exhaustion
2052  * (unless the library has been installed using the
2053  * --with-glib-memory-slices-compat or
2054  * --with-glib-memory-slices-no-compat configuration option, in which
2055  * case glib will terminate the program if it is unable to obtain
2056  * memory from the operating system).
2057  *
2058  * @note If a converter is provided, the stream will no longer be
2059  * seekable even if it otherwise would be, so tellg(), tellp(),
2060  * seekg() and seekp() will no longer work (they will return
2061  * pos_type(off_type(-1)). If the stream to which a converter has
2062  * been attached represents a file on the file system (rather than a
2063  * socket), after a read has been made, no further write may be made
2064  * using the same GFileIOStream object. These restrictions do not
2065  * apply to sockets (which are not seekable) so the use of converters
2066  * with input-output streams (GIOStream) should generally be
2067  * restricted to sockets.
2068  */
2069  void attach(const GobjHandle<GIOStream>& stream,
2070  bool manage,
2071  const GobjHandle<GConverter>& input_converter = GobjHandle<GConverter>(),
2072  const GobjHandle<GConverter>& output_converter = GobjHandle<GConverter>())
2073  {buf.attach_stream(stream, manage, input_converter, output_converter); this->clear();}
2074 
2075  /**
2076  * Call g_io_stream_close() on the GIO stream at present attached (if
2077  * any), and release the underlying C++ streambuffer's reference to
2078  * that stream. If the caller wants the GIO stream to survive the
2079  * call to this method (albeit in a closed state), the caller should,
2080  * before the call is made, keep a separate GobjHandle object which
2081  * references the stream. If the close fails, the failbit will be
2082  * set with setstate(std::ios_base::failbit). This class does not
2083  * offer concurrent access from multiple threads to the same stream
2084  * object, and if that is required users should provide their own
2085  * synchronisation.
2086  *
2087  * @exception std::ios_base::failure This exception will be thrown if
2088  * an error arises on closing the stream and such an exception has
2089  * been required by a call to the exceptions() method of this class
2090  * (inherited from std::basic_ios<>). No exception will be thrown if
2091  * exceptions() has not been called.
2092  */
2093  void close() {if (!buf.close_stream()) this->setstate(std::ios_base::failbit);}
2094 
2095  /**
2096  * Get the GIO input-output stream at present attached (if any), by
2097  * GobjHandle. If no stream has been attached, this method will
2098  * return an empty GobjHandle object. Retaining the return value
2099  * will cause the GIO input-output stream to survive the destruction
2100  * of this object. This method does not throw. This class does not
2101  * offer concurrent access from multiple threads to the same stream
2102  * object, and if that is required users should provide their own
2103  * synchronisation.
2104  *
2105  * @return The GIO input-output stream at present attached, or an
2106  * empty GobjHandle object if none has been attached
2107  */
2108  GobjHandle<GIOStream> get_gio_io_stream() const {return buf.get_iostream();}
2109 
2110  /**
2111  * Get the underlying GIO output stream at present attached (if any),
2112  * by GobjHandle. If none has been attached, this method will return
2113  * an empty GobjHandle object. Retaining the return value will cause
2114  * the GIO output stream to survive the destruction of this object.
2115  * The return value may be a different stream from the one kept by
2116  * the GIOStream object passed to this object's constructor or to
2117  * attach(). It will be different if a converter has been attached
2118  * to it. This method does not throw. This class does not offer
2119  * concurrent access from multiple threads to the same stream object,
2120  * and if that is required users should provide their own
2121  * synchronisation.
2122  *
2123  * @return The GIO output stream at present attached, or an empty
2124  * GobjHandle object if none has been attached
2125  */
2126  GobjHandle<GOutputStream> get_gio_output_stream() const {return buf.get_ostream();}
2127 
2128  /**
2129  * Get the GIO input stream at present attached (if any), by
2130  * GobjHandle. If none has been attached, this method will return an
2131  * empty GobjHandle object. Retaining the return value will cause
2132  * the GIO input stream to survive the destruction of this object. The
2133  * return value may be a different stream from the one kept by the
2134  * GIOStream object passed to this object's constructor or to
2135  * attach(). It will be different if a converter has been attached
2136  * to it. This method does not throw. This class does not offer
2137  * concurrent access from multiple threads to the same stream object,
2138  * and if that is required users should provide their own
2139  * synchronisation.
2140  *
2141  * @return The GIO input stream at present attached, or an empty
2142  * GobjHandle object if none has been attached
2143  */
2144  GobjHandle<GInputStream> get_gio_input_stream() const {return buf.get_istream();}
2145 
2146  /**
2147  * Causes the underlying streambuffer to swap bytes in the incoming
2148  * text, so as to convert big endian text to little endian text, or
2149  * little endian text to big endian text. It is called by the user
2150  * in response to finding a byte order marker (BOM) 0xfffe (UTF-16)
2151  * or 0xfffe0000 (UTF-32) as the first character of a newly opened
2152  * file/stream, or if the user knows by some other means that the
2153  * native endianness of the machine doing the reading differs from
2154  * the endianness of the file/stream being read. This only has
2155  * effect on wide character streams for input (for example, a
2156  * wgiostream object), and not the giostream narrow character stream.
2157  * Note also that characters held for output are always outputted in
2158  * native endian format unless a GConverter object has been attached,
2159  * and this method does not affect that. This method does not throw.
2160  * This class does not offer concurrent access from multiple threads
2161  * to the same stream object, and if that is required users should
2162  * provide their own synchronisation.
2163  *
2164  * @param swap 'true' if byte swapping for input is to be turned on,
2165  * 'false' if it is to be turned off. This will affect all
2166  * characters extracted from the underlying streambuffer after this
2167  * call is made. If a previously extracted character is to be
2168  * putback(), it must be put back before this function is called (or
2169  * unget() should be called instead) to avoid a putback mismatch,
2170  * because this call will byte-swap anything already in the buffers.
2171  * (Characters extracted after the call to this method may be putback
2172  * normally.)
2173  */
2174  void set_byteswap(bool swap) {buf.set_byteswap(swap);}
2175 
2176 /**
2177  * This method converts the attached GIO input-output stream to an
2178  * unbuffered stream for output if 'buffered' is false, or back to a
2179  * buffered stream if buffering has previously been switched off and
2180  * 'buffered' is true. Buffering is on by default for any newly
2181  * created giostream object and any newly attached GIO input-output
2182  * stream. If buffering is turned off, all characters at present in
2183  * the buffers which are stored for output are flushed (but if writing
2184  * to a file which is being written over/replaced, output may not
2185  * appear in the destination until the GIO stream is closed). This
2186  * method has no effect if no GIO input-output stream has yet been
2187  * attached. Switching output buffering off is similar in effect to
2188  * setting the std::ios_base::unitbuf flag, except that switching
2189  * buffering off is slightly more efficient, and setting the
2190  * std::ios_base::unitbuf flag will not retain the automatic tying of
2191  * logical and actual file positions that occurs when output buffering
2192  * is switched off, as explained @ref GioRandomAccessAnchor "here".
2193  * This class does not offer concurrent access from multiple threads
2194  * to the same stream object, and if that is required users should
2195  * provide their own synchronisation.
2196  *
2197  * @param buffered 'false' if buffering for output is to be turned
2198  * off, 'true' if it is to be turned back on.
2199  *
2200  * @exception std::bad_alloc This method will throw std::bad_alloc if
2201  * 'buffered' is true, output buffering had previously been switched
2202  * off, memory is exhausted and the system throws on such exhaustion
2203  * (unless the library has been installed using the
2204  * --with-glib-memory-slices-compat or
2205  * --with-glib-memory-slices-no-compat configuration option, in which
2206  * case glib will terminate the program if it is unable to obtain
2207  * memory from the operating system).
2208  */
2209  void set_output_buffered(bool buffered) {buf.set_output_buffered(buffered);}
2210 
2211 /**
2212  * This method indicates whether the attached GIO stream implements
2213  * GSeekable, so that a call to tellg(), tellp(), seekg() or seekp()
2214  * can succeed. Note that in the seekg(off_type off,
2215  * ios_base::seekdir dir) and seekp(off_type off, ios_base::seekdir
2216  * dir) variants, on wide character streams the 'off' argument is
2217  * dimensioned as the number of wchar_t/char32_t/char16_t units not
2218  * the number of bytes (that is, it is bytes/sizeof(char_type)). This
2219  * method does not throw. This class does not offer concurrent access
2220  * from multiple threads to the same stream object, and if that is
2221  * required users should provide their own synchronisation.
2222  *
2223  * @return true if the attached GIO stream implements GSeekable,
2224  * otherwise false. The result is only meaningful if a GIO stream has
2225  * been attached to this C++ stream object.
2226  */
2227  bool can_seek() const {return buf.can_seek();}
2228 
2229 /**
2230  * This method reports the error status of any attached GIO output
2231  * stream, and is intended to be called where failbit or badbit has
2232  * been set. It can be useful for interpreting conversion errors on
2233  * converting streams where one of those bits is set. This class does
2234  * not offer concurrent access from multiple threads to the same
2235  * stream object, and if that is required users should provide their
2236  * own synchronisation.
2237  *
2238  * @return NULL if no output stream is attached, or it is not in an
2239  * error state. If an attached output stream is in an error state,
2240  * say because it is a converting output stream which has encountered
2241  * a conversion error, the most recent GError object emitted by a
2242  * write operation on it is returned. Ownership of the return value
2243  * is retained, so if it is intended to be used after the next write
2244  * operation, it should be copied using g_error_copy().
2245  *
2246  * Since 2.0.5
2247  */
2248  GError* is_output_error() {return buf.is_output_error();}
2249 
2250 /**
2251  * This method reports the error status of any attached GIO input
2252  * stream, and is intended to be called where failbit has been set.
2253  * It can be useful for establishing, where that bit is set, whether
2254  * failbit indicates normal end-of-file or a conversion error on a
2255  * converting stream. This class does not offer concurrent access
2256  * from multiple threads to the same stream object, and if that is
2257  * required users should provide their own synchronisation.
2258  *
2259  * @return NULL if no input stream is attached, or it is not in an
2260  * error state. If an attached input stream is in an error state, say
2261  * because it is a converting input stream which has encountered a
2262  * conversion error, the most recent GError object emitted by a read
2263  * operation on it is returned. Ownership of the return value is
2264  * retained, so if it is intended to be used after the next read
2265  * operation, it should be copied using g_error_copy().
2266  *
2267  * Since 2.0.5
2268  */
2269  GError* is_input_error() {return buf.is_input_error();}
2270 
2271 /* Only has effect if --with-glib-memory-slices-compat or
2272  * --with-glib-memory-slices-no-compat option picked */
2274 };
2275 
2276 /**
2277  * @defgroup gstreams gstreams
2278  */
2279 /**
2280  * @typedef gstreambuf.
2281  * @brief C++ stream buffer for GIO streams for char type
2282  * @ingroup gstreams
2283  */
2285 
2286 /**
2287  * @typedef gistream.
2288  * @brief C++ input stream for GIO streams for char type
2289  * @anchor gistreamAnchor
2290  * @ingroup gstreams
2291  */
2293 
2294 /**
2295  * @typedef gostream.
2296  * @brief C++ output stream for GIO streams for char type
2297  * @anchor gostreamAnchor
2298  * @ingroup gstreams
2299  */
2301 
2302 /**
2303  * @typedef giostream.
2304  * @brief C++ input/output stream for GIO streams for char type
2305  * @anchor giostreamAnchor
2306  * @ingroup gstreams
2307  */
2309 
2310 /**
2311  * @typedef wgstreambuf.
2312  * @brief C++ stream buffer for GIO streams for wchar_t type
2313  * @ingroup gstreams
2314  */
2316 
2317 /**
2318  * @typedef wgistream.
2319  * @brief C++ input stream for GIO streams for wchar_t type
2320  * @anchor wgistreamAnchor
2321  * @ingroup gstreams
2322  */
2324 
2325 /**
2326  * @typedef wgostream.
2327  * @brief C++ output stream for GIO streams for wchar_t type
2328  * @anchor wgostreamAnchor
2329  * @ingroup gstreams
2330  */
2332 
2333 /**
2334  * @typedef wgiostream.
2335  * @brief C++ input/output stream for GIO streams for wchar_t type
2336  * @anchor wgiostreamAnchor
2337  * @ingroup gstreams
2338  */
2340 
2341 /**
2342  * @typedef u16gstreambuf.
2343  * @brief C++ stream buffer for GIO streams for char16_t type
2344  * @ingroup gstreams
2345  */
2347 
2348 /**
2349  * @typedef u16gistream.
2350  * @brief C++ input stream for GIO streams for char16_t type
2351  * @anchor u16gistreamAnchor
2352  * @ingroup gstreams
2353  */
2355 
2356 /**
2357  * @typedef u16gostream.
2358  * @brief C++ output stream for GIO streams for char16_t type
2359  * @anchor u16gostreamAnchor
2360  * @ingroup gstreams
2361  */
2363 
2364 /**
2365  * @typedef u16giostream.
2366  * @brief C++ input/output stream for GIO streams for char16_t type
2367  * @anchor u16giostreamAnchor
2368  * @ingroup gstreams
2369  */
2371 
2372 /**
2373  * @typedef u32gstreambuf.
2374  * @brief C++ stream buffer for GIO streams for char32_t type
2375  * @ingroup gstreams
2376  */
2378 
2379 /**
2380  * @typedef u32gistream.
2381  * @brief C++ input stream for GIO streams for char32_t type
2382  * @anchor u32gistreamAnchor
2383  * @ingroup gstreams
2384  */
2386 
2387 /**
2388  * @typedef u32gostream.
2389  * @brief C++ output stream for GIO streams for char32_t type
2390  * @anchor u32gostreamAnchor
2391  * @ingroup gstreams
2392  */
2394 
2395 /**
2396  * @typedef u32giostream.
2397  * @brief C++ input/output stream for GIO streams for char32_t type
2398  * @anchor u32giostreamAnchor
2399  * @ingroup gstreams
2400  */
2402 
2403 } // namespace Cgu
2404 
2405 #include <c++-gtk-utils/gstream.tpp>
2406 
2407 #else
2408 #warning gstreams are not available: glib >= 2.16.0 is required
2409 #endif /*GLIB_CHECK_VERSION(2,16,0)*/
2410 
2411 #endif /*CGU_GSTREAM_H*/