Sather Home Page

Section 8.10.1.5:
$FILE_CURSORS

This page contains the definition of the two variants of the $FILE_CURSORS abstractions.

abstract class $FILE_CURSORS

Formal Definitions

This abstract class defines a state component which is a set of all instantiations of objects of any class sub-typing from this class in addition to the vdm model types used wherever this class name is used. Note that SAME has to be an instantiated class, not an abstract one.

types

SAME = object_type ;
$FILE_CURSORS = set of object_type

state

multi : $FILE_CURSORS
inv multi_types ==
forall obj in set multi_types & sub_type($FILE_CURSORS,obj)
NOTE See the important note about vdm state in the notes on vdm-sl usage in this specification.

This abstraction models a cursor which indicates a particular position in a very large storage file. It is defined in order to enable programs to handle large files for which there is insufficient space in computer system memory.


size

This feature provides the current size of the associated file.

error : CARD
Formal Signature
size(self : SAME) res : CARD
Pre-condition

The pre-condition is vacuously true since the cursor cannot be created unless the file exists (see the cursor feature of the class BIN_FILE for example).

Post-condition

The result, in the absence of filing system errors, is the size of the associated file in octets.

This feature returns the size of the associated file. The value provided is the same as that which could be obtaines by enquiring of the file directly.


readable

This predicate returns true if and only if the associated file is readable. It provides the same answer as would be provided by a direct enquiry of the associated file.

readable : BOOL
Formal Signature
readable(self : SAME) res : BOOL
Pre-condition

Being a predicate the pre-condition is vacuously true.

Post-condition

Being a predicate the post-condition is also vacuously true.

This feature returns true if and only if the associated file is readable, otherwise false.


writable

This predicate returns true if and only if the associated file is writable. It provides the same answer as would be provided by a direct enquiry of the associated file.

writable : BOOL
Formal Signature
writable(self : SAME) res : BOOL
Pre-condition

Being a predicate the pre-condition is vacuously true.

Post-condition

Being a predicate the post-condition is also vacuously true.

This feature returns true if and only if the associated file is writable, otherwise false.


at_end

This predicate returns true if and only if the cursor is positioned at the end of the associated file.

at_end : BOOL
Formal Signature
at_end(self : SAME) res : BOOL
Pre-condition

Being a predicate the pre-condition is vacuously true.

Post-condition

Being a predicate the post-condition is also vacuously true.

This feature returns true if and only if the cursor is positioned at the end of the file.


position

This routine returns the current position of the cursor in the file in storage units.

position : CARD
Formal Signature
position1(self : SAME) res : CARD
Pre-condition

This feature is defined irrespective of pre-condition.

Post-condition
post backward(self,position(self)) = 0

This feature provides the numeric value of the position of the cursor in the associated file based on an offset from the first position in the file which is position 0.


position

This feature is the writer routine corresponding to the above reader routine, enabling the cursor position in the associated file to be adjusted to the given offset from the beginning.

position (
at : CARD
) : SAME
Formal Signature
position(self : SAME, at : CARD) res : SAME
Pre-condition
pre at < size(self)
Post-condition
post position(self) = at
and (res = self)

This feature provides the facility to set a new current position of the cursor in the file to be the value given as an offset in storage units (number of octets) from the beginning of the file, returning the modified cursor resulting from this.


forward

This feature provides for relative positioning within a file from the current position to a new position count storage units (octets) nearer to the end of the file.

forward (
count : CARD
) : SAME
Formal Signature
forward(self : SAME, count : CARD) res : SAME
Pre-condition
pre position(self) + count < size(self)
Post-condition
post position(self) = position(self)~ + count
and (res = self)

This feature provides the facility to set a new current position of the cursor in the file to be the value given as an offset in storage units (number of octets) from the current position in the file, returning the modified cursor resulting from this.


backward

This feature provides for relative positioning within a file from the current position to a new position count storage units (octets) closer to the beginning of the file.

backward (
count : CARD
) : SAME
Formal Signature
backward(self : SAME, count : CARD) res : SAME
Pre-condition
pre position(self) >= count
Post-condition
post position(self) = position(self)~ - count
and (res = self)

This feature provides the facility to set a new current position of the cursor in the file to be the value given as an offset in storage units (number of octets) towards the beginning of the file from the current position, returning the modified cursor resulting from this.


skip

This feature provides a facility for skipping a given number of stored items (which need not all be of the same storage size). If there are insufficient items remaining in the file then void is returned instead of the modified cursor.

skip (
cnt : CARD
) : SAME
Formal Signature
skip(self : SAME, count : CARD) res : [SAME]
Pre-condition

Since the size of the underlying stored items may be variable, the pre-condition cannot guarantee that there will be no problem; any problem has to be detected dynamically during program execution (see post-condition below).

pre count > 0
Post-condition

If there are insufficient stored items remaining in the file beyond the current position then the return value is nil, otherwise the modified cursor repositioned as requested.

post (res = nil)
or (position(self) > position(self)~)

This feature provides a facility to move forward by a number of stored items in the file rather than in terms of storage units. Only where storage units are identical in storage size to the stored items will this be equivalent to the forward feature above.


flush

This feature ensures that any buffer contents which has not been written to the file has been written, synchronising the program with the file store in the environment.

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

This is vacuously true.

Post-condition

Any output which has been sent to the file since either it was opened or the most recent previous call of this routine, will be forced out to synchronise the environment with the program.

This routine flushes the cursor buffer to the file, ensuring that file and program are synchronised.


error

This predicate may be used to determine whether there has been a problem relating to the file with which this cursor and buffer are associated.

error : BOOL
Formal Signature
error(self : SAME) res : BOOL
Pre-condition

Being a predicate the pre-condition is vacuously true.

Post-condition

Being a predicate the post-condition is also vacuously true.

This feature provides an indication whether some error in the program environment has affected the behaviour of the buffer since either creation or the most recent use of the clear feature defined below.


error_message

This feature provides a program environment dependent string indicating the nature of any error which may have been detected. Note that the message only refers to the latest error (if any) in an environment-defined manner.

error_message : STR
Formal Signature
error_message(self : SAME) res : STR
Pre-condition
pre error(self)
Post-condition
post STR.size(res) > 0

This feature provides an indication whether some error in the program environment has affected the behaviour of the buffer since either creation or the most recent prior use of the clear feature defined below.


clear

This feature clears any error which may have occurred in the underlying file system in relation to the file which is associated with this cursor and buffer.

clear
Formal Signature
clear(self : SAME)
Pre-condition
pre true
Post-condition
post not error(self)

This feature provides a way of clearing any error which may have occurred in relation to the file with which this cursor and buffer are associated.



abstract class $FILE_CURSORS{ETP < $IS_EQ, SEQ < $STRING{ETP}} < $FILE_CURSORS

Inheritance map $IS_EQ $ELT $HASH $STR $STRINGS $STRING{ETP} $FILE_CURSORS

Formal Definitions

This abstract class defines a state component which is a set of all instantiations of objects of any class sub-typing from this class in addition to the vdm model types used wherever this class name is used. Note that SAME has to be an instantiated class, not an abstract one.

The type definitions in this class specification fall into two groups :-

  1. The definition of $FILE_CURSORS{ETP_SEQ itself (including SAME).
  2. Auxiliary vdm types needed to define the Sather type arguments used in the feature definitions which follow.
types

SAME = object_type ;
$FILE_CURSORS_ETP_SEQ = set of object_type ;

-- Auxiliary Types

Element_Type = @ETP ;
String_Type = @SEQ ;

state

multi : $FILE_CURSORS_ETP_SEQ
inv multi_types ==
forall obj in set multi_types & sub_type($FILE_CURSORS_ETP_SEQ,obj)
NOTE See the important note about vdm state in the notes on vdm-sl usage in this specification.

This abstraction models a cursor in a file consisting of a sequence of elements of the first argument type (ETP) which may be composed into strings which are the second argument type(SEQ). It only specifies output operations directly.

plus

This first variant of plus places the value of the single item at the current position in the file buffer.

plus (
item : ETP
)
Formal Signature
plus1(self : SAME, item : Element_Type)
Pre-condition
pre writable(self)
Post-condition

Note the use of the position routine which is inherited from the parent class.

post let head : seq of Element_Type be st len head = position(self) in
let tail : seq of Element_Type be st self~ = head ^ tail in
self = head ^ [item] ^ tail(2, ..., (len tail))
and position(self) = position(self~) + 1

This feature inserts the given item at the current position of the file cursor, oevrwriting any previous item in doing so. The cursor position is advanced by one.


plus

This second variant of plus inserts the given item at the current cursor position and then returns the cursor.

plus (
item : ETP
) : SAME
Formal Signature
plus2(self : SAME, item : Element_Type) res : SAME
Pre-condition
pre writable(self)
Post-condition
post let head : seq of Element_Type be st len head = position(self) in
let tail : seq of Element_Type be st self~ = head ^ tail in
res = head ^ [item] ^ tail(2, ..., (len tail))
and position(self) = position(self~) + 1

This feature inserts the given item at the file position indicated by the cursor, overwriting any previous element at that position in doing so. The cursor position is advanced by one and the cursor object is returned.


plus

This is the first of the two features which are provided to insert a string of data at the current position in the file. The current cursor position is advanced by the length of the string.

plus (
entity : SEQ
)
Formal Signature
plus3(self : SAME, entity : String_Type)
Pre-condition
pre writable(self)
and (String_Type.size(entity) > 0)
Post-condition
post let head : seq of Element_Type be st len head = position(self) in
let tail : seq of Element_Type be st self~ = head ^ tail in
self = head ^ entity ^ tail((len tail - len entity), ..., (len tail))
and position(self) = position(self~) + len entity

This feature inserts the string at the current position in the file buffer, overwriting any previous contents in doing so. The cursor position is moved forward by the length of the string.


plus

This is the second feature provided to insert a string of data in the file at the current cursor position. This version returns the cursor itself.

plus (
entity : SEQ
) : SAME
Formal Signature
plus4(self : SAME, entity : String_Type) res : SAME
Pre-condition
pre writable(self)
and (String_Type.size(entity) > 0)
Post-condition
post let head : seq of Element_Type be st len head = position(self) in
let tail : seq of Element_Type be st self~ = head ^ tail in
res = head ^ entity ^ tail((len tail - len entity), ..., (len tail))
and position(self) = position(self~) + len entity

This feature inserts the contents of the string in the file at the current cursor position, overwriting previous file contents (if any). The cursor position is then moved forward by that number of items. The cursor itself is returned.


Language Index Library Index Input/Output Index
Comments or enquiries should be made to Keith Hopper.
Page last modified: Friday, 17 November 2000.
Produced with Amaya