// Xtrema Framework x32 : Documentation : String Class

Properties

The table below includes both properties and property-like methods for selecting substrings and / or modifying strings.
[ note: page to be redesigned - currently best viewed with ie / no table resize in firefox ]

Get-Only properties
	err	no args	one arg	two args	get returns	set expects	count
string	<ram>	v			dirStr			Translates to SDS and returns a copy as a Director string (for strS objects, same as .stringX)
stringX	<ram>	v			dirStr			Returns a copy of the object's primary buffer as a Director string.
stringP	x	v			true			Returns true.
value	<var>	v			dirValue			Same as Director's 'value' command - returns the logical value of a string.
length	x	v			int char count			Returns the length of a string, in characters.
err	x	v			<err> / 0			If the result of the last operation on the string failed, returns an <err> value. Otherwise, 0
errNum	x	v			int err code			If the result of the last operation on the string failed, returns the integer error code. Otherwise, 0
CP	x	v			int code page			Returns the string's integer CodePage
BPD	x	v			1 or 2			Returns 1 for single, or 2 for double digit strings.
maxBPC	x	v			1, 2 or 4			Returns the maximum bytes per character. SBCS:1, DBCS:2 \| UCS-2:2 , UTF-16:4
maxDPC	x	v			1 or 2			Returns the maximum digits per character. SBCS:1, DBCS:2 \| UCS-2:4 , UTF-16:8

get byte, digit, char value /set byte or digit value								Operations performed on the original buffer. Changing a character's value is not allowed, since resizing the string may be required (DBCS, UTF-16). For SBCS and UCS2, digits and character values are equal.
	err	no args	one arg	two args	get returns	set expects	count
byte / BDec	-1	byte 0	byte pos		int byte value	int/str		Get: returns the byte's integer value. Set: sets the byte's value - accepts integer or hex string
BHex	<oob>	byte 0	byte pos		hex byte value	hex		Get: returns the byte's value as a hex string
DDec	-1	digit 0	digit pos		int digit value	int/str		Get: returns the digits's integer value. Set: sets the digit's value - accepts integer or hex string
DHex	<oob>	digit 0	digit pos		hex digit value	hex		Get: returns the digit's value as a hex string
CDec	-1	char 0	char pos		int char value	x		Get: returns the character's integer Value.
CHex	<oob>	char 0	char pos		hex char value	x		Get: returns the character's value as a hex string.

DWinCP	<0	x	digit pos		digit's cp	x		Returns the character's Windows SBCS code page. Other values: 0:7bit (anypage) -1=unmappapbe, -2=error.
DMacCP	<0	x	digit pos		digit's cp	x		Returns the character's Mac SBCS code page. Other values: 0:7bit (anypage), -1=unmappapbe, -2=error.

upper / lower case								In place Upper/Lower case. To return a new string instead, use e.g. str.dupe().upper. Though all types of strings (SBCS, DBCS, DDS) are supported, using strDs is recommended.
	err	no args	one arg	two args	get returns	set expects	count
upper	x	v	x		parent			Converts all characters of the selection to upper case
lower	x	v	x		parent			Converts all characters of the selection to lower case

select / insert digits, chars, words, lines, items								Set: returns a reference (if the object is a reference) or a copy of the target area of the string. Get: inserts the specified data in the target area, resizing the string as required, and dereferencing it (if reference). Singe digit properties use zero-based. e.g. _s("abc").d[0] returns "a" L values expect length as the second value of the range. e.g. _s("0123456").dL[3..2] returns "34" The rest of the properties are compatible to their Director's equivalents (one-based). e.g. _s("abc").d[1] returns "a"
	err	no args	one arg	two args	get returns	set expects	count
D	x	x	pos, pos	posA, posB	offspring	any val	v	Digit a to b, zero-based
C	x	x	pos, pos	posA, posB	offspring	any val	v	Character a to b, zero-based
W	x	x	pos, pos	posA, posB	offspring	any val	v	Word a to b, zero-based
L	x	x	pos, pos	posA, posB	offspring	any val	v	Line a to b, zero-based. Note: both CR and LF are considered line delimiters. a CRLF is counted as two lines. Tip: Use the leCR to convert CRLFs and orphaned LFs to single CRs
I	x	x	pos, pos	posA, posB	offspring	any val	v	Item a to b, zero-based

DL	x	x	pos, 1	pos, len	offspring	any val	x	Digit start, length, zero-based
CL	x	x	pos, 1	pos, len	offspring	any val	x	Character start, length, zero-based
WL	x	x	pos, 1	pos, len	offspring	any val	x	Word start, length, zero-based
LL	x	x	pos, 1	pos, len	offspring	any val	x	Line start, length, zero-based
IL	x	x	pos, 1	pos, len	offspring	any val	x	Item start, length, zero-based

dgt	x	x	pos, pos	posA, posB	offspring	any val	v	Digit a to b, one-based
char	x	x	pos, pos	posA, posB	offspring	any val	v	Character a to b, one-based
word	x	x	pos, pos	posA, posB	offspring	any val	v	Word a to b, one-based
line	x	x	pos, pos	posA, posB	offspring	any val	v	Line a to b, one-based
item	x	x	pos, pos	posA, posB	offspring	any val	v	Item a to b, one-based


get / set word and item delimiters
iDl	var	v	x	x	x	new dlm str	x	Get or set the item delimiter
wDl	var	v	x	x	x	new dlm str	x	Get or set the word delimiter
set delimiter, return parent
wDl	var	x	new wDlm str	x	parent	x	x	Allows setting the item delimiter while executing a dot queue.	put _s("ab#cd").idl["#"].i[1].idl["*"].i[0] --c
iDl	var	x	new iDlm str	x	parent	x	x	Allows setting the word delimiter while executing a dot queue.

select / move / expand / shrink selection								Performed on the top or parent object of a dot queue. The returned string will be either a reference, if the top string is a reference, or a copy of the top object's selected area. C/D: End the command with C for characters or D for Digits s/i: Begin the command with s for case sensitive or i for case isensitive searches. inst: instance to search for. E.g 1 (default) will seek for the first instance, 2 for the second. Negative values signify distance from the end. E.g. -1 for the last instance.
	err	no args	one arg	two args	get returns	set expects	count
prev		v	x	x	ref			Selects the first digit of the top object up to the first digit before the start of the selection.	put _s("abcd").d[2].prev -- ab
next		v	x	x	ref			Selects the first digit after the end of the selection up to the end of the top object.	put _s("abcd").d[2].next -- d
bef		v	x	x	ref			Selects an area whose start is the first digit of the selection and it's length 0.	put _s("abcd").d[2].bef.ins("") -- abcd
aft		v	x	x	ref			Selects an area whose start is the first digit after the end of the selection and it's length 0.	put _s("abcd").d[2].aft.ins("") -- abcd
exp		v	x	x	ref			Selects all digits (begining to end) of the top object.	put _s("one two").w[1].upper.exp -- one TWO
expBgn		v	x	x	ref			Expands the begining of the selection to the begining of the top object.	put _s("abcd").d[2].expBgn -- abc
expEnd		v	x	x	ref			Expands the end of the selection to the end of the top object.	put _s("abcd").d[2].expEnd -- cd

expC/D		x	int len	bgnLen, endLen	ref			Expands the begining and the end of the selection by the number of digits or characters specified.	put _s("abcd").d[2].expC[1] -- bcd
expBgnC/D		x	int step	x	ref			Expands the begining of the selection by the number of digits or characters specified.	put _s("abcd").d[2].expBgnD[1] -- bc
expEndC/D		x	int step	x	ref			Expands the end of the selection by the number of digits or characters specified.	put _s("abcd").d[2].expEndD[1] -- cd
movC/D		x	int step	bgnStep, endStep	ref			Moves the selection by the number of digits or characters specified.	put _s("abcd").d[2].movC[-1] -- b
movBgnC/D		x	int step	x	ref			Moves the begining of the selection by the amount of digits specified. Unlike the expBgnC/D, uses negative values to expand towards the begining of the top object.
movEndC/D		x	int step	x	ref			Moves the end of the selection by the amount of digits specified. Same as the expEndC/D.

s/iSel		x	str	str, pos	ref			Selects the specified string in the parent object.	put _s("abcdabcd").iSel["bc"..2].ins("2nd") -- abcda2ndd
s/iSelTag		x	x	strBgn, strEnd	ref			Parser helper - select a tag by defining start and end.	put _s("pre <b><i><b>text</b></i></b> post").iSelTag["<b".."/b>"] -- <b><i><b>text</b></i></b>
s/iSelInc		x	x	strBgn, strEnd	ref			Selects a substring of the parent string, begining at the fist occurance of strBgn and ending at the end of the first occurance of strEnd after strBgn.	put _s("abcdefg").iSelInc["b".."f"].ins("") -- ag
s/iSelExc		x	x	strBgn, strEnd	ref			Selects a substring of the parent string, begining after the fist occurance of strBgn and ending before the first occurance of strEnd after strBgn.	put _s("abcdefg").iSelExc["b".."f"].ins("") -- abfg
s/iBgnBef		x	strBgn	strBgn, inst=1	ref			Selects a substring of the parent string, begining before the specified occurance of strBgn.	put _s("abcd-abcd").iBgnBef["b"..-1].ins("last") -- abcd-alast
s/iBgnAft		x	strBgn	strBgn, inst=1	ref			Selects a substring of the parent string, begining after the specified occurannce of strBgn.	put _s("abcd-abcd").iBgnAft["b"..-1].ins("last") -- abcd-ablast
s/iEndBef		x	strEnd	strEnd, inst=1	ref			Selects a substring of the parent string, ending before the specified occurance of strEnd.	put _s("abcdABCD").sEndBef["B"] -- abcdA
s/iEndAft		x	strEnd	strEnd, inst=1	ref			Selects a substring of the parent string, ending after the specified occurance of strEnd.	put _s("abcdABCD").sEndAft["B"] -- abcdAB

s/iExpTag		x	x	strBgn, end	ref			Parser helper - expands a substring of a tag to the enclosing tag.	put _s("pre <b><i><b>text</b></i></b> post").iSel["<i>"].iExpTag["<b".."/b>"] -- <b><i><b>text</b></i></b>
s/iExpInc		x	x	strBgn, end	ref			Expands a substring towards the beging before the first digit of strBgn and towards the end till after the last digit of strEnd.	put _s("pre <b><i><b>text</b></i></b> post").iSel["<i>"].iExpInc["<b".."/b>"] -- <b><i><b>text</b>
s/iExpExc		x	x	strBgn, end	ref			Expands a substring towards the beging after the last digit of strBgn and towards the end till before the first digit of strEnd.	put _s("pre <b><i><b>text</b></i></b> post").iSel["<i>"].iExpExc["<b".."/b>"] -- ><i><b>text<
s/iExpBgnBef		x	strBgn	strBgn, inst=1	ref			Expands a substring's begining before the first digit of the specified occurance of strBgn.	put _s("abcdABCD").sSel["c"].sExpBgnBef["a"] -- abc
s/iExpBgnAft		x	strBgn	strBgn, inst=1	ref			Expands a substring's begining after the last digit of the specified occurance of strBgn.	put _s("abcdABCD").sSel["c"].sExpBgnAft["a"] -- bc
s/iExpEndBef		x	strEnd	strEnd, inst=1	ref			Expands a substring's end before the first digit of the specified occurance of strEnd.	put _s("abcdABCD").sSel["c"].iExpEndBef["a"..-1] -- cd
s/iExpEndAft		x	strEnd	strEnd, inst=1	ref			Expands a substring's end after the last digit of the specified occurance of strEnd.	put _s("abcdABCD").sSel["c"].iExpEndAft["a"..-1] -- cdA

s/iBgnAnyOf		x	strBlock	x	ref			Sets the begining of a string to the first occurance of any of the strBlock characters	put _s("abcdABCD").sBgnAnyOf["cB"] -- cdABCD
s/iBgnNotOf		x	strBlock	x	ref			Sets the begining of a string to the first occurance of a character not belonging to the strBlock characters	put _s("abcdABCD").sBgnNotOf["cba"] -- dABCD
s/iSselBlkOf		x	strBlock	x	ref			Selects the first sequence of characters belonging to strBlock	put _s("abcdABCD").sSelBlkOf["dAc"] -- cdA

s/iTrim		whtSpc	str	x	ref			Shrinks the selection's ends by excluding any characters belonging to str	put _s(" ab cd ").sTrim.enclose() -- "ab cd"
s/iTrimBgn		whtSpc	str	x	ref			Shrinks the selection's begining, by excluding any characters belonging to str	put _s(" ab cd ").sTrimBgn.enclose() -- "ab cd "
s/iTrimEnd		whtSpc	str	x	ref			Shrinks the selection's end, by excluding any characters belonging to str	put _s("!abcd#!").sTrimEnd["!#"].enclose() -- "!abcd"

s/iEase		whtSpc	str	x	ref			Expands the selection's ends by including any adjacent characters belonging to str	put _s("*ABC*").iSel["b"].sEase["CA"] -- ABC
s/iEaseBgn		whtSpc	str	x	ref			Expands the selection's begining, by including any adjacent characters belonging to str	put _s("*ABC*").iSel["b"].sEaseBgn["CA"] -- AB
s/iEaseEnd		whtSpc	str	x	ref			Expands the selection's end, by including anyadjacent characters belonging to str	put _s("*ABC").iSel["b"].sEaseEnd["CA"] -- BC***

position of the selection relative to top object (in characters or digits)								Note:the length is returned using the .d.count or .c.count commands
	err	no args	one arg	two args	get returns	set expects	count
offC/D		v			start pos			Returns the zero-based offset of the begining of the selection, relative to the top object, in digits or characters	put _s("0123456789").iSel["56"].offD -- 5
selC/D		v			[pos, len]			Returns the zero-based [begining, length] of the selection, relative to the top object, in digits or characters	put _s("0123456789").iSel["56"].selD -- [5, 2]

create ref / get top object								Use references (objects containing c++ pointers, rather than copies of the actual data) to increase performance and versatility. WARNING: improper use of references will most probably crash your app
	err	no args	one arg	two args	get returns	set expects	count
top		v	x	x	top obj			Returns the top object
ref		v	x	x	ref			Creates and returns a reference to the selection	p=_s("one two three") r=p.w[1].ref put r -- two
[ra]/ref[ra..rb]		x	ref of par	refA, refB	ref in top			Assuming r is an offspring (selection) of p, p[r] will set p as the top object of a dot queue, and r the selected area of p.	put p[r].prev -- one

[1]