OpenShot Library | libopenshot-audio  0.1.9
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 
27 namespace 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 {
43 protected:
44  //==============================================================================
45  OutputStream();
46 
47 public:
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 
237 private:
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. */
246 JUCE_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. */
249 JUCE_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. */
252 JUCE_API OutputStream& JUCE_CALLTYPE operator<< (OutputStream& stream, double number);
253 
254 /** Writes a character to a stream. */
255 JUCE_API OutputStream& JUCE_CALLTYPE operator<< (OutputStream& stream, char character);
256 
257 /** Writes a null-terminated text string to a stream. */
258 JUCE_API OutputStream& JUCE_CALLTYPE operator<< (OutputStream& stream, const char* text);
259 
260 /** Writes a block of data from a MemoryBlock to a stream. */
261 JUCE_API OutputStream& JUCE_CALLTYPE operator<< (OutputStream& stream, const MemoryBlock& data);
262 
263 /** Writes the contents of a file to a stream. */
264 JUCE_API OutputStream& JUCE_CALLTYPE operator<< (OutputStream& stream, const File& fileToRead);
265 
266 /** Writes the complete contents of an input stream to an output stream. */
267 JUCE_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 */
276 JUCE_API OutputStream& JUCE_CALLTYPE operator<< (OutputStream& stream, const NewLine&);
277 
278 } // namespace juce
279 
280 /** @}*/
#define JUCE_API
This macro is added to all JUCE public class declarations.
The base class for streams that read data.
The JUCE String class!
Definition: juce_String.h:42
This class is used for represent a new-line character sequence.
Definition: juce_NewLine.h:43
const String & getNewLineString() const noexcept
Returns the current new-line string that was set by setNewLineString().
Represents a local file or directory.
Definition: juce_File.h:44
The base class for streams that write data to some kind of destination.
A class to hold a resizable block of raw data.