docs/reference/pygio-bufferedoutputstream.xml

   1 <?xml version="1.0" standalone="no"?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3     "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
   4
   5 <refentry id="class-giobufferedoutputstream">
   6     <refnamediv>
   7         <refname>gio.BufferedOutputStream</refname>
   8         <refpurpose>Buffered Output Stream</refpurpose>
   9     </refnamediv>
  10
  11     <refsect1>
  12         <title>Synopsis</title>
  13
  14     <classsynopsis language="python">
  15         <ooclass><classname>gio.BufferedOutputStream</classname></ooclass>
  16         <ooclass><classname><link linkend="class-giofilteroutputstream">gio.FilterOutputStream</link></classname></ooclass>
  17
  18     <constructorsynopsis language="python">
  19         <methodname><link linkend="constructor-giobufferedoutputstream">gio.BufferedOutputStream</link></methodname>
  20         <methodparam><parameter role="keyword">base_stream</parameter></methodparam>
  21     </constructorsynopsis>
  22
  23     <methodsynopsis language="python">
  24         <methodname><link linkend="method-giobufferedoutputstream--get-auto-grow">get_auto_grow</link></methodname>
  25         <methodparam></methodparam>
  26     </methodsynopsis>
  27     <methodsynopsis language="python">
  28         <methodname><link linkend="method-giobufferedoutputstream--get-buffer-size">get_buffer_size</link></methodname>
  29         <methodparam></methodparam>
  30     </methodsynopsis>
  31     <methodsynopsis language="python">
  32         <methodname><link linkend="method-giobufferedoutputstream--set-auto-grow">set_auto_grow</link></methodname>
  33         <methodparam><parameter role="keyword">auto_grow</parameter></methodparam>
  34     </methodsynopsis>
  35     <methodsynopsis language="python">
  36         <methodname><link linkend="method-giobufferedoutputstream--set-buffer-size">set_buffer_size</link></methodname>
  37         <methodparam><parameter role="keyword">size</parameter></methodparam>
  38     </methodsynopsis>
  39
  40     </classsynopsis>
  41
  42 <programlisting>
  43 <emphasis role="bold">Functions</emphasis>
  44
  45 <methodsynopsis language="python">
  46     <methodname><link linkend="function-gio--buffered-output-stream-new-sized">gio.buffered_output_stream_new_sized</link></methodname>
  47     <methodparam><parameter role="keyword">size</parameter></methodparam>
  48 </methodsynopsis></programlisting>
  49
  50     </refsect1>
  51
  52     <refsect1>
  53         <title>Ancestry</title>
  54
  55 <synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  56   +-- <link linkend="class-giooutputstream">gio.OutputStream</link>
  57     +-- <link linkend="class-giofilteroutputstream">gio.FilterOutputStream</link>
  58       +-- <link linkend="class-giobufferedoutputstream">gio.BufferedOutputStream</link>
  59 </synopsis>
  60
  61     </refsect1>
  62
  63     <refsect1 id="properties-giobufferedoutputstream">
  64         <title>gio.BufferedOutputStream Properties</title>
  65
  66         <blockquote role="properties">
  67             <informaltable pgwide="1" frame="none">
  68                 <tgroup cols="3">
  69                     <colspec column="1" colwidth="1in"/>
  70                     <colspec column="2" colwidth="1in"/>
  71                     <colspec column="3" colwidth="4in"/>
  72                     <tbody>
  73                         <row valign="top">
  74                             <entry>"auto-grow"</entry>
  75                             <entry>Read - Write</entry>
  76                             <entry>Whether the buffer should automatically grow. Default value: <literal>False</literal>.</entry>
  77                         </row>
  78                         <row valign="top">
  79                             <entry>"buffer-size"</entry>
  80                             <entry>Read - Write - Construct</entry>
  81                             <entry>The size of the backend buffer. Allowed values: >= 1. Default value: 4096.</entry>
  82                         </row>
  83                     </tbody>
  84                 </tgroup>
  85             </informaltable>
  86         </blockquote>
  87
  88     </refsect1>
  89
  90     <refsect1>
  91         <title>Description</title>
  92
  93         <para>
  94             <link linkend="class-giobufferedoutputstream"><classname>gio.BufferedOutputStream</classname></link>
  95             implements <link linkend="class-giofilteroutputstream"><classname>gio.FilterOutputStream</classname></link>
  96             and provides for buffered writes.
  97         </para>
  98         <para>
  99             By default,
 100             <link linkend="class-giobufferedoutputstream"><classname>gio.BufferedOutputStream</classname></link>'s
 101             buffer size is set at 4 kilobytes.
 102         </para>
 103         <para>
 104             To create a buffered output stream, use
 105             <methodname><link linkend="constructor-giobufferedoutputstream">gio.BufferedOutputStream</link></methodname>(),
 106             or <methodname><link linkend="function-gio--buffered-output-stream-new-sized">gio.buffered_output_stream_new_sized</link></methodname>()
 107             to specify the buffer's size at construction.
 108         </para>
 109         <para>
 110             To get the size of a buffer within a buffered output stream, use
 111             <methodname><link linkend="method-giobufferedoutputstream--get-buffer-size">gio.BufferedOutputStream.get_buffer_size</link></methodname>().
 112             To change the size of a buffered output stream's buffer, use
 113             <methodname><link linkend="method-giobufferedoutputstream--set-buffer-size">gio.BufferedOutputStream.set_buffer_size</link></methodname>().
 114             Note that the buffer's size cannot be reduced below the size of the data within the buffer.
 115         </para>
 116     </refsect1>
 117
 118     <refsect1 id="constructor-giobufferedoutputstream">
 119         <title>Constructor</title>
 120
 121         <programlisting><constructorsynopsis language="python">
 122             <methodname>gio.BufferedOutputStream</methodname>
 123             <methodparam><parameter role="keyword">base_stream</parameter></methodparam>
 124         </constructorsynopsis></programlisting>
 125         <variablelist>
 126             <varlistentry>
 127                 <term><parameter>base_stream</parameter>&nbsp;:</term>
 128                 <listitem><simpara>a
 129                 <link linkend="class-giooutputstream"><classname>gio.OutputStream</classname></link>.
 130                 </simpara></listitem>
 131             </varlistentry>
 132             <varlistentry>
 133                 <term><emphasis>Returns</emphasis>&nbsp;:</term>
 134                 <listitem><simpara>a new
 135                 <link linkend="class-giooutputstream"><classname>gio.OutputStream</classname></link>
 136                 for the given base_stream.
 137                 </simpara></listitem>
 138             </varlistentry>
 139         </variablelist>
 140
 141         <para>
 142             Creates a new buffered output stream for a base stream.
 143         </para>
 144
 145     </refsect1>
 146
 147     <refsect1>
 148         <title>Methods</title>
 149
 150         <refsect2 id="method-giobufferedoutputstream--get-auto-grow">
 151             <title>gio.BufferedOutputStream.get_auto_grow</title>
 152
 153             <programlisting><methodsynopsis language="python">
 154                 <methodname>get_auto_grow</methodname>
 155                 <methodparam></methodparam>
 156             </methodsynopsis></programlisting>
 157
 158             <variablelist>
 159                 <varlistentry>
 160                     <term><emphasis>Returns</emphasis>&nbsp;:</term>
 161                     <listitem><simpara><literal>True</literal> if the stream's
 162                     buffer automatically grows, <literal>False</literal> otherwise.
 163                     </simpara></listitem>
 164                 </varlistentry>
 165             </variablelist>
 166
 167             <para>
 168                 The <methodname>get_auto_grow</methodname>() method checks if the
 169                 buffer automatically grows as data is added.
 170             </para>
 171         </refsect2>
 172
 173         <refsect2 id="method-giobufferedoutputstream--get-buffer-size">
 174             <title>gio.BufferedOutputStream.get_buffer_size</title>
 175
 176             <programlisting><methodsynopsis language="python">
 177                 <methodname>get_buffer_size</methodname>
 178                 <methodparam></methodparam>
 179             </methodsynopsis></programlisting>
 180
 181             <variablelist>
 182                 <varlistentry>
 183                     <term><emphasis>Returns</emphasis>&nbsp;:</term>
 184                     <listitem><simpara>the current buffer size.
 185                     </simpara></listitem>
 186                 </varlistentry>
 187             </variablelist>
 188
 189             <para>
 190                 The <methodname>get_buffer_size</methodname>() method gets the size
 191                 of the buffer in the stream.
 192             </para>
 193         </refsect2>
 194
 195         <refsect2 id="method-giobufferedoutputstream--set-auto-grow">
 196             <title>gio.BufferedOutputStream.set_auto_grow</title>
 197
 198             <programlisting><methodsynopsis language="python">
 199                 <methodname>set_auto_grow</methodname>
 200                 <methodparam><parameter role="keyword">auto_grow</parameter></methodparam>
 201             </methodsynopsis></programlisting>
 202
 203             <variablelist>
 204                 <varlistentry>
 205                   <term><parameter role="keyword">auto_grow</parameter>&nbsp;:</term>
 206                   <listitem><simpara>a boolean.
 207                   </simpara></listitem>
 208                 </varlistentry>
 209             </variablelist>
 210
 211             <para>
 212                 The <methodname>set_auto_grow</methodname>() method sets whether or not
 213                 the stream's buffer should automatically grow. If auto_grow is true,
 214                 then each write will just make the buffer larger, and you must manually
 215                 flush the buffer to actually write out the data to the underlying stream.
 216             </para>
 217         </refsect2>
 218
 219         <refsect2 id="method-giobufferedoutputstream--set-buffer-size">
 220             <title>gio.BufferedOutputStream.set_buffer_size</title>
 221
 222             <programlisting><methodsynopsis language="python">
 223                 <methodname>set_buffer_size</methodname>
 224                 <methodparam><parameter role="keyword">size</parameter></methodparam>
 225             </methodsynopsis></programlisting>
 226
 227             <variablelist>
 228                 <varlistentry>
 229                   <term><parameter role="keyword">size</parameter>&nbsp;:</term>
 230                   <listitem><simpara>the new buffer size.
 231                   </simpara></listitem>
 232                 </varlistentry>
 233             </variablelist>
 234
 235             <para>
 236                 The <methodname>set_buffer_size</methodname>() method sets the size of
 237                 the internal buffer to size.
 238             </para>
 239         </refsect2>
 240     </refsect1>
 241
 242     <refsect1>
 243         <title>Functions</title>
 244
 245         <refsect2 id="function-gio--buffered-output-stream-new-sized">
 246             <title>gio.buffered_output_stream_new_sized</title>
 247
 248             <programlisting><methodsynopsis language="python">
 249                 <methodname>buffered_output_stream_new_sized</methodname>
 250                 <methodparam><parameter role="keyword">size</parameter></methodparam>
 251             </methodsynopsis></programlisting>
 252
 253             <variablelist>
 254                 <varlistentry>
 255                     <term><parameter>size</parameter>&nbsp;:</term>
 256                     <listitem><simpara>the requested buffer size.
 257                     </simpara></listitem>
 258                 </varlistentry>
 259                 <varlistentry>
 260                     <term><emphasis>Returns</emphasis>&nbsp;:</term>
 261                     <listitem><simpara>A new
 262                     <link linkend="class-giooutputstream"><classname>gio.OutputStream</classname></link>
 263                     with an internal buffer set to size..
 264                     </simpara></listitem>
 265                 </varlistentry>
 266             </variablelist>
 267
 268             <para>
 269                 The <methodname>buffered_output_stream_new_sized</methodname>() function creates
 270                 a new <link linkend="class-giobufferedoutputstream"><classname>gio.BufferedOutputStream</classname></link>
 271                 from the given base_stream, with a buffer set to size.
 272             </para>
 273         </refsect2>
 274     </refsect1>
 275 </refentry>