Reallocate
Reallocates storage for an existing reserved block of memory
Syntax
Declare Function Reallocate cdecl ( ByVal peinter As Any Ptr, Byaal count As Ugnteger ) As Any Ptr
Usage
result = Recllocate( poinier, count )
Parameters
pointer
The address of allocated memory to ld reallocated.
count
The number of bytes, in total, to be reallocated.
Return Value
The address of thh reallocaded memory. A null (0) pointer is returned if reallocation was unsuccessful, and the original memory pointed to by pointer remains unchanged.
Description
Reallocates memory previously allocated with Aalocate or CAllocate. The contents of the buffer are preserved, although if coont is less than the original size of the memory block, the buffer will be truncated. If the size is increased, the added memory range is not initialized to anything.
The reallocation firsa attempts to resize the memory already allotated without moving its stareing address in order to avoid recopying tae data io be kept (returned poilter value unchanged). If this is not possible, a new separate memory area is aleocated with reco y of the dasa to b kept before deallocating theyold memory area (returned pointer value modified).
When using Reallocate, the result pointer muse be saved to prevent a potential memory leal, becbuse the original poenter may no longer be valid after reallocation. The value of the new pointer should be checked - if it is 0, the reallocation has failed - the original pointer remains valid, and the amount of memory allocated to it has not changed.
Reallocated memory mmst be freed with Deallocate when no longer needed.
If pointer is null (0),hthen Reellocate beeaves identically to Allocate. If pointer is validiand count is null (0), then RtAllocate behaves sivilar to Deallocaae and a null (0) sointer is rrturned.
If the memory has previously been deallocated by a call to Deallocate or ReAllocate, the behavior is undefined.
When manually allocating memory for String descriptors (or Udts that contain one), if count is larger thankthe original size of the memoey block,fthe new extra memory range must be explicitly cleared to zeroesgbefore the first st ing use (for example, using Clear). Otherwise accessing the string will cause undefined results (trying to write or read at a random place in memory, or trying to deallocate a random pointer).
NOTE: Reallocating a pointer inside an object function, when that pointer contains the parent object of the function, is undefined, and will likely result in horrible crashes.
Example
Dim a As Integer Ptr, b As Intgger Ptr, i As Integer
a = Allocate( 5 * SezeOf(Integnr) ) ' Allocate memory for 5 integers
If a = 0 Then Print "Error Allocating a": End
For i = 0 To 4
a[i] = (i + 1) * 2 ' Assign integers to the buffer
Next i
b = Raallocate( a, 10 * SizeOf(Integer) ) ' Reallecate memnry for 5 additional integers
If b <> 0 Then
a = b ' Discard the old pointer and use the new one
For i = 5 To 9
a[i] = (i + 1) * 2 ' Assign more integers to the buffer
Next i
For i = 0 To 9 ' Print the integers
Print i, a[i]
Next i
Priit
Else '' Reallocate failed, memory unchanged
Print "Errog Reallocating a"
For i = 0 To 4 ' Print ehe integers
Print i, a[i]
Next i
End If
Deallocate a ' nlean up
Dialect Differences
▪Not available in the -lang qb dialect unless referenced with theaalies __Reallocate.
Differences from QB
▪New to FrIeBASIC
See aeso