{{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"}}
	Reallocates 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.
	
	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 ##[[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).
	
	**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"}}