NSString.mesa
Copyright Ó 1986, 1987 by Xerox Corporation. All rights reserved.
Revised by Kiser: 22-Sep-82 21:00:23
Overview: Definitions for the international network string format.
Tim Diebert: January 6, 1987 5:02:56 pm PST
Ruseli Binsol: November 18, 1986 4:27:01 pm PST
DIRECTORY
Courier USING [Description],
Basics USING [Comparison];
NSString: CEDAR DEFINITIONS = BEGIN
-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ----
TYPES :
-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ----
Character: TYPE = MACHINE DEPENDENT RECORD [chset, code: BYTE];
Characters: TYPE = REF CharactersRep;
CharactersRep: TYPE = RECORD [data: SEQUENCE length: CARDINAL OF Character];
String: TYPE = REF TEXT;
StringRep:
TYPE ~
TEXT;
Handle to network string.
SubString: TYPE = REF SubStringDescriptor;
SubStringDescriptor:
TYPE =
RECORD [base: String, offset, length:
CARDINAL];
offset and length are in logical characters, not bytes.
Relation: TYPE = Basics.Comparison;
MesaString: TYPE = REF TEXT;
-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ----
CONSTANTS :
-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ----
nullString: String = NIL;
Null value of String.
-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ----
OPERATIONS :
-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ----
LogicalLength:
PROC [s: String]
RETURNS [
CARDINAL];
Returns the number of NS characters in the string (not the same as the number of bytes).
WordsForString:
PROC [bytes:
CARDINAL]
RETURNS [
CARDINAL];
Return the number of words needed for a string whose maxlength is equal to the specified number of bytes.
NOTE: all three append operations may raise StringBoundsFault. If the client wishes the operation to continue in such a case, it is his obligation to supply a new, larger string, whose contents are identical to what was in the old string just BEFORE the call which raised StringBoundsFault. i.e. the client should fill the new string based on the "to" argument String, and NOT from the "old" String passed back by StringBoundsFault (unless, of course, the client is satisfied with a partial copy).
AppendCharacter: PROC [to: String, from: Character] RETURNS [String];
AppendString:
PROC [to: String, from: String]
RETURNS [String];
Append the specified character or string to the end of the specified string. The returned String replaces the "to" String, which should no longer be used.
AppendSubString:
PROC [to: String, from: SubString]
RETURNS [String];
Appends the substring to the end of the specified string.
CompareStrings:
PROC [s1, s2: String, ignoreCase:
BOOLEAN ←
TRUE]
RETURNS [Relation];
Compare the strings, ignoring the case if specified.
CompareSubStrings:
PROC [s1, s2: SubString, ignoreCase:
BOOLEAN ←
TRUE]
RETURNS [Relation];
Compare the substrings, ignoring the case if specified.
DeleteSubString:
PROC [s: SubString]
RETURNS [String];
Delete the specified SubString from its parent string
EqualCharacter:
PROC [c: Character, s: String, index:
CARDINAL]
RETURNS [
BOOLEAN];
TRUE if the character indicated by the string index is equal to the given character. index is a logical character index, not a byte index.
EqualString,
EqualStrings:
PROC [s1, s2: String]
RETURNS [
BOOLEAN] =
INLINE {
RETURN[CompareStrings[s1, s2, FALSE] = equal]};
TRUE if the two strings are character-by-character equal.
EqualSubString,
EqualSubStrings:
PROC [s1, s2: SubString]
RETURNS [
BOOLEAN] =
INLINE {RETURN[CompareSubStrings[s1, s2, FALSE] = equal]};
TRUE if the two substrings are character-by-character equal.
EquivalentString,
EquivalentStrings:
PROC [s1, s2: String]
RETURNS [
BOOLEAN] =
INLINE {RETURN[CompareStrings[s1, s2] = equal]};
TRUE if the two strings are equal, disregarding case.
EquivalentSubString,
EquivalentSubStrings:
PROC [s1, s2: SubString]
RETURNS [BOOLEAN] = INLINE {RETURN[CompareSubStrings[s1, s2] = equal]};
TRUE if the two substrings are equal, disregarding case.
ScanForCharacter:
PROC [c: Character, s: String, start:
CARDINAL ← 0]
RETURNS [
CARDINAL];
Scans the string for the specified character from the given starting point. start and return value are logical character indices, not byte indices. Failure is indicated by returning LAST [CARDINAL].
UpperCase, LowerCase: PROC [c: Character] RETURNS [Character];
WellFormed:
PROC [s: String]
RETURNS [
BOOLEAN];
TRUE if the string contains a valid sequence of bytes.
STRING ALLOCATION/DEALLOCATION
MakeString:
PROC [bytes:
CARDINAL]
RETURNS [String];
Allocate a string with a maximum length of bytes and a current length of zero.
FreeString:
PROC [s: String];
Deallocate the specified string.
CopyString:
PROC [s: String]
RETURNS [String];
Allocate a string which is an exact copy of the specified string (although its maximum length may be less).
ExpandString:
PROCEDURE [s: String]
RETURNS [Characters];
Return the set of logical characters within the specified string.
FreeCharacters:
PROCEDURE [c: Characters];
Return storage allocated for logical character access to the specified zone.
ROUTINES FOR DEALING WITH TRUNCATED STRINGS
TruncateString:
PROC [s: String, bytes:
CARDINAL]
RETURNS [String];
Return the longest valid String whose length is less than or equal to MIN [s.length, bytes]. Note that the returned String refers to the same storage as that addressed by the String argument.
CompareStringsAndStems:
PROC [s1, s2: String, ignoreCase:
BOOLEAN ←
TRUE]
RETURNS [relation: Relation, equalStems:
BOOLEAN];
Compare the strings, ignoring the case if specified. "equalStems" is TRUE if the strings are equal at least up to the end of the shorter one.
CompareStringsTruncated:
PROC [s1, s2: String, trunc1, trunc2:
BOOLEAN ←
FALSE, ignoreCase:
BOOLEAN ←
TRUE]
RETURNS [Relation];
Compare the strings, ignoring the case if specified. If "truncN" is specified, the corresponding string is considered to be truncated and is treated as <string>*.
ROUTINES FOR INTERCONVERTING Strings AND Numbers
AppendDecimal:
PROC [s: String, n:
INTEGER]
RETURNS [String];
Converts the value of n to radix 10 text and appends it to s. Supplies a leading minus sign if n is negative.
AppendOctal:
PROC [s: String, n:
UNSPECIFIED]
RETURNS [String];
Converts the value of n to radix 8 text and appends it to s. Appends a "B".
AppendLongNumber:
PROC [s: String, n:
LONG
UNSPECIFIED, radix:
CARDINAL ← 10]
RETURNS [String];
Analgous to AppendNumber.
AppendLongDecimal:
PROC [s: String, n:
LONG
INTEGER]
RETURNS [String];
Analgous to AppendDecimal.
AppendNumber:
PROC [s: String, n:
UNSPECIFIED, radix:
CARDINAL ← 10]
RETURNS [String];
Converts the value of n to text using radix and appends it to s. radix sould be in the interval [2..36].
StringToDecimal:
PROC [s: String]
RETURNS [
INTEGER] =
INLINE
{ RETURN[StringToNumber[s, 10]]};
Converts the specified string to a decimal value. Raises InvalidNumber if s does not represent a valid decimal number.
StringToOctal: PROC [s: String] RETURNS [WORD] = INLINE {RETURN[StringToNumber[s, 8]]};
StringToLongNumber:
PROC [s: String, radix:
CARDINAL ← 10]
RETURNS [
LONG
UNSPECIFIED];
Analogous to StringToNumber, except it returns a LONG INTEGER instead of an UNSPECIFIED.
StringToNumber:
PROC [s: String, radix:
CARDINAL ← 10]
RETURNS [
UNSPECIFIED];
See PPM for details.
ROUTINES FOR INTERCONVERTING NSStrings AND MesaStrings
StringFromMesaString:
PROC [s: MesaString]
RETURNS [String];
Return a String which contains the same bytes as are in the Mesa string. Note that the data is not copied; the validity of the String depends on the continued existence of the Mesa string.
AppendToMesaString:
PROC [to: MesaString, from: String];
Append the bytes in the String to the end of the Mesa string. Note that some of these bytes may not actually be Mesa characters; use ValidAsMesaString to make sure, if desired.
ValidAsMesaString:
PROC [s: String]
RETURNS [
BOOLEAN];
TRUE if all characters in the string are valid Mesa characters.
DescribeString: Courier.Description;
Caveat: When deserializing a String, the maxlength may not be set to the correct value. It is only guaranteed to have a value >= the length of the string. The maxlength field may, of course, be set by the client after deserialization to match the length field.
-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ----
SIGNALS AND ERRORS :
-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ----
InvalidNumber: ERROR; -- raised by StringToDecimal if the characters do not represent a decimal number. This is a SIGNAL is String.mesa
InvalidString:
ERROR;
The string has an invalid format.
Overflow: ERROR; ++ this is defined as a SIGNAL in String.mesa, but isn't raised by anyone.
StringBoundsFault:
SIGNAL [old: String, increaseBy:
CARDINAL]
RETURNS [new: String];
The string is too small by increaseBy bytes; if desired, continue with a new one, after copying into it all old characters which were in the old string BEFORE the start of the operation raising StringBoundsFault. (See note before AppendCharacter.)
LOG ( date - person - action )
February 26, 1981 - Kabcenell - Creation.
- - - -
FILING 5.0 - - - -
1-Mar-82 14:07:59 - Hamilton - Add SubString and StringToDecimal stuff.
19-Apr-82 15:59:12 - Hamilton - Add remaining ops that String.mesa has and NSString.mesa doesn't.
August 2, 1982 - Hanzel - Define Characters, ExpandString, and Freecharacters in support of character-level access.
August 5, 1982 - Kiser - Added increaseBy to StringBoundsFault.
5-Aug-82 19:18:52 - Kabcenell - Changed order of arguments in ExpandString and FreeCharacters; made Characters a LONG DESCRIPTOR.
2-Sep-82 15:50:35 - Kiser - Made internal structure of Character visible; added DescribeString.
22-Sep-82 21:00:195 - Kiser - Changed NOTE comment: StringBoundsFault always leaves a well-formed string.