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