| # Section 7.3.1: AREF |

###### class AREF{T}

#### Formal Types

types
SAME = AREF_T ;
AREF_T = seq of T

This pervasive 'constructor' class encapsulates the concept of an array of elements of the argument type T. As a 'constructor' it is provided for inclusion in reference implementation classes which contain an array component. In order to minimize name clashes in programmer defined classes which include this class, all feature names apart from 'create' begin with the letter "a".

NOTE | The class ARRAY{T} provides an array abstraction which may be used directly.

The type of numeric arguments and results in this class is given as nat in order that implementations of the language which do not need the Required Library but wish to conform to the language specification may implement this unsigned number type in some suitable way - which must be implementation-defined. Where an implementation is providing the Required Library then these values must be of class CARD.

#### asize

This feature provides the count of elements in the array.

asize | : nat

##### Formal Signature

asize(self : SAME) res : nat

##### Pre-condition

This is vacuously true since th argument type is not optional. Therefore in Sather terms it may not be void.

##### Post-condition

post res = card elems self

This feature returns the count of elements of the array self.

#### create

This creation feature produces an empty object which contains the number of elements indicated by the value of the single parameter.

Note that the parameter may have the value zero - which produces an empty array of zero elements as would be expected, although this is not very often useful in practice.

create | (
| cnt : nat
| ) : SAME

##### Formal Signature

create(cnt : nat) res : SAME

##### Post-condition

post card res = cnt
and forall elem in set dom res & elem = nil

This routine returns a new empty array containing the number of elements specified by the argument.

#### aget

This feature provides the default indexed element retrieval operation. See the infix expression concrete syntactic version which uses square brackets '[' and ']' to surround the index value.

aget | (
| index : nat
| ) : T

##### Formal Signature

aget(self : SAME, index : nat) res : T

##### Pre-condition

pre (index <= (asize - 1))

##### Post-condition

post res = self(index + 1)

This routine returns the array element indexed by the parameter.

NOTE | The index used in the application to self in the above post-condition is one greater than that used in Sather. Indices in vdm-sl are an ordinal sequence starting at 1 - in Sather indices start from 0!

#### aset

This feature is the value setting counterpart of aget above. The corresponding 'infix' assignment version using square brackets '[' and ']' is defined in the assignment statement section of this document.

aset | (
| index : nat
| val : T
| )

##### Formal Signature

aset(self : SAME, index : nat, val : T)

##### Pre-condition

pre (index <= (asize(self) - 1))

NOTE | Since the self argument is not optional, this has the same effect as stating in a Sather pre-condition that self is not void. This applies to all cases in this class.

##### Post-condition

post self(index + 1) = val

This routine sets, to the value of the val argument, the element of the array which has the given index.

#### aclear

This feature is provided for efficiency where some array needs to be rewritten. Without creating a new array it sets all of the elements to be empty.

aclear

##### Formal Signature

aclear(self : SAME)

##### Post-condition

post asize(self) = asize(self~)
forall elem in set dom self & elem = nil

This routine sets each element of self to the state of a newly created object.

#### acopy

This feature provides self with as many of the element values of src as will fit into it.

acopy | (
| src : SAME
| )

##### Formal Signature

acopy1(self : SAME, src : SAME)

##### Pre-condition

pre src <> self

##### Post-condition

post ((asize(self) >= asize(src)
and forall index in inds src & self(index) = src(index))
or forall index in inds self & self(index) = src(index)

This routine copies elements sequentially from src to self starting at the lowest index until either there are no more elements in src to copy or there are no more elements in self to fill, whichever occurs first.

#### acopy

This version of acopy copies elements from src to self beginning at the element with the given index.

acopy | (
| beg : nat
| src : SAME
| )

##### Formal Signature

acopy2(self : SAME, beg : nat, src : SAME)

##### Pre-condition

pre asize(self) <> 0
and src <> self
and (beg <= asize(self))

##### Post-condition

post forall index in set {1,...,beg}
& self~(index) = self(index)
and forall index in set {(beg + 1),...,(beg + src.asize)}
& index in set {1,...,asize} & self(index) = src(index - beg)
and forall index in set {(beg + src.size + 1),...,asize}
& index in set {1,...,asize} & self(index) = self~(index)

Starting at index beg of self, this routine copies elements sequentially from src to self starting at the lowest index until either there are no more elements in src to copy or there are no more elements in self to fill, whichever occurs first.

#### acopy

This version of acopy copies the number of elements given by the second parameter from src to self beginning at the element with the given index.

acopy | (
| beg,
| num : nat
| src : SAME
| )

##### Formal Signature

acopy3(self : SAME, beg,num : nat, src : SAME)

##### Pre-condition

pre asize(self) <> 0
and src <> self and beg <= (asize(self) - 1))
and (num <= (asize(self) - beg))
and (num <= asize(src))

##### Post-condition

post forall index in set {1,...,beg}
& self(index) = self~(index)
and forall index in set {(beg + 1),...,(beg + num)}
& index in set {1,...,asize} & self(index) = src(index - beg)
and forall index in set {(beg + num),...,asize)}
& index in set {1,...,asize)} & self(index) = self~(index)

This routine copies num elements from src to self starting at index beg of self until either there are no more elements in src to copy or there are no more elements in self to be filled, whichever occurs first.

#### acopy

This final version of acopy has four arguments - the index of self at which value storage is to begin, the count of values to be copied, the index in src from which copying is to start and, lastly, the source array itself.

acopy | (
| beg,
| num,
| srcbeg : nat
| src : SAME
| )

##### Formal Signature

acopy4(self : SAME, beg, num, srcbeg : nat, src : SAME)

##### Pre-condition

pre asize(self) <> 0
and src <> self
and (beg <= (asize(self) - 1))
and (num <= (asize(self) - beg))
and (srcbeg >= asize(src))
and (num <= (asize(src) - srcbeg))

##### Post-condition

post forall index in set {1,...,beg)}
& self(index) = self~(index)
and forall index in set {(beg + 1),...,(beg + num)}
and (indsb in set {(srcbeg + 1),...,(srcbeg + num)}
& index in set {1,...,asize} & self(index) = src(indsb)
and forall index in set {(beg + num + 1),...,asize}
& index in set {1,...,asize} & self(index) = self~(index)

This routine copies num elements starting to store in the beg element of self, taking values starting with the srcbeg elemenbt of src. This copying continues sequentially until the first of the three following events occurs; num elements have been copied; the last element of src has been copied or the last element of self has been filled.

#### array_ptr

This feature provides a reference to the array in a form which can be used by the external execution environment.

array_ptr | : REFERENCE

##### Formal Signature

array_ptr(self : SAME) res : REFERENCE

##### Post-condition

The post-condition is expected to be such that the returned value is a valid reference to the array in the external execution environment of the program. This cannot be enforced by this specification since its value can only be known at run-time.

This routine returns a reference to self suitable for use with services provided by the external execution environment.

#### aind!

This feature is an iterator over the indices of the array, yielding each one in sequence from zero upwards.

aind! | : nat

##### Formal Signature

Note that the formal name of the iter has been changed to replace the exclamation mark iter symbol to a name acceptable to vdm tools.

aind_iter(self : SAME) yld : nat

##### Post-condition

This post-condition makes use of the history concept from vdm++ (see the vdm dialect notes).

post ((history~ = []
or (yld > tl history~))
and history = history~ ^ yld)

##### Quit condition

For quit actions see the specificatiion of the quit statement.

errs QUIT : (set dom history~ = set inds self) -> quit

This iter yields the indices of self in numeric order, starting with zero. The iter quits when applied after yielding the value of the highest index of the array.

#### aelt!

This iter yields in sequence all of the array element values beginning with that element indexed by zero.

aelt! | : T

##### Formal Signature

Note that the formal name of the iter has been changed to replace the exclamation mark iter symbol to a name acceptable to vdm tools.

aelt_iter(self : SAME) yld : T

##### Post-condition

This post-condition makes use of the history concept from vdm++ (see the vdm dialect notes).

post ((history~ = [])
or (yld = self(card elems history~ + 1)))
and (history = history~ ^ yld)

##### Quit condition

For quit actions see the specification of the quit statement.

errs QUIT : (elems history~ = elems self) -> quit

This iter yields all of the elements of self in the order that they would be produced by applying the sequence of indices produced by aind! to self.

#### aelt!

This variant of aelt! takes an argument which is evaluated on first entry to give the index of the first element to be yielded.

aelt! | (
once | beg : nat
| ) : T

##### Formal Signature

Note that the formal name of the iter has been changed to replace the exclamation mark iter symbol to a name acceptable to vdm tools.

aelt_iter2(self : SAME, beg : nat) yld : T

##### Pre-condition

pre beg < card elems self

##### Post-condition

This post-condition makes use of the history concept from vdm++ (see the vdm dialect notes).

post ((history~ = [])
or (yld = self(card elems history~ + beg + 1)))
and (history = history~ ^ yld)

##### Quit condition

For quit actions see the specification of the quit statement.

errs QUIT : (card elems history~ = card elems self - beg) -> quit

This iter yields all of the elements of self in the order that they would be produced by applying the sequence of indices produced by aind! to self starting with the value indicated by the parameter.

#### aelt!

This variant of aelt!, in addition to the starting index argument, takes a second argument indicating the number of element values that are to be yielded.

aelt! | : T
once | beg : nat
once | num : nat
| ) : T

##### Formal Signature

Note that the formal name of the iter has been changed to replace the exclamation mark iter symbol to a name acceptable to vdm tools.

aelt_iter3(self : SAME, beg : nat, num : nat) yld : T

##### Pre-condition

pre beg < card elems self
and (beg + num) <= card elems self

##### Post-condition

This post-condition makes use of the history concept from vdm++ (see the vdm dialect notes).

post ((history~ = [])
or (yld = self(card elems history~ + beg + 1)))
and (history = history~ ^ yld)

##### Quit condition

For quit actions see the specification of the quit statement.

errs QUIT : (card elems history~ = num) -> quit

This iter yields num elements of self in the order that they would be produced by applying the sequence of indices produced by aind! to self starting with the value indicated by the parameter.

#### aelt!

This final variant of aelt! takes three arguments - the index of the first element to be yielded, the count of elements and the increment/decrement of the index value between each application.

aelt! | : T
once | beg : nat
once | num : nat
once | step : int
| ) : T

##### Formal Signature

Note that the formal name of the iter has been changed to replace the exclamation mark iter symbol to a name acceptable to vdm tools.

aelt_iter4(self : SAME, beg : nat, num : nat, step : int) yld : T

##### Pre-condition

pre (((step > 0)
and beg < card elems self
and (beg + num * step) <= card elems self)
or ((step < 0)
and beg < card elems self
and (beg - num * step) >= 0))

##### Post-condition

This post-condition makes use of the history concept from vdm++ (see the vdm dialect notes).

post ((history~ = [])
or (yld = self((card elems history~ * step) + beg + 1)))
and (history = history~ ^ yld)

##### Quit condition

For quit actions see the specification of the quit statement.

errs QUIT : (card elems history~ = num) -> quit

This iter yields num elements of self in the order that they would be produced by applying the sequence of indices produced by aind! multiplied by step to self starting with the value indicated by the parameter.

#### aset!

This feature enables successive elements of the array to be set in turn, beginning with the first element.

aset! | (
| val : T
| )

##### Formal Signature

Note that the formal name of the iter has been changed to replace the exclamation mark iter symbol to a name acceptable to vdm tools.

set1_iter(self : SAME, val : T)

##### Post-condition

This post-condition makes use of the history concept from vdm++ (see the vdm dialect notes).

post (history = history~ ^ val)
and card elems history <= card elems self
and tl history = self(card elems history~ + 1)

##### Quit condition

For quit actions see the specification of the quit statement.

errs QUIT : card elems history~ = card elems self -> quit

This iter sets successive elements of self in the sequence of indices which would be yielded by aind! to the value of the parameter current on each successive application.

#### aset!

This variant of aset! takes an argument which is the index of the first element of the array to be set.

aset! | (
once | beg : nat
| val : T
| )

##### Formal Signature

Note that the formal name of the iter has been changed to replace the exclamation mark iter symbol to a name acceptable to vdm tools.

aset2_iter(self : SAME, beg : nat, val : T)

##### Pre-condition

pre beg < card elems self

##### Post-condition

This post-condition makes use of the history concept from vdm++ (see the vdm dialect notes).

post (history = history~ ^ val)
and card elems history <= card elems self
and tl history = self(card history~ + beg + 1)

##### Quit condition

For quit actions see the specification of the quit statement.

errs QUIT : card elems history~ = (card elems self - beg) -> quit

This iter sets successive elements of self beginning with the index value provided by the first parameter and continuing in the order which would be yielded by the iter aind!.

#### aset!

This variant of aset! provides the facility to set num elements of the array starting at the given index.

aset! | (
once | beg : nat
once | num : nat
| val : T
| )

##### Formal Signature

Note that the formal name of the iter has been changed to replace the exclamation mark iter symbol to a name acceptable to vdm tools.

aset3_iter(self : SAME, beg : nat, num : nat, val : T)

##### Pre-condition

pre beg < card elems self
and (beg + num) <= card elems self

##### Post-condition

This post-condition makes use of the history concept from vdm++ (see the vdm dialect notes).

post (history = history~ ^ val)
and card elems history <= card elems self
and tl history = self(card elems history~ + beg + 1)

##### Quit condition

For quit actions see the specification of the quit statement.

errs QUIT : card elems history~ = num -> quit

This iter sets num successive elements of self beginning with the index value provided by the first parameter and continuing in the order which would be yielded by the iter aind!.

#### aset!

This final version of aset! provides the facility to set num elements of the array starting with the one indicated and stepping between each application by the index decrement/increment given.

aset! | (
once | beg : nat
once | step : int
once | num : nat
| val : T
| )

##### Formal Signature

Note that the formal name of the iter has been changed to replace the exclamation mark iter symbol to a name acceptable to vdm tools.

aset4_iter(self : SAME, beg : nat, num : nat, step : int, val : T)

##### Pre-condition

pre (((step > 0)
and beg < card elems self
and (beg + num * step) <= card elems self)
or ((step < 0)
and beg < card elems self
and (beg - num * step) >= 0))

##### Post-condition

This post-condition makes use of the history concept from vdm++ (see the vdm dialect notes).

post (history = history~ ^ val)
and card elems history <= card elems self
and tl history = self((card elems history~ * step) + beg + 1)

##### Quit condition

For quit actions see the specification of the quit statement.

errs QUIT : card elems history~ = num -> quit

This iter sets num elements of the array starting with the element at the index value provided by the first parameter and incrementing/decrementing the index by step at each successive application.

| Language Index |  | Library Index |  | Section 7 Index

Comments or enquiries should be made to Keith Hopper. Page last modified: Friday, 19 May 2000. |