indexing
	description: "String formatters"
	library: "Gobo Eiffel Utility Library"
	author: "Eric Bezault <ericb@gobo.demon.co.uk>"
	copyright: "Copyright (c) 1997, Eric Bezault"

class interface
	UT_STRING_FORMATTER

feature -- Access

	array_formatter_: UT_ARRAY_FORMATTER
			-- Formatting routines that ought
			-- to be in class ARRAY
			-- (from UT_IMPORTED_FORMATTERS)
		ensure -- from UT_IMPORTED_FORMATTERS
			array_formatter_not_void: Result /= void

	character_formatter_: UT_CHARACTER_FORMATTER
			-- Formatting routines that ought
			-- to be in class CHARACTER
			-- (from UT_IMPORTED_FORMATTERS)
		ensure -- from UT_IMPORTED_FORMATTERS
			character_formatter_not_void: Result /= void

	eiffel_string_out (a_string: STRING): STRING
			-- Formatted version of a_string, where all
			-- non-printable characters are replaced by their
			-- escaped character sequence as described in
			-- ETL, section 25.15, page 422;
			-- Return a new string at each call.
			-- Regexp: ([ !#$&(-~]|%[BFNRTU%'"]|%/[0-9]+/)*
		require
			a_string_not_void: a_string /= void
		ensure
			eiffel_string_out_not_void: Result /= void

	integer_formatter_: UT_INTEGER_FORMATTER
			-- Formatting routines that ought
			-- to be in class INTEGER
			-- (from UT_IMPORTED_FORMATTERS)
		ensure -- from UT_IMPORTED_FORMATTERS
			integer_formatter_not_void: Result /= void

	left_padded_string_out (a_string: STRING; a_length: INTEGER; c: CHARACTER): STRING
			-- Clone of a_string, padded on the left with
			-- c characters if a_string is less than
			-- a_length character long;
			-- Return a new string at each call.
			-- Regexp: c{(a_length-a_string.count).max (0)}a_string
		require
			a_string_not_void: a_string /= void;
			a_length_positive: a_length >= 0
		ensure
			left_padded_string_out_not_void: Result /= void

	output_stream_: KL_OUTPUT_STREAM_ROUTINES
			-- Routines that ought to be in class OUTPUT_STREAM
			-- (from KL_IMPORTED_OUTPUT_STREAM_ROUTINES)
		ensure -- from KL_IMPORTED_OUTPUT_STREAM_ROUTINES
			output_stream_routines_not_void: Result /= void

	quoted_eiffel_string_out (a_string: STRING): STRING
			-- Formatted version of a_string, surrounded
			-- by double quotes, where all non-printable
			-- characters are replaced by their escaped
			-- character sequence as described in ETL,
			-- section 25.15, page 422;
			-- Return a new string at each call.
			-- Regexp: \"([ !#$&(-~]|%[BFNRTU%'"]|%/[0-9]+/)*\"
		require
			a_string_not_void: a_string /= void
		ensure
			quoted_eiffel_string_out_not_void: Result /= void

	string_: KL_STRING_ROUTINES
			-- Routines that ought to be in class STRING
			-- (from KL_IMPORTED_STRING_ROUTINES)
		ensure -- from KL_IMPORTED_STRING_ROUTINES
			string_routines_not_void: Result /= void

	string_formatter_: UT_STRING_FORMATTER
			-- Formatting routines that ought
			-- to be in class STRING
			-- (from UT_IMPORTED_FORMATTERS)
		ensure -- from UT_IMPORTED_FORMATTERS
			string_formatter_not_void: Result /= void
	
feature -- File handling

	put_eiffel_string (a_file: like output_stream_type; a_string: STRING)
			-- Write a_string to a_file, where all
			-- non-printable characters are replaced by their
			-- escaped character sequence as described in
			-- ETL, section 25.15, page 422.
		require
			a_file_not_void: a_file /= void;
			a_file_is_open_write: output_stream_.is_open_write (a_file);
			a_string_not_void: a_string /= void

	put_left_padded_string (a_file: like output_stream_type; a_string: STRING; a_length: INTEGER; c: CHARACTER)
			-- Write a_string to a_file, padded on the
			-- left with c characters if a_string is less
			-- than a_length character long.
		require
			a_file_not_void: a_file /= void;
			a_file_is_open_write: output_stream_.is_open_write (a_file);
			a_string_not_void: a_string /= void;
			a_length_positive: a_length >= 0

	put_quoted_eiffel_string (a_file: like output_stream_type; a_string: STRING)
			-- Write a_string, surrounded by double quotes, to
			-- a_file, where all non-printable characters are
			-- replaced by their escaped character sequence as
			-- described in ETL, section 25.15, page 422.
		require
			a_file_not_void: a_file /= void;
			a_file_is_open_write: output_stream_.is_open_write (a_file);
			a_string_not_void: a_string /= void
	
feature -- String handling

	append_eiffel_string (a_target: STRING; a_string: STRING)
			-- Append a_string to a_target, where all
			-- non-printable characters are replaced by their
			-- escaped character sequence as described in
			-- ETL, section 25.15, page 422.
		require
			a_target_not_void: a_target /= void;
			a_string_not_void: a_string /= void

	append_left_padded_string (a_target: STRING; a_string: STRING; a_length: INTEGER; c: CHARACTER)
			-- Append a_string to a_target, padded on the
			-- left with c characters if a_string is less
			-- than a_length character long.
		require
			a_target_not_void: a_target /= void;
			a_string_not_void: a_string /= void;
			a_length_positive: a_length >= 0

	append_quoted_eiffel_string (a_target: STRING; a_string: STRING)
			-- Append a_string, surrounded by double quotes, to
			-- a_target, where all non-printable characters are
			-- replaced by their escaped character sequence as
			-- described in ETL, section 25.15, page 422.
		require
			a_target_not_void: a_target /= void;
			a_string_not_void: a_string /= void
	
feature -- Type anchors

	output_stream_type: IO_MEDIUM
			-- (from KL_IMPORTED_OUTPUT_STREAM_ROUTINES)
	
invariant

		-- from GENERAL
	reflexive_equality: standard_is_equal (Current);
	reflexive_conformance: conforms_to (Current);

end -- class UT_STRING_FORMATTER