Reallocate

Reallocates storage for an existing reserved block of memory

Syntax
   Declare Function Reallocate cdecl ( ByVal pointer As Any Ptr, ByVal 
   count As UInteger ) 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
   Reallocates 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. If the 
   size is increased, the added memory range is not initialized to 
   anything.

   The reallocation first attempts to resize the memory already allocated 
   without moving its starting address in order to avoid recopying the data 
   to be kept (returned pointer value unchanged). If this is not possible, 
   a new separate memory area is allocated with recopy of the data to be 
   kept before deallocating the old memory area (returned pointer value 
   modified).

   When using Reallocate, the result pointer must be saved to prevent a 
   potential memory leak, because the original pointer 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 must be freed with Deallocate when no longer needed.

   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.

   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 than the original size of the memory 
   block, the new extra memory range must be explicitly cleared to zeroes 
   before the first string 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 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   ' 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
      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

