The Simons     Component Library

           

---

String Class Reference

#include <String.h>

Inheritance diagram for String:

List of all members.

---

Detailed Description

String: a compact sequence of characters.

A String is a kind of Sequence that stores all of its Character elements in a compact memory block. A String is most efficient for reading, writing, searching and concatenating blocks of text. Individual Character elements may be inserted or removed individually, but this is less efficient, using general Sequence methods. A String is indexed from 0..n-1 where n is the size() of the String. The memory used to store elements may expand to accommodate more elements. A String may be constructed from a literal Character string and from all the basic types. A String may be converted back to values of basic types. A String may be searched for single Characters, substrings and bags of Characters.

Public Member Functions
	String ()
	Construct an empty String.
virtual	~String ()
	Destroy and release a String.
	String (const Character *)
	Construct a String from a Character array.
	String (CollectionID)
	Copy a String from a Collection of Characters.
	String (Boolean)
	Construct a String from a Boolean.
	String (Character)
	Construct a String from a Character.
	String (Natural)
	Construct a String from a Natural.
	String (Integer)
	Construct a String from an Integer.
	String (Decimal, Natural=5)
	Construct a String from a Decimal.
virtual ObjectID	clone () const
	Clone a deep copy of this String.
virtual Natural	hash () const
	Return a quasi-unique hash code for this String.
virtual Order	compare (ObjectID) const
	Compare this String with another Object.
Order	compare (StringID) const
	Compare this String with another String.
virtual Void	readOn (ReaderID)
	Read this String on a Reader stream.
virtual Void	writeOn (WriterID) const
	Write this String on a Writer stream.
virtual Natural	size () const
	Return the size of this String.
virtual ObjectID	getAt (Integer) const
	Return the ith Character of this String as an Object.
virtual Void	putAt (Integer, ObjectID)
	Replace a Character, supplied as an Object, at the ith index position.
virtual Void	addAt (Integer, ObjectID)
	Insert a Character, supplied as an Object, at the ith index position.
virtual Void	removeAt (Integer)
	Remove the Character at the ith index position.
Boolean	has (Character) const
	Test if this String contains a given Character.
virtual Boolean	has (ObjectID) const
	Test if this String contains a given Character, supplied as an Object.
Void	addAll (StringID)
	Add all the elements of another String to this String.
virtual Void	addAll (CollectionID)
	Add all the elements of another Collection to this String.
Character	getValue (Integer) const
	Return the ith Character in a String.
Void	putValue (Integer, Character)
	Replace the Character at the ith index position.
Integer	indexOf (Character, Integer=0) const
	Find the next index of a Character in this String after a given index.
Integer	indexOfString (StringID, Integer=0) const
	Find the next index of a substring in this String after a given index.
Integer	indexOfBag (StringID, Integer=0) const
	Find the next index of a Character bag in this String, after a given index.
StringID	subString (Integer) const
	Return a substring starting at an index.
StringID	subString (Integer, Natural) const
	Return a substring of a given length starting at an index.
Boolean	toBoolean () const
	Convert String contents to a Boolean value.
Character	toCharacter () const
	Convert String contents to a Character value.
Natural	toNatural () const
	Convert String contents to a Natural value.
Integer	toInteger () const
	Convert String contents to an Integer value.
Decimal	toDecimal () const
	Convert String contents to a Decimal value.
const Character *	value () const
	Return the Character array encapsulated in this String.
Protected Member Functions
	String (const String &)
	Copy another String.
	String (const String &, Natural)
	Copy a prefix of another String.

---

Constructor & Destructor Documentation

String::String (  const String &  string  )  [protected]

Copy another String. Allocates sufficient capacity to hold all the contents of the other String and takes a deep copy of the primitive Character array managed by the other String, setting the terminating null byte at index size(). Required by C++ and used by other public String methods. Parameters: string  - the String to copy. Returns: the copied String.

String::String (  const String &  string, Natural  count )  [protected]

Copy a prefix of another String. Allocates sufficient capacity to hold the requested prefix of the other String and copies that number of Character elements from the other String, setting the terminating null byte at index size(). Used by the subString() method. Parameters: string  - the String to copy. count  - the number of Characters to copy. Returns: the copied String.

String::String (   )

Construct an empty String. Does not allocate any storage, but sets the internal primitive Character pointer to refer to a static array containing the empty character string. Returns: an empty String.

String::~String (   )  [virtual]

Destroy and release a String. If this String allocated some storage, deletes the primitive Character array managed by this String. If this String was empty and referred to the static empty character string, does nothing.

String::String (  const Character *  literal  )

Construct a String from a Character array. Allocates sufficient capacity to hold all the contents of the primitive array and copies the array's contents, setting the terminating null byte at index size(). This is the standard constructor for initialising String objects from literal Character data. Parameters: literal  - a pointer to a literal Character array. Returns: a String copy of the Character array.

String::String (  CollectionID  collection  )

Copy a String from a Collection of Characters. Does not initially allocate any storage, but constructs an empty String, then calls addAll() to include the contents of the other Collection, which is expected to contain Characters. If this is the case, this String allocates sufficient capacity to store the contents of the other Collection and copies its Characters. Otherwise, a TypeFailure exception is raised on this String, which remains empty. Parameters: collection  - the Collection containing Characters. Returns: a String copy of the Collection.

String::String (  Boolean  value  )

Construct a String from a Boolean. Converts a Boolean into the String "true" or "false". Allocates storage exactly and sets the terminating null byte. Parameters: value  - a Boolean value. Returns: a String containing "true" or "false".

String::String (  Character  value  )

Construct a String from a Character. Converts a Character into a unit length String containing the Character. Allocates storage exactly and sets the terminating null byte. Parameters: value  - a Character value Returns: a String of unit size containing the Character.

String::String (  Natural  number  )

Construct a String from a Natural. Converts a Natural number into its String representation. Allocates storage exactly and sets the terminating null byte. Implementation note: assumes that no representable number will exceed 20 characters in length. Parameters: number  - a Natural number. Returns: a String representation of the Natural number.

String::String (  Integer  number  )

Construct a String from an Integer. Converts an Integer number into its String representation. Allocates storage exactly and sets the terminating null byte. Implementation note: assumes that no representable number will exceed 20 characters in length. Parameters: number  - an Integer number. Returns: a String representation of the Integer number.

String::String (  Decimal  number, Natural  places = 5 )

Construct a String from a Decimal. Converts a Decimal number into its String representation, rounding to a given number of decimal places. Rounds to 5 decimal places by default, with a maximum precision of 9 places. Truncates any trailing zeros in the fractional part. Allocates sufficient storage to hold the sign, the decimal point, and the integral and fractional parts of the number. Sets the terminating null byte. Implementation note: assumes that no integral number will exceed 20 characters in length. Parameters: number  - a Decimal number. places  - the precision, from 0..9 decimal places. Returns: a String representation of the Decimal number.

---

Member Function Documentation

Void String::addAll (  CollectionID  collection  )  [virtual]

Add all the elements of another Collection to this String. If the other Collection is a String, concatenates the String's contents directly, after adjusting the capacity of this String to accommodate the other String's contents. Otherwise, iterates over the elements of the other Collection using item() up to the limit size() and uses add() to insert individual elements into this String. Raises a TypeFailure exception if any element of the other Collection is not a CharacterBox, but preserves the state of this String immediately prior to the failure. Parameters: collection  - the Collection whose elements are to be added. Reimplemented from Collection.

Void String::addAll (  StringID  string  )

Add all the elements of another String to this String. This method is highly efficient. If this String has sufficient capacity, concatenates the other String's contents directly. Otherwise, doubles the capacity until this exceeds the required capacity and concatenates the other String's contents. Implementation note: this method is safe even if this and the other String are identical. Parameters: string  - the String whose elements are to be added.

Void String::addAt (  Integer  index, ObjectID  object )  [virtual]

Insert a Character, supplied as an Object, at the ith index position. Part of the Sequence protocol, this method allows a String to be treated like a Sequence of Objects. The argument must be a CharacterBox. All existing Characters from the index position to the end of the String are moved up by one position and the new Character is inserted at the vacant index position. If the capacity of the String is exceeded, a larger memory block is allocated. Raises an OutOfRange exception if the index is out of range. Parameters: index  - an Integer index. object  - a CharacterBox. Reimplemented from Sequence.

ObjectID String::clone (   )  const [virtual]

Clone a deep copy of this String. This returns a deep copy, rather than the default shallow copy, so that clients may freely modify the returned String. Returns: a deep copy of this String. Reimplemented from Object.

Order String::compare (  StringID  string  )  const

Compare this String with another String. Lexicographic comparison, based on the alphabetical order of the two Strings. This String is considered LESS than, EQUAL to, or MORE than the other String if it appears before, in the same place, or after the other in the alphabet, respectively. Parameters: string  - a String. Returns: an Order in {LESS, EQUAL, MORE}.

Order String::compare (  ObjectID  object  )  const [virtual]

Compare this String with another Object. Generic comparison that tries to convert the other Object into a String and then proceeds to compare according to the lexicographic ordering of characters. If the other Object is not a String, the comparison is undefined and the result is NONE. Parameters: object  - an Object Returns: an Order in { NONE, LESS, EQUAL, MORE }. Reimplemented from Sequence.

ObjectID String::getAt (  Integer  index  )  const [virtual]

Return the ith Character of this String as an Object. Part of the Sequence protocol, this method allows a String to be treated like a Sequence of Objects. The result is wrapped in a CharacterBox. Raises an OutOfRange exception if the index is out of range. Parameters: index  - an index. Returns: the ith Character, in a CharacterBox. Reimplemented from Sequence.

Character String::getValue (  Integer  index  )  const

Return the ith Character in a String. This returns the simple Character value directly. May raise an OutOfRange exception if the index is out of range. Parameters: index  - an Integer index. Returns: the ith Character.

Boolean String::has (  ObjectID  object  )  const [virtual]

Test if this String contains a given Character, supplied as an Object. Part of the Collection protocol, this method allows a String to be treated just like any other Collection. The argument must be a CharacterBox. Otherwise, a TypeFailure exception is raised. Parameters: object  - a CharacterBox. Returns: true if this String contains the Character, otherwise false. Reimplemented from Collection.

Boolean String::has (  Character  character  )  const

Test if this String contains a given Character. Scans the String in linear time searching for the Character. Parameters: character  - a Character. Returns: true if this String contains the Character, otherwise false.

Natural String::hash (   )  const [virtual]

Return a quasi-unique hash code for this String. Uses the famous P J Weinberger hashing algorithm from Aho, Sethi and Ullman, p 436. The result is based both on the value and the ordering of the Characters. For each Character, the result so far is shifted left by 4 bits, then the next Character ASCII code is added. If this sets any of the four high-order bits, these are stripped, shifted right by 24 bits and XORed with the result. Returns: a quasi-unique hash code. Reimplemented from Sequence.

Integer String::indexOf (  Character  character, Integer  index = 0 )  const

Find the next index of a Character in this String after a given index. Searches for the Character in this String starting at the given index. If the starting index is omitted, this defaults to 0 and the search is from the beginning of this String. Parameters: character  - a character to search for. index  - a starting index from which to search. Returns: the index of the Character, or -1 if the Character is not found.

Integer String::indexOfBag (  StringID  characterBag, Integer  index = 0 )  const

Find the next index of a Character bag in this String, after a given index. If the starting index is omitted, this defaults to 0 and the search is from the beginning of this String. Parameters: characterBag  - a bag of characters, as a String. index  - a starting index from which to search. Returns: the index of the character bag, or -1 if no Character from the character bag could be found.

Integer String::indexOfString (  StringID  substring, Integer  index = 0 )  const

Find the next index of a substring in this String after a given index. Searches for a substring in this String starting at the given index. If the starting index is omitted, this defaults to 0 and the search is from the beginning of this String. Parameters: substring  - a substring to search for. index  - a starting index from which to search. Returns: the index of the substring, or -1 if the substring is not found.

Void String::putAt (  Integer  index, ObjectID  object )  [virtual]

Replace a Character, supplied as an Object, at the ith index position. Part of the Sequence protocol, this method allows a String to be treated like a Sequence of Objects. The argument must be a CharacterBox. Otherwise, a TypeFailure exception is raised and this String is not modified. Raises an OutOfRange exception if the index is out of range. Parameters: index  - an Integer index. object  - a CharacterBox. Reimplemented from Sequence.

Void String::putValue (  Integer  index, Character  character )

Replace the Character at the ith index position. The argument is a simple Character. May raise an OutOfRange exception if the index is out of range. Parameters: index  - an Integer index. character  - the replacement Character.

Void String::readOn (  ReaderID  in  )  [virtual]

Read this String on a Reader stream. String is a leaf-Object in any Object cluster. It determines its size from the Reader, then allocates a block large enough to hold that number of Character s and reads them in as a single block. Parameters: in  - a Reader stream. Reimplemented from Collection.

Void String::removeAt (  Integer  index  )  [virtual]

Remove the Character at the ith index position. Part of the Sequence protocol, this method allows a String to be treated like any other Sequence of Objects. All existing characters from the index+1 position to the end of the String are moved down by one position. The removed Character is overwritten. May raise an OutOfRange exception if the index is out of range. Parameters: index  - an Integer index. Reimplemented from Sequence.

Natural String::size (   )  const [virtual]

Return the size of this String. Returns the active String length, which is the number of Character elements up to, but not including, the terminating null byte. Returns: the Character count. Reimplemented from Collection.

StringID String::subString (  Integer  index, Natural  count )  const

Return a substring of a given length starting at an index. If the index is valid, creates a new String which copies this String's Character sequence starting from the index position, for at most the requested Character count. If this String is shorter, copies to the end of this String. Parameters: index  - the index from which to start copying. count  - the number of Character s to copy. Returns: a sub-String of this String.

StringID String::subString (  Integer  index  )  const

Return a substring starting at an index. If the index is valid, creates a new String which copies this String's Character sequence from the index position to the end of this String. Otherwise, raises an OutOfRange exception. Parameters: index  - the index from which to start copying. Returns: a sub-String of this String.

Boolean String::toBoolean (   )  const [virtual]

Convert String contents to a Boolean value. Succeeds if this String does indeed represent a Boolean value, otherwise raises a TypeFailure exception. Returns: the Boolean value represented by this String. Reimplemented from Object.

Character String::toCharacter (   )  const [virtual]

Convert String contents to a Character value. Succeeds if this String does indeed store a single Character value, otherwise raises a TypeFailure exception. Returns: the Character value represented by this String. Reimplemented from Object.

Decimal String::toDecimal (   )  const [virtual]

Convert String contents to a Decimal value. Succeeds if this String does indeed represent a Decimal value, otherwise raises a TypeFailure exception. Returns: the Decimal value represented by this String. Reimplemented from Object.

Integer String::toInteger (   )  const [virtual]

Convert String contents to an Integer value. Succeeds if this String does indeed represent an Integer value, otherwise raises a TypeFailure exception. Returns: the Integer value represented by this String. Reimplemented from Object.

Natural String::toNatural (   )  const [virtual]

Convert String contents to a Natural value. Succeeds if this String does indeed represent a Natural value, otherwise raises a TypeFailure exception. Returns: the Natural value represented by this String. Reimplemented from Object.

const Character * String::value (   )  const

Return the Character array encapsulated in this String. This method is not intended to be used by clients, but is provided so that Stream classes, such as TextOutput, can access the primitive data. Note that the returned primitive Character array is constant. Returns: a primitive Character array.

Void String::writeOn (  WriterID  out  )  const [virtual]

Write this String on a Writer stream. String is a leaf-Object in any Object cluster. It expects the Writer to encode its size in the header then writes its Character s out as a single block. Parameters: out  - a Writer stream. Reimplemented from Collection.

---

The documentation for this class was generated from the following files:

• String.h
• Basic.cc
• String.cc

---