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