_____________________________________________________________________________

  AppEngine_StringOp						 SWI &4D941
_____________________________________________________________________________

							   AppEngine_StringOp
								 (SWI &4D941)

	Provides string-handling operations

On entry
	R0 = reason code
	other registers are reason code dependent

On exit
	R0 preserved
	other registers are reason code dependent

Interrupts
	Interrupt status is undefined
	Fast interrupts are enabled

Processor mode
	Processor is in SVC mode

Re-entrancy
	Not defined

Use
	This call provides various operations to deal with ASCII strings.

	Most (if not all) of the calls place their result within AppEngine's
	workspace and return a pointer to the string within the workspace.
	For this reason, you must always copy the string to somewhere else
	before calling StringOp again - if you don't do that then further
	calls to StringOp will overwrite the workspace, destroying the
	string.

	All strings are stored in the same style as BASIC, i.e. with CR (13)
	as the terminating character.  As with BASIC, they are limited to a
	maximum of 256 characters, including terminator (although this may
	change later on).  Typically you will use the operations in this way:

		SYS "AppEngine_StringOp",1,source% TO ,,string$

	Input strings can be terminated by any control character, unless
	otherwise stated.

	The action of the SWI depends on the reason code passed in R0:

		R0	Action
		0	reads a string from memory (LF terminated)
		1	reads a string from memory (control terminated)
		2	shortens a string, adding an ellipsis on the left
		3	shortens a string, adding an ellipsis on the right
		4	converts a string to lower-case characters
		5	converts a string to upper-case characters
		6	tests whether a string is a valid integer number
		7	strips leading spaces and tabs from a string
		8	compares two strings
		9	joins two strings
		10	returns the leafname from a path string
		(11	returns the branchname from a path string)
		12	substitutes arguments into a string
		13	returns the length of a string
		14	copies a string

	Note: StringOp 11 is not yet implemented.

Related SWIs
	None

Related vectors
	None
_____________________________________________________________________________

							 AppEngine_StringOp 0
								 (SWI &4D941)

	Reads a string from memory (LF terminated)

On entry
	R0 = 0
	R1 = pointer to address to read string from

On exit
	R0 preserved
	R1 = pointer to character after the inputs terminator
	R2 = pointer to read string (up to 255 chars)

Use
	This call converts an LF-terminated string in memory into a
	CR-terminated string in the module's internal workspace.
_____________________________________________________________________________

							 AppEngine_StringOp 1
								 (SWI &4D941)

	Reads a string from memory (control terminated)

On entry
	R0 = 1
	R1 = pointer to address to read string from

On exit
	R0 preserved
	R1 = pointer to character after the inputs terminator
	R2 = pointer to read string (up to 255 chars)

Use
	This call converts a string in memory into a
	CR-terminated string in the module's internal workspace.
_____________________________________________________________________________

							 AppEngine_StringOp 2
								 (SWI &4D941)

	Shortens a string, adding an ellipsis on the left

On entry
	R0 = 2
	R1 = pointer to address to read string from
	R2 = length of output string (maximum of 255, <3 is undefined)

On exit
	R0, R2 preserved
	R1 = pointer to character after the inputs terminator
	R3 = pointer to output string (up to 255 chars)

Use
	This call copies a string, truncating the left-hand side and
	prefixing an ellipsis (...) if it's longer than the specified size.
_____________________________________________________________________________

							 AppEngine_StringOp 3
								 (SWI &4D941)

	Shortens a string, adding an ellipsis on the right

On entry
	R0 = 3
	R1 = pointer to address to read string from
	R2 = length of output string (maximum of 255, <3 is undefined)

On exit
	R0, R2 preserved
	R1 = pointer to character after the inputs terminator
	R3 = pointer to output string (up to 255 chars)

Use
	This call copies a string, truncating the right-hand side and
	appending an ellipsis (...) if its longer than the specified size.
_____________________________________________________________________________

							 AppEngine_StringOp 4
								 (SWI &4D941)

	Converts a string to lower-case characters

On entry
	R0 = 4
	R1 = pointer to address to read string from

On exit
	R0 preserved
	R1 = pointer to character after the input's terminator
	R2 = pointer to output string (up to 255 chars)

Use
	This call converts a string in memory into a
	CR-terminated string, using only lower-case characters, in the
	module's internal workspace.
_____________________________________________________________________________

							 AppEngine_StringOp 5
								 (SWI &4D941)

	Converts a string to upper-case characters

On entry
	R0 = 5
	R1 = pointer to address to read string from

On exit
	R0 preserved
	R1 = pointer to character after the input's terminator
	R2 = pointer to output string (up to 255 chars)

Use
	This call converts a string in memory into a
	CR-terminated string, using only upper-case characters, in the
	module's internal workspace.
_____________________________________________________________________________

							 AppEngine_StringOp 6
								 (SWI &4D941)

	Tests whether a string is a valid integer number

On entry
	R0 = 6
	R1 = pointer to address to read string from

On exit
	R0 preserved
	R1 = pointer to character after the inputs terminator
	R2 = TRUE (-1) or FALSE (0) for valid or invalid respectively

Use
	This call reads a string from memory, if it finds that the string
	contains non-numeric characters then it will return FALSE.  If it
	finds that the string contains only numeric characters, then it will
	return TRUE.
_____________________________________________________________________________

							 AppEngine_StringOp 7
								 (SWI &4D941)

	Strips leading spaces and tabs from a string

On entry
	R0 = 7
	R1 = pointer to address to read string from

On exit
	R0 preserved
	R1 = pointer to character after the input's terminator
	R2 = pointer to output string (up to 255 chars)

Use
	This call converts an input string which contains leading space and
	tab characters to one without them.
_____________________________________________________________________________

							 AppEngine_StringOp 8
								 (SWI &4D941)

	Compares two strings

On entry
	R0 = 8
	R1 = pointer to address to read string from
	R2 = pointer to address to read second string from

On exit
	R0 preserved
	R1 = pointer to character after the input's terminator
	R2 = pointer to character after the second input's terminator
	R3 = -1 for string 1 < string 2
	      0 for string 1 = string 2
	      1 for string 1 > string 2

Use
	This call compares two strings and returns an integer representing
	the relationship of the two strings (less than, equal, greater than).
_____________________________________________________________________________

							 AppEngine_StringOp 9
								 (SWI &4D941)

	Joins two strings

On entry
	R0 = 9
	R1 = pointer to address to read first string from
	R2 = pointer to address to read second string from

On exit
	R0 preserved
	R1 = pointer to character after the input's terminator
	R2 = pointer to character after the second input's terminator
	R3 = pointer to output string (up to 255 chars)

Use
	This call takes two strings and returns the second string joined to
	the first.
_____________________________________________________________________________

							AppEngine_StringOp 10
								 (SWI &4D941)

	Returns the leafname of a path string

On entry
	R0 = 10
	R1 = pointer to address to read string from
	R2 = directory separator character, typically '.' or '/' (ASCII code)

On exit
	R0, R2 preserved
	R1 = pointer to character after the input's terminator
	R3 = pointer to output string (up to 255 chars)

Use
	This call takes an input path string (e.g. ADFS::HD4.$.Sounds.Wave)
	and returns what follows the last instance of the separator character
	(in this case, Wave).
_____________________________________________________________________________

							AppEngine_StringOp 12
								 (SWI &4D941)

	Substitutes arguments into a string

On entry
	R0 = 12
	R1 = pointer to template string, containing '%0' up to '%3'.
	R3 = string to substitute for '%0' or 0 for no string
	R4 = string to substitute for '%1' or 0 for no string
	R5 = string to substitute for '%2' or 0 for no string
	R6 = string to substitute for '%3' or 0 for no string

On exit
	R0, R3, R4, R5, R6 preserved
	R1 = pointer to character after the template string's terminator
	R2 = pointer to output string (up to 255 chars)

Use
	This call takes an input template string and substitutes another
	string where an identifier '%0'..'%3' appears.
_____________________________________________________________________________

							AppEngine_StringOp 13
								 (SWI &4D941)

	Returns the length of a string

On entry
	R0 = 13
	R1 = pointer to address to read string from

On exit
	R0 preserved
	R1 = pointer to character after the input's terminator
	R2 = length of string

Use
	This call determines the length of a string, in characters.
_____________________________________________________________________________

							AppEngine_StringOp 14
								 (SWI &4D941)

	Copies a string

On entry
	R0 = 14
	R1 = pointer to address to read string from
	R2 = pointer to address to copy string to

On exit
	R0 preserved
	R1 = pointer to character after the input's terminator
	R2 = pointer to character after the output's terminator

Use
	This copies a string from one location to another.
