[Main]
Name=HeapRealloc
Type=Function
Subtype=ROM Call
Header Files=alloc.h
Definition=HANDLE HeapRealloc (HANDLE Handle, unsigned long NewSize);

[ROM Call]
Index=$9D

[Description]
Reallocates a block to a new size.

[Explanation]
If <I>Handle</I> is <A HREF="$$LINK(alloc.h/H_NULL)">H_NULL</A>, HeapRealloc calls
<A HREF="$$LINK(alloc.h/HeapAlloc)">HeapAlloc</A>. Otherwise, it tries to reallocate the given heap block
to a new size. Returns <A HREF="$$LINK(alloc.h/H_NULL)">H_NULL</A> if there is not enough memory (it will
try to call <A HREF="$$LINK(alloc.h/HeapCompress)">HeapCompress</A>) or if new size is invalid; otherwise
returns <I>Handle</I> (but <I>Handle</I> will still be valid even if there was not enough memory).
If the heap block is locked, then the block will not be moved in
order to reallocate it. However, unlocked blocks above the heap block will be moved.
The contents of the object will be unchanged up to
the lesser of the new and old size. If the new size is larger, the value of the
newly allocated portion of the block is indeterminate.
This routine may cause garbage collection.
<BR><BR>
<B>Note:</B> Reallocating a locked block may fail very easily, especially if
you have allocated and locked some blocks just shortly before. The reason is
simple: If you allocate memory blocks in sequence, they are usually located
close to each other. If you try to grow a locked block which lies directly in
front of another locked block, the operation will fail because the second
locked block cannot be moved. In general it is a good idea to unlock memory
blocks before using HeapRealloc, and to lock them again afterwards if
necessary. This way the probability to succeed is much higher.

[References]
In=alloc.h/HeapReallocThrow, alloc.h/realloc, bascmd.h/cmd_blddata, bascmd.h/cmd_cubicreg, bascmd.h/cmd_dialog, bascmd.h/cmd_expreg, bascmd.h/cmd_linreg, bascmd.h/cmd_lnreg, bascmd.h/cmd_logistic, bascmd.h/cmd_medmed, bascmd.h/cmd_newdata, bascmd.h/cmd_onevar, bascmd.h/cmd_powerreg, bascmd.h/cmd_quadreg, bascmd.h/cmd_quartreg, bascmd.h/cmd_request, bascmd.h/cmd_twovar, dialogs.h/DialogAdd, estack.h/check_estack_size, estack.h/display_statements, estack.h/index_below_display_expression_aux, estack.h/Parse1DExpr, estack.h/reset_estack_size, files.h/TIOS_FClose: FClose, files.h/TIOS_FPutC: FPutC, homescr.h/HomeExecute, link.h/LIO_Receive, menus.h/DynMenuAdd, menus.h/DynMenuChange, stdio.h/fclose, stdio.h/fputc, system.h/CB_replaceTEXT, textedit.h/TE_checkSlack, textedit.h/TE_handleEvent, textedit.h/TE_pasteText, textedit.h/TE_shrinkWrap, unknown.h/convert_to_TI_92, unknown.h/delete_list_element, alloc.h/hStrAppend, unknown.h/OO_SetAttr, unknown.h/PlotDel, unknown.h/PlotPut, unknown.h/ReallocExprStruct, unknown.h/spike_geo_titles, unknown.h/spike_in_editor, unknown.h/spike_optionD, unknown.h/tokenize_if_TI_92_or_text, vat.h/AddSymToFolder, vat.h/FolderAdd, vat.h/FolderDel, vat.h/FolderRename, vat.h/HSymDel, vat.h/SymAddTwin, vat.h/SymDel, vat.h/SymDelTwin, vat.h/VarStore, wingraph.h/WinReOpen, unknown.h/_ROM_CALL_439, unknown.h/_ROM_CALL_4CB
Out=alloc.h/HeapAlloc, alloc.h/HeapCompress, mem.h/memmove, system.h/NeedStack
