source/modules/water/streams/InputStream.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_INPUTSTREAM_H_INCLUDED
  27 #define WATER_INPUTSTREAM_H_INCLUDED
  28
  29 #include "../water.h"
  30
  31 namespace water {
  32
  33 //==============================================================================
  34 /** The base class for streams that read data.
  35
  36     Input and output streams are used throughout the library - subclasses can override
  37     some or all of the virtual functions to implement their behaviour.
  38
  39     @see OutputStream, MemoryInputStream, BufferedInputStream, FileInputStream
  40 */
  41 class InputStream
  42 {
  43 public:
  44     /** Destructor. */
  45     virtual ~InputStream()  {}
  46
  47     //==============================================================================
  48     /** Returns the total number of bytes available for reading in this stream.
  49
  50         Note that this is the number of bytes available from the start of the
  51         stream, not from the current position.
  52
  53         If the size of the stream isn't actually known, this will return -1.
  54
  55         @see getNumBytesRemaining
  56     */
  57     virtual int64 getTotalLength() = 0;
  58
  59     /** Returns the number of bytes available for reading, or a negative value if
  60         the remaining length is not known.
  61         @see getTotalLength
  62     */
  63     int64 getNumBytesRemaining();
  64
  65     /** Returns true if the stream has no more data to read. */
  66     virtual bool isExhausted() = 0;
  67
  68     //==============================================================================
  69     /** Reads some data from the stream into a memory buffer.
  70
  71         This is the only read method that subclasses actually need to implement, as the
  72         InputStream base class implements the other read methods in terms of this one (although
  73         it's often more efficient for subclasses to implement them directly).
  74
  75         @param destBuffer       the destination buffer for the data. This must not be null.
  76         @param maxBytesToRead   the maximum number of bytes to read - make sure the
  77                                 memory block passed in is big enough to contain this
  78                                 many bytes. This value must not be negative.
  79
  80         @returns    the actual number of bytes that were read, which may be less than
  81                     maxBytesToRead if the stream is exhausted before it gets that far
  82     */
  83     virtual int read (void* destBuffer, int maxBytesToRead) = 0;
  84
  85     /** Reads a byte from the stream.
  86         If the stream is exhausted, this will return zero.
  87         @see OutputStream::writeByte
  88     */
  89     virtual char readByte();
  90
  91     /** Reads a boolean from the stream.
  92         The bool is encoded as a single byte - non-zero for true, 0 for false.
  93         If the stream is exhausted, this will return false.
  94         @see OutputStream::writeBool
  95     */
  96     virtual bool readBool();
  97
  98     /** Reads two bytes from the stream as a little-endian 16-bit value.
  99         If the next two bytes read are byte1 and byte2, this returns (byte1 | (byte2 << 8)).
 100         If the stream is exhausted partway through reading the bytes, this will return zero.
 101         @see OutputStream::writeShort, readShortBigEndian
 102     */
 103     virtual short readShort();
 104
 105     /** Reads two bytes from the stream as a little-endian 16-bit value.
 106         If the next two bytes read are byte1 and byte2, this returns (byte2 | (byte1 << 8)).
 107         If the stream is exhausted partway through reading the bytes, this will return zero.
 108         @see OutputStream::writeShortBigEndian, readShort
 109     */
 110     virtual short readShortBigEndian();
 111
 112     /** Reads four bytes from the stream as a little-endian 32-bit value.
 113
 114         If the next four bytes are byte1 to byte4, this returns
 115         (byte1 | (byte2 << 8) | (byte3 << 16) | (byte4 << 24)).
 116
 117         If the stream is exhausted partway through reading the bytes, this will return zero.
 118
 119         @see OutputStream::writeInt, readIntBigEndian
 120     */
 121     virtual int readInt();
 122
 123     /** Reads four bytes from the stream as a big-endian 32-bit value.
 124
 125         If the next four bytes are byte1 to byte4, this returns
 126         (byte4 | (byte3 << 8) | (byte2 << 16) | (byte1 << 24)).
 127
 128         If the stream is exhausted partway through reading the bytes, this will return zero.
 129
 130         @see OutputStream::writeIntBigEndian, readInt
 131     */
 132     virtual int readIntBigEndian();
 133
 134     /** Reads eight bytes from the stream as a little-endian 64-bit value.
 135
 136         If the next eight bytes are byte1 to byte8, this returns
 137         (byte1 | (byte2 << 8) | (byte3 << 16) | (byte4 << 24) | (byte5 << 32) | (byte6 << 40) | (byte7 << 48) | (byte8 << 56)).
 138
 139         If the stream is exhausted partway through reading the bytes, this will return zero.
 140
 141         @see OutputStream::writeInt64, readInt64BigEndian
 142     */
 143     virtual int64 readInt64();
 144
 145     /** Reads eight bytes from the stream as a big-endian 64-bit value.
 146
 147         If the next eight bytes are byte1 to byte8, this returns
 148         (byte8 | (byte7 << 8) | (byte6 << 16) | (byte5 << 24) | (byte4 << 32) | (byte3 << 40) | (byte2 << 48) | (byte1 << 56)).
 149
 150         If the stream is exhausted partway through reading the bytes, this will return zero.
 151
 152         @see OutputStream::writeInt64BigEndian, readInt64
 153     */
 154     virtual int64 readInt64BigEndian();
 155
 156     /** Reads four bytes as a 32-bit floating point value.
 157         The raw 32-bit encoding of the float is read from the stream as a little-endian int.
 158         If the stream is exhausted partway through reading the bytes, this will return zero.
 159         @see OutputStream::writeFloat, readDouble
 160     */
 161     virtual float readFloat();
 162
 163     /** Reads four bytes as a 32-bit floating point value.
 164         The raw 32-bit encoding of the float is read from the stream as a big-endian int.
 165         If the stream is exhausted partway through reading the bytes, this will return zero.
 166         @see OutputStream::writeFloatBigEndian, readDoubleBigEndian
 167     */
 168     virtual float readFloatBigEndian();
 169
 170     /** Reads eight bytes as a 64-bit floating point value.
 171         The raw 64-bit encoding of the double is read from the stream as a little-endian int64.
 172         If the stream is exhausted partway through reading the bytes, this will return zero.
 173         @see OutputStream::writeDouble, readFloat
 174     */
 175     virtual double readDouble();
 176
 177     /** Reads eight bytes as a 64-bit floating point value.
 178         The raw 64-bit encoding of the double is read from the stream as a big-endian int64.
 179         If the stream is exhausted partway through reading the bytes, this will return zero.
 180         @see OutputStream::writeDoubleBigEndian, readFloatBigEndian
 181     */
 182     virtual double readDoubleBigEndian();
 183
 184     /** Reads an encoded 32-bit number from the stream using a space-saving compressed format.
 185         For small values, this is more space-efficient than using readInt() and OutputStream::writeInt()
 186         The format used is: number of significant bytes + up to 4 bytes in little-endian order.
 187         @see OutputStream::writeCompressedInt()
 188     */
 189     virtual int readCompressedInt();
 190
 191     //==============================================================================
 192     /** Reads a UTF-8 string from the stream, up to the next linefeed or carriage return.
 193
 194         This will read up to the next "\n" or "\r\n" or end-of-stream.
 195
 196         After this call, the stream's position will be left pointing to the next character
 197         following the line-feed, but the linefeeds aren't included in the string that
 198         is returned.
 199     */
 200     virtual String readNextLine();
 201
 202     /** Reads a zero-terminated UTF-8 string from the stream.
 203
 204         This will read characters from the stream until it hits a null character
 205         or end-of-stream.
 206
 207         @see OutputStream::writeString, readEntireStreamAsString
 208     */
 209     virtual String readString();
 210
 211     /** Tries to read the whole stream and turn it into a string.
 212
 213         This will read from the stream's current position until the end-of-stream.
 214         It can read from UTF-8 data, or UTF-16 if it detects suitable header-bytes.
 215     */
 216     virtual String readEntireStreamAsString();
 217
 218     /** Reads from the stream and appends the data to a MemoryBlock.
 219
 220         @param destBlock            the block to append the data onto
 221         @param maxNumBytesToRead    if this is a positive value, it sets a limit to the number
 222                                     of bytes that will be read - if it's negative, data
 223                                     will be read until the stream is exhausted.
 224         @returns the number of bytes that were added to the memory block
 225     */
 226     virtual size_t readIntoMemoryBlock (MemoryBlock& destBlock,
 227                                         ssize_t maxNumBytesToRead = -1);
 228
 229     //==============================================================================
 230     /** Returns the offset of the next byte that will be read from the stream.
 231         @see setPosition
 232     */
 233     virtual int64 getPosition() = 0;
 234
 235     /** Tries to move the current read position of the stream.
 236
 237         The position is an absolute number of bytes from the stream's start.
 238
 239         Some streams might not be able to do this, in which case they should do
 240         nothing and return false. Others might be able to manage it by resetting
 241         themselves and skipping to the correct position, although this is
 242         obviously a bit slow.
 243
 244         @returns  true if the stream manages to reposition itself correctly
 245         @see getPosition
 246     */
 247     virtual bool setPosition (int64 newPosition) = 0;
 248
 249     /** Reads and discards a number of bytes from the stream.
 250
 251         Some input streams might implement this efficiently, but the base
 252         class will just keep reading data until the requisite number of bytes
 253         have been done.
 254     */
 255     virtual void skipNextBytes (int64 numBytesToSkip);
 256
 257 protected:
 258     //==============================================================================
 259     InputStream() noexcept {}
 260
 261 private:
 262     CARLA_DECLARE_NON_COPYABLE (InputStream)
 263 };
 264
 265 }
 266
 267 #endif // WATER_INPUTSTREAM_H_INCLUDED