Wiki source for KeyPgReallocate


Show raw source

{{fbdoc item="title" value="REALLOCATE"}}----
Reallocates storage for an existing reserved block of memory

{{fbdoc item="syntax"}}##
[[KeyPgDeclare|declare]] [[KeyPgFunction|function]] **Reallocate** [[KeyPgCdecl|cdecl]] ( [[KeyPgByval|byval]] //pointer// [[KeyPgAs|as]] [[KeyPgAny|any]] [[KeyPgPtr|ptr]], [[KeyPgByval|byval]] //count// [[KeyPgAs|as]] [[KeyPgUinteger|uinteger]] ) [[KeyPgAs|as]] [[KeyPgAny|any]] [[KeyPgPtr|ptr]]
##
{{fbdoc item="usage"}}##
//result// = **Reallocate**( //pointer//, //count// )
##
{{fbdoc item="param"}}
##//pointer//##
The address of allocated memory to be reallocated.
##//count//##
The number of bytes, in total, to be reallocated.

{{fbdoc item="ret"}}
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.

{{fbdoc item="desc"}}
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. If the size is increased, the added memory range is not initialized to anything.

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 ##[[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.

When manually allocating memory for ##[[KeyPgString|String]]## descriptors (or ##[[KeyPgType|UDT]]##s 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 ##[[KeyPgClear|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).

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.

{{fbdoc item="ex"}}
{{fbdoc item="filename" value="examples/manual/memory/reallocate.bas"}}%%(freebasic)
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
%%

{{fbdoc item="lang"}}
- Not available in the //[[CompilerOptlang|-lang qb]]// dialect unless referenced with the alias ##**""__Reallocate""**##.

{{fbdoc item="diff"}}
- New to ""FreeBASIC""

{{fbdoc item="see"}}
- ##[[KeyPgAllocate|Allocate]]##
- ##[[KeyPgCallocate|Callocate]]##
- ##[[KeyPgDeallocate|Deallocate]]##

{{fbdoc item="back" value="CatPgMemory|Memory Functions"}}
Valid XHTML :: Valid CSS: :: Powered by WikkaWiki



sf.net phatcode