REALLOCATE

• Source: https://www.freebasic.net/wiki/wikka.php?wakka=KeyPgReallocate
• Last revised: 2024-06-19

---

REALLOCATE — Resize an existing memory allocation

Syntax

declare function Reallocate cdecl ( byval pointer as any ptr, byval count as uinteger ) as any ptr

Usage

result = Reallocate( pointer, count )

Parameters

Parameter	Description
pointer	The address of the memory block to resize (previously allocated by Allocate or Callocate).
count	The new total size in bytes.

Return Value

• On success: returns the address of the resized memory block (may differ from pointer).
• On failure: returns a null pointer (0); the original memory block at pointer remains unchanged.

Description

Reallocate resizes a memory block previously allocated by Allocate or Callocate.

Behavior:

• The contents of the buffer are preserved up to the minimum of the old and new sizes.
• If count is smaller than the original size, the buffer is truncated.
• If count is larger, the newly added memory region is not initialized.
• Reallocation first tries to resize the block in place (returning the same pointer). If that is not possible, a new block is allocated, the existing data is copied, and the old block is freed (returning a different pointer).

Critical rules:

1. Always save the return value. The original pointer may become invalid after a successful reallocation. Discarding the return value causes a memory leak.
2. Check the return value. If it is 0, reallocation failed; the original pointer is still valid and the allocation size is unchanged.
3. Free with Deallocate. The reallocated block must be released when no longer needed.
4. Special cases:
   • If pointer is 0, Reallocate behaves exactly like Allocate.
   • If pointer is valid but count is 0, Reallocate behaves like Deallocate and returns 0.
5. Undefined behavior: Calling Reallocate on a pointer that has already been freed causes undefined behavior.
6. Strings / UDTs with strings: If count is larger than the original size, the new memory region must be explicitly zeroed (e.g., with Clear) before any string members are accessed. Failing to do so may cause reads or writes to random memory addresses.
7. Member procedures: Do not use Reallocate inside a member procedure to resize the object instance itself (This). If the memory is moved, the This reference becomes inconsistent.

Example

Dim a As Integer Ptr, b As Integer Ptr, i As Integer

' Allocate space for 5 integers
a = Allocate(5 * SizeOf(Integer))
If a = 0 Then Print "Error allocating a": End

' Assign values
For i = 0 To 4
    a[i] = (i + 1) * 2
Next i

' Resize to hold 10 integers
b = Reallocate(a, 10 * SizeOf(Integer))

If b <> 0 Then
    a = b  ' Use the new pointer; old pointer is now invalid
    For i = 5 To 9
        a[i] = (i + 1) * 2
    Next i
    For i = 0 To 9
        Print i, a[i]
    Next i
Else
    Print "Reallocation failed"
    For i = 0 To 4
        Print i, a[i]
    Next i
End If

Deallocate a

Dialect Differences

• Not available in the -lang qb dialect unless referenced via its alias __Reallocate.

Differences from QB

• This is a FreeBASIC extension; QB has no equivalent.

See Also

• KeyPgAllocate — Allocate
• KeyPgCallocate — Callocate
• KeyPgDeallocate — Deallocate