OpenShot Library | libopenshot-audio 0.2.0
juce_OutputStream.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
27namespace juce
28{
29
30//==============================================================================
31/**
32 The base class for streams that write data to some kind of destination.
33
34 Input and output streams are used throughout the library - subclasses can override
35 some or all of the virtual functions to implement their behaviour.
36
37 @see InputStream, MemoryOutputStream, FileOutputStream
38
39 @tags{Core}
40*/
42{
43protected:
44 //==============================================================================
46
47public:
48 /** Destructor.
49
50 Some subclasses might want to do things like call flush() during their
51 destructors.
52 */
53 virtual ~OutputStream();
54
55 //==============================================================================
56 /** If the stream is using a buffer, this will ensure it gets written
57 out to the destination. */
58 virtual void flush() = 0;
59
60 /** Tries to move the stream's output position.
61
62 Not all streams will be able to seek to a new position - this will return
63 false if it fails to work.
64
65 @see getPosition
66 */
67 virtual bool setPosition (int64 newPosition) = 0;
68
69 /** Returns the stream's current position.
70
71 @see setPosition
72 */
73 virtual int64 getPosition() = 0;
74
75 //==============================================================================
76 /** Writes a block of data to the stream.
77
78 When creating a subclass of OutputStream, this is the only write method
79 that needs to be overloaded - the base class has methods for writing other
80 types of data which use this to do the work.
81
82 @param dataToWrite the target buffer to receive the data. This must not be null.
83 @param numberOfBytes the number of bytes to write.
84 @returns false if the write operation fails for some reason
85 */
86 virtual bool write (const void* dataToWrite,
87 size_t numberOfBytes) = 0;
88
89 //==============================================================================
90 /** Writes a single byte to the stream.
91 @returns false if the write operation fails for some reason
92 @see InputStream::readByte
93 */
94 virtual bool writeByte (char byte);
95
96 /** Writes a boolean to the stream as a single byte.
97 This is encoded as a binary byte (not as text) with a value of 1 or 0.
98 @returns false if the write operation fails for some reason
99 @see InputStream::readBool
100 */
101 virtual bool writeBool (bool boolValue);
102
103 /** Writes a 16-bit integer to the stream in a little-endian byte order.
104 This will write two bytes to the stream: (value & 0xff), then (value >> 8).
105 @returns false if the write operation fails for some reason
106 @see InputStream::readShort
107 */
108 virtual bool 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 @returns false if the write operation fails for some reason
113 @see InputStream::readShortBigEndian
114 */
115 virtual bool writeShortBigEndian (short value);
116
117 /** Writes a 32-bit integer to the stream in a little-endian byte order.
118 @returns false if the write operation fails for some reason
119 @see InputStream::readInt
120 */
121 virtual bool writeInt (int value);
122
123 /** Writes a 32-bit integer to the stream in a big-endian byte order.
124 @returns false if the write operation fails for some reason
125 @see InputStream::readIntBigEndian
126 */
127 virtual bool writeIntBigEndian (int value);
128
129 /** Writes a 64-bit integer to the stream in a little-endian byte order.
130 @returns false if the write operation fails for some reason
131 @see InputStream::readInt64
132 */
133 virtual bool writeInt64 (int64 value);
134
135 /** Writes a 64-bit integer to the stream in a big-endian byte order.
136 @returns false if the write operation fails for some reason
137 @see InputStream::readInt64BigEndian
138 */
139 virtual bool writeInt64BigEndian (int64 value);
140
141 /** Writes a 32-bit floating point value to the stream in a binary format.
142 The binary 32-bit encoding of the float is written as a little-endian int.
143 @returns false if the write operation fails for some reason
144 @see InputStream::readFloat
145 */
146 virtual bool writeFloat (float value);
147
148 /** Writes a 32-bit floating point value to the stream in a binary format.
149 The binary 32-bit encoding of the float is written as a big-endian int.
150 @returns false if the write operation fails for some reason
151 @see InputStream::readFloatBigEndian
152 */
153 virtual bool writeFloatBigEndian (float value);
154
155 /** Writes a 64-bit floating point value to the stream in a binary format.
156 The eight raw bytes of the double value are written out as a little-endian 64-bit int.
157 @returns false if the write operation fails for some reason
158 @see InputStream::readDouble
159 */
160 virtual bool writeDouble (double value);
161
162 /** Writes a 64-bit floating point value to the stream in a binary format.
163 The eight raw bytes of the double value are written out as a big-endian 64-bit int.
164 @see InputStream::readDoubleBigEndian
165 @returns false if the write operation fails for some reason
166 */
167 virtual bool writeDoubleBigEndian (double value);
168
169 /** Writes a byte to the output stream a given number of times.
170 @returns false if the write operation fails for some reason
171 */
172 virtual bool writeRepeatedByte (uint8 byte, size_t numTimesToRepeat);
173
174 /** Writes a condensed binary encoding of a 32-bit integer.
175
176 If you're storing a lot of integers which are unlikely to have very large values,
177 this can save a lot of space, because values under 0xff will only take up 2 bytes,
178 under 0xffff only 3 bytes, etc.
179
180 The format used is: number of significant bytes + up to 4 bytes in little-endian order.
181
182 @returns false if the write operation fails for some reason
183 @see InputStream::readCompressedInt
184 */
185 virtual bool writeCompressedInt (int value);
186
187 /** Stores a string in the stream in a binary format.
188
189 This isn't the method to use if you're trying to append text to the end of a
190 text-file! It's intended for storing a string so that it can be retrieved later
191 by InputStream::readString().
192
193 It writes the string to the stream as UTF8, including the null termination character.
194
195 For appending text to a file, instead use writeText, or operator<<
196
197 @returns false if the write operation fails for some reason
198 @see InputStream::readString, writeText, operator<<
199 */
200 virtual bool writeString (const String& text);
201
202 /** Writes a string of text to the stream.
203
204 It can either write the text as UTF-8 or UTF-16, and can also add the UTF-16 byte-order-mark
205 bytes (0xff, 0xfe) to indicate the endianness (these should only be used at the start
206 of a file).
207
208 If lineEndings is nullptr, then line endings in the text won't be modified. If you
209 pass "\\n" or "\\r\\n" then this function will replace any existing line feeds.
210
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 const char* lineEndings);
217
218 /** Reads data from an input stream and writes it to this stream.
219
220 @param source the stream to read from
221 @param maxNumBytesToWrite the number of bytes to read from the stream (if this is
222 less than zero, it will keep reading until the input
223 is exhausted)
224 @returns the number of bytes written
225 */
226 virtual int64 writeFromInputStream (InputStream& source, int64 maxNumBytesToWrite);
227
228 //==============================================================================
229 /** Sets the string to write to the stream when a new line is written.
230 By default this will be set the value of NewLine::getDefault().
231 */
232 void setNewLineString (const String& newLineString);
233
234 /** Returns the current new-line string that was set by setNewLineString(). */
235 const String& getNewLineString() const noexcept { return newLineString; }
236
237private:
238 //==============================================================================
239 String newLineString;
240
241 JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (OutputStream)
242};
243
244//==============================================================================
245/** Writes a number to a stream as 8-bit characters in the default system encoding. */
246JUCE_API OutputStream& JUCE_CALLTYPE operator<< (OutputStream& stream, int number);
247
248/** Writes a number to a stream as 8-bit characters in the default system encoding. */
249JUCE_API OutputStream& JUCE_CALLTYPE operator<< (OutputStream& stream, int64 number);
250
251/** Writes a number to a stream as 8-bit characters in the default system encoding. */
252JUCE_API OutputStream& JUCE_CALLTYPE operator<< (OutputStream& stream, double number);
253
254/** Writes a character to a stream. */
255JUCE_API OutputStream& JUCE_CALLTYPE operator<< (OutputStream& stream, char character);
256
257/** Writes a null-terminated text string to a stream. */
258JUCE_API OutputStream& JUCE_CALLTYPE operator<< (OutputStream& stream, const char* text);
259
260/** Writes a block of data from a MemoryBlock to a stream. */
261JUCE_API OutputStream& JUCE_CALLTYPE operator<< (OutputStream& stream, const MemoryBlock& data);
262
263/** Writes the contents of a file to a stream. */
264JUCE_API OutputStream& JUCE_CALLTYPE operator<< (OutputStream& stream, const File& fileToRead);
265
266/** Writes the complete contents of an input stream to an output stream. */
267JUCE_API OutputStream& JUCE_CALLTYPE operator<< (OutputStream& stream, InputStream& streamToRead);
268
269/** Writes a new-line to a stream.
270 You can use the predefined symbol 'newLine' to invoke this, e.g.
271 @code
272 myOutputStream << "Hello World" << newLine << newLine;
273 @endcode
274 @see OutputStream::setNewLineString
275*/
276JUCE_API OutputStream& JUCE_CALLTYPE operator<< (OutputStream& stream, const NewLine&);
277
278} // namespace juce
279
280/** @}*/
The base class for streams that read data.
The base class for streams that write data to some kind of destination.
virtual bool write(const void *dataToWrite, size_t numberOfBytes)=0
Writes a block of data to the stream.
virtual int64 getPosition()=0
Returns the stream's current position.
virtual bool setPosition(int64 newPosition)=0
Tries to move the stream's output position.
virtual void flush()=0
If the stream is using a buffer, this will ensure it gets written out to the destination.
const String & getNewLineString() const noexcept
Returns the current new-line string that was set by setNewLineString().
The JUCE String class!
Definition juce_String.h:43
#define JUCE_API
This macro is added to all JUCE public class declarations.