;
; string.sh
;
; String handling routines (control terminated)
;
; © 1994-1998 Straylight
;

;----- Licensing note -------------------------------------------------------
;
; This file is part of Straylight's Sapphire library.
;
; Sapphire is free software; you can redistribute it and/or modify
; it under the terms of the GNU General Public License as published by
; the Free Software Foundation; either version 2, or (at your option)
; any later version.
;
; Sapphire is distributed in the hope that it will be useful,
; but WITHOUT ANY WARRANTY; without even the implied warranty of
; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
; GNU General Public License for more details.
;
; You should have received a copy of the GNU General Public License
; along with Sapphire.  If not, write to the Free Software Foundation,
; 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

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

		[	:LNOT::DEF:string__dfn
		GBLL	string__dfn

; --- 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

		IMPORT	str_cpy

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

		IMPORT	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.

		IMPORT	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.

		IMPORT	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.

		IMPORT	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.

		IMPORT	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.

		IMPORT	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.

		IMPORT	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.

		IMPORT	str_buffer

		]

;----- That's all, folks ----------------------------------------------------

		END