![]() |
Section 8.5.4.2.1: |
![]() |
This class specifies features appropriate to the abstraction of a mutable list from which it sub-types. The sub-typing from $ELT_NIL permits the definition of creation for an empty list.
types SAME = FLIST_ETP ; FLIST_ETP = seq of ETP
This class implements lists of elements with mutable semantics. These may be viewed as extensible stacks. Like any list abstraction (eg linked lists) they serve as general container objects for holding collections of other objects. The requirement for this class is specified in order that implementations may provide a highly efficient list facility.
The following features are required to be implemented for this class in accordance with the specification given in the class $FLISTS{} of which this is a sub-type :-
The following features are required to be implemented for this class in accordance with the specification given in the class $LISTS{} of which $FLISTS{} is a sub-type :-
The following features are required to be implemented for this class in accordance with the specification given in the class $ARR{} of which $FLISTS{} is a sub-type :-
The following features are required to be implemented for this class in accordance with the specification given in the class $RO_ARR{} of which $FLISTS{} is a sub-type :-
The following features are required to be implemented for this class in accordance with the specification given in the class $CONTAINER{} of which $FLISTS{} is a sub-type :-
The following features are required to be implemented for this class in accordance with the specification given in $FILTERS of which $FLISTS{} is a sub-type :-
The following feature is required to be implemented for this class in accordance with the specification given in the class $COPY of which $FLISTS{} is a sub-type :-
The following features are required to be implemented for this class in accordance with the specification given in $ELT of which $FLISTS{} is a sub-type :-
The following features are required to be implemented for this class in accordance with the specifications given by inheritance in $STR of which $FLISTS{} is a sub-type :-
The following features are required to be implemented for this class in accordance with the specifications given by inheritance in $ELT_NIL of which this class is a sub-type :-
This feature creates and returns a list of the elements for which the argument is a textual representation.
create(src : STR, sep : CHAR) res : SAME
pre (CHAR::is_space(sep) and sep <> LIBCHARS::char(LIBCHARS::Space(STR::index_lib(src)))) or not CHAR::is_control(sep)
post res(str(STR::index_lib(src), sep)) = src
This feature creates a new list, the elements of which are set to have the values represented in the string argument, the result having the size given by the number of elements in the src string.
This feature creates and returns a list of any kind of container which derives from the abstraction $ELT.
create_from | ( |
container : $ELT{ETP} | |
) : SAME |
create_from(container : $ELT_T) res : SAME
Since the argument is not an optional type, the pre-condition is vacuously true.
post size(res) = size(container) and forall index | index in set inds res & container(index) = res(index)
This feature creates a new list, the elements of which are set to have the values of the elements in the given container in such a way that the order of elements in the sequence indexed for the result is the same as that of the argument.
This feature creates and returns a list of the required size all of the elements of which are nil.
create_empty_sized | ( |
size : CARD | |
) : SAME |
create_empty_sized(size : CARD) res : SAME
Since the argument is never negative, the pre-condition is vacuously true.
post size(res) = count and forall index | index in set inds res & res(index) = elt_nil(res(index))
This feature creates a new list, the elements of which are set to have the value elt_nil.
This feature creates and returns a list of the elements from the cursor given, taking the start argument as the character which is expected as the first non-space character in the buffer and the finish argument as the non-space element in the buffer which closes the list source in the buffer.
build | ( |
cursor : STR_CURSOR, | |
start : CHAR, | |
finish : CHAR | |
) : SAME |
build(cursor : STR_CURSOR, start : CHAR, finish : CHAR) res : SAME
pre (CHAR::is_print(start) and not CHAR::is_space(start)) and (CHAR::is_print(finish) and not CHAR::is_space(finish)) and (STR_CURSOR::remaining(cursor) >= 2 and let buff : seq of CHAR be st buff = STR_CURSOR::buffer(cursor) in forall idx1, idx2 in set inds buff | (idx1 <> idx2 and exists idx1 & buff(idx1) = start and exists idx2 & buff(idx2) = finish) & idx2 > idx1)
post res(str(STR::index_lib(src), sep)) = src
This feature creates a new list, the elements of which are set to have the values represented in the string argument, the result having the size given by the number of elements in the src string.
This feature provides a conventional stack operation for the list, successive calls returning items in LIFO order.
pop | : ETP |
pop(self : SAME) res : [ETP]
This is vacuously true since the list itself is required to exist by the definition of this feature.
post ((loc~ = 0) and (res = nil)) or ((res = [loc]) and (loc + 1 = loc~))
This routine removes the element at the head of the list and returns the object removed.
This feature provides a conventional stack operation for the list, always returning the item at the head of it.
top | : ETP |
top(self : SAME) res : [ETP]
This is vacuously true since the list itself is required to exist by the definition of this feature.
post ((loc~ = 0) and (res = nil)) or ((res = [loc - 1]) and (loc = loc~))
This routine returns the element at the head of the list.
This feature provides a mechanism for re-using, rather than re-creating a mutable list.
reset(self : SAME)
This is vacuously true since the list itself is required to exist by the definition of this feature.
post (loc = 0)
This routine resets the list to be the empty list.
This feature returns the index of the first occurrence of the given element in the list.
index_of(self : SAME, elt : ETP) res : CARD
Since the arguments are not optional this is vacuously true.
post let list : seq of ETP be st list = self in (elt not in set dom list and res = nil or let head ^ tail = list be st elt not in set dom head and tail(1) = elt in res = len head
This feature searches the list from the beginning to find the first occurrence (if any) of the given element in the list. If the search was successful then the index where it was found is returned, otherwise CARD::nil.
This feature returns the result of appending the argument list to self.
append | ( |
list : SAME | |
) : SAME |
append(self : SAME, list : SAME) res : SAME
Since the arguments are not optional this is vacuously true.
post res = copy(self) ^ list
This routine appends the given list to the end of a copy of self and returns the result. Self may be void; list must not be the same as self unless it is void!
This feature returns the result of appending the argument list to self destructively and should therefore be faster than append above.
concat | ( |
list : SAME | |
) : SAME |
concat(self : SAME, list : SAME) res : SAME
Since the arguments are not optional this is vacuously true.
post res = self ^ list
This routine appends the given list to the end of self and returns the result. Self may be void; list must not be the same as self unless it is void!
sublist( beg, num : CARD ) : SAMEThis feature provides a facility similar to the substring feature for strings. The items in the sublist are in the same order as they are in the parent list.
sublist(self : SAME, startindex, count : CARD) res : SAME
pre (startindex < len self) and (count > 0)
post let head, tail : seq of ELT be st head ^ res ^ tail = self and len head = start_index and (((len tail = 0) and (len res = len self - len head)) or ((len res = count) and (len tail > 0)) and forall idx | idx in set inds res & res(idx) = self(idx + start_index)
This routine returns a sublist of num entries starting at the entry indicated. The items in the sub-list are in the same order as they are in self.
This feature reverses the contents of the list. This is similar to the reverse feature of string classes, but the change is done in situ.
to_reverse(self : SAME)
Since the argument is not optional then the pre-condition is vacuously true.
postlet original : seq of ELT be st original = self~ in forall idx1 | idx1 in set inds original & original(idx1) = self(len self + 1 - idx1)
This feature sets the contents of self into the inverse of the initial order of elements.
This feature sets all of the elements of self to have the same, given value.
fill | ( |
elem : ETP | |
) |
fill(self : SAME, elem : ELT)
Since neither of the arguments is optional, the pre-condition is vacuously true.
post forall idx | idx in set inds self & self(idx) = elem
This feature sets every element of the list to have the given value.
inds : ARRAY{CARD}This feature returns an array all of the elements of which are valid indices of self. Each element value is the same as its index in the returmed result.
inds(self : SAME) res : seq of CARD
Since the argument is not optional then this pre-condtion is vacuously true.
post len res = len self and forall idx | idx in set inds self & res(idx) = idx
This feature returns an array containing the same number of elements as self, the individual elements of which have the same value as their index in the array.
This routine returns the list which is the result of deleting the element of self at the given index.
delete(self : SAME, index : CARD) res : SAME
pre index < len self
post let head, tail : seq of ELT, item : ELT be st head ^ [item] + tail = self and item = self(index + 1) in dom res = dom (head ^ tail)
This feature returns the list which has the same contents as self except for the element at the index given in the original version of self. The order of elements in the result is not necessarily the same as that in self.
This routine returns the list which is the result of deleting the element of self at the given index. The result has elements in the same order as they are in self.
delete_ordered | ( |
index : CARD | |
) : SAME |
delete_ordered(self : SAME, index : CARD) res : SAME
pre index < len self
post let head, tail : seq of ELT, item : ELT be st head ^ [item] + tail = self and item = self(index + 1) in res = head ^ tail
This feature returns the list which has the same contents as self except for the element at the index given in the original version of self. The order of elements in the result is exactly the same as the original order in self.
This routine returns the list which is the result of deleting the first occurrence of the given element in self.
delete_elt | ( |
elem : ELT | |
) : SAME |
delete_elt(self : SAME, elem : ELT) res : SAME
pre elem in dom self
post let idx be st self(idx) = elem and (forall index | index in set inds [1, ..., (idx - 1)] & self(index) <> elem) in head ^ [self(idx)] ^ tail = self and len head = idx - 1 and dom res = dom (head ^ tail)
This feature returns the list which has the same contents as self except for the first element of the given value in the original version of self. The order of elements in the result is not necessarily the same as that in self.
This routine returns the list which is the result of deleting the first occurrence of the given element in self in which the order of elements is guaranteed to be the same as that of self.
delete_elt_ordered | ( |
elem : ELT | |
) : SAME |
delete_elt_ordered(self : SAME, elem : ELT) res : SAME
pre elem in dom self
post let idx be st self(idx) = elem and (forall index | index in set inds [1, ..., (idx - 1)] & self(index) <> elem) in head ^ [self(idx)] ^ tail = self and len head = idx - 1 and res = head ^ tail
This feature returns the list which has the same contents as self except for the first element of the given value in the original version of self in such a way as to preserve the original order of self.
This iter version and the one following complement the one inherited by this abstraction. This permits the first element yielded to be the element indexed by the start argument.
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.
elt_iter2(self : SAME, start : CARD) res : ELT
Since the iter may quit if start is not in the domain of indices of self, the pre-condition is vacuously true.
This post-condition makes use of the history concept from vdm++ (see the vdm dialect notes).
post history = history~ ^ [res] and res = self(len history + start)
For quit actions see the specification of the quit statement.
errs QUIT : (len history + start) = len self -> quit
This iter yields the elements of self in order beginning with the element at the given starting index.
This iter version specifies both the element to yield first and the number of elements to be yielded.
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.
elt_iter3(self : SAME, start : CARD, num : CARD) res : ELT
Since the iter may quit if start is not in the domain of indices of self, the pre-condition is vacuously true.
This post-condition makes use of the history concept from vdm++ (see the vdm dialect notes).
post history = history~ ^ [res] and res = self(len history + start)
For quit actions see the specification of the quit statement.
errs QUIT : (len history = num) or (len history + start) = len self -> quit
This iter yields num elements of self in order beginning with the element at the given starting index.
This final version of the elt! iter specifies the element to yield first, the number of elements to be yielded and the index interval between the elements to be yielded.
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.
elt_iter3(self : SAME, start : CARD, num : CARD, step : INT) res : ELT
Since the iter may quit if start is not in the domain of indices of self, the pre-condition is vacuously true.
This post-condition makes use of the history concept from vdm++ (see the vdm dialect notes).
post history = history~ ^ [res] and res = self(len history + start)
For quit actions see the specification of the quit statement.
errs QUIT : (len history = num) or (len history + start) = len self -> quit
This iter yields num elements of self in order beginning with the element at the given starting index, each element yielded being at an interval step (which may be negative) from the previous element yielded.
This is a specialised version of the text string representation routine which specifies the character which is to be treated as the separator between list elements in the text.
str(self : SAME, lib : LIBCHARS, sep : CHAR) res : STR
Since there is a representation of an empty list - as {}, the pre-condition is vacuously true.
postself = create(res,sep)
This feature returns a text string consisting of the textual representation of each list element separated by the given character sep, enclosed in braces.
The remaining features of this class provide facilities for set-like operations on mutable lists. These are defined as a convenience where occasional use of such a feature on a list is required.
An implementation is required to provide the features above in as efficient a manner as possible. The set-like feature efficiency must be subordinate in this context (see, however, the class FSET{ELT}).
This routine implements the set union operation on the two lists. This is not required to be efficient at the expense of the efficiency of other list operations.
union | ( |
list : SAME | |
) : SAME |
union(self : [SAME], list : SAME) res : SAME
Note that, given the nature of this operation and the fact that at least one of the arguments is non-void, the pre-condition is true.
post ((self = nil) and (res = list)) or ((self <> nil) and res = self union list
This feature returns a new list containing the elements in the union of self and the argument. Note that self may be void but the argument may not be void.
This routine implements the set intersection operation on the two lists. This is not required to be efficient at the expense of the efficiency of other list operations.
intersect | ( |
list : SAME | |
) : SAME |
intersect(self : [SAME], list : SAME) res : SAME
Note that, given the nature of this operation and the fact that at least one of the arguments is non-void, the pre-condition is true.
post ((self = nil) and (res = list)) or ((self <> nil) and res = self inter list
This feature returns a new list containing the elements in the intersection of self and the argument. Note that self may be void but the argument may not be void.
This routine implements the set difference operation on the two lists. This is not required to be efficient at the expense of the efficiency of other list operations.
difference | ( |
list : SAME | |
) : SAME |
difference(self : [SAME], list : SAME) res : SAME
Note that, given the nature of this operation and the fact that at least one of the arguments is non-void, the pre-condition is true.
post ((self = nil) and (res = list)) or ((self <> nil) and res = self \ list
This feature returns a new list containing the elements in the set difference of self and the argument. Note that self may be void but the argument may not be void.
This routine implements the set difference operation on the two lists. This is not required to be efficient at the expense of the efficiency of other list operations.
sym_difference | ( |
list : SAME | |
) : SAME |
sym_difference(self : [SAME], list : SAME) res : SAME
Note that, given the nature of this operation and the fact that at least one of the arguments is non-void, the pre-condition is true.
post ((self = nil) and (res = list)) or ((self <> nil) and res = (self union list) \ (self intersect list)
This feature returns a new list containing the elements in the set symmetric difference of self and the argument. Note that self may be void but the argument may not be void.
![]() |
Language Index | ![]() |
Library Index | ![]() |
Container Index |
Comments or enquiries should be made to
Keith
Hopper. Page last modified: Thursday, 22 March 2001. |
![]() |