Modified September 2014; see History

.EXTENT(ARY(){,SUBNO}) returns the "extent" of the subscript number SUBNO (default 1) in the array ARY(). This works for static arrays, but is mainly of interest with DIMX arrays, and especially those with the AUTO_EXTEND attribute. For example:

DIMX ARY(P,Q,R),S,25,AUTO_EXTEND

...

PRINT .EXTENT(ARY())    ! prints maximum current value of the first subscript, i.e. P in ARY(P,Q,R)

PRINT .EXTENT(ARY(),2)  ! prints maximum current value of the second subscript, i.e. Q in ARY(P,Q,R)

Comments

.EXTENT(ARY()) will return -1 if the array ARY() has not yet been DIMX'd, or if it has been de-allocated, whether explicitly via a REDIMX ARY(0) or implicitly by returning from a procedure or function in which the DIMX was local. See notes in the Dynamic Arrays (DIMX) topic.

For fixed sized arrays, or arrays that have been DIMX'd but not yet auto-extended, .EXTENT() will return the fixed or initial allocated size, including if the initial DIMX size is zero. This may be considered the physical extent, as it has nothing to do with the contents of the array. For arrays that have been auto-extended, .EXTENT() will return the highest element number that has been written, i.e. the logical extent. Note that this behavior changed in A-Shell version 6.1.1389; see History below for details.

Note that .EXTENT may also be used with Ordered Maps.

See Also

•   Sample programs in EXLIB:[908,61]

History

2014 September, A-Shell 6.1:  Significant behavior (semantic) change. Prior behavior and documentation was: .EXTENT(ARY()) will report the actual size of the array, which, depending on the availability and organization of the A-Shell heap when the array was last allocated or expanded, could be larger than what you explicitly asked for. This may be true even for arrays initially sized to 0 elements. This could lead to confusion in the case of AUTO_EXTEND arrays, leading you to falsely believe that all of the elements in the array, according to .EXTENT(ARY()), have actually been assigned values. If you need to keep track of how many elements have been assigned values, and can't tell by the fact that the un-assigned elements will be pre-initialized to nulls, then you'll need to use your own separate variable to keep track.

2010 September, A-Shell 6.0.1192:  Function added to A-Shell.