juce/source/src/io/streams/juce_OutputStream.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library - "Jules' Utility Class Extensions"
   5    Copyright 2004-11 by Raw Material Software Ltd.
   6
   7   ------------------------------------------------------------------------------
   8
   9    JUCE can be redistributed and/or modified under the terms of the GNU General
  10    Public License (Version 2), as published by the Free Software Foundation.
  11    A copy of the license is included in the JUCE distribution, or can be found
  12    online at www.gnu.org/licenses.
  13
  14    JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  15    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  16    A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  17
  18   ------------------------------------------------------------------------------
  19
  20    To release a closed-source product which uses JUCE, commercial licenses are
  21    available: visit www.rawmaterialsoftware.com/juce for more information.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef __JUCE_OUTPUTSTREAM_JUCEHEADER__
  27 #define __JUCE_OUTPUTSTREAM_JUCEHEADER__
  28
  29 #include "../../text/juce_String.h"
  30 #include "../../text/juce_NewLine.h"
  31 class InputStream;
  32 class MemoryBlock;
  33 class File;
  34
  35
  36 //==============================================================================
  37 /**
  38     The base class for streams that write data to some kind of destination.
  39
  40     Input and output streams are used throughout the library - subclasses can override
  41     some or all of the virtual functions to implement their behaviour.
  42
  43     @see InputStream, MemoryOutputStream, FileOutputStream
  44 */
  45 class JUCE_API  OutputStream
  46 {
  47 protected:
  48     //==============================================================================
  49     OutputStream();
  50
  51 public:
  52     /** Destructor.
  53
  54         Some subclasses might want to do things like call flush() during their
  55         destructors.
  56     */
  57     virtual ~OutputStream();
  58
  59     //==============================================================================
  60     /** If the stream is using a buffer, this will ensure it gets written
  61         out to the destination. */
  62     virtual void flush() = 0;
  63
  64     /** Tries to move the stream's output position.
  65
  66         Not all streams will be able to seek to a new position - this will return
  67         false if it fails to work.
  68
  69         @see getPosition
  70     */
  71     virtual bool setPosition (int64 newPosition) = 0;
  72
  73     /** Returns the stream's current position.
  74
  75         @see setPosition
  76     */
  77     virtual int64 getPosition() = 0;
  78
  79     //==============================================================================
  80     /** Writes a block of data to the stream.
  81
  82         When creating a subclass of OutputStream, this is the only write method
  83         that needs to be overloaded - the base class has methods for writing other
  84         types of data which use this to do the work.
  85
  86         @returns false if the write operation fails for some reason
  87     */
  88     virtual bool write (const void* dataToWrite,
  89                         int howManyBytes) = 0;
  90
  91     //==============================================================================
  92     /** Writes a single byte to the stream.
  93
  94         @see InputStream::readByte
  95     */
  96     virtual void writeByte (char byte);
  97
  98     /** Writes a boolean to the stream as a single byte.
  99         This is encoded as a binary byte (not as text) with a value of 1 or 0.
 100         @see InputStream::readBool
 101     */
 102     virtual void writeBool (bool boolValue);
 103
 104     /** Writes a 16-bit integer to the stream in a little-endian byte order.
 105         This will write two bytes to the stream: (value & 0xff), then (value >> 8).
 106         @see InputStream::readShort
 107     */
 108     virtual void writeShort (short value);
 109
 110     /** Writes a 16-bit integer to the stream in a big-endian byte order.
 111         This will write two bytes to the stream: (value >> 8), then (value & 0xff).
 112         @see InputStream::readShortBigEndian
 113     */
 114     virtual void writeShortBigEndian (short value);
 115
 116     /** Writes a 32-bit integer to the stream in a little-endian byte order.
 117         @see InputStream::readInt
 118     */
 119     virtual void writeInt (int value);
 120
 121     /** Writes a 32-bit integer to the stream in a big-endian byte order.
 122         @see InputStream::readIntBigEndian
 123     */
 124     virtual void writeIntBigEndian (int value);
 125
 126     /** Writes a 64-bit integer to the stream in a little-endian byte order.
 127         @see InputStream::readInt64
 128     */
 129     virtual void writeInt64 (int64 value);
 130
 131     /** Writes a 64-bit integer to the stream in a big-endian byte order.
 132         @see InputStream::readInt64BigEndian
 133     */
 134     virtual void writeInt64BigEndian (int64 value);
 135
 136     /** Writes a 32-bit floating point value to the stream in a binary format.
 137         The binary 32-bit encoding of the float is written as a little-endian int.
 138         @see InputStream::readFloat
 139     */
 140     virtual void writeFloat (float value);
 141
 142     /** Writes a 32-bit floating point value to the stream in a binary format.
 143         The binary 32-bit encoding of the float is written as a big-endian int.
 144         @see InputStream::readFloatBigEndian
 145     */
 146     virtual void writeFloatBigEndian (float value);
 147
 148     /** Writes a 64-bit floating point value to the stream in a binary format.
 149         The eight raw bytes of the double value are written out as a little-endian 64-bit int.
 150         @see InputStream::readDouble
 151     */
 152     virtual void writeDouble (double value);
 153
 154     /** Writes a 64-bit floating point value to the stream in a binary format.
 155         The eight raw bytes of the double value are written out as a big-endian 64-bit int.
 156         @see InputStream::readDoubleBigEndian
 157     */
 158     virtual void writeDoubleBigEndian (double value);
 159
 160     /** Writes a byte to the output stream a given number of times. */
 161     virtual void writeRepeatedByte (uint8 byte, int numTimesToRepeat);
 162
 163     /** Writes a condensed binary encoding of a 32-bit integer.
 164
 165         If you're storing a lot of integers which are unlikely to have very large values,
 166         this can save a lot of space, because values under 0xff will only take up 2 bytes,
 167         under 0xffff only 3 bytes, etc.
 168
 169         The format used is: number of significant bytes + up to 4 bytes in little-endian order.
 170
 171         @see InputStream::readCompressedInt
 172     */
 173     virtual void writeCompressedInt (int value);
 174
 175     /** Stores a string in the stream in a binary format.
 176
 177         This isn't the method to use if you're trying to append text to the end of a
 178         text-file! It's intended for storing a string so that it can be retrieved later
 179         by InputStream::readString().
 180
 181         It writes the string to the stream as UTF8, including the null termination character.
 182
 183         For appending text to a file, instead use writeText, or operator<<
 184
 185         @see InputStream::readString, writeText, operator<<
 186     */
 187     virtual void writeString (const String& text);
 188
 189     /** Writes a string of text to the stream.
 190
 191         It can either write the text as UTF-8 or UTF-16, and can also add the UTF-16 byte-order-mark
 192         bytes (0xff, 0xfe) to indicate the endianness (these should only be used at the start
 193         of a file).
 194
 195         The method also replaces '\\n' characters in the text with '\\r\\n'.
 196     */
 197     virtual void writeText (const String& text,
 198                             bool asUTF16,
 199                             bool writeUTF16ByteOrderMark);
 200
 201     /** Reads data from an input stream and writes it to this stream.
 202
 203         @param source               the stream to read from
 204         @param maxNumBytesToWrite   the number of bytes to read from the stream (if this is
 205                                     less than zero, it will keep reading until the input
 206                                     is exhausted)
 207     */
 208     virtual int writeFromInputStream (InputStream& source, int64 maxNumBytesToWrite);
 209
 210     //==============================================================================
 211     /** Sets the string that will be written to the stream when the writeNewLine()
 212         method is called.
 213         By default this will be set the the value of NewLine::getDefault().
 214     */
 215     void setNewLineString (const String& newLineString);
 216
 217     /** Returns the current new-line string that was set by setNewLineString(). */
 218     const String& getNewLineString() const noexcept         { return newLineString; }
 219
 220 private:
 221     //==============================================================================
 222     String newLineString;
 223
 224     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (OutputStream);
 225 };
 226
 227 //==============================================================================
 228 /** Writes a number to a stream as 8-bit characters in the default system encoding. */
 229 OutputStream& JUCE_CALLTYPE operator<< (OutputStream& stream, int number);
 230
 231 /** Writes a number to a stream as 8-bit characters in the default system encoding. */
 232 OutputStream& JUCE_CALLTYPE operator<< (OutputStream& stream, double number);
 233
 234 /** Writes a character to a stream. */
 235 OutputStream& JUCE_CALLTYPE operator<< (OutputStream& stream, char character);
 236
 237 /** Writes a null-terminated text string to a stream. */
 238 OutputStream& JUCE_CALLTYPE operator<< (OutputStream& stream, const char* text);
 239
 240 /** Writes a block of data from a MemoryBlock to a stream. */
 241 OutputStream& JUCE_CALLTYPE operator<< (OutputStream& stream, const MemoryBlock& data);
 242
 243 /** Writes the contents of a file to a stream. */
 244 OutputStream& JUCE_CALLTYPE operator<< (OutputStream& stream, const File& fileToRead);
 245
 246 /** Writes a new-line to a stream.
 247     You can use the predefined symbol 'newLine' to invoke this, e.g.
 248     @code
 249     myOutputStream << "Hello World" << newLine << newLine;
 250     @endcode
 251     @see OutputStream::setNewLineString
 252 */
 253 OutputStream& JUCE_CALLTYPE operator<< (OutputStream& stream, const NewLine&);
 254
 255
 256 #endif   // __JUCE_OUTPUTSTREAM_JUCEHEADER__