REM >BASIC:String
REM
REM Copyright 2001-2014, Stephen Fryatt (info@stevefryatt.org.uk)
REM
REM This file is part of WimpLib:
REM
REM   http://www.stevefryatt.org.uk/software/
REM
REM Licensed under the EUPL, Version 1.2 only (the "Licence");
REM You may not use this work except in compliance with the
REM Licence.
REM
REM You may obtain a copy of the Licence at:
REM
REM   http://joinup.ec.europa.eu/software/page/eupl
REM
REM Unless required by applicable law or agreed to in
REM writing, software distributed under the Licence is
REM distributed on an "AS IS" basis, WITHOUT WARRANTIES
REM OR CONDITIONS OF ANY KIND, either express or implied.
REM
REM See the Licence for the specific language governing
REM permissions and limitations under the Licence.
:
REM String handling library


REM Return as a BASIC string a string from memory terminated by
REM ASCII 0, 10 or 13.
REM
REM \param string%		Pointer to the string in memory.
REM \return			The string extracted from memory.
:
DEF FNstring_read(string%)
LOCAL string$
SYS "XOS_GenerateError", string% TO string$
=string$


REM Return as a BASIC string a control character terminated string from the
REM supplied pointer. Update the pointer to point to the next piece of data.
REM
REM \param string%		Pointer to the string to extract; updated on
REM				return to point to terminating byte.
REM \return			The string extracted from the pointer.
:
DEF FNstring_extract_ctrl(RETURN string%)
LOCAL string$

WHILE ?string% >= 32
	string$ += CHR$(?string%)
	string% += 1
ENDWHILE
=string$


REM Remove all leading and trailing whitespace from a sreing.
REM
REM \param			The string to be trimmed.
REM \return			The string without any surrounding whitespace.

DEF FNstring_trim(string$)
WHILE ASC(LEFT$(string$,1)) <= 32 AND LEN(string$) > 0
	string$ = MID$(string$, 2)
ENDWHILE
WHILE ASC(RIGHT$(string$)) <= 32 AND LEN(string$) > 0
	string$ = LEFT$(string$)
ENDWHILE
=string$


REM Convert a string into upper case.
REM
REM \param string$		The string to be converted.
REM \return			The string converted into upper case.
:
DEF FNstring_to_upper(string$)
LOCAL loop%, char%, table%

SYS "Territory_UpperCaseTable", -1 TO table%

FOR loop% = 1 TO LEN(string$)
	char% = ASC(MID$(string$, loop%, 1))
	MID$(string$, loop%, 1) = CHR$(table%?char%)
NEXT loop%
=string$


REM Convert a string into lower case.
REM
REM \param string$		The string to be converted.
REM \return			The string converted into lower case.
:
DEF FNstring_to_lower(string$)
LOCAL loop%, char%, table%

SYS "Territory_LowerCaseTable", -1 TO table%

FOR loop% = 1 TO LEN(string$)
	char% = ASC(MID$(string$, loop%, 1))
	MID$(string$, loop%, 1) = CHR$(table%?char%)
NEXT loop%
=string$


REM Given a filename, return the leafname portion of the string (ie. everything
REM following the final '.' in the string).
REM 
REM \param filename$		The filename to process.
REM \return			The leafname portion of the filename.
:
DEF FNstring_leafname(filename$)
IF INSTR(filename$, ":") THEN filename$ = MID$(filename$, INSTR(filename$, ":") + 1)

WHILE INSTR(filename$, ".")
	filename$ = MID$(filename$, INSTR(filename$, ".") + 1)
ENDWHILE
=filename$


REM Given a filename, return the pathname portion of the string (ie. everything
REM before the final '.' in the string).
REM 
REM \param filename$		The filename to process.
REM \return			The pathname portion of the filename.
:
DEF FNstring_pathname(filename$)
LOCAL pathname$

WHILE INSTR(filename$, ".")
	pathname$ += LEFT$(filename$, INSTR(filename$, ".") - 1) + "."
	filename$ = MID$(filename$, INSTR(filename$, ".") + 1)
ENDWHILE
=LEFT$(pathname$)

