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

#: Copyright (c) 1995, 1997, 2003 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 utility

#: This module implements some utility procedures.


#: Some {character} procedures:

procedure read@character
    takes
	in_stream in_stream
    returns character

    #: This procedure will read in and return a character from {in_stream}.


procedure write@character
    takes
	character character
	out_stream out_stream
    returns_nothing

    #: This procedure write {character} to {out_stream}.


#: Some {in_stream} procedures:

procedure number_input@in_stream
    takes
	in_stream in_stream
	line string
	error_stream out_stream
    returns unsigned

    #: This procedure will read a line in from {in_stream}, parse it as
    #, a decimal number and return the result.  {line} is used a temporary
    #, buffer.  If the line read does not contain a number, a fatal assertion
    #, will occur.


#: Some {logical} procedures:

procedure copy@logical
    takes
	logical logical
    returns logical

    #: This procedure will return a copy of {logical}.


#: Some {string} procedures:

procedure xread@string
    takes
	in_stream in_stream
    returns string

    #: This procedure will read in a {string} from {in_stream}.


procedure xwrite@string
    takes
	string string
	out_stream out_stream
    returns_nothing

    #: This procedure will write {string} to {out_stream}.


#: Some {unsigned} helper routines:

procedure xread@unsigned
    takes
	in_stream in_stream
    returns unsigned

    #: This procedure will read in an {unsigned} value from {in_stream}.


procedure has_suffix@string
    takes
	string string
	suffix string
    returns logical

    #: This procedure will return {true} if {suffix} exactly matches
    #, the last characters in {string}.


procedure xwrite@unsigned
    takes
	value unsigned
	out_stream out_stream
    returns_nothing

    #: This procedure will write {value} to {out_stream}.