42.9. newString

newString is used to create a STRING descriptor.

newString returns a STRING of length n of which the first character is at the location given by c. The STRING so created is not subject to garbage collection if it is not in MAINSAIL's STRING space, e.g., if it is in storage allocated by a call to newPage or newScratch. If it is desired to reuse the storage to create new STRINGs or to make the STRING subject to garbage collection, the PROCEDURE $getInArea should be used.

If c is NULLCHARADR or n less than or equal to 0, the result is the empty STRING.

For example, t := newString(cvc(s),length(s)) is equivalent to t := s; i.e., the STRING descriptor for t is a copy of the STRING descriptor for s.

It is the caller's responsibility to ensure that the second parameter to newString is less than or equal to $maxStringLength. An invalid STRING descriptor can result if a greater value is specified.