| # Section 8.16.1.7: $CURSOR |

###### abstract class $CURSOR{ELT < $IS_EQ, STP < $STRING{ELT}}

#### 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 ;
$CURSOR_ELT_STP = set of object_type
state
multi : $CURSOR_ELT_STP
inv multi_types ==
forall obj in set multi_types & sub_type($CURSOR_ELT_STP,obj)

NOTE | See the important note about vdm state in the notes on vdm-sl usage in this specification.

This abstract class defines the features of generic cursor scanning objects of all string/stream kinds.

The purpose of the cursor class is to provide facilities to extract or pass over subsequences of a string (which are also called sequences or streams). This permits perfectly general scanning which depends only on the content of the string, not its meaning. Since the associated string is not consumed by scanning, it is possible to perform test on contents/structure in order to 'synchronise' the program with the data content.

#### advance

This feature is provided so that any single string element may be passed over during scanning - for example after testing for validity/presence.

advance |

##### Formal Signature

advance(self : SAME)

##### Pre-condition

pre not has_error(self)

##### Post-condition

post has_error(self)
or remaining = remaining~ -1

This feature advances the cursor to the next string element. If the cursor had already reached the end then has_error will return true.

#### advance

This feature is provided so that any single string element may be passed over during scanning - for example after testing for validity/presence. This differs from the avove feature since it also returns the cursor object itself.

advance | : SAME

##### Formal Signature

advance(self : SAME) res : SAME

##### Pre-condition

pre not has_error(self)

##### Post-condition

post has_error(self)
or remaining = remaining~ -1

This feature advances the cursor to the next string element. If the cursor had already reached the end then has_error will return true. The updated version of self is returned.

retract ; -- This routine retracts the cursor to point to the previous string -- element. It is an error if the current value of the cursor indicated the -- beginning of the string before this routine was called.
retract : SAME ; -- This routine retracts the cursor to point to the previous string -- element. It is an error if the current value of the cursor indicated the -- beginning of the string before this routine was called. It then returns -- the updated value of the cursor.
item : ELT ; -- This routine returns the string element indicated by the current -- value of the cursor -- or void if an error condition exists. It does -- NOT advance the cursor.
reassign( str : STP ) ; -- This routine changes the string to which this cursor is pointing, -- so that the current element is the first. Any error condition is -- cleared.
clear ; -- This routine resets the cursor to be indicating an empty string -- and clears any error condition.
set_index( new_posn : CARD ) ; -- This routine resets the index position to new_posn, provided that -- that is a valid index for the buffer, then clears any end of buffer -- condition.
set_skip( val : ELT ) ; -- This routine sets the value of the element used in all skipping -- operations - until this is next set. The default value depends on -- the element class.
set_skip( val : ELT ) : SAME ; -- This routine sets the value of the element used in all skipping -- operations - until this is next set. It then returns self.
-- The following operations all skip various parts of the string. -- It is not an error if such skipping reaches the end of the -- string.
skip_over ; -- This routine advances the cursor until the current element is -- different from the currently set skip element value.
skip_over : SAME ; -- This routine advances the cursor until the current element is -- different from the currently set skip element value. It then returns self.
skip_to ; -- This routine advances the cursor until the current element is equal -- to the currently set skip element value.
skip_to : SAME ; -- This routine advances the cursor until the current element is equal -- to the currently set skip element value. It then returns self.
skip_to( elem : ELT ) ; -- This routine sets elem to be the currently set skip element value -- and then advances the cursor until the current element is equal -- to that value - then restoring the currently set skip element value -- to its former value.
skip_to( elem : ELT ) : SAME ; -- This routine sets elem to be the currently set skip element value -- and then advances the cursor until the current element is equal -- to that value - then restoring the currently set skip element value -- to its former value. It then returns self.
skip_block( start_delimiter, finish_delimiter : ELT ) ; -- Providing that the current string element is start_delimiter, this -- routine skips further string elements up to and including the matching -- occurrence of finish_delimiter. It is an ERROR if the start delimiter -- is found but not the finishing one.
is_value( val : ELT ) : BOOL ; -- This routine returns true if and only if the current string element -- has the value val, otherwise false.
remaining : CARD ; -- This routine returns the number of items yet to be scanned in -- the buffer.
get_item : ELT ; -- This routine returns the currently indicated item and advances -- the cursor value by one. Note that it is not an error condition if -- the cursor cannot be advanced as the current cursor value indicates -- the last element in the string.
get_upto : STP ; -- This routine scans the string from the current element, skipping -- until a value which is not the current value of skip_val is found, then -- up to the next occurrence of the current value of the skip_val, -- returning the string scanned NOT including the skip element found. -- It is NOT an error if the skip element is not detected before the end of -- the string.
get_upto( count : CARD ) : STP ; -- This routine returns the string starting at the current element -- until either the given count is reached or the end of the string, -- whichever occurs first.
get_upto( elem : ELT ) : STP ; -- This routine returns the string starting at the current element -- until either the element with the value elem is reached or the end of -- the string, whichever occurs first. It is an error if elem is not -- detected before the end of the string.
get_remainder : STP ; -- This routine returns the remainder of the string from the current -- element.
get_rest_upto( elem : ELT ) : STP ; -- This routine returns the string starting at the current element -- until either the element with the value elem is reached or the end of -- the string, whichever occurs first. It is NOT an error if elem is not -- detected before the end of the string.
get_block( start_delimiter, finish_delimiter : ELT ) : STP ; -- Providing that the current string element is start_delimiter, this -- routine returns further string elements up to and including the first -- occurrence of finish_delimiter, otherwise void. It is an error if, -- having detected the start_delimiter value, finish_delimiter is not -- detected before the end of the string.
-- The final group of items is concerned with error indications. error : CURSOR_ERRORS ; -- This is a value associated with the string cursor indicating what, -- if any error has occurred and not been cleared.
clear_error ; -- This routine resets the error value to 'No Error'.
has_error : BOOL ; -- This routine returns true if and only if the cursor has encountered -- an error which has not been cleared.

| Language Index |  | Library Index |  | String Index

Comments or enquiries should be made to Keith Hopper. Page last modified: Thursday, 20 July 2000. |