OpenShot Library | OpenShotAudio 0.2.2
juce_MemoryBlock.h
1
2/** @weakgroup juce_core-memory
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 A class to hold a resizable block of raw data.
33
34 @tags{Core}
35*/
37{
38public:
39 //==============================================================================
40 /** Create an uninitialised block with 0 size. */
41 MemoryBlock() noexcept;
42
43 /** Creates a memory block with a given initial size.
44
45 @param initialSize the size of block to create
46 @param initialiseToZero whether to clear the memory or just leave it uninitialised
47 */
48 MemoryBlock (const size_t initialSize,
49 bool initialiseToZero = false);
50
51 /** Creates a copy of another memory block. */
52 MemoryBlock (const MemoryBlock&);
53
54 /** Creates a memory block using a copy of a block of data.
55
56 @param dataToInitialiseFrom some data to copy into this block
57 @param sizeInBytes how much space to use
58 */
59 MemoryBlock (const void* dataToInitialiseFrom, size_t sizeInBytes);
60
61 /** Destructor. */
62 ~MemoryBlock() noexcept;
63
64 /** Copies another memory block onto this one.
65 This block will be resized and copied to exactly match the other one.
66 */
67 MemoryBlock& operator= (const MemoryBlock&);
68
69 /** Move constructor */
70 MemoryBlock (MemoryBlock&&) noexcept;
71
72 /** Move assignment operator */
73 MemoryBlock& operator= (MemoryBlock&&) noexcept;
74
75 //==============================================================================
76 /** Compares two memory blocks.
77 @returns true only if the two blocks are the same size and have identical contents.
78 */
79 bool operator== (const MemoryBlock& other) const noexcept;
80
81 /** Compares two memory blocks.
82 @returns true if the two blocks are different sizes or have different contents.
83 */
84 bool operator!= (const MemoryBlock& other) const noexcept;
85
86 /** Returns true if the data in this MemoryBlock matches the raw bytes passed-in. */
87 bool matches (const void* data, size_t dataSize) const noexcept;
88
89 //==============================================================================
90 /** Returns a void pointer to the data.
91
92 Note that the pointer returned will probably become invalid when the
93 block is resized.
94 */
95 void* getData() noexcept { return data; }
96
97 /** Returns a void pointer to the data.
98
99 Note that the pointer returned will probably become invalid when the
100 block is resized.
101 */
102 const void* getData() const noexcept { return data; }
103
104 /** Returns a byte from the memory block.
105 This returns a reference, so you can also use it to set a byte.
106 */
107 template <typename Type>
108 char& operator[] (const Type offset) noexcept { return data [offset]; }
109
110 /** Returns a byte from the memory block. */
111 template <typename Type>
112 const char& operator[] (const Type offset) const noexcept { return data [offset]; }
113
114 /** Returns an iterator for the data. */
115 char* begin() noexcept { return data; }
116
117 /** Returns an iterator for the data. */
118 const char* begin() const noexcept { return data; }
119
120 /** Returns an end-iterator for the data. */
121 char* end() noexcept { return begin() + getSize(); }
122
123 /** Returns an end-iterator for the data. */
124 const char* end() const noexcept { return begin() + getSize(); }
125
126 //==============================================================================
127 /** Returns the block's current allocated size, in bytes. */
128 size_t getSize() const noexcept { return size; }
129
130 /** Resizes the memory block.
131
132 Any data that is present in both the old and new sizes will be retained.
133 When enlarging the block, the new space that is allocated at the end can either be
134 cleared, or left uninitialised.
135
136 @param newSize the new desired size for the block
137 @param initialiseNewSpaceToZero if the block gets enlarged, this determines
138 whether to clear the new section or just leave it
139 uninitialised
140 @see ensureSize
141 */
142 void setSize (const size_t newSize,
143 bool initialiseNewSpaceToZero = false);
144
145 /** Increases the block's size only if it's smaller than a given size.
146
147 @param minimumSize if the block is already bigger than this size, no action
148 will be taken; otherwise it will be increased to this size
149 @param initialiseNewSpaceToZero if the block gets enlarged, this determines
150 whether to clear the new section or just leave it
151 uninitialised
152 @see setSize
153 */
154 void ensureSize (const size_t minimumSize,
155 bool initialiseNewSpaceToZero = false);
156
157 /** Frees all the blocks data, setting its size to 0. */
158 void reset();
159
160 //==============================================================================
161 /** Fills the entire memory block with a repeated byte value.
162 This is handy for clearing a block of memory to zero.
163 */
164 void fillWith (uint8 valueToUse) noexcept;
165
166 /** Adds another block of data to the end of this one.
167 The data pointer must not be null. This block's size will be increased accordingly.
168 */
169 void append (const void* data, size_t numBytes);
170
171 /** Resizes this block to the given size and fills its contents from the supplied buffer.
172 The data pointer must not be null.
173 */
174 void replaceWith (const void* data, size_t numBytes);
175
176 /** Inserts some data into the block.
177 The dataToInsert pointer must not be null. This block's size will be increased accordingly.
178 If the insert position lies outside the valid range of the block, it will be clipped to
179 within the range before being used.
180 */
181 void insert (const void* dataToInsert, size_t numBytesToInsert, size_t insertPosition);
182
183 /** Chops out a section of the block.
184
185 This will remove a section of the memory block and close the gap around it,
186 shifting any subsequent data downwards and reducing the size of the block.
187
188 If the range specified goes beyond the size of the block, it will be clipped.
189 */
190 void removeSection (size_t startByte, size_t numBytesToRemove);
191
192 //==============================================================================
193 /** Copies data into this MemoryBlock from a memory address.
194
195 @param srcData the memory location of the data to copy into this block
196 @param destinationOffset the offset in this block at which the data being copied should begin
197 @param numBytes how much to copy in (if this goes beyond the size of the memory block,
198 it will be clipped so not to do anything nasty)
199 */
200 void copyFrom (const void* srcData,
201 int destinationOffset,
202 size_t numBytes) noexcept;
203
204 /** Copies data from this MemoryBlock to a memory address.
205
206 @param destData the memory location to write to
207 @param sourceOffset the offset within this block from which the copied data will be read
208 @param numBytes how much to copy (if this extends beyond the limits of the memory block,
209 zeros will be used for that portion of the data)
210 */
211 void copyTo (void* destData,
212 int sourceOffset,
213 size_t numBytes) const noexcept;
214
215 //==============================================================================
216 /** Exchanges the contents of this and another memory block.
217 No actual copying is required for this, so it's very fast.
218 */
219 void swapWith (MemoryBlock& other) noexcept;
220
221 //==============================================================================
222 /** Attempts to parse the contents of the block as a zero-terminated UTF8 string. */
223 String toString() const;
224
225 //==============================================================================
226 /** Parses a string of hexadecimal numbers and writes this data into the memory block.
227
228 The block will be resized to the number of valid bytes read from the string.
229 Non-hex characters in the string will be ignored.
230
231 @see String::toHexString()
232 */
233 void loadFromHexString (StringRef sourceHexString);
234
235 //==============================================================================
236 /** Sets a number of bits in the memory block, treating it as a long binary sequence. */
237 void setBitRange (size_t bitRangeStart,
238 size_t numBits,
239 int binaryNumberToApply) noexcept;
240
241 /** Reads a number of bits from the memory block, treating it as one long binary sequence */
242 int getBitRange (size_t bitRangeStart,
243 size_t numBitsToRead) const noexcept;
244
245 //==============================================================================
246 /** Returns a string of characters in a JUCE-specific text encoding that represents the
247 binary contents of this block.
248
249 This uses a JUCE-specific (i.e. not standard!) 64-bit encoding system to convert binary
250 data into a string of ASCII characters for purposes like storage in XML.
251 Note that this proprietary format is mainly kept here for backwards-compatibility, and
252 you may prefer to use the Base64::toBase64() method if you want to use the standard
253 base-64 encoding.
254
255 @see fromBase64Encoding, Base64::toBase64, Base64::convertToBase64
256 */
257 String toBase64Encoding() const;
258
259 /** Takes a string created by MemoryBlock::toBase64Encoding() and extracts the original data.
260
261 The string passed in must have been created by to64BitEncoding(), and this
262 block will be resized to recreate the original data block.
263
264 Note that these methods use a JUCE-specific (i.e. not standard!) 64-bit encoding system.
265 You may prefer to use the Base64::convertFromBase64() method if you want to use the
266 standard base-64 encoding.
267
268 @see toBase64Encoding, Base64::convertFromBase64
269 */
270 bool fromBase64Encoding (StringRef encodedString);
271
272
273private:
274 //==============================================================================
275 using HeapBlockType = HeapBlock<char, true>;
276 HeapBlockType data;
277 size_t size = 0;
278
279 JUCE_LEAK_DETECTOR (MemoryBlock)
280};
281
282} // namespace juce
283
284/** @}*/
A class to hold a resizable block of raw data.
const char * end() const noexcept
Returns an end-iterator for the data.
const char * begin() const noexcept
Returns an iterator for the data.
char * end() noexcept
Returns an end-iterator for the data.
void * getData() noexcept
Returns a void pointer to the data.
size_t getSize() const noexcept
Returns the block's current allocated size, in bytes.
const void * getData() const noexcept
Returns a void pointer to the data.
char * begin() noexcept
Returns an iterator for the data.
A simple class for holding temporary references to a string literal or String.
The JUCE String class!
Definition: juce_String.h:43
#define JUCE_API
This macro is added to all JUCE public class declarations.