OpenShot Library | libopenshot-audio 0.2.0
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() const noexcept { return data; }
96
97 /** Returns a byte from the memory block.
98 This returns a reference, so you can also use it to set a byte.
99 */
100 template <typename Type>
101 char& operator[] (const Type offset) const noexcept { return data [offset]; }
102
103 /** Returns an iterator for the data. */
104 char* begin() const noexcept { return data; }
105
106 /** Returns an end-iterator for the data. */
107 char* end() const noexcept { return begin() + getSize(); }
108
109 //==============================================================================
110 /** Returns the block's current allocated size, in bytes. */
111 size_t getSize() const noexcept { return size; }
112
113 /** Resizes the memory block.
114
115 Any data that is present in both the old and new sizes will be retained.
116 When enlarging the block, the new space that is allocated at the end can either be
117 cleared, or left uninitialised.
118
119 @param newSize the new desired size for the block
120 @param initialiseNewSpaceToZero if the block gets enlarged, this determines
121 whether to clear the new section or just leave it
122 uninitialised
123 @see ensureSize
124 */
125 void setSize (const size_t newSize,
126 bool initialiseNewSpaceToZero = false);
127
128 /** Increases the block's size only if it's smaller than a given size.
129
130 @param minimumSize if the block is already bigger than this size, no action
131 will be taken; otherwise it will be increased to this size
132 @param initialiseNewSpaceToZero if the block gets enlarged, this determines
133 whether to clear the new section or just leave it
134 uninitialised
135 @see setSize
136 */
137 void ensureSize (const size_t minimumSize,
138 bool initialiseNewSpaceToZero = false);
139
140 /** Frees all the blocks data, setting its size to 0. */
141 void reset();
142
143 //==============================================================================
144 /** Fills the entire memory block with a repeated byte value.
145 This is handy for clearing a block of memory to zero.
146 */
147 void fillWith (uint8 valueToUse) noexcept;
148
149 /** Adds another block of data to the end of this one.
150 The data pointer must not be null. This block's size will be increased accordingly.
151 */
152 void append (const void* data, size_t numBytes);
153
154 /** Resizes this block to the given size and fills its contents from the supplied buffer.
155 The data pointer must not be null.
156 */
157 void replaceWith (const void* data, size_t numBytes);
158
159 /** Inserts some data into the block.
160 The dataToInsert pointer must not be null. This block's size will be increased accordingly.
161 If the insert position lies outside the valid range of the block, it will be clipped to
162 within the range before being used.
163 */
164 void insert (const void* dataToInsert, size_t numBytesToInsert, size_t insertPosition);
165
166 /** Chops out a section of the block.
167
168 This will remove a section of the memory block and close the gap around it,
169 shifting any subsequent data downwards and reducing the size of the block.
170
171 If the range specified goes beyond the size of the block, it will be clipped.
172 */
173 void removeSection (size_t startByte, size_t numBytesToRemove);
174
175 //==============================================================================
176 /** Copies data into this MemoryBlock from a memory address.
177
178 @param srcData the memory location of the data to copy into this block
179 @param destinationOffset the offset in this block at which the data being copied should begin
180 @param numBytes how much to copy in (if this goes beyond the size of the memory block,
181 it will be clipped so not to do anything nasty)
182 */
183 void copyFrom (const void* srcData,
184 int destinationOffset,
185 size_t numBytes) noexcept;
186
187 /** Copies data from this MemoryBlock to a memory address.
188
189 @param destData the memory location to write to
190 @param sourceOffset the offset within this block from which the copied data will be read
191 @param numBytes how much to copy (if this extends beyond the limits of the memory block,
192 zeros will be used for that portion of the data)
193 */
194 void copyTo (void* destData,
195 int sourceOffset,
196 size_t numBytes) const noexcept;
197
198 //==============================================================================
199 /** Exchanges the contents of this and another memory block.
200 No actual copying is required for this, so it's very fast.
201 */
202 void swapWith (MemoryBlock& other) noexcept;
203
204 //==============================================================================
205 /** Attempts to parse the contents of the block as a zero-terminated UTF8 string. */
206 String toString() const;
207
208 //==============================================================================
209 /** Parses a string of hexadecimal numbers and writes this data into the memory block.
210
211 The block will be resized to the number of valid bytes read from the string.
212 Non-hex characters in the string will be ignored.
213
214 @see String::toHexString()
215 */
216 void loadFromHexString (StringRef sourceHexString);
217
218 //==============================================================================
219 /** Sets a number of bits in the memory block, treating it as a long binary sequence. */
220 void setBitRange (size_t bitRangeStart,
221 size_t numBits,
222 int binaryNumberToApply) noexcept;
223
224 /** Reads a number of bits from the memory block, treating it as one long binary sequence */
225 int getBitRange (size_t bitRangeStart,
226 size_t numBitsToRead) const noexcept;
227
228 //==============================================================================
229 /** Returns a string of characters in a JUCE-specific text encoding that represents the
230 binary contents of this block.
231
232 This uses a JUCE-specific (i.e. not standard!) 64-bit encoding system to convert binary
233 data into a string of ASCII characters for purposes like storage in XML.
234 Note that this proprietary format is mainly kept here for backwards-compatibility, and
235 you may prefer to use the Base64::toBase64() method if you want to use the standard
236 base-64 encoding.
237
238 @see fromBase64Encoding, Base64::toBase64, Base64::convertToBase64
239 */
240 String toBase64Encoding() const;
241
242 /** Takes a string created by MemoryBlock::toBase64Encoding() and extracts the original data.
243
244 The string passed in must have been created by to64BitEncoding(), and this
245 block will be resized to recreate the original data block.
246
247 Note that these methods use a JUCE-specific (i.e. not standard!) 64-bit encoding system.
248 You may prefer to use the Base64::convertFromBase64() method if you want to use the
249 standard base-64 encoding.
250
251 @see toBase64Encoding, Base64::convertFromBase64
252 */
253 bool fromBase64Encoding (StringRef encodedString);
254
255
256private:
257 //==============================================================================
258 using HeapBlockType = HeapBlock<char, true>;
259 HeapBlockType data;
260 size_t size = 0;
261
262 JUCE_LEAK_DETECTOR (MemoryBlock)
263};
264
265} // namespace juce
266
267/** @}*/
Very simple container class to hold a pointer to some data on the heap.
A class to hold a resizable block of raw data.
char * end() const noexcept
Returns an end-iterator for the data.
char * begin() const noexcept
Returns an iterator for the data.
size_t getSize() const noexcept
Returns the block's current allocated size, in bytes.
void * getData() const noexcept
Returns a void pointer to 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.