Revision [17009]
This is an old revision of KeyPgReallocate made by FxMwikki on 2014-03-09 14:57:37.
REALLOCATE
Reallocates storage for an existing reserved block of memory
Syntax:
KeyPgDeclare declare KeyPgFunction function Reallocate KeyPgCdecl cdecl ( KeyPgByval byval pointer KeyPgAs as KeyPgAny any KeyPgPtr ptr, KeyPgByval byval count KeyPgAs as KeyPgInteger integer ) KeyPgAs as KeyPgAny any KeyPgPtr 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 KeyPgAllocate Allocate or KeyPgCallocate 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 KeyPgString String or KeyPgType 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 KeyPgClear 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).
Reallocated memory must be deallocated, or freed, with KeyPgDeallocate Deallocate when no longer needed.
If pointer is null (0), then ReAllocate behaves identically to KeyPgAllocate Allocate. If pointer is valid and count is null (0), then ReAllocate behaves similar to KeyPgDeallocate Deallocate and a null (0) pointer is returned.
If the memory has previously been deallocated by a call to KeyPgDeallocate Deallocate or ReAllocate, the behavior is undefined.
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.
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.
Examples:
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
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
Else '' Reallocate failed, memory unchanged
Print "Error Reallocating a"
For i = 0 To 4 ' Print the integers
Print i, a[i]
Next i
End If
Deallocate a ' Clean up
Dialect Differences:
- Not available in the CompilerOptlang -lang qb dialect unless referenced with the alias __Reallocate.
Differences from QB:
- New to FreeBASIC
See also:
Back to Memory Functions
