english
version "1.0"
identify "%Z%%M% %I% %E%"

#: Copyright (c) 1991-2005 by Wayne C. Gramlich.
#, All rights reserved.

module vector

#: This module declares and implements the {vector} abstraction.  The
#, {vector} abstraction is a variable length array of elements whose
#, first element is indexed by 0.

define vector[item]
    external


procedure address_get@vector[item]
    takes
	vector vector[item]
    returns address
    external vector__address_get



procedure allocate@vector[item]
    takes_nothing
    returns vector[item]
    external vector__allocate

    #: This procedure will create and return a new {vector[item]}.



procedure append@vector[item]
    takes
	vector vector[item]
	item item
    returns_nothing
    external vector__append



procedure buffer_append@vector[item]
    takes
	vector vector[item]
	buffer string
    returns_nothing
    needs
	procedure buffer_append@item
	    takes item, string
	    returns_nothing

    #: This procedure will iterate across the items in {vector}
    #, invoking {buffer_append}.


procedure compare@vector[item]
    takes
	vector1 vector[item]
	vector2 vector[item]
    returns integer
    needs
	procedure compare@item
	    takes item, item
	    returns integer
    #: This procedure will compare {vector1} to {vector2} and return
    #, -1, 0, or 1 depending upon whether {vector1} is less than, equal to,
    #, or greater than {vector2} respectively.  Elements of {vector1} and
    #, {vector2} are compared pairwaise using {compare}@{item}() until
    #, a difference is encountered.  0 is only returned if all items
    #, are pairwise equal and both vectors have the same length.


procedure copy@vector[item]
    takes
	vector vector[item]
    returns vector[item]
    needs
	procedure copy@item
	    takes item
	    returns item

    #: This procedure will create and return a copy of {vector}.


procedure copy_shallow@vector[item]
    takes
	vector vector[item]
    returns vector[item]

    #: This procedure will create and return a shallow copy of
    #, {vector}.


procedure delete@vector[item]
    takes
	vector vector[item]
	index unsigned
    returns_nothing

    #: This procedure will delete the {index}'th itme from {vector}.


procedure delete_range@vector[item]
    takes
	vector vector[item]
	index unsigned
	count unsigned
    returns_nothing

    #: This procedure will delete the {index}'th through {index}+{count}-1'th
    #, items from {vector}.


procedure equal@vector[item]
    takes
	vector1 vector[item]
	vector2 vector[item]
    returns logical
    needs
	procedure equal@item
	    takes item, item
	    returns logical

    #: This procedure will return {true} if each item in {vector1] is
    #, equal to the corresponding item in {vector2}.


procedure hash@vector[item]
    takes
	vector vector[item]
    returns unsigned
    needs
	procedure hash@item
	    takes item
	    returns unsigned

    #: This procedure will return {true} if each item in {vector1] is
    #, equal to the corresponding item in {vector2}.


procedure identical@vector[item]
    takes
	vector1 vector[item]
	vector2 vector[item]
    returns logical

    #: This procedure will return {true} if {vector1} and {vector2} are
    #, exactly the same object and {false} otherwise.


procedure insert@vector[item]
    takes
	vector vector[item]
	index unsigned
	item item
    returns_nothing

    #: This procedure will insert {item} into {vector} at {index} moving
    #, all other items from {index} on up by one.


procedure xxxx_insert@vector[item]
    takes
	vector vector[item]
	index unsigned
	item item
    returns_nothing

    #: For debugging!!!


procedure fetch1@vector[item]
    takes
	vector vector[item]
	index unsigned
    returns item
    external vector__fetch1

    #: This procedure will return the {index}'th item from {vector}.



procedure format@vector[item]
    takes
	vector vector[item]
	out_stream out_stream
	format string
	offset unsigned
    returns_nothing
    needs
	procedure format@item
	    takes item, out_stream, string, unsigned
	    returns_nothing
	procedure print@item
	    takes item, out_stream
	    returns_nothing

    #: This procedure will output {vector} to {out_stream}.


procedure is_empty@vector[item]
    takes
	vector vector[item]
    returns logical

    #: This procedure will return {true} if {vector} is empty and {false}
    #, otherwise.


procedure limit_get@vector[item]
    takes
	vector vector[item]
    returns unsigned
    external vector__limit_get

    #: This procedure will return the limit of {vector}.  This is
    #, really just for development purposes.  Nobody should really
    #, ever care what the current limit is.



procedure lop@vector[item]
    takes
	vector vector[item]
    returns item

    #: This procedure will return the first item from the end of {vector}.


procedure pop@vector[item]
    takes
	vector vector[item]
    returns item

    #: This procedure will return remove the last item from the end of
    #, {vector} and return it.  A fatal error occurs if {vector} is empty.


procedure predict@vector[item]
    takes
	vector vector[item]
	size unsigned
    returns_nothing
    external vector__predict

    #: This procedure will ensure that {vector} can take up {size} elements
    #, without being resized.



procedure prepend@vector[item]
    takes
	vector vector[item]
	item item
    returns_nothing

    #: This procedure will prepend {item} to the begining of {vector{.


procedure print@vector[item]
    takes
	vector vector[item]
	out_stream out_stream 
    returns_nothing
    needs
	procedure print@item
	    takes item, out_stream
	    returns_nothing

    #: This procedure will print out each item in {vector} to {out_stream}.


procedure put@vector[item]
    takes
	vector vector[item]
	out_stream out_stream
    returns_nothing
    needs
	procedure put@item
	    takes item, out_stream
	    returns_nothing

    #: This procedure will output each item in {vector} to {out_stream}
    #, using {put}@{item}() to output each item.


procedure range_append@vector[item]
    takes
	to_vector vector[item]
	from_vector vector[item]
	start_index unsigned
	count unsigned
    returns_nothing

    #: This procedure will append {count} items from {from_vector} starting
    #, at {start_index} to the end of {to_vector}.


procedure read@vector[item]
    takes
	in_stream in_stream
    returns vector[item]
    needs
	procedure read@item
	    takes in_stream
	    returns item
    #: This procedure will read in a vector of {item} from {in_stream}
    #, and return it.


procedure save@vector[item]
    takes
	vector vector[item]
	save save
	offset unsigned
    returns_nothing
    needs
	procedure save@item
	    takes item, save, unsigned
	    returns_nothing

    #: This procedure will cause {vector} to be saved into {save} at
    #, {offset}.


procedure shallow_copy@vector[item]
    takes
	vector vector[item]
    returns vector[item]

    #: This procedure will create and return a shallow copy of {vector}.


procedure size_get@vector[item]
    takes
	vector vector[item]
    returns unsigned
    external vector__size_get

    #: This procedure will return the size of {vector}.



procedure store1@vector[item]
    takes
	vector vector[item]
	index unsigned
	item item
    returns_nothing
    external vector__store1

    #: This procedure will store {item} into {vector} at {index}.



procedure sort@vector[item]
    takes
	vector vector[item]
    returns_nothing
    needs
	procedure compare@item
	    takes item, item
	    returns integer

    #: This procedure will sort the items in {vector} in asscending
    #, order.


procedure transfer@vector[item]
    takes
	to_vector vector[item]
	to_index unsigned
	from_vector vector[item]
	from_index unsigned
	length unsigned
	fill_item item
    returns_nothing
    external vector__transfer

    #: This procedure will transfer {length} items from {from_vector}
    #, starting at {from_index} into {to_vector} starting at {to_index}.
    #, Overlapping transfers from the same {vector} are permitted.
    #, Also, {to_vector} will be extended as necessary to accept
    #, the transfer.



procedure truncate@vector[item]
    takes
	vector vector[item]
	size unsigned
    returns_nothing
    external vector__trim

    #: This procedure will truncate {vector} to have no more that
    #, {size} items.



procedure unique@vector[item]
    takes
	vector vector[item]
    returns_nothing
    needs
	procedure equal@item
	    takes item, item
	    returns logical

    #: This procedure will take a presorted vector and remove duplicate
    #, entries.


procedure vector_append@vector[item]
    takes
	to_vector vector[item]
	from_vector vector[item]
    returns_nothing

    #: This procedure will append all of the items in {from_vector} to the end
    #, of {to_vector}.


procedure write@vector[item]
    takes
	vector vector[item]
	out_stream out_stream
    returns_nothing
    needs
	procedure write@item
	    takes item, out_stream
	    returns_nothing
    #: This procedure will write {vector} to {out_stream}.