A-Shell Reference

Rewritten March 2025

.EXTENT(ary(){,subno})

This function returns the "extent" of the specified array or collection, i.e. the number of elements in it. The first syntax applies to arrays; the optional subno parameter specifies the subscript or dimension number, defaulting to 1 for single-dimension array. It works for both static and DIMX arrays and is especially useful for those with the AUTO_EXTEND attribute.  For example:

DIMX ary(p,q,r),s,25,AUTO_EXTEND

...

? .EXTENT(ary())    ! prints maximum current value of the first subscript, i.e. p in ary(p,q,r)

? .EXTENT(ary(),2)  ! prints maximum current value of the second subscript, i.e. q in ary(p,q,r)

 

The second syntax applies to ordered maps or Gridmaps.  For example:

DIMX $zipcodes, ORDMAP(varstr;varstr)

$zipcodes("00000") = "North Pole" ! add an element

? .EXTENT($zipcodes())            ! displays 1 (one name-value pair)

$zipcodes("00000") = .NULL        ! delete the element

? .EXTENT($zipcodes())            ! displays 0

 

DIMX $table(int, int, varstr)

? .EXTENT($table())               ! displays 0 (map initialized but empty)

REDIMX $table()

? .EXTENT($table())               ! displays -1 (map uninitialized)

 

Comments

In all the variations involving DIMX, if the array or map has not yet been initialized (i.e. the compiler has seen the DIMX statement but it was not yet executed at runtime), or it was executed and then freed with REDIMX (as in the last example above), .EXTENT will return -1.

As illustrated above, deleting elements from an ordered map or gridmap (by setting the value to .NULL) reduces the extent.  For standard arrays, there is no equivalent to deleting an element, and there is no way to add an element (x) without automatically adding any previously missing elements from (1) to (x-1).  So for those arrays, .EXTENT effectively returns the highest element number previously assigned to that subscript (unless the array has been redimensioned with REDIMX), for example:

DIMX a(0),b, 2, AUTO_EXTEND

a(9) = 1

? .EXTENT(a())    ! prints 9 (elements 1-8 were auto-filled with zeros)

REDIMX a(5)

? .EXTENT(a())    ! prints 5 (redimensioned size)

 

Also note that when a standard array is auto-extended, even though as an efficiency measure it typically allocates room for more than just the latest element, .EXTENT only reports the highest element number actually assigned.

See Also