Modified January 2022

.CLEAR ary()          ! clear a dimx or fixed array

.CLEAR $ary()        ! clear a collection

The "dot-clear" statement clears or removes all the elements of an array or collection.   

For traditional MAP arrays, as well as for DIMX arrays without the AUTO_EXTEND attribute, .CLEAR ARY() simply clears the contents of the array without affecting its structure. This applies to both single and multi-dimensioned arrays. The end result is exactly equivalent to iterating through all of the array elements and setting each to null, except that it is easier to code and faster to execute.

For DIMX arrays with the AUTO_EXTEND attribute, the extent of the first dimension of the array is reset to 0. This is similar to resizing the array to 0 using REDIMX except that the array remains defined and ready to receive new elements (via auto-extension). Note that for multi-dimensional arrays, dimensions beyond the first retain their original extents; this is necessary for re-using the array since only the first dimension is subject to auto-extension.

Examples

This illustrates the case with an ordered map (collection).

dimx $capitals,ordmap(varstr;varstr)   ! declare array

print .extent($capitals())             ! initial extent is 0

$capitals(“california”) = “sacramento” ! add an element

$capitals(“nevada”) = “carson city”    ! add another element

print .extent($capitals())             ! extent is now 2

.clear $capitals()                     ! clear all elements

print .extent($capitals())             ! extent is now 0

This illustrates the use of .CLEAR to clear regular arrays created with MAP or DIMX:

map1 ary1(25),b,4

map1 ary2(10,5),f,6

dimx ary3(75),s,32

dimx ary4(0),x,0,auto_extend

...

.clear ary1()     ! all 25 elements cleared; array allocation unaffected

.clear ary2()     ! all 10x5 (50) elements cleared; allocation unaffected

.clear ary3()     ! all 75 elements cleared; allocation unaffected

.clear ary4()     ! array extent set back to 0; memory freed

History

January 2018, A-Shell build 6.5.1624, compiler edit 846:  .CLEAR enhancement:  .CLEAR ARY() now supported for all types of arrays; previously it only applied to collections. The details of the clearing operation depend on the nature of the array being cleared. Warning: using .CLEAR with any array type other than a collection (e.g. ORDMAP) requires that runtime version 6.5.1624 or above. Otherwise it will generate an Unsupported Function error.

June 2013, A-Shell build 6.1.1354, compiler edit 638:  .CLEAR $ARY() introduced.