english
version "1.0"
identify "xyz"

#: Copyright (c) 1997, 2000, 2002 by Wayne C. Gramlich.
#, All rights reserved.
#, 
#, Permission to use, copy, modify, distribute, and sell this software
#, for any purpose is hereby granted without fee provided that the above
#, copyright notice and this permission are retained.  The author makes
#, no representations about the suitability of this software for any purpose.
#, It is provided "as is" without express or implied warranty.

module memory

#: This module implements a bounds protected memory module.

define memory
    external


procedure address_get@memory
    takes
	memory memory
    returns address
    external memory__address_get

    #: This procedure will return the address associated with {memory}.
    #, Please note, this is the address associated with the {memory}
    #, object, not the memory buffer pointed to by {memory}.



procedure buffer_address_get@memory
    takes
	memory memory
    returns address
    external memory__buffer_address_get

    #: This procedure will return the buffer address associated with
    #, {memory}.  The buffer address can change as a result of the
    #, {resize}@{memory}() operation.



procedure byte_add@memory
    takes
	to_memory memory
	to_offset unsigned
	from_memory memory
	from_offset unsigned
	byte unsigned
	length unsigned
    returns_nothing

    #: This procedure will perform a add {byte} to the {length} bytes
    #, in {from_memory} starting at {from_offset} and store the result
    #, in {to_memory} starting at {to_offset}.  {to_memory} and
    #, {from_memory} can point to the same {memory} object, but the
    #, regions must either exactly overlap or be totally non-overlapping.
    #, The semantics of partial overlappiny memory regions are undefined.


procedure byte_and@memory
    takes
	to_memory memory
	to_offset unsigned
	from_memory memory
	from_offset unsigned
	byte unsigned
	length unsigned
    returns_nothing

    #: This procedure will perform a bitwise AND of {byte} with the {length}
    #, bytes in {from_memory} starting at {from_offset} and store the
    #, result in {to_memory} starting at {to_offset}.  {to_memory} and
    #, {from_memory} can point at the same {memory} object, but the
    #, regions must either exactly overlap or be totally non-overlapping.
    #, The semantics of partial overlapping memory regions are undefined.


procedure byte_equal@memory
    takes
	memory memory
	offset unsigned
	byte unsigned
	length unsigned
    returns logical

    #: This procedure will return {true}@{logical} if the {length} bytes
    #, in {memory} starting at {offset} are equal to {byte} and {false}
    #, otherwise.


procedure byte_multiply@memory
    takes
	from_memory memory
	from_offset unsigned
	to_memory memory
	to_offset unsigned
	byte unsigned
	length unsigned
    returns_nothing

    #: This procedure will multiply {byte} times each byte in the {length}
    #, bytes in {from_memory} starting at {from_offset} and store the result
    #, in {to_memory} starting at {to_offset}.  {to_memory} and {from_memory}
    #, can point the same {memory} object, but the regions must either
    #, exactly overlap or be totally non-overlapping.  The semantics of
    #, partial overlapping memory regions are undefined.


procedure byte_or@memory
    takes
	to_memory memory
	to_offset unsigned
	from_memory memory
	from_offset unsigned
	byte unsigned
	length unsigned
    returns_nothing

    #: This procedure will perform a bitwise OR of {byte} with the {length}
    #, bytes in {from_memory} starting at {from_offset} and store the result
    #, in {to_memory} starting at {to_offset}.  {to_memory} and {from_memory}
    #, can point to the same {memory} object, but the regions must either
    #, exactly overlap or be totally non-overlapping.  The semantics of
    #, partial overlapping memory regions are undefined.


procedure byte_search@memory
    takes
	memory memory
	offset unsigned
	byte unsigned
	length unsigned
    returns unsigned

    #: This procedure will search the {length} bytes of {memory} starting at
    #, {offset} for a byte that equals {byte}.  If a matching byte is found,
    #, the index of the matching byte is returned; otherwise, {memory}.{size}
    #, is returned.


procedure byte_subtract@memory
    takes
	to_memory memory
	to_offset unsigned
	from_memory memory
	from_offset unsigned
	byte unsigned
	length unsigned
    returns_nothing

    #: This procedure will subtract {byte} from the {length} bytes in
    #, {from_memory} starting at {from_offset} and store the result in
    #, {to_memory} starting at {to_offset}.  {to_memory} and {from_memory}
    #, can point to the same {memory} object, but the regions must either
    #, exactly overlap, or be totally non-overlapping.  The semantics of
    #, partial overlapping memory regions are undefined.


procedure byte_xor@memory
    takes
	to_memory memory
	to_offset unsigned
	from_memory memory
	from_offset unsigned
	byte unsigned
	length unsigned
    returns_nothing

    #: This procedure will perform a bitwis XOR of {byte} with the {length}
    #, bytes in {from_memory} starting at {from_offset} and store the result
    #, in {to_memory} starting at {to_offset}.  {to_memory} and {from_memory}
    #, can point to the same {memory} object, but the regions must either
    #, exactly overlap, or be totally non-overlapping.  The semantics of
    #, partial overlapping memory regions are undefined.


procedure clear@memory
    takes
	memory memory
    returns_nothing

    #: This procuedure will set every byte in {memory} to zero.


procedure copy@memory
    takes
	memory memory
    returns memory

    #: This procedure will return a byte wise copy of {memory}.


procedure create@memory
    takes
	size unsigned
    returns memory
    external memory__create

    #: This procedure will return a chunk of memory that contains
    #, {size} bytes of memory.  The mode of the returned memory is
    #, {read_write}.



procedure equal@memory
    takes
	memory1 memory
	memory2 memory
    returns logical

    #: This procedure will return {true} if the entire contents of
    #, {memory1} is equal to the contents of {memory2} and {false}
    #, otherwise.


procedure fetch1@memory
    takes
	memory memory
	index unsigned
    returns unsigned
    external memory__fetch1

    #: This procedure will fetch and return the byte value at the
    #, {index}'th location in {memory}.



procedure identical@memory
    takes
	memory1 memory
	memory2 memory
    returns logical

    #: This procedure will return {true} if {memory1} is identical to
    #, {memory2} and {false} otherwise.


procedure integer_word_fetch@memory
    takes
	memory memory
	word_index unsigned
    returns integer
    external memory__integer_word_fetch

    #: This procedure will return the 4-byte signed integer from {memory}
    #, starting at {word_index}.  The word is fetched from the memory
    #, location in the "natural" byte order for the machine.



procedure integer_word_store@memory
    takes
	memory memory
	word_index unsigned
	value unsigned
    returns_nothing
    external memory__integer_word_store

    #: This procedure will store {value} into {memory} at {word_index}
    #, as a 4-byte signed integer.  The word is fetched from the memory
    #, location in the "natural" byte order for the machine.



procedure limit_get@memory
    takes
	memory memory
    returns unsigned
    external memory__limit_get

    #: This procedure will fetch and return the maximum size that
    #, {memory} can get in bytes before it must be reallocated.



procedure print@memory
    takes
	memory memory
	out_stream out_stream
    returns_nothing

    #: This procedure will print out the contents of {memory} to {out_stream}.


procedure region_and@memory
    takes
	memory1 memory
	offset1 unsigned
	memory2 memory
	offset2 unsigned
	memory3 memory
	offset3 unsigned
	length unsigned
    returns_nothing

    #: This procedure will AND the {length} btyes from {memory1} starting
    #, at {offset1} with the bits from {memory2} starting at {offset2}
    #, and store the result into {memory3} starting at {offset3}.
    #, This operation does allow {memory1}, {memory2} and {memory3} to
    #, point to the exact same {memory} object, but only if the corresponding
    #, offsets are either equal or totally non-overlapping.


procedure region_equal@memory
    takes
	memory1 memory
	offset1 unsigned
	memory2 memory
	offset2 unsigned
	length unsigned
    returns logical

    #: This procedure will return {true} if the {length} bytes from
    #, {memory1} starting at {offset1} are equal to the {length} bytes
    #, of {memory2} starting at {offset2}.


procedure region_not@memory
    takes
	memory1 memory
	offset1 unsigned
	memory2 memory
	offset2 unsigned
	length unsigned
    returns_nothing

    #: This procedure will complement the {length} btyes from {memory1}
    #, starting at {offset1} and store the result into {memory2} starting
    #, at {offset3}.  This operation does allow {memory1} and {memory2}
    #, to point to the exact same {memory} object, but only if the
    #, corresponding offsets are either equal or totally non-overlapping.


procedure region_or@memory
    takes
	memory1 memory
	offset1 unsigned
	memory2 memory
	offset2 unsigned
	memory3 memory
	offset3 unsigned
	length unsigned
    returns_nothing

    #: This procedure will OR the {length} btyes from {memory1} starting
    #, at {offset1} with the bits from {memory2} starting at {offset2}
    #, and store the result into {memory3} starting at {offset3}.
    #, This operation does allow {memory1}, {memory2} and {memory3} to
    #, point to the exact same {memory} object, but only if the corresponding
    #, offsets are either equal or totally non-overlapping.


procedure region_search@memory
    takes
	search_memory memory
	search_offset unsigned
	search_length unsigned
	pattern_memory memory
	pattern_offset unsigned
	pattern_length unsigned
    returns unsigned

    #: This procedure will search forward through {search_memory} starting
    #, at {search_offset} for {search_length} bytes for an exact match
    #, with the {pattern_length} bytes in {pattern_memory} starting at
    #, {pattern_offset}.  If a match is found, the index of the first
    #, matching region is returned; otherwise, if no match is found,
    #, {search_memory}.{size} is returned. 


procedure region_set@memory
    takes
	memory memory
	offset unsigned
	length unsigned
	value unsigned
    returns_nothing

    #: This procedure will set the {length} bytes of {memory} starting at
    #, {offset} to {value}.


procedure region_xor@memory
    takes
	memory1 memory
	offset1 unsigned
	memory2 memory
	offset2 unsigned
	memory3 memory
	offset3 unsigned
	length unsigned
    returns_nothing

    #: This procedure will XOR the {length} btyes from {memory1} starting
    #, at {offset1} with the bits from {memory2} starting at {offset2}
    #, and store the result into {memory3} starting at {offset3}.
    #, This operation does allow {memory1}, {memory2} and {memory3} to
    #, point to the exact same {memory} object, but only if the corresponding
    #, offsets are either equal or totally non-overlapping.


procedure resize@memory
    takes
	memory memory
	new_size unsigned
    returns_nothing
    external memory__resize

    #: This procedure ensure that there are {new_size} bytes of
    #, memory in {memory}.



procedure size_get@memory
    takes
	memory memory
    returns unsigned
    external memory__size_get

    #: This procudure will the number of bytes associated with {memory}.



procedure store1@memory
    takes
	memory memory
	index unsigned
	value unsigned
    returns_nothing
    external memory__store1

    #: This procedure will store {value} into the {index}'th location
    #, in {memory}.



procedure string_copy_from@memory
    takes
	to_memory memory
	to_offset unsigned
	from_string string
	from_offset unsigned
	amount unsigned
    returns_nothing

    #: This procedure will transfer {amount} characters from {from_string}
    #, starting at {from_offset} into {to_memory} starting at {to_offset}.
    #, Each characters in {from_string} must be representable as an 8-bit
    #, byte.  This operation will fail if any attempt is made to access
    #, beyond the upper limit of either {from_string} or {to_memory}.


procedure transfer@memory
    takes
	from_memory memory
	from_offset unsigned
	to_memory memory
	to_offset unsigned
	length unsigned
    returns_nothing

    #: This procedure will transfer {length} bytes of memory from
    #, {from_memory} at {from_offset} to {to_memory} at {to_offset}.
    #, {from_memory} and {to_memory} are permitted to reference the
    #, same {memory} object.


procedure unsigned_word_fetch@memory
    takes
	memory memory
	word_index unsigned
    returns unsigned
    external memory__unsigned_word_fetch

    #: This procedure will return the 4-byte unsigned word from {memory}
    #, starting {word_index}.  The word is fetched from the memory
    #, location in the "natural" byte order for the machine.



procedure unsigned_word_store@memory
    takes
	memory memory
	word_index unsigned
	value unsigned
    returns_nothing
    external memory__unsigned_word_store

    #: This procedure will store {value} into {memory} at {word_index}
    #, as a the 4-byte unsigned word.  The word is fetched from the memory
    #, location in the "natural" byte order for the machine.