Very simple container class to hold a pointer to some data on the heap. More...

#include <juce_HeapBlock.h>

Collaboration diagram for juce::HeapBlock< ElementType, throwOnFailure >:

Public Types
using	Type = ElementType
	This typedef can be used to get the type of the heapblock's elements. More...

Public Member Functions
	HeapBlock ()=default
	Creates a HeapBlock which is initially just a null pointer. More...

	HeapBlock (HeapBlock &&other) noexcept
	Move constructor. More...

template<class OtherElementType , bool otherThrowOnFailure, typename = AllowConversion<OtherElementType>>
	HeapBlock (HeapBlock< OtherElementType, otherThrowOnFailure > &&other) noexcept
	Converting move constructor. More...

template<typename SizeType , std::enable_if_t< std::is_convertible< SizeType, int >::value, int > = 0>
	HeapBlock (SizeType numElements)
	Creates a HeapBlock containing a number of elements. More...

template<typename SizeType , std::enable_if_t< std::is_convertible< SizeType, int >::value, int > = 0>
	HeapBlock (SizeType numElements, bool initialiseToZero)
	Creates a HeapBlock containing a number of elements. More...

	~HeapBlock ()
	Destructor. More...

template<typename SizeType >
void	allocate (SizeType newNumElements, bool initialiseToZero)
	Allocates a specified amount of memory and optionally clears it. More...

template<typename SizeType >
void	calloc (SizeType newNumElements, const size_t elementSize=sizeof(ElementType))
	Allocates a specified amount of memory and clears it. More...

template<typename SizeType >
void	clear (SizeType numElements) noexcept
	This fills the block with zeros, up to the number of elements specified. More...

void	free () noexcept
	Frees any currently-allocated data. More...

ElementType *	get () const noexcept
	Returns a raw pointer to the allocated data. More...

ElementType *	getData () const noexcept
	Returns a raw pointer to the allocated data. More...

template<typename SizeType >
void	malloc (SizeType newNumElements, size_t elementSize=sizeof(ElementType))
	Allocates a specified amount of memory. More...

	operator const void * () const noexcept
	Returns a void pointer to the allocated data. More...

	operator ElementType * () const noexcept
	Returns a raw pointer to the allocated data. More...

	operator void * () const noexcept
	Returns a void pointer to the allocated data. More...

bool	operator!= (const ElementType *otherPointer) const noexcept
	Compares the pointer with another pointer. More...

template<typename IndexType >
ElementType *	operator+ (IndexType index) const noexcept
	Returns a pointer to a data element at an offset from the start of the array. More...

ElementType *	operator-> () const noexcept
	Lets you use indirect calls to the first element in the array. More...

HeapBlock &	operator= (HeapBlock &&other) noexcept
	Move assignment operator. More...

template<class OtherElementType , bool otherThrowOnFailure, typename = AllowConversion<OtherElementType>>
HeapBlock &	operator= (HeapBlock< OtherElementType, otherThrowOnFailure > &&other) noexcept
	Converting move assignment operator. More...

bool	operator== (const ElementType *otherPointer) const noexcept
	Compares the pointer with another pointer. More...

template<typename IndexType >
ElementType &	operator[] (IndexType index) const noexcept
	Returns a reference to one of the data elements. More...

template<typename SizeType >
void	realloc (SizeType newNumElements, size_t elementSize=sizeof(ElementType))
	Re-allocates a specified amount of memory. More...

template<bool otherBlockThrows>
void	swapWith (HeapBlock< ElementType, otherBlockThrows > &other) noexcept
	Swaps this object's data with the data of another HeapBlock. More...

Private Types
template<class OtherElementType >
using	AllowConversion = typename std::enable_if< std::is_base_of< typename std::remove_pointer< ElementType >::type, typename std::remove_pointer< OtherElementType >::type >::value >::type

Private Member Functions
void	throwOnAllocationFailure () const

Private Attributes
ElementType *	data = nullptr

Friends
template<class OtherElementType , bool otherThrowOnFailure>
class	HeapBlock

Detailed Description

template<class ElementType, bool throwOnFailure = false>
class juce::HeapBlock< ElementType, throwOnFailure >

Very simple container class to hold a pointer to some data on the heap.

When you need to allocate some heap storage for something, always try to use this class instead of allocating the memory directly using malloc/free.

A HeapBlock<char> object can be treated in pretty much exactly the same way as an char*, but as long as you allocate it on the stack or as a class member, it's almost impossible for it to leak memory.

It also makes your code much more concise and readable than doing the same thing using direct allocations,

E.g. instead of this:

int* temp = (int*) malloc (1024 * sizeof (int));
memcpy (temp, xyz, 1024 * sizeof (int));
free (temp);
temp = (int*) calloc (2048 * sizeof (int));
temp[0] = 1234;
memcpy (foobar, temp, 2048 * sizeof (int));
free (temp);

..you could just write this:

HeapBlock<int> temp (1024);
memcpy (temp, xyz, 1024 * sizeof (int));
temp.calloc (2048);
temp[0] = 1234;
memcpy (foobar, temp, 2048 * sizeof (int));

The class is extremely lightweight, containing only a pointer to the data, and exposes malloc/realloc/calloc/free methods that do the same jobs as their less object-oriented counterparts. Despite adding safety, you probably won't sacrifice any performance by using this in place of normal pointers.

The throwOnFailure template parameter can be set to true if you'd like the class to throw a std::bad_alloc exception when an allocation fails. If this is false, then a failed allocation will just leave the heapblock with a null pointer (assuming that the system's malloc() function doesn't throw).

See also: Array, OwnedArray, MemoryBlock

@tags{Core}

Member Typedef Documentation

◆ AllowConversion

template<class ElementType , bool throwOnFailure = false>

template<class OtherElementType >

using juce::HeapBlock< ElementType, throwOnFailure >::AllowConversion = typename std::enable_if<std::is_base_of<typename std::remove_pointer<ElementType>::type, typename std::remove_pointer<OtherElementType>::type>::value>::type

private

◆ Type

template<class ElementType , bool throwOnFailure = false>

using juce::HeapBlock< ElementType, throwOnFailure >::Type = ElementType

This typedef can be used to get the type of the heapblock's elements.

Constructor & Destructor Documentation

◆ HeapBlock() [1/5]

template<class ElementType , bool throwOnFailure = false>

juce::HeapBlock< ElementType, throwOnFailure >::HeapBlock ( )

default

Creates a HeapBlock which is initially just a null pointer.

After creation, you can resize the array using the malloc(), calloc(), or realloc() methods.

◆ HeapBlock() [2/5]

template<class ElementType , bool throwOnFailure = false>

template<typename SizeType , std::enable_if_t< std::is_convertible< SizeType, int >::value, int > = 0>

juce::HeapBlock< ElementType, throwOnFailure >::HeapBlock ( SizeType numElements )

inlineexplicit

Creates a HeapBlock containing a number of elements.

The contents of the block are undefined, as it will have been created by a malloc call.

If you want an array of zero values, you can use the calloc() method or the other constructor that takes an InitialisationState parameter.

◆ HeapBlock() [3/5]

template<class ElementType , bool throwOnFailure = false>

template<typename SizeType , std::enable_if_t< std::is_convertible< SizeType, int >::value, int > = 0>

juce::HeapBlock< ElementType, throwOnFailure >::HeapBlock	(	SizeType	numElements,
		bool	initialiseToZero
	)

inline

Creates a HeapBlock containing a number of elements.

The initialiseToZero parameter determines whether the new memory should be cleared, or left uninitialised.

◆ ~HeapBlock()

template<class ElementType , bool throwOnFailure = false>

juce::HeapBlock< ElementType, throwOnFailure >::~HeapBlock ( )

inline

Destructor.

This will free the data, if any has been allocated.

◆ HeapBlock() [4/5]

template<class ElementType , bool throwOnFailure = false>

juce::HeapBlock< ElementType, throwOnFailure >::HeapBlock ( HeapBlock< ElementType, throwOnFailure > && other )

inlinenoexcept

Move constructor.

◆ HeapBlock() [5/5]

template<class ElementType , bool throwOnFailure = false>

template<class OtherElementType , bool otherThrowOnFailure, typename = AllowConversion<OtherElementType>>

juce::HeapBlock< ElementType, throwOnFailure >::HeapBlock ( HeapBlock< OtherElementType, otherThrowOnFailure > && other )

inlinenoexcept

Converting move constructor.

Only enabled if this is a HeapBlock<Base*> and the other object is a HeapBlock<Derived*>, where std::is_base_of<Base, Derived>::value == true.

Member Function Documentation

◆ allocate()

template<class ElementType , bool throwOnFailure = false>

template<typename SizeType >

void juce::HeapBlock< ElementType, throwOnFailure >::allocate	(	SizeType	newNumElements,
		bool	initialiseToZero
	)

inline

Allocates a specified amount of memory and optionally clears it.

This does the same job as either malloc() or calloc(), depending on the initialiseToZero parameter.

Referenced by juce::AudioBuffer< float >::setSize().

◆ calloc()

template<class ElementType , bool throwOnFailure = false>

template<typename SizeType >

void juce::HeapBlock< ElementType, throwOnFailure >::calloc	(	SizeType	newNumElements,
		const size_t	elementSize = `sizeof (ElementType)`
	)

inline

Allocates a specified amount of memory and clears it.

This does the same job as the malloc() method, but clears the memory that it allocates.

◆ clear()

template<class ElementType , bool throwOnFailure = false>

template<typename SizeType >

void juce::HeapBlock< ElementType, throwOnFailure >::clear ( SizeType numElements )

inlinenoexcept

This fills the block with zeros, up to the number of elements specified.

Since the block has no way of knowing its own size, you must make sure that the number of elements you specify doesn't exceed the allocated size.

Referenced by juce::Reverb::CombFilter::clear(), juce::Reverb::AllPassFilter::clear(), juce::AudioBuffer< float >::setSize(), and juce::SpeakerMappings::VstSpeakerConfigurationHolder::VstSpeakerConfigurationHolder().

◆ free()

template<class ElementType , bool throwOnFailure = false>

void juce::HeapBlock< ElementType, throwOnFailure >::free ( )

inlinenoexcept

Frees any currently-allocated data.

This will free the data and reset this object to be a null pointer.

Referenced by juce::HeapBlock< ChannelInfo * >::operator=(), juce::ArrayAllocationBase< ElementType, TypeOfCriticalSectionToUse >::setAllocatedSize(), juce::ArrayBase< juce::InAppPurchases::Listener *, DummyCriticalSection >::setAllocatedSize(), and juce::AudioBuffer< float >::setDataToReferTo().

◆ get()

template<class ElementType , bool throwOnFailure = false>

ElementType* juce::HeapBlock< ElementType, throwOnFailure >::get ( ) const

inlinenoexcept

Returns a raw pointer to the allocated data.

This may be a null pointer if the data hasn't yet been allocated, or if it has been freed by calling the free() method.

Referenced by juce::SpeakerMappings::VstSpeakerConfigurationHolder::allocate(), juce::AudioBuffer< float >::allocateChannels(), juce::AudioBuffer< float >::allocateData(), juce::SpeakerMappings::VstSpeakerConfigurationHolder::get(), and juce::AudioBuffer< float >::setSize().

◆ getData()

template<class ElementType , bool throwOnFailure = false>

ElementType* juce::HeapBlock< ElementType, throwOnFailure >::getData ( ) const

inlinenoexcept

Returns a raw pointer to the allocated data.

This may be a null pointer if the data hasn't yet been allocated, or if it has been freed by calling the free() method.

Referenced by juce::dsp::FIR::Filter< SampleType >::reset().

◆ malloc()

template<class ElementType , bool throwOnFailure = false>

template<typename SizeType >

void juce::HeapBlock< ElementType, throwOnFailure >::malloc	(	SizeType	newNumElements,
		size_t	elementSize = `sizeof (ElementType)`
	)

inline

Allocates a specified amount of memory.

This uses the normal malloc to allocate an amount of memory for this object. Any previously allocated memory will be freed by this method.

The number of bytes allocated will be (newNumElements * elementSize). Normally you wouldn't need to specify the second parameter, but it can be handy if you need to allocate a size in bytes rather than in terms of the number of elements.

The data that is allocated will be freed when this object is deleted, or when you call free() or any of the allocation methods.

Referenced by juce::SpeakerMappings::VstSpeakerConfigurationHolder::allocate(), juce::AudioBuffer< float >::allocateChannels(), juce::AudioBuffer< float >::allocateData(), juce::File::getCurrentWorkingDirectory(), juce::dsp::FIR::Filter< SampleType >::reset(), juce::Reverb::CombFilter::setSize(), and juce::Reverb::AllPassFilter::setSize().

◆ operator const void *()

template<class ElementType , bool throwOnFailure = false>

juce::HeapBlock< ElementType, throwOnFailure >::operator const void * ( ) const

inlinenoexcept

Returns a void pointer to the allocated data.

This may be a null pointer if the data hasn't yet been allocated, or if it has been freed by calling the free() method.

◆ operator ElementType *()

template<class ElementType , bool throwOnFailure = false>

juce::HeapBlock< ElementType, throwOnFailure >::operator ElementType * ( ) const

inlinenoexcept

Returns a raw pointer to the allocated data.

This may be a null pointer if the data hasn't yet been allocated, or if it has been freed by calling the free() method.

◆ operator void *()

template<class ElementType , bool throwOnFailure = false>

juce::HeapBlock< ElementType, throwOnFailure >::operator void * ( ) const

inlinenoexcept

Returns a void pointer to the allocated data.

This may be a null pointer if the data hasn't yet been allocated, or if it has been freed by calling the free() method.

◆ operator!=()

template<class ElementType , bool throwOnFailure = false>

bool juce::HeapBlock< ElementType, throwOnFailure >::operator!= ( const ElementType * otherPointer ) const

inlinenoexcept

Compares the pointer with another pointer.

This can be handy for checking whether this is a null pointer.

◆ operator+()

template<class ElementType , bool throwOnFailure = false>

template<typename IndexType >

ElementType* juce::HeapBlock< ElementType, throwOnFailure >::operator+ ( IndexType index ) const

inlinenoexcept

Returns a pointer to a data element at an offset from the start of the array.

This is the same as doing pointer arithmetic on the raw pointer itself.

◆ operator->()

template<class ElementType , bool throwOnFailure = false>

ElementType* juce::HeapBlock< ElementType, throwOnFailure >::operator-> ( ) const

inlinenoexcept

Lets you use indirect calls to the first element in the array.

Obviously this will cause problems if the array hasn't been initialised, because it'll be referencing a null pointer.

◆ operator=() [1/2]

template<class ElementType , bool throwOnFailure = false>

HeapBlock& juce::HeapBlock< ElementType, throwOnFailure >::operator= ( HeapBlock< ElementType, throwOnFailure > && other )

inlinenoexcept

Move assignment operator.

◆ operator=() [2/2]

template<class ElementType , bool throwOnFailure = false>

template<class OtherElementType , bool otherThrowOnFailure, typename = AllowConversion<OtherElementType>>

HeapBlock& juce::HeapBlock< ElementType, throwOnFailure >::operator= ( HeapBlock< OtherElementType, otherThrowOnFailure > && other )

inlinenoexcept

Converting move assignment operator.

Only enabled if this is a HeapBlock<Base*> and the other object is a HeapBlock<Derived*>, where std::is_base_of<Base, Derived>::value == true.

◆ operator==()

template<class ElementType , bool throwOnFailure = false>

bool juce::HeapBlock< ElementType, throwOnFailure >::operator== ( const ElementType * otherPointer ) const

inlinenoexcept

Compares the pointer with another pointer.

This can be handy for checking whether this is a null pointer.

◆ operator[]()

template<class ElementType , bool throwOnFailure = false>

template<typename IndexType >

ElementType& juce::HeapBlock< ElementType, throwOnFailure >::operator[] ( IndexType index ) const

inlinenoexcept

Returns a reference to one of the data elements.

Obviously there's no bounds-checking here, as this object is just a dumb pointer and has no idea of the size it currently has allocated.

◆ realloc()

template<class ElementType , bool throwOnFailure = false>

template<typename SizeType >

void juce::HeapBlock< ElementType, throwOnFailure >::realloc	(	SizeType	newNumElements,
		size_t	elementSize = `sizeof (ElementType)`
	)

inline

Re-allocates a specified amount of memory.

The semantics of this method are the same as malloc() and calloc(), but it uses realloc() to keep as much of the existing data as possible.

Referenced by juce::ArrayAllocationBase< ElementType, TypeOfCriticalSectionToUse >::setAllocatedSize(), and juce::ArrayBase< juce::InAppPurchases::Listener *, DummyCriticalSection >::setAllocatedSizeInternal().

◆ swapWith()

template<class ElementType , bool throwOnFailure = false>

template<bool otherBlockThrows>

void juce::HeapBlock< ElementType, throwOnFailure >::swapWith ( HeapBlock< ElementType, otherBlockThrows > & other )

inlinenoexcept

Swaps this object's data with the data of another HeapBlock.

The two objects simply exchange their data pointers.

Referenced by juce::AudioBuffer< float >::setSize(), juce::ArrayAllocationBase< ElementType, TypeOfCriticalSectionToUse >::swapWith(), and juce::ArrayBase< juce::InAppPurchases::Listener *, DummyCriticalSection >::swapWith().

◆ throwOnAllocationFailure()

template<class ElementType , bool throwOnFailure = false>

void juce::HeapBlock< ElementType, throwOnFailure >::throwOnAllocationFailure ( ) const

inlineprivate

Referenced by juce::HeapBlock< ChannelInfo * >::allocate(), juce::HeapBlock< ChannelInfo * >::calloc(), juce::HeapBlock< ChannelInfo * >::HeapBlock(), juce::HeapBlock< ChannelInfo * >::malloc(), and juce::HeapBlock< ChannelInfo * >::realloc().

Friends And Related Function Documentation

◆ HeapBlock

template<class ElementType , bool throwOnFailure = false>

template<class OtherElementType , bool otherThrowOnFailure>

friend class HeapBlock

friend

Member Data Documentation

◆ data

template<class ElementType , bool throwOnFailure = false>

ElementType* juce::HeapBlock< ElementType, throwOnFailure >::data = nullptr

private

The documentation for this class was generated from the following file:

juce_HeapBlock.h

Public Types

Public Member Functions

Private Types

Private Member Functions

Private Attributes

Friends

Detailed Description

template<class ElementType, bool throwOnFailure = false> class juce::HeapBlock< ElementType, throwOnFailure >

Member Typedef Documentation

◆ AllowConversion

◆ Type

Constructor & Destructor Documentation

◆ HeapBlock() [1/5]

◆ HeapBlock() [2/5]

◆ HeapBlock() [3/5]

◆ ~HeapBlock()

◆ HeapBlock() [4/5]

◆ HeapBlock() [5/5]

Member Function Documentation

◆ allocate()

◆ calloc()

◆ clear()

◆ free()

◆ get()

◆ getData()

◆ malloc()

◆ operator const void *()

◆ operator ElementType *()

◆ operator void *()

◆ operator!=()

◆ operator+()

◆ operator->()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ operator[]()

◆ realloc()

◆ swapWith()

◆ throwOnAllocationFailure()

Friends And Related Function Documentation

◆ HeapBlock

Member Data Documentation

◆ data

template<class ElementType, bool throwOnFailure = false>
class juce::HeapBlock< ElementType, throwOnFailure >