english
version "1.0"
identify "xyz"

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

module character

#: The character module implements an 8/16/32-bit character object with
#, associated operations.

define character
    external

define character_data
    record
	buffer string
	initialized logical
    generate allocate, erase, print

object first@character

object last@character



procedure buffer_append@character
    takes
	character character
	buffer string
    returns_nothing

    #: This procedure will append {character} to {buffer}.  It has
    #, the same functionality as {character_append}@{string} only
    #, with the arguments transposed.


procedure compare@character
    takes
	character1 character
	character2 character
    returns integer

    #: This procedure will return -1, 0, or 1 depending upon whether
    #, {character1} is less than, equal to, or greater than {character2}.


procedure decimal_convert@character
    takes
	character character
    returns unsigned

    #: This procedure takes {character} which is assumed to be a character
    #, between `0' and `9', and converts it to a number between 0 and 9.


procedure equal@character
    takes
	character1 character
	character2 character
    returns logical
    external character__equal

    #: This procedure will return {true} if {character1} is equal to
    #, {character2} and {false} otherwise.



procedure format@character
    takes
	character character
	out_stream out_stream
	format string
	offset unsigned
    returns_nothing

    #: This routine will output {character} to {out_stream} using the
    #, formatting characters in {format} starting at {offset} until a
    #, terminating "%" is  encountered.  See the {format} module find
    #, out more about formatted output.
    #,
    #, The accepted formats are:
    #,	 b	Enclose a character in balanced single quotes (i.e. `...')
    #,   c	Center the character
    #,	 C	Output a C-style character.
    #,	 d	Enclose the character in double quotes.
    #,   l	Left justify the string.
    #,   p<pad>	Set padding character to <pad>.
    #,	 q	Enclose the string in single quotes.
    #,	 s	Output a raw string.
    #,	 S	Output a STIPPLE-style string.
    #,   w<width> Output a minimim of <width> characters.


procedure greater_than@character
    takes
	character1 character
	character2 character
    returns logical
    external character__greater_than

    #: This procedure will return {true} if {character1} is lexically
    #, greater than {character2} and {false} otherwise.



procedure hash@character
    takes
	character character
    returns unsigned
    external character__hash

    #: This procedure will return a hash value based on {character}.



procedure hexadecimal_convert@character
    takes
	character character
    returns unsigned

    #: This procedure takes {character} which is assumed to be a character
    #, between `0' and `9' or `A' and `F' or `a' and `f',  and converts it
    #, to a number between 0 and 15.


procedure is_alpha_numeric@character
    takes
	character character
    returns logical
    external character__is_alpha_numeric

    #: This procedure will return {true} if {character} is an alpha-numeric
    #, character and {false} otherwise.



procedure is_digit@character
    takes
	character character
    returns logical
    external character__is_digit

    #: This procedure will return {true} if {character} is a decimal digit and
    #, {false} otherwise.



procedure is_letter@character
    takes
	character character
    returns logical
    external character__is_letter

    #: This procedure will return {true} if {character} is a letter and
    #, {false} otherwise.



procedure is_hex_digit@character
    takes
	character character
    returns logical
    external character__is_hex_digit

    #: This procedure will return {true} if {character} is a hexadecimal
    #, digit and {false} otherwise.



procedure is_lower_case@character
    takes
	character character
    returns logical
    external character__is_lower_case

    #: This procedure will return {true} if {character} is a lower case
    #, letter and {false} otherwise.



procedure is_octal_digit@character
    takes
	character character
    returns logical
    external character__is_octal_digit

    #: This procedure will return {true} if {character} is an octal digit and
    #, {false} otherwise.



procedure is_white_space@character
    takes
	character character
    returns logical
    external character__is_white_space

    #: This procedure will return {true} if {character} is white space
    #, character (i.e. space, tab, carriage-return, new-line, vertical-tab,
    #, or form-feed) and {false} otherwise.



procedure is_printing@character
    takes
	character character
    returns logical
    external character__printing_case

    #: This procedure will return {true} if {character} is a printing
    #, character and {false} otherwise.



procedure is_upper_case@character
    takes
	character character
    returns logical
    external character__is_upper_case

    #: This procedure will return {true} if {character} is an upper case
    #, letter and {false} otherwise.



procedure is_vowel@character
    takes
	character character
    returns logical

    #: This procedure will return {true} if {character} is either an
    #, upper case ("AEIOU") or lower case vowel ("aeiou").


procedure less_than@character
    takes
	character1 character
	character2 character
    returns logical
    external character__less_than

    #: This procedure will return {true} if {character1} is lexically less
    #, than {character2} and {false} otherwise.



procedure lower_case_convert@character
    takes
	character character
    returns character
    external character__lower_case_convert

    #: This procedure will convert {character} to a lower case character
    #, and return it.



procedure print@character
    takes
	character character
	out_stream out_stream
    returns_nothing

    #: This procedure will output {character} to {out_stream} as a printable
    #, character.


procedure put@character
    takes
	character character
	out_stream out_stream
    returns_nothing

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


procedure string_printing_convert@character
    takes
	character character
    returns string
    external character__string_printing_convert

    #: This procedure will convert {character} into a permanent read only
    #, string that is human readable.



procedure integer_convert@character
    takes
	character character
    returns integer
    external character__integer_convert

    #: This procedure will convert {character} into an signed integer
    #, and return the result.



procedure unsigned_convert@character
    takes
	character character
    returns unsigned
    external character__unsigned_convert

    #: This procedure will convert {character} into an unsigned integer
    #, and return the result.



procedure upper_case_convert@character
    takes
	character character
    returns character
    external character__upper_case_convert

    #: This procedure will convert {character} to an upper case character
    #, and return it.