OpenShot Library | libopenshot-audio  0.1.9
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() 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 
256 private:
257  //==============================================================================
259  HeapBlockType data;
260  size_t size = 0;
261 
262  JUCE_LEAK_DETECTOR (MemoryBlock)
263 };
264 
265 } // namespace juce
266 
267 /** @}*/
size_t getSize() const noexcept
Returns the block&#39;s current allocated size, in bytes.
char * end() const noexcept
Returns an end-iterator for the data.
#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.
The JUCE String class!
Definition: juce_String.h:42
void * getData() const noexcept
Returns a void pointer to the data.
char * begin() const noexcept
Returns an iterator for the data.
A class to hold a resizable block of raw data.