Sather Home Page

Section 8.5.4.2.1:
FLIST

class FLIST{ETP} < $FLISTS{ETP}

Inheritance map

$NIL

Formal Definitions

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.


External specifications

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 :-


create

This feature creates and returns a list of the elements for which the argument is a textual representation.

create (
str : STR
) : SAME
Formal Signature
create(src : STR, sep : CHAR) res : SAME
Pre-condition
pre (CHAR::is_space(sep)
         and sep <> LIBCHARS::char(LIBCHARS::Space(STR::index_lib(src))))
      or not CHAR::is_control(sep)
Post-condition
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.


create_from

This feature creates and returns a list of any kind of container which derives from the abstraction $ELT.

create_from (
container : $ELT{ETP}
) : SAME
Formal Signature
create_from(container : $ELT_T) res : SAME
Pre-condition

Since the argument is not an optional type, the pre-condition is vacuously true.

Post-condition
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.


create_empty_sized

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
Formal Signature
create_empty_sized(size : CARD) res : SAME
Pre-condition

Since the argument is never negative, the pre-condition is vacuously true.

Post-condition
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.


build

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
Formal Signature
build(cursor : STR_CURSOR, start : CHAR, finish : CHAR) res : SAME
Pre-condition
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-condition
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.


pop

This feature provides a conventional stack operation for the list, successive calls returning items in LIFO order.

pop : ETP
Formal Signature
pop(self : SAME) res : [ETP]
Pre-condition

This is vacuously true since the list itself is required to exist by the definition of this feature.

Post-condition
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.


top

This feature provides a conventional stack operation for the list, always returning the item at the head of it.

top : ETP
Formal Signature
top(self : SAME) res : [ETP]
Pre-condition

This is vacuously true since the list itself is required to exist by the definition of this feature.

Post-condition
post ((loc~ = 0)
         and (res = nil))
      or ((res = [loc - 1])
         and (loc = loc~))

This routine returns the element at the head of the list.


reset

This feature provides a mechanism for re-using, rather than re-creating a mutable list.

reset
Formal Signature
reset(self : SAME)
Pre-condition

This is vacuously true since the list itself is required to exist by the definition of this feature.

Post-condition
post (loc = 0)

This routine resets the list to be the empty list.


index_of

This feature returns the index of the first occurrence of the given element in the list.

index_of (
elem : ETP
) : CARD
Formal Signature
index_of(self : SAME, elt : ETP) res : CARD
Pre-condition

Since the arguments are not optional this is vacuously true.

Post-condition
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.


append

This feature returns the result of appending the argument list to self.

append (
list : SAME
) : SAME
Formal Signature
append(self : SAME, list : SAME) res : SAME
Pre-condition

Since the arguments are not optional this is vacuously true.

Post-condition
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!


concat

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
Formal Signature
concat(self : SAME, list : SAME) res : SAME
Pre-condition

Since the arguments are not optional this is vacuously true.

Post-condition
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 ) : SAME

sublist

This 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 (
start_index : CARD
count : CARD
) : SAME
Formal Signature
sublist(self : SAME, startindex, count : CARD) res : SAME
Pre-condition
pre (startindex < len self)
      and (count > 0)
Post-condition
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.


to_reverse

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
Formal Signature
to_reverse(self : SAME)
Pre-condition

Since the argument is not optional then the pre-condition is vacuously true.

Post-condition
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.


fill

This feature sets all of the elements of self to have the same, given value.

fill (
elem : ETP
)
Formal Signature
fill(self : SAME, elem : ELT)
Pre-condition

Since neither of the arguments is optional, the pre-condition is vacuously true.

Post-condition
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}

inds

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 : ARRAY{CARD}
Formal Signature
inds(self : SAME) res : seq of CARD
Pre-condition

Since the argument is not optional then this pre-condtion is vacuously true.

Post-condition
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.


delete

This routine returns the list which is the result of deleting the element of self at the given index.

delete (
index : CARD
) : SAME
Formal Signature
delete(self : SAME, index : CARD) res : SAME
Pre-condition
pre index < len self
Post-condition
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.


delete_ordered

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
Formal Signature
delete_ordered(self : SAME, index : CARD) res : SAME
Pre-condition
pre index < len self
Post-condition
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.


delete_elt

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
Formal Signature
delete_elt(self : SAME, elem : ELT) res : SAME
Pre-condition
pre elem in dom self
Post-condition
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.


delete_elt_ordered

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
Formal Signature
delete_elt_ordered(self : SAME, elem : ELT) res : SAME
Pre-condition
pre elem in dom self
Post-condition
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.


elt!

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.

elt! (
once  start : CARD
) : ELT
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.

elt_iter2(self : SAME, start : CARD) res : ELT
Pre-condition

Since the iter may quit if start is not in the domain of indices of self, the pre-condition is vacuously true.

Post-condition

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)
Quit condition

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.


elt!

This iter version specifies both the element to yield first and the number of elements to be yielded.

elt! (
once  start : CARD
once  num : CARD
) : ELT
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.

elt_iter3(self : SAME, start : CARD, num : CARD) res : ELT
Pre-condition

Since the iter may quit if start is not in the domain of indices of self, the pre-condition is vacuously true.

Post-condition

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)
Quit condition

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.


elt!

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.

elt! (
once  start : CARD
once  num : CARD
once  step : INT
) : ELT
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.

elt_iter3(self : SAME, start : CARD, num : CARD, step : INT) res : ELT
Pre-condition

Since the iter may quit if start is not in the domain of indices of self, the pre-condition is vacuously true.

Post-condition

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)
Quit condition

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.


str

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 (
lib : LIBCHARS
sep : CHAR
) : STR
Formal Signature
str(self : SAME, lib : LIBCHARS, sep : CHAR) res : STR
Pre-condition

Since there is a representation of an empty list - as {}, the pre-condition is vacuously true.

Post-condition
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.

Set-like Features

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}).


union

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
Formal Signature
union(self : [SAME], list : SAME) res : SAME
Pre-condition

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-condition
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.


intersect

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
Formal Signature
intersect(self : [SAME], list : SAME) res : SAME
Pre-condition

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-condition
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.


difference

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
Formal Signature
difference(self : [SAME], list : SAME) res : SAME
Pre-condition

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-condition
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.


sym_difference

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
Formal Signature
sym_difference(self : [SAME], list : SAME) res : SAME
Pre-condition

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-condition
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.
Produced with Amaya