DARY is a system for working with dynamically allocated arrays. One master global array, udg_heap, is partitioned by DARY_alloc and DARY_free. Use parallel arrays if you want to work with structures or other types. rheap and uheap are intended for this purpose for reals and units respectively.
It includes some secondary functionality for sorting, heaping, shuffling and searching dynamic arrays, since these are rather tricky to get right.
The arrays are primarily intended for temporary use when speed is essential. In the interest of speed, no array lengthening tricks are used, so you can only allocate 8191 elements. 8191 is the upper limit for one array because save games can fail when one uses the 8192nd element.
For permanent storage, structures and even arrays of fixed length, use Karukef's system. DARY is a niche system for the 1% of the time when you need to random access sets of varying length. If you need more permanent arrays, Vex's CSCache implements very similar functionality with graceful overflow handling.
Example: Find a group of the n closest units to some point
JASS:
function FillArrayWithGroup takes integer arr, integer max, group g returns integer
local unit u
local integer i = 0
loop
exitwhen i >= max
set u = FirstOfGroup(g)
exitwhen u == null
set udg_uheap[arr+i] = u
set i = i + 1
endloop
return i
endfunction
function FillUdist takes integer arr, integer len, real x, real y returns nothing
local integer i = 0
local real ux
local real uy
loop
exitwhen i >= len
set ux = GetUnitX(udg_uheap[arr+i]) - x
set uy = GetUnitY(udg_uheap[arr+i]) - y
set udg_rheap[arr+i] = ux*ux+uy*uy
set i = i + 1
endloop
endfunction
function FillGroupWithPermutedArray takes group g, integer arr, integer size, integer max returns nothing
local integer i = 0
if size > max then
set size = max
endif
loop
exitwhen i>= size
call GroupAddUnit(g,udg_uheap[udg_heap[arr+i]])
set i = i + 1
endloop
endfunction
function sort_uloc takes nothing returns nothing
local group g = CreateGroup()
local integer arr
local integer n
local real x = 0.
local real y = 0.
set arr = DARY_allocn(100)
call GroupEnumUnitsInRange(g,x,y,1000000.,null)
set n = FillArrayWithGroup(arr,100,g)
call DARY_initperm(arr,n)
call FillUdist(arr,n,x,y)
call DARY_sort(arr,n,udg_callbacks[DARY_RHEAP_LESS()])
call FillGroupWithPermutedArray(g,arr,n,5)
call DARY_freen(arr,100)
call DestroyGroup(g)
set g = null
endfunction
