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