edu.vub.at.objects
Interface Text

 Text

ATText is the public interface to a native AmbientTalk string (a string of characters). Extends the ATExpression interface since a Text can also be output by the parser as a literal.

Author:

tvc

Method Summary

Number	<=>(Text other) Returns the value of evaluating the generalized equality between this text and a given one.
Text	+(Object other) Concatenation infix operator.
Boolean	~=(Text other) Attempts to match this text against a given regular expression.
Table	explode() Explodes a text into a table of constituent characters.
Nil	find:do:(Text regexp, Closure consumer) Evaluates a given closure on those elements of this text that match a given regular expression.
Number	length() Returns the length of this text.
Numeric	parseNumeric() Tries to convert the text into a numeric object (a number or a fraction).
Text	replace:by:(Text regexp, Closure transformer) Returns a new text replacing those elements of this text that match a given regular expression with the value resulting of the evaluation of a given closure.
Table	split(Text regexpr) Splits a text according to the given regular expression.
Text	toLowerCase() Converts all of the characters in this text to lower case.
Number	toNumber() Converts a single AmbientTalk character (i.e. a text of length 1) into its corresponding numeric Unicode value.
Text	toUpperCase() Converts all of the characters in this text to upper case.

Methods inherited from interface edu.vub.at.objects.AbstractGrammar

freeVariables

Methods inherited from interface edu.vub.at.objects.Object

super

Method Detail

explode

Table explode()

Explodes a text into a table of constituent characters.

Usage example: "ambienttalk".explode() returns [a, m, b, i, e, n, t, t, a, l, k]

Returns:

an Table resulting of exploding the receiver text into a table of constituent characters.

split

Table split(Text regexpr)

Splits a text according to the given regular expression.

For regular expression syntax, see the Java regular-expression constructs in java.util.regex.Pattern. For regular expression syntax, see the Apache Regexp API of class RE.

Usage example: "one, two, three".split(", ") returns [ "one", "two", "three" ]

Parameters:

regexpr - a text representing the regular expression to apply in the split.

Returns:

an Table resulting of splitting the receiver text into a table according to the given regular expression.

Throws:

edu.vub.at.exceptions.XIllegalArgument - if regular expression's syntax is invalid.

find:do:

Nil find:do:(Text regexp,
             Closure consumer)

Evaluates a given closure on those elements of this text that match a given regular expression.

For regular expression syntax, see the Apache Regexp API of class RE.

Usage example: "ambienttalk".find: "[aeiou]" do: { |vowel| buff << vowel; nil } returns buff = "aiea"

Parameters:

regexp - a text representing the regular expression to be found in the text.

consumer - the closure code that is applied each time the regular expression is matched in the text.

Returns:

nil

Throws:

edu.vub.at.exceptions.XIllegalArgument - if regular expression's syntax is invalid.

edu.vub.at.exceptions.InterpreterException - if raised inside the code closure.

replace:by:

Text replace:by:(Text regexp,
                 Closure transformer)

Returns a new text replacing those elements of this text that match a given regular expression with the value resulting of the evaluation of a given closure.

For regular expression syntax, see the Apache Regexp API of class RE.

Usage example: "ambienttalk".replace: "[aeiou]" by: { |vowel| vowel.toUpperCase() } returns AmbIEnttAlk

Parameters:

regexp - a text representing the regular expression to be found in the text.

transformer - the closure code that is applied each time the regular expression matches.

Returns:

Text replacing those elements of the table that match the regexpr pattern with the value resulting of the evaluation of the transformer closure.

Throws:

edu.vub.at.exceptions.XIllegalArgument - if regular expression's syntax is invalid.

edu.vub.at.exceptions.InterpreterException - if raised inside the code closure.

toUpperCase

Text toUpperCase()

Converts all of the characters in this text to upper case.

Returns:

the Text resulting of the conversion.

toLowerCase

Text toLowerCase()

Converts all of the characters in this text to lower case.

Returns:

the Text resulting of the conversion.

length

Number length()

Returns the length of this text.

Returns:

the Number representing the length of the sequence of characters of this text.

+

Text +(Object other)

Concatenation infix operator. Returns the concatenation of the this text and the text representing a given object.

Usage example: "ambient" + "talk" returns "ambienttalk"

Parameters:

other - an object whose text representation is concatenated to the receiver text.

Returns:

an ATText containing the elements of the receiver text and then the elements of text representing the other object.

<=>

Number <=>(Text other)

Returns the value of evaluating the generalized equality between this text and a given one.

The generalized equality returns:

• -1 if the receiver is numerically greater than the text passed as argument.
• 1 if the receiver is numerically smaller than the text passed as argument.
• 0 if the receiver is numerically equal to the the text passed as argument.

Usage example: "ambienttalk" <=> "ambienttalk" returns 0

Parameters:

other - a text.

Returns:

a Number resulting of applying the generalized equality between the receiver and other.

~=

Boolean ~=(Text other)

Attempts to match this text against a given regular expression.

For regular expression syntax, see the Apache Regexp API of class RE.

Usage example: "ambienttalk" ~= ".*tt.*" returns true

Parameters:

other - a text representing the regular expression to be found in the text.

Returns:

true if and only if, the receiver text matches completely the other text pattern.

Throws:

edu.vub.at.exceptions.XIllegalArgument - if regular expression's syntax is invalid.

parseNumeric

Numeric parseNumeric()

Tries to convert the text into a numeric object (a number or a fraction). Example: "1.0".parseNumeric() => 1.0

Returns:

the numeric object denoted by this text

Throws:

edu.vub.at.exceptions.XIllegalArgument - if the text cannot be converted into a number or a fraction

toNumber

Number toNumber()

Converts a single AmbientTalk character (i.e. a text of length 1) into its corresponding numeric Unicode value. See Character.getNumericValue(char).

Returns:

a number that represents the unicode value of the text character

Throws:

XTypeMismatch - if the receiver text is not a character (i.e. if it has length() > 1)