HEAP_Realloc

<< Click to Display Table of Contents >>

Navigation:  ThinBASIC Language > thinBasic Functions > Memory handling and pointers > Heap memory >

HEAP_Realloc

 

Description

 

Reallocate a block of memory previously allocated by Heap_Alloc, while preserving the original content.

Old memory block is released.

 

Syntax

 

ptr = HEAP_ReAlloc(OldPtr, Size)

 

Returns

 

DWORD

value > 0, if the function succeeds. Pointer to the new allocated memory block.

value = 0 in case of error.

 

 

Parameters

 

Name

Type

Optional

Meaning

OldPtr

Number

No

Pointer to memory previously allocated by Heap_Alloc. If zero, a completely new block of memory will be allocated.

Size

Number

No

Number of bytes to allocate. Up to 2GB.

 

Remarks

 

The theoretical maximum of 2 147 483 647 bytes is mostly theoretical, as 32bit process cannot address more than 2GB of RAM and thinBASIC process already occupies some memory. The actual number might be also lower due to memory fragmentation.

 

Restrictions

 

Use this function only with memory previously allocated by Heap_Alloc.

 

See also

 

Heap_Alloc, Heap_ReallocByStr, Redim Preserve

 

Examples

 

' Allocate 8 bytes

dim pMemory as dword = heap_alloc(8)

 

' Overlay array of bytes

dim bytes(8) as byte at pMemory

 

msgbox 0, "After creation:" + $CRLF + ToHumanReadableByteValues(pMemory)

 

' Writing data to the allocated memory, via overlay array

bytes(1) = 1, 2, 3, 4, 5, 6, 7, 8

 

msgbox 0, "After writing to memory via array:" + $CRLF + ToHumanReadableByteValues(pMemory)

 

' Re-allocate the original 8 bytes to 16 bytes block

dim pNewMemory as dword = heap_reAlloc(pMemory, 16)

 

msgbox 0, "After memory extension:" + $CRLF + ToHumanReadableByteValues(pNewMemory) + $CRLF(2) + "Notice the preserved original data"

 

' Release the memory (please note no need to free the original pMemory location)

heap_free(pNewMemory)

 

function ToHumanReadableByteValues(pMemoryLocation as dwordas string

 

  dim bytes(heap_size(pMemoryLocation)) as byte at pMemoryLocation

 

  return join$(bytes, " ")

 

end function