Reallocate
Reallocates storage for an existing reserved block of memory
Syntax
`
Declare Function Reallocate cdecl ( ByVal pointer As Any Ptr, ByVal count As Integer ) As Any Ptr
`
Usage
`
result = Reallocate( pointer, count )
`
Parameters
`pointer`
The address of allocated memory to be reallocated.
`count`
The number of bytes, in total, to be reallocated.
Return Value
The address of the reallocated memory. A null (`0`) pointer is returned if reallocation was unsuccessful, and the original memory pointed to by `pointer` remains unchanged.
Description
Attempts to reallocate, or resize, memory previously allocated with `Allocate` or `CAllocate`. The contents of the buffer are preserved, although if `count` is less than the original size of the memory block, the buffer will be truncated. In case of increase of memory, the added memory range is not initialized.
When use with `String` or `Udt` containing string, and if `count` is larger than the original size of the memory block, the new extra memory range must be explicitly cleared (set to 0) before the first string use (with for example keyword `Clear`), otherwise a not cleared string descriptor (containing random data) may induce corrupted string or more (trying to write to a random place in memory or trying to deallocate a random pointer).
If `pointer` is null (`0`), then `ReAllocate` behaves identically to `Allocate`.
If `pointer` is valid and `count` is null (0), then `ReAllocate` behaves similar to `Deallocate` and a null (0) pointer is returned.
Reallocated memory must be deallocated, or freed, with `Deallocate` when no longer needed.
This function is not part of the FreeBASIC runtime library, it is an alias for the C runtime library's `realloc`, so it's not guaranteed to be thread safe in all platforms.
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 Integer Ptr, i As Integer
a = Allocate( 5 * SizeOf(Integer) ) ' 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 = Reallocate( a, 10 * SizeOf(Integer) ) ' Reallocate memory for 5 additional integers
If b <> 0 Then
a = b
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
Print
Else '' Reallocate failed, memory unchanged
Print "Error Reallocating a"
For i = 0 To 4 ' Print the integers
Print i, a[i]
Next i
Print
End If
Deallocate a ' Clean up
`
Dialect Differences

- Not available in the -lang qb dialect unless referenced with the alias `__Reallocate`.

Differences from QB

- New to FreeBASIC

See also

- `Allocate`
- `CAllocate`
- `Deallocate`