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