Vision Class: String

Overview

Strings are objects that represent sequences of characters. Strings respond to messages that format, parse, and perform comparisons with other strings. The literal representation of a string is a sequence of characters delimited by double quotes. For example:

"xyz"
"a"
"The Vision language is fun"

Any character may be included in a string. If you need to include a double quote in the string, it must be escaped using the '\' character to avoid confusion with the string delimiters. For example:

  "He said, \"The Vision language is fun\" "

returns the string:

  He said, "The Vision language is fun"

The String class is a direct subclass of the class Ordinal:

  Object
     |
     Ordinal
        |
        String

Basic String Messages

The following messages perform basic String operations. Except where noted, these messages return a String object. Note that the original string is never modified; a new string object is returned.

Message	Definition	Sample
count	Number of characters in string returned as an Integer	"xyz" count
drop:	Drop parameter characters from beginning or end of recipient	"xyz" drop: 2 .
take:	Take parameter characters from beginning or end of recipient	"xyz" take: 2 .
concat:	Concatenate the parameter string to the recipient	"xyz" concat: "abc"
at:	Return single character at position indicated by parameter	"xyz" at: 2 .
contains:	Return boolean indicating if recipient contains parameter	"whatAmI" contains: "what" .

Formatting Messages

Many messages defined for the class String allow you to reformat the strings in a variety of ways. These messages all return a String object. Note that the original string is never modified; a new string object is returned.

The following messages provide different ways to pad strings:

Message	Definition	Sample
center:	Center recipient over parameter columns	"xyz" center: 80 .
fill:	Repeat characters in recipient until string of parameter length is formed	"xyz" fill: 20 .
pad:	Pad recipient with blanks until string of parameter length is formed	"xyz" pad: 20 .

The following messages provide different ways to strip characters out of strings:

Message	Definition	Sample
stripChar:	Remove the characters in parameter from recipient	"abacadae" stripChar: "ad" .
stripBoundingBlanks	Remove blanks from start and end of recipient	" xyz " stripBoundingBlanks
stripLeadingBlanks	Remove blanks from start of recipient	" xyz " stripLeadingBlanks
stripTrailingBlanks	Remove blanks from end of recipient	" xyz " stripTrailingBlanks

The following messages provide some basic reformatting operations:

Message	Definition	Sample
asQuotedString	Returns recipient surrounded by quote characters	"xyz" asQuotedString
capitalize	Capitalize first letter in recipient	"xyz" capitalize
lowercase	Change first letter in recipient to a lower case letter	"Xyz" lowercase
reverse	Reverse order of characters in recipient	"xyz" reverse
toLower	Convert all letters in recipient to lower case	"XYZ" toLower
toUpper	Convert all letters in recipient to upper case	"xyz" toUpper
at:put:	Insert string supplied as second parameter at position in recipient indicated by first parameter	"xyz" at: 2 put: "abc"
translate:to:	Replace all occurrences of character supplied as first parameter with string supplied as second parameter	"xyz" translate: "x" to: "a" .

Parsing Input And Output Messages

Many messages defined for the class String allow you to read and parse input files and generate output files.

The following messages provide different ways to read in files. More detailed samples are available.

Message	Definition	Sample
asFileContents	Interpret recipient as a file name and return file's contents as a single string	"myFile" asFileContents
asRecords	Interpret recipient as a file name and return contents as a list of strings where each element corresponds to a row in the file	"myFile" asRecords
asCSVRecords	Interpet recipient as a file name for a file in comma-separated-value format and return contents as a list of strings where each element corresponds to a row in the file and each element is extended by the message fields which returns a list of strings	"myFile" asCSVRecords
asOpenVisionChannel	Convert recipient containing a channel specification in form type,options:resource to an OpenVisionChannel	"file:/tmp/file1.dat" asOpenVisionChannel

The following messages provide string parsing operations that are useful for processing strings representing the contents of data files. More detailed samples are available.

Message	Definition	Sample
asLines	Convert recipient to list of strings breaking original on new line character	"myFile" asFileContents asLines
asWords	Convert recipient to list of strings breaking original on tab, space, and new line characters	"multi word string" asWords
breakOn:	Convert recipient to list of strings breaking original on any character in parameter	"1,2,3,4,5" breakOn: "," .
cbreakOn:	Convert recipient to list of strings breaking original on any character not in parameter	"1xyz3" cbreakOn: "1234567890" .
asCells	Convert recipient to list of strings corresponding to records where each record is extended by cells which breaks each element into a list of strings using tab and octal 377	"myFile" asFileContents asCells
asCellsOn:	Convert recipient to list of strings corresponding to records where each record is extended by cells which breaks each element into a list of strings using characters in parameter as break points.	"myFile" asFileContents asCellsOn: "," .

The following messages provide different ways to output files. More detailed samples are available.

Message	Definition	Sample
substituteOutputOf:	Interpret recipient as a file name and output all printing encountered in parameter, a block, to this file	"outFile" substituteOutputOf: [ ] ;
appendOutputOf:	Interpret recipient as a file name and append all printing encountered in parameter, a block, to the end of this file	"outFile" appendOutputOf: [ ] ;
filterOutputOf:	Interpret recipient as a program name and supply all printing encountered in parameter, a block, as input	"myProgram" filterOutputOf: [ ] ;

Conversion Messages

Several messages have been defined to convert an instance of String to an instance of another class:

Message	Definition	Sample
asCurrency	Convert recipient to an instance of Currency	"USD" asCurrency
asInteger	Convert recipient to an integer	"123" asInteger
asNumber	Convert recipient to a number	"123.45" asNumber
convertToNumber	Remove non-numeric characters from start and end of recipient and any commas from remaining string and convert to a number	"123,456.78" convertToNumber
toList	Convert recipient to a list of one character strings	"abcdef" toList

Several messages have been defined to convert a String into a Vision program. The program can be run immediately or returned as a Block that can be evaluated at a later time.

Message	Definition	Sample
evaluate	Interpret the recipient as Vision code and run it	"whatAmI" evaluate
evaluateIn:	Interpret the recipient as Vision code and run it in the context of parameter	"whatAmI" evaluateIn: Currency .
asBlock	Convert recipient to a block	"whatAmI" asBlock value
asBlockIn:	Convert recipient to a block in the context of parameter	"whatAmI" asBlockIn: Named Currency USD . value

Comparison Messages

The following messages perform basic comparison operations between the recipient and parameter string values. These messages return an instance of the Boolean class except where noted.

Message	Definition	Sample
=	Is recipient equal to parameter?	"y" = ("xy" at: 2)
==	Is recipient identical to parameter?	"y" == ("xy" at: 2)
!=	Is recipient not equal to parameter?	"y" != ("y" at: 2)
!==	Is recipient not identical to parameter?	"y" !== ("y" at: 2)
<	Is recipient less than parameter?	"x" < "y"
<=	Is recipient less than or equal to parameter?	"x" <= "y"
>	Is recipient greater than parameter?	"x" > "y"
>=	Is recipient greater than or equal to parameter?	"x" >= "y"
between:and:	Is recipient value between two parameter values?	"b" between: "a" and: "c" .
inRange:	Is recipient value in the range implied by the parameter, a list of two elements representing the start and end of the range inclusively?	"b" inRange: "a","c" .
inSet:	Is recipient equal to one of the values in the parameter, a list containing one or more elements?	"b" inSet: "a","b","c" .
notBetween:and:	Is recipient value not between two parameter values?	"b" notBetween: "a" and: "c" .
max:	Returns the larger of recipient and parameter value	"a" max: "b" .
min:	Returns the smaller of recipient and parameter value	"a" min: "b" .

String Identity

Warning!! Two strings with the same content may not be the same object. For example:
  !string1 <- "abc" ;
  !string2 <- "ABC" toLower ;
  (string1 = string2) printNL ;
  (string1 == string2) printNL ;
Strings are equal (i.e., = ) when they have the same content. Strings are identical (i.e., == ) when they are the same object. Strings that are created directly in quotes or by manipulating string objects produce distinct objects.

The groupedBy: message defined for Collections requires strings to be identical if they are to be included in the same group. The groupedByString: variation relaxes this constraint and uses string equality as the basis for groups. If you want to use a string object as an index in an IndexedList, you need to use the identical string to access the element from the list.

Several techniques are available to preserve string identity. For example, suppose you wanted to rate each currency with an A, B, or C value. You could create class constants to hold unique versions of the strings:

  #-- define constant
  Currency define: 'ratingA' toBe: "A" ;
  Currency define: 'ratingB' toBe: "B" ;
  Currency define: 'ratingC' toBe: "C" ;

  #-- define property
  Currency defineFixedProperty: 'rating' ;

  #-- assign values
  Named Currency send: [ USD, CAD ] .
     do: [ :rating <- ratingA ] ;

  #-- compare
  (Named Currency USD rating == Named Currency CAD rating) printNL ;

The US and Canadian currencies will have identical values for their rating.

You can create a Dictionary to hold an unique version of the string:

  #--  create dictionary
  Currency define: "StringLookup" toBe: Dictionary new ;
  Currency StringLookup at: "A" put: "A" ;
  Currency StringLookup at: "B" put: "B" ;
  Currency StringLookup at: "C" put: "C" ;

  #-- define property
  Currency defineFixedProperty: 'rating' ;

  #-- assign values
  Named Currency send: [ USD, CAD ] .
     do: [ :rating <- StringLookup at: "A" ] ;

  #-- compare
  (Named Currency USD rating == Named Currency CAD rating) printNL ;

Alternatively, you could create a new class of rating values and assign each value to an entry in this table as illustrated below:

  Entity createSubclass: "Rating" ;
  Rating createInstance: "A" ; 
  Rating createInstance: "B" ; 
  Rating createInstance: "C" ; 
  Named Currency USD :rating <- Named Rating A ; 
  Named Currency CAD :rating <- Named Rating A ;

Additional Substring Messages

Many additional messages that support substring operations are defined for the class String:

The following messages return a substring of the recipient:

Message	Definition	Sample
from:to:	Extracts substring from position parameter1 to position parameter2	"abcdef" from: 2 to: 4 .
from:for:	Extracts substring from position parameter1 for number of characters indicated by parameter2	"abcdef" from: 2 for: 3 .
from:	If parameter is a number, extracts substring from this position to end; if parameter is a string, extracts from first occurrence to end	"abcdef" from: "b" .
to:	If parameter is a number, extracts substring from beginning to this position; if parameter is a string, extracts from beginning to its first occurrence	"abcdef" to: "b" .

The following messages are inquiries about the recipient and return a Boolean value:

Message	Definition	Sample
isBlank	Is recipient blank?	" abc" isBlank
isBlankFor:	Are the first parameter characters of recipient blank?	" abc" isBlankFor: 2 .
contains:	Does recipient contain parameter as a substring? (wildcards are recognized)	"whatAmI" contains: "^what" .
containsSubstring:	Does recipient contain parameter as a substring? (wildcards viewed as literals)	"whatAmI" containsSubstring: "^what"

The following messages return integer values representing a position or a length:

Message	Definition	Sample
findPatternExtent:	Length of parameter if present in recipient, interpretting wildcards	"abcdef" findPatternExtent: "[a-c][a-c]" .
findSubstringExtent:	Length of parameter if present in recipient, viewing wildcards as literals	"abcdef" findSubstringExtent: "[a-c][a-c]" .
findPatternOrigin:	Zero-based position of first occurrence of parameter in recipient, interpretting wildcards	"ab^c" findPatternOrigin: "^c" .
findSubstringOrigin:	Zero-based position of first occurrence of parameter in recipient, viewing wildcards as literals	"ab^c" findSubstringOrigin: "^c" .
findPatternSuffix:	Zero-based position of first character after first occurrence of parameter in recipient, interpretting wildcards	"ab^cd" findPatternSuffix: "^c" .
findSubstringSuffix:	Zero-based position of first character after first occurrence of parameter in recipient, viewing wildcards as literals	"ab^cd" findSubstringSuffix: "^c" .
startingPositionOf:	Position of first occurrence of parameter in recipient	"abc" startingPositionOf: "bc" .
startingPositionsOf:	List of position numbers at which parameter starts in recipient	"abcdbcebc" startingPositionsOf: "bc" .
prefixNotSpannedBy:	Number of characters at start of recipientthat do not match any character in parameter	"abc" prefixNotSpannedBy: "cdefg" .
prefixSpannedBy:	Number of characters at start of recipient that match any character in parameter	"abc" prefixSpannedBy: "aeiou" .

String Clustering

Currently in development ..