Module Interface Object

SUMMARY: MODULE | CLASS | TYPE | PROC | VAR | CONST | DETAIL: TYPE | PROC | VAR | CONST

# Object

This module provides the definitions for a basic object type used in most of the ADT library, and the implementation of the predefined type STRING.

Note: This module is a construction site. New type definitions and features are added on demand. If it is not used, it has no place here.

### Import List

Class List
Object | This class is the common base type of (almost) all classes defined in this module and the ADT library.
String |
String16 |
String8 |

Class Summary: Object [Detail]
      +--Object.Object
This class is the common base type of (almost) all classes defined in this module and the ADT library. It provides the methods Object.Equals and Object.HashCode. It is an abstract class without any state of its own. As such, it has no initialization procedure or cleanup method. String constants are assignment compatbile with variables of type Object. Such an assignment automatically converts the constant into an instance of String. That is, in an assignment, for a procedure argument passed to a value parameter, and as a function result, a string constant can be used instead of a String. The string object is created once, as part of the module's initialization code, not each time its surrounding code is evaluated.
Method Summary
Equals(Object): BOOLEAN Indicates whether some other object is "equal to" this one.
HashCode(): Hash Returns a hash code value for the object.
ToString(): String Returns a string representation of the object.

Class Summary: String [Detail]
      +---Object.Object
           |
           +--Object.String
Field Summary
length-: LONGINT Number of words points in the sequence.
Constructor Summary
Concat2(String, String): String Concatenates two strings.
NewUCS4(ARRAY OF UCS4CHAR): String Create a string value from str without any translation.
NewUCS4Char(UCS4CHAR): String Create a string value from ch.
NewUCS4Region(ARRAY OF UCS4CHAR, LONGINT, LONGINT): String Create a string value from ``str[start, end]`' without any translation.
NewUTF16(ARRAY OF LONGCHAR): String Create a string value from str without any translation.
NewUTF16Char(LONGCHAR): String Create a string value of length 1 from ``ch`' without any translation.
NewUTF16Region(ARRAY OF LONGCHAR, LONGINT, LONGINT): String Create a string value from ``str[start, end-1]`' without any translation.
Method Summary
CharAt(LONGINT): UCS4CHAR Return the character at position index.
Compare(Object): LONGINT Compares the two strings s and y.
Concat(String): String Concatenates strings s and t.
EndsWith(String): BOOLEAN Return TRUE is the last characters in s equal suffix.
Equals(Object): BOOLEAN Indicates whether some other object is "equal to" this one.
EqualsIgnoreCase(Object): BOOLEAN
HashCode(): Hash Returns a hash code value for the object.
IndexOf(UCS4CHAR, LONGINT): LONGINT Return the index of the first character matching char.
LastIndexOf(UCS4CHAR, LONGINT): LONGINT Return the index of the last character matching char.
NextChar(VAR LONGINT): UCS4CHAR Return the character at position index and increment index to point to the next character in the string.
StartsWith(String): BOOLEAN Return TRUE is the first characters in s equal prefix.
Substring(LONGINT, LONGINT): String Return the substring of s starting at start (inclusive) and ending at end (exclusive).
ToString(): String Identity operation returning s.
ToString16(): String16 Identity operation returning s as an instance of String16.
ToString8(CHAR): String8 Identity operation returning s if all characters are in the range of String8.
Trim(): String Return the substring beginning with the first character of s and ending with the last character of s with a code greater than space (``20X`').
Inherited Methods
From Object.Object: Equals, HashCode, ToString

Class Summary: String16 [Detail]
      +---Object.Object
           |
           +---Object.String
                |
                +--Object.String16
Inherited Fields
From Object.String: length
Method Summary
CharAt(LONGINT): UCS4CHAR Return the character at position index.
CharsUTF16(): CharsUTF16 Return a reference to the string's content.
Compare(Object): LONGINT Compares the two strings s and y.
Equals(Object): BOOLEAN Indicates whether some other object is "equal to" this one.
EqualsIgnoreCase(Object): BOOLEAN
HashCode(): Hash Returns a hash code value for the object.
IndexOf(UCS4CHAR, LONGINT): LONGINT Return the index of the first character matching char.
LastIndexOf(UCS4CHAR, LONGINT): LONGINT Return the index of the last character matching char.
NextChar(VAR LONGINT): UCS4CHAR Return the character at position index and increment index to point to the next character in the string.
Substring(LONGINT, LONGINT): String16 Return the substring of s starting at start (inclusive) and ending at end (exclusive).
ToString16(): String16 Identity operation returning s as an instance of String16.
ToString8(CHAR): String8 Identity operation returning s if all characters are in the range of String8.
Trim(): String16 Return the substring beginning with the first character of s and ending with the last character of s with a code greater than space (``20X`').
Inherited Methods
From Object.String: CharAt, Compare, Concat, EndsWith, Equals, EqualsIgnoreCase, HashCode, IndexOf, LastIndexOf, NextChar, StartsWith, Substring, ToString, ToString16, ToString8, Trim

Class Summary: String8 [Detail]
      +---Object.Object
           |
           +---Object.String
                |
                +--Object.String8
Inherited Fields
From Object.String: length
Constructor Summary
NewLatin1(ARRAY OF CHAR): String8 Create a string value from str without any translation.
NewLatin1Char(CHAR): String8 Create a string value of length 1 from ``ch`' without any translation.
NewLatin1Region(ARRAY OF CHAR, LONGINT, LONGINT): String8 Create a string value from ``str[start, end-1]`' without any translation.
Method Summary
CharAt(LONGINT): UCS4CHAR Return the character at position index.
CharsLatin1(): CharsLatin1 Return a reference to the string's content.
Compare(Object): LONGINT Compares the two strings s and y.
Equals(Object): BOOLEAN Indicates whether some other object is "equal to" this one.
EqualsIgnoreCase(Object): BOOLEAN
HashCode(): Hash Returns a hash code value for the object.
IndexOf(UCS4CHAR, LONGINT): LONGINT Return the index of the first character matching char.
LastIndexOf(UCS4CHAR, LONGINT): LONGINT Return the index of the last character matching char.
NextChar(VAR LONGINT): UCS4CHAR Return the character at position index and increment index to point to the next character in the string.
Substring(LONGINT, LONGINT): String8 Return the substring of s starting at start (inclusive) and ending at end (exclusive).
ToString16(): String16 Identity operation returning s as an instance of String16.
ToString8(CHAR): String8 Identity operation returning s if all characters are in the range of String8.
Trim(): String8 Return the substring beginning with the first character of s and ending with the last character of s with a code greater than space (``20X`').
Inherited Methods
From Object.String: CharAt, Compare, Concat, EndsWith, Equals, EqualsIgnoreCase, HashCode, IndexOf, LastIndexOf, NextChar, StartsWith, Substring, ToString, ToString16, ToString8, Trim

Type Summary
CharsLatin1 = POINTER TO ARRAY OF CHAR Note: The elements of this type should be considered read-only in importing modules, similar to read-only exported record fields.
CharsUTF16 = POINTER TO ARRAY OF LONGCHAR Note: The elements of this type should be considered read-only in importing modules, similar to read-only exported record fields.
Hash = LONGINT The integer type used to store hash values.
ObjectArray = ARRAY OF E
ObjectArrayPtr = POINTER TO ObjectArray E
StringArray = ARRAY OF String
StringArrayPtr = POINTER TO StringArray

Variable Summary
emptyString-: String Initialized with an instance of String8 holding the empty string.

Constant Summary
surrogateEnd First code after the surrogate area.
surrogateHigh Beginning of the high surrogate area.
surrogateLimit Starting with this code point, a Unicode character is mapped onto two 16-bit values in UTF-16.
surrogateLow Smallest code of the surrogate area, and the beginning of the low surrogate area.

Class Detail: Object

Method Detail

### Equals

    PROCEDURE (x: Object) Equals(y: Object): BOOLEAN

> Indicates whether some other object is "equal to" this one.

> The Object.Equals method implements an equivalence relation:

> - It is reflexive: for any reference value ``x`', ``x.Equals(x)`' should return TRUE.

> - It is symmetric: for any reference values ``x`' and ``y`', ``x.Equals(y)`' should return TRUE if and only if ``y.Equals(x)`' returns TRUE.

> - It is transitive: for any reference values ``x`', ``y`', and ``z`', if ``x.Equals(y)`' returns TRUE and ``y.Equals(z)`' returns TRUE, then ``x.Equals(z)`' should return TRUE.

> - It is consistent: for any reference values ``x`' and ``y`', multiple invocations of ``x.Equals(y)`' consistently return TRUE or consistently return FALSE, provided no information used in equals comparisons on the object is modified.

> - For any non-NIL reference value ``x`', ``x.Equals(NIL)`' should return FALSE.

> The ``Equals`' method for class Object implements the most discriminating possible equivalence relation on objects; that is, for any reference values ``x`' and ``y`', this method returns TRUE if and only if ``x`' and ``y`' refer to the same object (``x=y`' has the value TRUE).

### HashCode

    PROCEDURE (x: Object) HashCode(): Hash

> Returns a hash code value for the object. This method is supported for the benefit of dictionaries such as those provided by ADT:Dictionary..

> The general contract of Object.HashCode is:

> - Whenever it is invoked on the same object more than once during an execution of an application, the Object.HashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.

> - If two objects are equal according to the Object.Equals method, then calling the Object.HashCode method on each of the two objects must produce the same integer result.

> - It is not required that if two objects are unequal according to the Object.Equals method, then calling the Object.HashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of dictionaries.

> As much as is reasonably practical, the Object.HashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required.)

### ToString

    PROCEDURE (x: Object) ToString(): String

> Returns a string representation of the object. Typically, the string is some form of "natural" representation of the value. For complex objects, it should describe the type and essential attributes of the object. The exact format of the returned value is intentionally left vague.

Class Detail: String

Field Detail

### length

    FIELD length-: LONGINT

> Number of words points in the sequence. For an instance of String8, this is the number of characters in the string. For String16, it is the number of 16-bit words in the sequence. This number may differ from the number of characters in the presence of surrogate pairs.

Constructor Detail

### Concat2

    PROCEDURE Concat2(s1: String;
                      s2: String): String

> Concatenates two strings.

> Pre-condition: Neither s1 nor s2 is NIL.

### NewUCS4

    PROCEDURE NewUCS4(str: ARRAY OF UCS4CHAR): String

> Create a string value from str without any translation.

> Pre-condition: The characters in str are Unicode 3.1 code points outside the surrogate areas.

### NewUCS4Char

    PROCEDURE NewUCS4Char(ch: UCS4CHAR): String

> Create a string value from ch. The length of the string instance is 2 if ``ch >= surrogateLimit`', and 1 otherwise.

> Pre-condition: ch is a Unicode code point.

### NewUCS4Region

    PROCEDURE NewUCS4Region(str: ARRAY OF UCS4CHAR;
                            start: LONGINT;
                            end: LONGINT): String

> Create a string value from ``str[start, end]`' without any translation.

> Pre-condition: ``0 <= start <= end <= LEN(str)`'. All characters are Unicode 3.1 code points outside the surrogate areas.

### NewUTF16

    PROCEDURE NewUTF16(str: ARRAY OF LONGCHAR): String

> Create a string value from str without any translation.

> Pre-condition: The characters in str are Unicode 3.1 code points outside the surrogate areas.

### NewUTF16Char

    PROCEDURE NewUTF16Char(ch: LONGCHAR): String

> Create a string value of length 1 from ``ch`' without any translation.

> Pre-condition: ch is a Unicode 3.1 code point outside the surrogate areas.

### NewUTF16Region

    PROCEDURE NewUTF16Region(str: ARRAY OF LONGCHAR;
                             start: LONGINT;
                             end: LONGINT): String

> Create a string value from ``str[start, end-1]`' without any translation.

> Pre-condition: ``0 <= start <= end <= LEN(str)`'. The characters in str are Unicode 3.1 code points outside the surrogate areas.

Method Detail

### CharAt

    PROCEDURE (s: String) CharAt(index: LONGINT): UCS4CHAR

> Return the character at position index.

> Pre-condition: ``0 <= index < s.length`'

### Compare

    PROCEDURE (s: String) Compare(y: Object): LONGINT

> Compares the two strings s and y. The sign of the result signals if s is less than, equal to, or greater than y:

> s < y | ==> < 0
> s = y | ==> > 0
> s > y | ==> > 0

> Pre-condition: y is not NIL.

### Concat

    PROCEDURE (s: String) Concat(t: String): String

> Concatenates strings s and t.

> Pre-condition: t is not NIL.

### EndsWith

    PROCEDURE (s: String) EndsWith(suffix: String): BOOLEAN

> Return TRUE is the last characters in s equal suffix. Result is FALSE if ``s.length < suffix.length`'.

> Pre-condition: ``suffix # NIL`'

### Equals

    PROCEDURE (s: String) Equals(y: Object): BOOLEAN

> Indicates whether some other object is "equal to" this one.

> The Object.Equals method implements an equivalence relation:

> - It is reflexive: for any reference value ``x`', ``x.Equals(x)`' should return TRUE.

> - It is symmetric: for any reference values ``x`' and ``y`', ``x.Equals(y)`' should return TRUE if and only if ``y.Equals(x)`' returns TRUE.

> - It is transitive: for any reference values ``x`', ``y`', and ``z`', if ``x.Equals(y)`' returns TRUE and ``y.Equals(z)`' returns TRUE, then ``x.Equals(z)`' should return TRUE.

> - It is consistent: for any reference values ``x`' and ``y`', multiple invocations of ``x.Equals(y)`' consistently return TRUE or consistently return FALSE, provided no information used in equals comparisons on the object is modified.

> - For any non-NIL reference value ``x`', ``x.Equals(NIL)`' should return FALSE.

> The ``Equals`' method for class Object implements the most discriminating possible equivalence relation on objects; that is, for any reference values ``x`' and ``y`', this method returns TRUE if and only if ``x`' and ``y`' refer to the same object (``x=y`' has the value TRUE).

> [Description inherited from Equals]

> Redefines: Equals

### EqualsIgnoreCase

    PROCEDURE (s: String) EqualsIgnoreCase(y: Object): BOOLEAN

### HashCode

    PROCEDURE (s: String) HashCode(): Hash

> Returns a hash code value for the object. This method is supported for the benefit of dictionaries such as those provided by ADT:Dictionary..

> The general contract of Object.HashCode is:

> - Whenever it is invoked on the same object more than once during an execution of an application, the Object.HashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.

> - If two objects are equal according to the Object.Equals method, then calling the Object.HashCode method on each of the two objects must produce the same integer result.

> - It is not required that if two objects are unequal according to the Object.Equals method, then calling the Object.HashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of dictionaries.

> As much as is reasonably practical, the Object.HashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required.)

> [Description inherited from HashCode]

> Redefines: HashCode

### IndexOf

    PROCEDURE (s: String) IndexOf(char: UCS4CHAR;
                      pos: LONGINT): LONGINT

> Return the index of the first character matching char. Search starts at pos and progresses to the end of the string s. If no matching character is found, result is ``-1`'.

> Pre-condition: ``0 <= pos <= s.length`'

### LastIndexOf

    PROCEDURE (s: String) LastIndexOf(char: UCS4CHAR;
                          pos: LONGINT): LONGINT

> Return the index of the last character matching char. Search starts with the character before pos and progresses to the beginning of the string s. If no matching character is found, result is ``-1`'.

> Pre-condition: ``0 <= pos <= s.length`'

### NextChar

    PROCEDURE (s: String) NextChar(VAR index: LONGINT): UCS4CHAR

> Return the character at position index and increment index to point to the next character in the string. If index equals the length of the string, then result is ``0X`'.

> Pre-condition: ``0 <= index <= s.length`'

### StartsWith

    PROCEDURE (s: String) StartsWith(prefix: String): BOOLEAN

> Return TRUE is the first characters in s equal prefix. Result is FALSE if ``s.length < prefix.length`'.

> Pre-condition: ``prefix # NIL`'

### Substring

    PROCEDURE (s: String) Substring(start: LONGINT;
                        end: LONGINT): String

> Return the substring of s starting at start (inclusive) and ending at end (exclusive). The length of the result is ``end-start`'.

> Pre-condition: ``0 <= start <= end <= s.length`'

### ToString

    PROCEDURE (s: String) ToString(): String

> Identity operation returning s.

> Redefines: ToString

### ToString16

    PROCEDURE (s: String) ToString16(): String16

> Identity operation returning s as an instance of String16.

### ToString8

    PROCEDURE (s: String) ToString8(replace: CHAR): String8

> Identity operation returning s if all characters are in the range of String8. Otherwise, characters outside this range are substituted with replace.

### Trim

    PROCEDURE (s: String) Trim(): String

> Return the substring beginning with the first character of s and ending with the last character of s with a code greater than space (``20X`'). If s contains no such characters, then result is the empty string.

Class Detail: String16

Method Detail

### CharAt

    PROCEDURE (s: String16) CharAt(index: LONGINT): UCS4CHAR

> Return the character at position index.

> Pre-condition: ``0 <= index < s.length`'

> [Description inherited from CharAt]

> Redefines: CharAt

### CharsUTF16

    PROCEDURE (s: String16) CharsUTF16(): CharsUTF16

> Return a reference to the string's content. The characters from the index range ``[0, s.length[`' hold valid data. The character at position s.length is 0X.

### Compare

    PROCEDURE (s: String16) Compare(y: Object): LONGINT

> Compares the two strings s and y. The sign of the result signals if s is less than, equal to, or greater than y:

> s < y | ==> < 0
> s = y | ==> > 0
> s > y | ==> > 0

> Pre-condition: y is not NIL.

> [Description inherited from Compare]

> Redefines: Compare

### Equals

    PROCEDURE (s: String16) Equals(y: Object): BOOLEAN

> Indicates whether some other object is "equal to" this one.

> The Object.Equals method implements an equivalence relation:

> - It is reflexive: for any reference value ``x`', ``x.Equals(x)`' should return TRUE.

> - It is symmetric: for any reference values ``x`' and ``y`', ``x.Equals(y)`' should return TRUE if and only if ``y.Equals(x)`' returns TRUE.

> - It is transitive: for any reference values ``x`', ``y`', and ``z`', if ``x.Equals(y)`' returns TRUE and ``y.Equals(z)`' returns TRUE, then ``x.Equals(z)`' should return TRUE.

> - It is consistent: for any reference values ``x`' and ``y`', multiple invocations of ``x.Equals(y)`' consistently return TRUE or consistently return FALSE, provided no information used in equals comparisons on the object is modified.

> - For any non-NIL reference value ``x`', ``x.Equals(NIL)`' should return FALSE.

> The ``Equals`' method for class Object implements the most discriminating possible equivalence relation on objects; that is, for any reference values ``x`' and ``y`', this method returns TRUE if and only if ``x`' and ``y`' refer to the same object (``x=y`' has the value TRUE).

> [Description inherited from Equals]

> Redefines: Equals, Equals

### EqualsIgnoreCase

    PROCEDURE (s: String16) EqualsIgnoreCase(y: Object): BOOLEAN

> Redefines: EqualsIgnoreCase

### HashCode

    PROCEDURE (s: String16) HashCode(): Hash

> Returns a hash code value for the object. This method is supported for the benefit of dictionaries such as those provided by ADT:Dictionary..

> The general contract of Object.HashCode is:

> - Whenever it is invoked on the same object more than once during an execution of an application, the Object.HashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.

> - If two objects are equal according to the Object.Equals method, then calling the Object.HashCode method on each of the two objects must produce the same integer result.

> - It is not required that if two objects are unequal according to the Object.Equals method, then calling the Object.HashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of dictionaries.

> As much as is reasonably practical, the Object.HashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required.)

> [Description inherited from HashCode]

> Redefines: HashCode, HashCode

### IndexOf

    PROCEDURE (s: String16) IndexOf(char: UCS4CHAR;
                      pos: LONGINT): LONGINT

> Return the index of the first character matching char. Search starts at pos and progresses to the end of the string s. If no matching character is found, result is ``-1`'.

> Pre-condition: ``0 <= pos <= s.length`'

> [Description inherited from IndexOf]

> Redefines: IndexOf

### LastIndexOf

    PROCEDURE (s: String16) LastIndexOf(char: UCS4CHAR;
                          pos: LONGINT): LONGINT

> Return the index of the last character matching char. Search starts with the character before pos and progresses to the beginning of the string s. If no matching character is found, result is ``-1`'.

> Pre-condition: ``0 <= pos <= s.length`'

> [Description inherited from LastIndexOf]

> Redefines: LastIndexOf

### NextChar

    PROCEDURE (s: String16) NextChar(VAR index: LONGINT): UCS4CHAR

> Return the character at position index and increment index to point to the next character in the string. If index equals the length of the string, then result is ``0X`'.

> Pre-condition: ``0 <= index <= s.length`'

> [Description inherited from NextChar]

> Redefines: NextChar

### Substring

    PROCEDURE (s: String16) Substring(start: LONGINT;
                        end: LONGINT): String16

> Return the substring of s starting at start (inclusive) and ending at end (exclusive). The length of the result is ``end-start`'.

> Pre-condition: ``0 <= start <= end <= s.length`'

> [Description inherited from Substring]

> Redefines: Substring

### ToString16

    PROCEDURE (s: String16) ToString16(): String16

> Identity operation returning s as an instance of String16.

> [Description inherited from ToString16]

> Redefines: ToString16

### ToString8

    PROCEDURE (s: String16) ToString8(replace: CHAR): String8

> Identity operation returning s if all characters are in the range of String8. Otherwise, characters outside this range are substituted with replace.

> [Description inherited from ToString8]

> Redefines: ToString8

### Trim

    PROCEDURE (s: String16) Trim(): String16

> Return the substring beginning with the first character of s and ending with the last character of s with a code greater than space (``20X`'). If s contains no such characters, then result is the empty string.

> [Description inherited from Trim]

> Redefines: Trim

Class Detail: String8

Constructor Detail

### NewLatin1

    PROCEDURE NewLatin1(str: ARRAY OF CHAR): String8

> Create a string value from str without any translation.

> Pre-condition: The characters in str are Latin-1 code points.

### NewLatin1Char

    PROCEDURE NewLatin1Char(ch: CHAR): String8

> Create a string value of length 1 from ``ch`' without any translation.

> Pre-condition: ch is a Latin-1 code point.

### NewLatin1Region

    PROCEDURE NewLatin1Region(str: ARRAY OF CHAR;
                              start: LONGINT;
                              end: LONGINT): String8

> Create a string value from ``str[start, end-1]`' without any translation.

> Pre-condition: ``0 <= start <= end <= LEN(str)`'. The characters in str are Latin-1 code points.

Method Detail

### CharAt

    PROCEDURE (s: String8) CharAt(index: LONGINT): UCS4CHAR

> Return the character at position index.

> Pre-condition: ``0 <= index < s.length`'

> [Description inherited from CharAt]

> Redefines: CharAt

### CharsLatin1

    PROCEDURE (s: String8) CharsLatin1(): CharsLatin1

> Return a reference to the string's content. The characters from the index range ``[0, s.length[`' hold valid data. The character at position s.length is 0X.

### Compare

    PROCEDURE (s: String8) Compare(y: Object): LONGINT

> Compares the two strings s and y. The sign of the result signals if s is less than, equal to, or greater than y:

> s < y | ==> < 0
> s = y | ==> > 0
> s > y | ==> > 0

> Pre-condition: y is not NIL.

> [Description inherited from Compare]

> Redefines: Compare

### Equals

    PROCEDURE (s: String8) Equals(y: Object): BOOLEAN

> Indicates whether some other object is "equal to" this one.

> The Object.Equals method implements an equivalence relation:

> - It is reflexive: for any reference value ``x`', ``x.Equals(x)`' should return TRUE.

> - It is symmetric: for any reference values ``x`' and ``y`', ``x.Equals(y)`' should return TRUE if and only if ``y.Equals(x)`' returns TRUE.

> - It is transitive: for any reference values ``x`', ``y`', and ``z`', if ``x.Equals(y)`' returns TRUE and ``y.Equals(z)`' returns TRUE, then ``x.Equals(z)`' should return TRUE.

> - It is consistent: for any reference values ``x`' and ``y`', multiple invocations of ``x.Equals(y)`' consistently return TRUE or consistently return FALSE, provided no information used in equals comparisons on the object is modified.

> - For any non-NIL reference value ``x`', ``x.Equals(NIL)`' should return FALSE.

> The ``Equals`' method for class Object implements the most discriminating possible equivalence relation on objects; that is, for any reference values ``x`' and ``y`', this method returns TRUE if and only if ``x`' and ``y`' refer to the same object (``x=y`' has the value TRUE).

> [Description inherited from Equals]

> Redefines: Equals, Equals

### EqualsIgnoreCase

    PROCEDURE (s: String8) EqualsIgnoreCase(y: Object): BOOLEAN

> Redefines: EqualsIgnoreCase

### HashCode

    PROCEDURE (s: String8) HashCode(): Hash

> Returns a hash code value for the object. This method is supported for the benefit of dictionaries such as those provided by ADT:Dictionary..

> The general contract of Object.HashCode is:

> - Whenever it is invoked on the same object more than once during an execution of an application, the Object.HashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.

> - If two objects are equal according to the Object.Equals method, then calling the Object.HashCode method on each of the two objects must produce the same integer result.

> - It is not required that if two objects are unequal according to the Object.Equals method, then calling the Object.HashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of dictionaries.

> As much as is reasonably practical, the Object.HashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required.)

> [Description inherited from HashCode]

> Redefines: HashCode, HashCode

### IndexOf

    PROCEDURE (s: String8) IndexOf(char: UCS4CHAR;
                      pos: LONGINT): LONGINT

> Return the index of the first character matching char. Search starts at pos and progresses to the end of the string s. If no matching character is found, result is ``-1`'.

> Pre-condition: ``0 <= pos <= s.length`'

> [Description inherited from IndexOf]

> Redefines: IndexOf

### LastIndexOf

    PROCEDURE (s: String8) LastIndexOf(char: UCS4CHAR;
                          pos: LONGINT): LONGINT

> Return the index of the last character matching char. Search starts with the character before pos and progresses to the beginning of the string s. If no matching character is found, result is ``-1`'.

> Pre-condition: ``0 <= pos <= s.length`'

> [Description inherited from LastIndexOf]

> Redefines: LastIndexOf

### NextChar

    PROCEDURE (s: String8) NextChar(VAR index: LONGINT): UCS4CHAR

> Return the character at position index and increment index to point to the next character in the string. If index equals the length of the string, then result is ``0X`'.

> Pre-condition: ``0 <= index <= s.length`'

> [Description inherited from NextChar]

> Redefines: NextChar

### Substring

    PROCEDURE (s: String8) Substring(start: LONGINT;
                        end: LONGINT): String8

> Return the substring of s starting at start (inclusive) and ending at end (exclusive). The length of the result is ``end-start`'.

> Pre-condition: ``0 <= start <= end <= s.length`'

> [Description inherited from Substring]

> Redefines: Substring

### ToString16

    PROCEDURE (s: String8) ToString16(): String16

> Identity operation returning s as an instance of String16.

> [Description inherited from ToString16]

> Redefines: ToString16

### ToString8

    PROCEDURE (s: String8) ToString8(replace: CHAR): String8

> Identity operation returning s if all characters are in the range of String8. Otherwise, characters outside this range are substituted with replace.

> [Description inherited from ToString8]

> Redefines: ToString8

### Trim

    PROCEDURE (s: String8) Trim(): String8

> Return the substring beginning with the first character of s and ending with the last character of s with a code greater than space (``20X`'). If s contains no such characters, then result is the empty string.

> [Description inherited from Trim]

> Redefines: Trim

Type Detail

### CharsLatin1

    TYPE CharsLatin1 = POINTER TO ARRAY OF CHAR

> Note: The elements of this type should be considered read-only in importing modules, similar to read-only exported record fields.

### CharsUTF16

    TYPE CharsUTF16 = POINTER TO ARRAY OF LONGCHAR

> Note: The elements of this type should be considered read-only in importing modules, similar to read-only exported record fields.

### Hash

    TYPE Hash = LONGINT

> The integer type used to store hash values.

### ObjectArray

    TYPE ObjectArray = ARRAY OF E

### ObjectArrayPtr

    TYPE ObjectArrayPtr = POINTER TO ObjectArrayE

### StringArray

    TYPE StringArray = ARRAY OF String

### StringArrayPtr

    TYPE StringArrayPtr = POINTER TO StringArray

Variable Detail

### emptyString

    VAR emptyString-: String

> Initialized with an instance of String8 holding the empty string.

Constant Detail

### surrogateEnd

    CONST surrogateEnd

> First code after the surrogate area.

### surrogateHigh

    CONST surrogateHigh

> Beginning of the high surrogate area.

### surrogateLimit

    CONST surrogateLimit

> Starting with this code point, a Unicode character is mapped onto two 16-bit values in UTF-16.

### surrogateLow

    CONST surrogateLow

> Smallest code of the surrogate area, and the beginning of the low surrogate area.