String API Functions

This document lists most useful (and most often needed) functions. Be aware, that there are many more to be found in either the class references or via the builtin class browser.

Reference: String inherits from: CharacterArray Collection

Back to Useful API Functions

Notice: unless when written otherwise, all indices are 1-based. Valid indices range from 1 to the string's size.

Literals (i.e. Constant Strings)

'...'

Smalltalk style string (as is; no escapes for special characters). Be aware, that this is inconvenient, if newlines, tabs or other non-graphical characters are to be in the string.

c'...'

C style string (supports the usual C-escapes, such as "\n" for newline, "\t" for tab or "\xHH" for hex codes). Backslashes and single quotes must be prefixed by a backslash (which is especially needed when a string prepresents a Windows pathname).

e'...{expr}...'

C style with embedded expressions. These expressions are evaluated and sliced into the string.
Example:

a := 1234.
b := true.
c := 'hello'.
foo := e'{c}; this string contains embedded exprs.\nYes, {b} and {a} are there.'
foo
   -> e'hello; this string contains embedded exprs.
Yes, true and 1234 are there.'

Queries

aString size
aString.size() [JS]

Returns the number of characters in the string (i.e. the string's length).

Example:

 'hello world' size
 => 11

Accessing

aString at:index
aString[índex] [JS]

Returns the character at an index.

Example:

 'hello world' at:2
 => $e

Copying

aString copyFrom:startIndex to: endIndex
aString.copyFrom_to(startIndex, endIndex) [JS]

Copies characters from a start index to an end index.

Example:

 'hello world' copyFrom:1 to:5. 
 => 'hello'

aString copyFrom:startIndex count:numChars
aString.copyFrom_count(startIndex, numChars) [JS]

Copies a number of characters starting at the given index.

Example:

 'hello world' copyFrom:7 count:3. 
 => 'wor'

aString copyFrom:startIndex'
aString.copyFrom(startIndex) [JS]

Copies from the given index to the end.

Example:

 'hello world' copyFrom:6. 
 => ' world'

aString copyTo:endIndex
aString.copyTo( endIndex ) [JS]

Copies from the start to the given index.

Example:

 'hello world' copyTo:6. 
 => 'hello '

aString copyLast:count
aString.copyLast( count ) [JS]

Copies the last count characters.

Example:

 'hello world' copyLast:4. 
 => 'world '

aString copyButFirst:count
aString.copyButFirst( count ) [JS]

Copies except for the first count characters.

Example:

 'hello world' copyButFirst:4. 
 => ' world'

aString copyButLast:count
aString.copyButLast( count ) [JS]

Copies except for the last count characters.

Example:

 'hello world' copyButLast:4. 
 => 'hello w'

aString copyBetween:leftString and:rightString caseSensitive:boolean
aString.copyBetween_and_caseSensitive(leftString, rightString, boolean ) [JS]

Finds two substrings and copies the part between them.

Example:

 'hello small world' copyBetween:'hello' and:'world' caseSensitive:true
 => ' small '

 'helloworld' copyBetween:'hello' and:'world' caseSensitive:true
 => 

 'hello small World' copyBetween:'hello' and:'world' caseSensitive:true
 => nil

 'hello small World' copyBetween:'hello' and:'world' caseSensitive:false
 => ' small '

aString copyReplaceString:oldString withString:newString
aString.copyReplaceString_withString( oldString, newString ) [JS]

Example:

 'hello small world' copyReplaceString:'small' withString:'big' 
 => ' hello big world '

 'hello small world' copyReplaceString:'big' withString:'bigger' 
 => ' hello small world '

aString withoutPrefix:prefixString [ caseSensitive: boolean ]

aString.withoutPrefix[_caseSensitive]( prefixString [, boolean ]) [JS]

If string starts with a prefix-string, return a copy without it. Otherwise return the original string.

Example:

 'hello small world' withoutPrefix:'hello ' 
 => ' small world '

 'small world' withoutPrefix:'hello '
 => ' small world '

aString withoutSuffix:suffixString [ caseSensitive: boolean' ]'
aString.withoutSuffix[_ caseSensitive]( suffixString [, boolean ) [JS]

If string ends with a prefix-string, return a copy without it. Otherwise return the original string.

Example:

 'hello small world' withoutSuffix:' world' 
 => ' hello small'

 'hello small' withoutSuffix:' world'
 => ' hello small '

Concatenation

string1 , string2
string1 + string2 [JS]

concatenates two strings

Example:

 'hello', ' ' , 'world'
 => 'hello world'

Splitting

aString splitBy:aCharacter
aString.splitBy( aCharacter ) [JS]

Splits a string into pieces, given a splitting character.

Example:

 'hello world here are six words' splitBy: $      <- trailing space here
 => #( 'hello' 'world' 'here' 'are' 'six' 'words')

 'hello-world here are six-words' splitBy: $-
 => #( 'hello' 'world here are six' 'words')

aString splitOn:aCharacter
string1 splitOn:string2
string1 splitOn:regex
aString splitOn:[:char | <condition-expression on char> ]
aString.splitOn( aCharacter ) [JS]
string1.splitOn( string2 ) [JS]
aString.splitOn( (char) => <condition-expression on char> ) [JS]

Splits a string into pieces, given a splitter.
The splitter may be a single character, a string, a regular expression or a block, which returns true to split.
This is a more general version of the above "splitBy:", for complex splits.

Example:

 'hello world here are six words' splitOn: $      <- trailing space here
 => #( 'hello' 'world' 'here' 'are' 'six' 'words')

 'hello-world here are six-words' splitOn: $-
 => #( 'hello' 'world here are six' 'words')

 'hello world and goodbye world' splitOn: ' and '
 => #( 'hello world' 'goodbye world')

 'hello-world, commas and semis; here' splitOn: [:ch | (ch == $,) or:[ ch == $; ]]
 => #( 'hello-world' 'çommas and semis' 'here')

 'aWordWithCamelCase' splitOn: [:ch | ch isUppercase ]
 => #( 'a' 'Word' 'With' 'Camel' 'Case')

 'aWordWithCamelCase' splitOn: #isUppercase
 => #( 'a' 'Word' 'With' 'Camel' 'Case')

 '123abc456def789' splitOn:'[a-z]*' asRegex 
 => #('123' '456' '789')

 "hello world here are six words".splitOn( $' ' )    <- space character here
 => [ "hello" , "world" , "here" , "are" , "six" , "words" ]

 "hello world and goodbye world".splitOn(" and ")
 => [ "hello world" , "goodbye world"]

 "123abc456def789".splitOn("[a-z]*" asRegex) 
 => [ "123" "456" "789" ]

 "hello-world, commas and semis; here".splitOn( (ch) => (ch == $',') || ( ch == $';') )
 => [ "hello-world" , "çommas and semis" , "here"]

Case Conversion

aString asLowercase
aString asUppercase
aString asUppercaseFirst
aString.asUppercase() [JS]
aString.asLowercase() [JS]
aString.asUppercaseFirst() [JS]

Covert to lowercase, uppercase

Example:

 'HELLO' asLowercase
 => 'hello'

 'hello' asUppercase
 => 'HELLO'

 'hello' asUppercaseFirst
 => 'Hello'

Comparing

string1 sameAs:string2
string1.sameAs( string2 ) [JS]

Compares two strings, ignoring case.
"caselessEqual:"is an alias which performs the same operation.

Example:

 'HELLO' sameAs: 'HeLlo'
 => true

 'HELxO' sameAs: 'HeLlo'
 => false

 'HELLO' caselessEqual: 'HeLlo'
 => true

string1 caselessBefore:string2
string1 caselessAfter:string2
string1.caselessBefore( string2 ) [JS]
string1.caselessAfter( string2 ) [JS]

Compare two strings, ignoring case.

Example:

 'HELLO' caselessBefore: 'world'
 => true

 'bce' caselessBefore: 'abc'
 => false

string1 startsWith:prefixString
string1 startsWith:prefixString caseSensitive: boolean
string1.startsWith( prefixString ) [JS]
string1.startsWith_caseSensitive( prefixString, boolean ) [JS]

Checks if a string starts with another string.

Comes in two variants, one being strict, the other with optional case-insensitivity.

Example:

 'hello' startsWith: 'hel'
 => true

 'Hello' startsWith: 'hel'
 => false

 'Hello' startsWith: 'hel' caseSensitive: false
 => true

 'Hexlo' startsWith: 'hel' caseSensitive: false
 => false

string1 endsWith:prefixString
string1 endsWith:prefixString caseSensitive:boolean

Checks if a string ends with another string.
Comes in two variants, one being strict, the other with optional case-insensitivity.

Example:

 'hello' endsWith: 'lo'
 => true

 'Hello' endsWith: 'Lo'
 => false

 'Hello' endsWith: 'Lo' caseSensitive: false
 => true

 'Hexlo' endsWith: 'LX' caseSensitive: false
 => false

Searching

aString indexOf:aCharacter
aString lastIndexOf:aCharacter

Returns the first/last index of an element (a character). Returns 0 if not found.

Example:

 'HELLO' indexOf: $L
 => 3

 'HELLO' indexOf: $x
 => 0

 'HELLO' lastIndexOf: $L
 => 4

aString indexOf:aCharacter startingAt:startIndex
aString lastIndexOf:aCharacter startingAt:startIndex

Returns the next/previous index of an element (a character) given a search start index .
Returns 0 if not found.

Example:

 'HELLO WORLD' indexOf: $O startingAt: 6
 => 8

 'HELLO WORLD' indexOf: $x startingAt: 6
 => 0

 'HELLO WORLD' indexOf: $L startingAt: 6
 => 0

 'HELLO WORLD' lastIndexOf: $O startingAt: 7
 => 5

aString indexOfAny:aCollectionOfCharacters [ startingAt:startIndex ]

aString lastIndexOfAny:aCollectionOfCharacters [ startingAt:startIndex ]

Similar to the above, but searches for any element in the given argument collection. This may be a string (of characters) or an array or any other collection of characters.
Returns 0 if not found.

Example:

 'HELLO, WORLD' indexOfAny: ',;'
 => 6

 'HELLO; WORLD' indexOfAny: ',;'
 => 6

 'HELLO; WORLD' indexOfAny: #( $, $; )
 => 6

 'HELLO. WORLD' indexOfAny: #( $, $; )
 => 0

aString indexOfSeparator
aString indexOfSeparatorStartingAt:startIndex

Searches for a whitespace character (Space, Tab, CR or NL).
Returns 0 if not found.

Example:

 'HELLO WORLD' indexOfSeparator
 => 6

 'HELLO WORLD' indexOfSeparatorStartingAt: 7
 => 0

aString indexOfString:aSubstring [ startingAt:startIndex ]
aString lastIndexOfString:aSubstring [ startingAt:startIndex ]

Returns the first/last index of an element (a character). Returns 0 if not found.

Example:

 'HELLO' indexOfString:'LL'
 => 3

 'HELLO' indexOfString: 'LX'
 => 0

 'HELLO BELLO' lastIndexOfString: 'LL'
 => 9

Pattern Matching

aString matches:patternString [ caseSensitive:boolean ]

True if a string matches a GLOB match pattern.

Example:

 'HELLO world' matches: 'HE*'
 => true

 'HELLO world' matches: 'he*'
 => false

 'HELLO world' matches: 'he*' caseSensitive: false
 => true

aString matchesRegex:patternString [ caseSensitive:boolean ]

True if a string matches a regex pattern.

Example

 'HELLO world' matchesRegex: 'H.*O'
 => true

 'HELLO world' matchesRegex: 'h.*o'
 => false

 'HELLO world' matchesRegex: 'h.*o' caseSensitive: false
 => true

Converting

aString asByteArray

Returns a byte array containing the codePoints (ISO8859 codes).

The characters must be within the ISO8859 range 0x00 .. 0xFF.

Example:

 'abc123' asByteArray
 => #[97 98 99 49 50 51]

 'äöü' asByteArray
 => #[228 246 252]

aString asFilename

Returns a filename instance, which provides functions top operate on files and directories.
See "Filename protocol" for its functions.

Example:

 'c:\data.txt' asFilename modificationTime
 => 2017-07-28 10:31:23

 '/etc' asFilename exists
 => true

aStringWithMultipleLines asCollectionOfLines

Returns a collection of strings, each containing one line from the original string. Handles any combination of CR, LF or CRLF as line separator. The resulting line-collection can then be further processed using functions from the Collection protocol.

Example:

 'data.txt' asFilename contents asCollectionOfLines
 => #( 'line1' 'line2' 'line3' ... )

Encoding / Decoding

aString utf8Encoded

Encode / decode into/from utf8 encoding.

Example:

 'äöü' utf8Encoded
 => 'äöü'

 'äöü' utf8Encoded asByteArray
 => #[195 164 195 182 195 188]

 'äöü' utf8Encoded utf8Decoded
 => 'äöü'

aString base64Encoded

Encode / decode into/from base64 encoding.

Example:

 'äöü' base64Encoded
 => '5Pb8'

 'äöü' base64Encoded asByteArray
 => #[53 80 98 56]

 'äöü' base64Encoded base64Decoded
 => #[228 246 252]

 'äöü' base64Encoded base64Decoded asString
 => 'äöü'

---

Copyright © 2014-2024 eXept Software AG