OpenShot Library | OpenShotAudio  0.2.1
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 
27 namespace juce
28 {
29 
30 //==============================================================================
31 /**
32  A class to hold a resizable block of raw data.
33 
34  @tags{Core}
35 */
37 {
38 public:
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 
273 private:
274  //==============================================================================
276  HeapBlockType data;
277  size_t size = 0;
278 
279  JUCE_LEAK_DETECTOR (MemoryBlock)
280 };
281 
282 } // namespace juce
283 
284 /** @}*/
size_t getSize() const noexcept
Returns the block&#39;s current allocated size, in bytes.
#define JUCE_API
This macro is added to all JUCE public class declarations.
A simple class for holding temporary references to a string literal or String.
char * end() noexcept
Returns an end-iterator for the data.
The JUCE String class!
Definition: juce_String.h:42
const char * begin() const noexcept
Returns an iterator for the data.
const char * end() const noexcept
Returns an end-iterator for the data.
const void * getData() const noexcept
Returns a void pointer to the data.
void * getData() noexcept
Returns a void pointer to the data.
A class to hold a resizable block of raw data.
char * begin() noexcept
Returns an iterator for the data.