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