/*
 * string.h
 *
 * [Generated from string, 25 September 1996]
 */

#if !defined(__CC_NORCROFT) || !defined(__arm)
  #error You must use the Norcroft ARM Compiler for Sapphire programs
#endif

#pragma include_only_once
#pragma force_top_level

#ifndef __string_h
#define __string_h

#ifndef __sapphire_h
  #include "sapphire.h"
#endif

/*----- Overview ----------------------------------------------------------*
 *
 * Functions provided:
 *
 *  str_cpy
 *  str_len
 *  str_cmp
 *  str_icmp
 *  str_index
 *  str_match
 *  str_subst
 *  str_error
 *  str_buffer
 */

/* --- str_cpy --- *
 *
 * On entry:	R0 == destination string
 * 		R1 == source string
 *
 * On exit:	R0 == pointer to terminator of destination
 *
 * Use:		Copies a string from one block to another.  It leaves the
 *		destination pointer at the end of the string so that any
 *		subsequent copies concatenate other bits on the same string.
 *		Single characters can of course be appended with
 *
 *			MOV	Rx,#&cc
 *			STRB	Rx,[R0],#1
 */

extern routine str_cpy;

/* --- str_len --- *
 *
 * On entry:	R0 == pointer to string
 *
 * On exit:	R0 == length of the string
 *
 * Use:		Calculates the length of a string.
 */

extern routine str_len;

/* --- str_cmp --- *
 *
 * On entry:	R0 == pointer to string A
 * 		R1 == pointer to string B
 *
 * On exit:	Flags as appropriate
 *
 * Use:		Case-sensitively compares two strings.  You can use the
 *		normal ARM condition codes after the compare, so you can
 *		treat this fairly much like a normal CMP.
 */

extern routine str_cmp;

/* --- str_icmp --- *
 *
 * On entry:	R0 == pointer to string A
 * 		R1 == pointer to string B
 *
 * On exit:	Flags as appropriate
 *
 * Use:		As for str_cmp above, but case-insensitive.
 */

extern routine str_icmp;

/* --- str_index --- *
 *
 * On entry:	R0 == pointer to name table
 *		R1 == index into name table
 *
 * On exit:	CS if index good, and
 *		  R0 == address of R0th string in table
 *		else CC and
 *		  R0 corrupted
 *
 * Use:		Finds an indexed string in a table.  The table consists of
 *		ctrl-terminated strings, with no separation.  The table is
 *		terminated by a zero-length entry.
 */

extern routine str_index;

/* --- str_find --- *
 *
 * On entry:	R0 == pointer to name table
 *		R1 == string to match in table
 *
 * On exit:	CS if match found, and
 *		  R0 == index of string matched
 *		else CC and
 *		  R0 corrupted
 *
 * Use:		Looks up a string in a table.  The table consists of
 *		ctrl-terminated strings, with no separation.  The table is
 *		terminated by a zero-length entry.
 */

extern routine str_match;

/* --- str_subst --- *
 *
 * On entry:	R0 == Pointer to skeleton
 *		R1 == Pointer to output buffer
 *		R2-R11 == Pointer to filler strings (optional)
 *
 * On exit:	R0 == Pointer to start of buffer
 *		R1 == Pointer to terminating null
 *
 * Use:		Performs string substitution, filling in a skeleton string
 *		containing placeholders with `filler' strings.  The
 *		placeholders are actually rather powerful.  The syntax of
 *		these is as follows:
 *
 *			`%' [<type>] <digit>
 *
 *		(spaces are for clarity -- in fact you must not include
 *		spaces in the format string.)
 *
 *		<digit> is any charater between `0' and `9'.  It refers to
 *		registers R2-R11 (so `0' means R2, `5' is R7 etc.)  How the
 *		value is interpreted is determined by <type>.
 *
 *		<type> is one of:
 *
 *		s	String.  This is the default.  The register is
 *			considered to be a pointer to an ASCII string
 *			(control terminated).
 *
 *		i	Integer.  The (signed) decimal representation is
 *			inserted.  Leading zeros are suppressed.
 *
 *		x	Hex fullword.  The hexadecimal representation of the
 *			register is inserted.  Leading zeros are included.
 *
 *		b	Hex byte.  The hexadecimal representation of the
 *			least significant byte is inserted.  Leading zeros
 *			are included.
 *
 *		c	Character.  The ASCII character corresponding to the
 *			least significant byte is inserted.
 */

extern routine str_subst;

/* --- str_error --- *
 *
 * On entry:	R0 == Pointer to skeleton
 *		R2-R11 == Pointers to fillin strings
 *
 * On exit:	R0 == Pointer to error in buffer
 *		R1 == Pointer to terminator
 *
 * Use:		Fills in an error skeleton (containing a 4 byte error number
 *		and a control terminated skeleton string as for str_subst)
 *		and returns the address of the filled in error block.  The
 *		error block is stored in a buffer obtained from str_buffer.
 *
 *		Filler strings may be held in the scratchpad.
 */

extern routine str_error;

/* --- str_buffer --- *
 *
 * On entry:	--
 *
 * On exit:	R1 == pointer to the next free buffer
 *
 * Use:		Returns a pointer to a 256-byte buffer.  There are at present
 *		2 buffers, which are returned alternately.
 */

extern routine str_buffer;

/*----- That's all, folks -------------------------------------------------*/

#endif