String manipulations



[1]
strX.resize( newSize {,fillStr} ) resize
  Returns strX / <err>
  newSize Desired size of the buffer, in digits.
  fillStr Optional string to fill the newly allocated part of strX with
     
  Description

Resizes strX to newSize, and optionally fills the extra size (if newSize is larger than the previous size) with fillStr.

If no fillStr is specified, the newly allocated part of strX will contain random data.
If strX is strD, the object's new buffer size in bytes will be newSize * 2 (bytes per digit).
After this command, the object's buffer address in memory may change. So, using previously created references to this object is unsafe.
If the memory required cannot be allocated, an <err> will be returned.

Otherwise, the original object will be returned to the command line.

     
  Examples

put _s().resize(10).length
-- 10

put _s("abcd").resize(10, "*")
-- abcd******
     
  Notes  

[2]
strX.reverse( ) reverse
  Returns <strX>/ <err>
     
  Description Returns a new string object, containing the characters of strX in reversed order.
This command works on characters, not digits, therefore it supports MBCS codepages and all UTF-16 characters.
     
  Examples put _s("012345").reverse()
-- 543210
     
  Notes  

[3]
strX.fill( str ) fill
  Returns topStr / <err>
  str String to fill strX with.
     
  Description Fills strX with str, by repeating str as required.
If used as the terminating command of a property accessing sequence, the top object will be returned to the command line.
When used directly on an object, the top object is the object itself, so it will be returned to the command line.
The fill command is performed directly on the object's (or on its data source's) buffer. Therefore, it will not dereference the object.
     
  Examples put _s().resize(10).fill("*")
-- **********
put _s().resize(10).fill("abc")
-- abcabcabca

put _s("four words of text").word[2].fill("*")
-- four ***** of text
note: though the above command is safe, sine the fill command will return the top object, it's in general safer to use:
s=_s("four words of text")
put s.word[2].fill("*")
-- four ***** of text
     
  Notes  

[4]
strX.paste( str ) paste
  Returns topStr / <err>
  str String to paste in str
     
  Description Similar to fill, but without the repetition part.
     
  Examples put _s().resize(7).fill("*").paste("ABC")
-- ABC****
put _s().resize(7).fill("*").paste("six characters")
-- six cha

put _s().resize(7).fill("*").paste("ABC")
-- ABC****
put _s().resize(7).fill("*").paste("six characters")
-- six cha

put _s("four words of text").word[2].paste("lines").word[-1].paste("data")
-- four lines of data
     
  Notes  

[5]
strX.del() del
  Returns topStr / <err>
     
  Description Delete the area that the reference strX occupies in its top object.
Returns the top object.
     
  Examples put _s("one two three").word[2].char[1..2].del()
-- one o three
     
  Notes  

[6]
strX.cut() cut
  Returns dereferenced strX / <err>
     
  Description Same as del, but will return a copy of strX, instead of the top object, to the command line.
     
  Examples s=_s("one two three")
put s.word[2].cut()
-- two
put s
-- one  three
     
  Notes  

[7]
strX.ins( str ) insert
  Returns topStr / <err>
  str String to insert
     
  Description Replaces the range that strX occupies in its top object with the contents of strX. Returns the top object.
     
  Examples s=_s("one two three")
put s.word[2].ins("2")
-- one 2 three
     
  Notes For compatibility with Director's strings, the 'put into' command is also supported:
s=_s("my [two] words")
put "three" into s.word[2].char[2..-2]
put s
-- my [three] words

[8]
strX.insBef( str ) insert before
  Returns topStr / <err>
  str String to insert
     
  Description Inserts strX's data before its offset in its top object. Returns the top object.
     
  Examples put _s("one two three").insBef("zero ")
-- zero one two three

put _s("one two three").word[2].insBef("and a half, ")
-- one and a half, two three
     
  Notes For compatibility with Director's string, the 'put before' command is also supported.

[9]
strX.insAft( str ) insert after
  Returns topStr / <err>
  str String to insert
     
  Description Inserts strX's data after its end position in its top object. Returns the top object.
     
  Examples put _d("keys help").w[0].c[-2].insAft("word")
-- keywords help
     
  Notes For compatibility with Director's string, the 'put after' command is also supported.

[10]
strX.appN( str ) duplicate and append
  Returns <strX> / <err>
  str String to append.
     
  Description Returns a copy of strX at which str is appended, or an <err> if the operation fails.
     
  Examples s=_s("a")
put s.appN("b")
-- ab
put s
-- a
     
  Notes  

[11]
strX.app( str ) append in place
  Returns strX / <err>
  str String to append.
     
  Description Appends str to strX, returning the modified original object, or an <err> if the operation fails.
     
  Examples s=_s("a")
put s.app("b")
-- ab
put s
-- ab
     
  Notes  

[12]
strX.appSC( charCode {, CP} )  / strX.appDC( charCode {, CP} ) append character by code
  Returns strX / <err>
  charCode Integer or hexStr character code.
     
  Description Creates a temporary string (with codepage CP, or glbCP if CP is not defined), which will contain one character, whose value will be charCode.
For appSC, the string will be a SDS, and charCode a  character's value (0-255 for SBPC, or 0-65535 for MBPC code pages)
For appDS, the string will be a DDS, and charCode a character's unicode value (for non UTF-16 characters, the value will be higher than 65535).

The temporary string is appended to strX, and strX is returned to the command line.
If the operation fails, an <err> is returned.
     
  Examples put _s("my string").appSC(43)
-- my string+
put _s("greek alpha: ").appSC(225, 1253) --or: put _s("greek alpha: ").appSC("E1", 1253)
-- greek alpha: α
     
  Notes