UXStrings.mesa
Copyright Ó 1988, 1991 by Xerox Corporation. All rights reserved.
Created by Christian Jacobi, May 23, 1988 3:19:13 pm PDT
Carl Hauser, November 21, 1988 2:33:48 pm PST
Willie-s, August 8, 1991 3:46 pm PDT
~
BEGIN
Error: ERROR [ec: ErrorCode];
ErrorCode:
TYPE = { clientModifiedReleasedString };
This error may be raised by ObtainScratch, below.
CString: TYPE = CStrings.CString;
Create:
PROC [from:
REF]
RETURNS [string: CString];
Creates a Unix compatible string by copying to a newly allocated object.
from: ROPE, REF TEXT
NIL creates an empty string [not a NIL string]
CreateSpace:
PROC [size:
INT]
RETURNS [string: CString];
Creates newly allocated space for a Unix compatible string of given size. Adds an extra byte for the null terminator.
ToRope:
PROC [from: CString, maxLength:
INT ¬
LAST[
INT]]
RETURNS [Rope.
ROPE];
Transforms unix compatible string into ROPE
Copies the bits; the ROPE is safe and subject to Cedar GC
ViewRefText:
UNSAFE
PROC [from:
REF
TEXT]
RETURNS [string: CString];
from: non-NIL REF TEXT
string: a pointer to the beginning of the text contents of from. Since from and string share storage, modifications to either appear in both. Further, holding string is not sufficient to prevent GC of from, so while the latter is in use, hold onto the former.
CreateScratch:
PROC [from:
REF]
RETURNS [string: UXStrings.CString];
Like CStrings.Create but obtains space from a scratch pool. See ObtainScratch, below, for caveats.
ObtainScratch:
PROC [nChars:
INT]
RETURNS [UXStrings.CString];
! Error [clientModifiedReleasedText]
Like CStrings.CreateSpace but obtains space from a scratch pool.
A call to ObtainScratch is less expensive than CreateSpace, but ObtainScratch should only be called with the expectation of calling ReleaseScratch (below) later on the resulting pointer. (It is ok for a client to occasionally "forget" to release a string obtained with this procedure, so for instance there is no need to call ReleaseScratch in UNWIND catch phrases unless UNWIND is expected most of the time!)
Raises Error [clientModifiedReleasedString] if the string it wanted to return has been tampered with (in a detectable way) since it was released with ReleaseScratch; this indicates that some client is not playing by the rules.
ReleaseScratch:
PROC [s: UXStrings.CString];
Caller asserts that it has no further interest in the string pointed to by s.
Noop if s was not obtained from scratch pool.
CopyRefToString:
UNSAFE
PROC [ref:
REF, string: UXStrings.CString];
Copies content of ref^ to string. Works for ROPE, REF TEXT, and NIL refs. Caller's responsibility to assure that string holds enough space for the copied characters.