{{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"}}