source/modules/water/streams/OutputStream.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the Water library.
   5    Copyright (c) 2016 ROLI Ltd.
   6    Copyright (C) 2017-2022 Filipe Coelho <falktx@falktx.com>
   7
   8    Permission is granted to use this software under the terms of the ISC license
   9    http://www.isc.org/downloads/software-support-policy/isc-license/
  10
  11    Permission to use, copy, modify, and/or distribute this software for any
  12    purpose with or without fee is hereby granted, provided that the above
  13    copyright notice and this permission notice appear in all copies.
  14
  15    THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH REGARD
  16    TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
  17    FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT,
  18    OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
  19    USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
  20    TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
  21    OF THIS SOFTWARE.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef WATER_OUTPUTSTREAM_H_INCLUDED
  27 #define WATER_OUTPUTSTREAM_H_INCLUDED
  28
  29 #include "../water.h"
  30 #include "../text/String.h"
  31
  32 namespace water {
  33
  34 //==============================================================================
  35 /**
  36     The base class for streams that write data to some kind of destination.
  37
  38     Input and output streams are used throughout the library - subclasses can override
  39     some or all of the virtual functions to implement their behaviour.
  40
  41     @see InputStream, MemoryOutputStream, FileOutputStream
  42 */
  43 class OutputStream
  44 {
  45 protected:
  46     //==============================================================================
  47     OutputStream();
  48
  49 public:
  50     /** Destructor.
  51
  52         Some subclasses might want to do things like call flush() during their
  53         destructors.
  54     */
  55     virtual ~OutputStream();
  56
  57     //==============================================================================
  58     /** If the stream is using a buffer, this will ensure it gets written
  59         out to the destination. */
  60     virtual void flush() = 0;
  61
  62     /** Tries to move the stream's output position.
  63
  64         Not all streams will be able to seek to a new position - this will return
  65         false if it fails to work.
  66
  67         @see getPosition
  68     */
  69     virtual bool setPosition (int64 newPosition) = 0;
  70
  71     /** Returns the stream's current position.
  72
  73         @see setPosition
  74     */
  75     virtual int64 getPosition() = 0;
  76
  77     //==============================================================================
  78     /** Writes a block of data to the stream.
  79
  80         When creating a subclass of OutputStream, this is the only write method
  81         that needs to be overloaded - the base class has methods for writing other
  82         types of data which use this to do the work.
  83
  84         @param dataToWrite      the target buffer to receive the data. This must not be null.
  85         @param numberOfBytes    the number of bytes to write.
  86         @returns false if the write operation fails for some reason
  87     */
  88     virtual bool write (const void* dataToWrite,
  89                         size_t numberOfBytes) = 0;
  90
  91     //==============================================================================
  92     /** Writes a single byte to the stream.
  93         @returns false if the write operation fails for some reason
  94         @see InputStream::readByte
  95     */
  96     virtual bool 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         @returns false if the write operation fails for some reason
 101         @see InputStream::readBool
 102     */
 103     virtual bool writeBool (bool boolValue);
 104
 105     /** Writes a 16-bit integer to the stream in a little-endian byte order.
 106         This will write two bytes to the stream: (value & 0xff), then (value >> 8).
 107         @returns false if the write operation fails for some reason
 108         @see InputStream::readShort
 109     */
 110     virtual bool writeShort (short value);
 111
 112     /** Writes a 16-bit integer to the stream in a big-endian byte order.
 113         This will write two bytes to the stream: (value >> 8), then (value & 0xff).
 114         @returns false if the write operation fails for some reason
 115         @see InputStream::readShortBigEndian
 116     */
 117     virtual bool writeShortBigEndian (short value);
 118
 119     /** Writes a 32-bit integer to the stream in a little-endian byte order.
 120         @returns false if the write operation fails for some reason
 121         @see InputStream::readInt
 122     */
 123     virtual bool writeInt (int value);
 124
 125     /** Writes a 32-bit integer to the stream in a big-endian byte order.
 126         @returns false if the write operation fails for some reason
 127         @see InputStream::readIntBigEndian
 128     */
 129     virtual bool writeIntBigEndian (int value);
 130
 131     /** Writes a 64-bit integer to the stream in a little-endian byte order.
 132         @returns false if the write operation fails for some reason
 133         @see InputStream::readInt64
 134     */
 135     virtual bool writeInt64 (int64 value);
 136
 137     /** Writes a 64-bit integer to the stream in a big-endian byte order.
 138         @returns false if the write operation fails for some reason
 139         @see InputStream::readInt64BigEndian
 140     */
 141     virtual bool writeInt64BigEndian (int64 value);
 142
 143     /** Writes a 32-bit floating point value to the stream in a binary format.
 144         The binary 32-bit encoding of the float is written as a little-endian int.
 145         @returns false if the write operation fails for some reason
 146         @see InputStream::readFloat
 147     */
 148     virtual bool writeFloat (float value);
 149
 150     /** Writes a 32-bit floating point value to the stream in a binary format.
 151         The binary 32-bit encoding of the float is written as a big-endian int.
 152         @returns false if the write operation fails for some reason
 153         @see InputStream::readFloatBigEndian
 154     */
 155     virtual bool writeFloatBigEndian (float value);
 156
 157     /** Writes a 64-bit floating point value to the stream in a binary format.
 158         The eight raw bytes of the double value are written out as a little-endian 64-bit int.
 159         @returns false if the write operation fails for some reason
 160         @see InputStream::readDouble
 161     */
 162     virtual bool writeDouble (double value);
 163
 164     /** Writes a 64-bit floating point value to the stream in a binary format.
 165         The eight raw bytes of the double value are written out as a big-endian 64-bit int.
 166         @see InputStream::readDoubleBigEndian
 167         @returns false if the write operation fails for some reason
 168     */
 169     virtual bool writeDoubleBigEndian (double value);
 170
 171     /** Writes a byte to the output stream a given number of times.
 172         @returns false if the write operation fails for some reason
 173     */
 174     virtual bool writeRepeatedByte (uint8 byte, size_t numTimesToRepeat);
 175
 176     /** Writes a condensed binary encoding of a 32-bit integer.
 177
 178         If you're storing a lot of integers which are unlikely to have very large values,
 179         this can save a lot of space, because values under 0xff will only take up 2 bytes,
 180         under 0xffff only 3 bytes, etc.
 181
 182         The format used is: number of significant bytes + up to 4 bytes in little-endian order.
 183
 184         @returns false if the write operation fails for some reason
 185         @see InputStream::readCompressedInt
 186     */
 187     virtual bool writeCompressedInt (int value);
 188
 189     /** Stores a string in the stream in a binary format.
 190
 191         This isn't the method to use if you're trying to append text to the end of a
 192         text-file! It's intended for storing a string so that it can be retrieved later
 193         by InputStream::readString().
 194
 195         It writes the string to the stream as UTF8, including the null termination character.
 196
 197         For appending text to a file, instead use writeText, or operator<<
 198
 199         @returns false if the write operation fails for some reason
 200         @see InputStream::readString, writeText, operator<<
 201     */
 202     virtual bool writeString (const String& text);
 203
 204     /** Writes a string of text to the stream.
 205
 206         It can either write the text as UTF-8 or UTF-16, and can also add the UTF-16 byte-order-mark
 207         bytes (0xff, 0xfe) to indicate the endianness (these should only be used at the start
 208         of a file).
 209
 210         The method also replaces '\\n' characters in the text with '\\r\\n'.
 211         @returns false if the write operation fails for some reason
 212     */
 213     virtual bool writeText (const String& text,
 214                             bool asUTF16,
 215                             bool writeUTF16ByteOrderMark);
 216
 217     /** Reads data from an input stream and writes it to this stream.
 218
 219         @param source               the stream to read from
 220         @param maxNumBytesToWrite   the number of bytes to read from the stream (if this is
 221                                     less than zero, it will keep reading until the input
 222                                     is exhausted)
 223         @returns the number of bytes written
 224     */
 225     virtual int64 writeFromInputStream (InputStream& source, int64 maxNumBytesToWrite);
 226
 227     //==============================================================================
 228     /** Sets the string to write to the stream when a new line is written.
 229         By default this will be set the value of NewLine::getDefault().
 230     */
 231     void setNewLineString (const String& newLineString);
 232
 233     /** Returns the current new-line string that was set by setNewLineString(). */
 234     const String& getNewLineString() const noexcept         { return newLineString; }
 235
 236 private:
 237     //==============================================================================
 238     String newLineString;
 239
 240     CARLA_DECLARE_NON_COPYABLE (OutputStream)
 241 };
 242
 243 //==============================================================================
 244 /** Writes a number to a stream as 8-bit characters in the default system encoding. */
 245 OutputStream& operator<< (OutputStream& stream, int number);
 246
 247 /** Writes a number to a stream as 8-bit characters in the default system encoding. */
 248 OutputStream& operator<< (OutputStream& stream, int64 number);
 249
 250 /** Writes a number to a stream as 8-bit characters in the default system encoding. */
 251 OutputStream& operator<< (OutputStream& stream, double number);
 252
 253 /** Writes a character to a stream. */
 254 OutputStream& operator<< (OutputStream& stream, char character);
 255
 256 /** Writes a null-terminated text string to a stream. */
 257 OutputStream& operator<< (OutputStream& stream, const char* text);
 258
 259 /** Writes a block of data from a MemoryBlock to a stream. */
 260 OutputStream& operator<< (OutputStream& stream, const MemoryBlock& data);
 261
 262 /** Writes the contents of a file to a stream. */
 263 OutputStream& operator<< (OutputStream& stream, const File& fileToRead);
 264
 265 /** Writes the complete contents of an input stream to an output stream. */
 266 OutputStream& operator<< (OutputStream& stream, InputStream& streamToRead);
 267
 268 /** Writes a new-line to a stream.
 269     You can use the predefined symbol 'newLine' to invoke this, e.g.
 270     @code
 271     myOutputStream << "Hello World" << newLine << newLine;
 272     @endcode
 273     @see OutputStream::setNewLineString
 274 */
 275 OutputStream& operator<< (OutputStream& stream, const NewLine&);
 276
 277 }
 278
 279 #endif // WATER_OUTPUTSTREAM_H_INCLUDED