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.

See also "String Handling" in Expecco_API.
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" and "\uHHHH" for hex codes). Backslashes and single quotes must be prefixed by a backslash (which is especially needed when a string represents a Windows pathname). For example, the literal c'abc\u2021def' represents the characters "abc‡def".

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

C style with embedded expressions. In addition to C-style escapes, expressions in braces are embedded. These expressions are evaluated and their string representation (i.e. the printString, which is Smalltalk's equivalent of toString in JS) 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
   -> 'hello; this string contains embedded exprs.
       Yes, true and 1234 are there.'

i'...{expr}...'

C style with embedded expressions and automatic nationalization. First, it is expanded as a C-style string. Then a translation is looked up in the currently loaded language resources. The template searched has successive expression positions replaced by "%i".

For example, the literal "i'Hello {name}'" will look for a translation of "Hello %1" in the language pack, and may find one of "Hallo %1", "Hola %1", etc. depending on your current language setting. Then the variable "name" is converted to a string and sliced on, finally generating "Hallo Tom" or "Hola Tom" etc.

Translations are loaded from resource files in the "resources" folder.

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

aString bitsPerCharacter

Returns one of {8, 16, 32}.

aString isWideString

Same as "aString bitsPerCharacter > 8""

aString containsNon7BitAscii'

true if aString is either a wide string, or contains any character above the 7bit Ascii range (i.e. a national character in the ISO8859 charset)

Accessing

aString at: index

aString [ índex ]   [ST/X *]

aString [ índex ]   [JS]

Returns the character at an index (1-based; valid indices are [1 .. size]).

Example:

 'hello world' at:2
 => $e

aString at: index put: char

aString [ índex ] := char   [ST/X *]

aString [ índex ] = char   [JS]

Changes the character at an index (1-based; valid indices are [1 .. size]).
Notice that string constants (and freeze values) are immutable (i.e. readonly strings). Only strings which have been created dynamically can be modified.

• ) this non-ANSI-Smalltalk syntax is supported by Smalltalk/X and thus also valid in expecco.

Copying

aString copy

Generates a mutable copy.

Example:

 'hello world' copy at:1 
 => $h

aString copyFrom: startIndex to: endIndex

aString.copyFrom_to( startIndex, endIndex )   [JS]

Copies characters from a start index to an end index (1-based; valid indices are [1 .. size]).

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
 => '' (an empty string)

 '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]

the Smalltalk comma operator¹ and the JavaScript plus operator concatenate two strings

Example:

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

¹⁾Although in theory, the plus operator could have been overloaded in Smalltalk as well, this was not done for readability reasons: using a comma makes it clear that the intention is string concatenation and not addition.

Splitting

aString splitBy: aCharacter

aString.splitBy( aCharacter ) [JS]

Splits a string into pieces, given a splitting character. The result is a collection containing the parts.

Examples:

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

 'hello world here are six words' splitBy: (Character space) <- no invisible space
 => #( '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: #<name of 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/the name of an element-method, which returns true to split.
This is a more general version of the above "splitBy:", for complex splits.

Examples:

 'hello here are five words' splitOn: $      <- trailing space here
 => #( 'hello' 'here' 'are' 'five' '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, commas and semis; here' splitOn: [:ch | (ch == $,) or:[ ch == $; ]]
 => #( 'hello' 'commas and semis' 'here')

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

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

 c'some text\twith\ndifferent separators' splitOn: #isSeparator
 => #( 'some' 'text' 'with' 'different' 'separators')

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

 "hello here are five words".splitOn( $' ' )    <- space character here
 => [ "hello" , "here" , "are" , "five" , "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 caselessEqual: 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). The index is 1-based; 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

aString lastIndexOfSeparator

aString lastIndexOfSeparatorStartingAt: startIndex

Searches for the first/last whitespace character (Space, Tab, CR or NL).
Returns 0 if not found.

Example:

 'HELLO WORLD' indexOfSeparator
 => 6

 'HELLO WORLD' indexOfSeparatorStartingAt: 7
 => 0

 'HELLO abc World' lastIndexOfSeparator
 => 10

 'HELLO abc World' lastIndexOfSeparatorStartingAt:10
 => 10

 'HELLO abc World' lastIndexOfSeparatorStartingAt:9
 => 6

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

aString includesString: aSubstring [ caseSensitive: boolean ]

Returns true if aString contains the sub-string aSubstring; false otherwise.

Example:

 'HELLO' includesString:'LL'
 => true

 'HELLO' includesString: 'll'
 => false

 'HELLO' includesString: 'll' caseSensitive: false 
 => true

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' ... )

aString asCollectionOfWords

Returns a collection of strings, each containing one word from the original string. Words are separated by whitespace (space, tab or CR/LF).

Example:

 'hello bla bla world' asCollectionOfWords
 => #( 'hello' 'bla' 'bla' 'world' )

Encoding / Decoding

aString utf8Encoded

aString utf8Decoded

Encode / decode into/from utf8 encoding.

Example:

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

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

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

aString utf16Encoded

Encode into an utf16 encoded two byte string (ie. still a vector of characters), caring for characters above codepoint 0xFFFF. This can then be further converted to a vector of bytes in BE (big end) or LE (low end) order (see below).

Example:

 'hello äöü' utf16Encoded encodeInto:#utfLE16
 => #[104 0 101 0 108 0 108 0 111 0 32 0 228 0 246 0 252 0]

aString encodeInto: nameOfEncoding

aString decodeFrom: nameOfEncoding

Similar to the above, but nameOfEncoding gives the encoding's name (as symbol). Supported encodings are: #utf, #utf16BE, #utf16LE, #iso8859-1 to #iso8859-8, #iso8859-15, #iso8859-16, #koi7, #cp437, #cp850, #cp1250, #cp1252, #jis7, #gb, #big5, #ebcdic.

aString encodeFrom: nameOfEncoding1 into: nameOfEncoding2

to transcode from one encoding into another. Eg. "someString encodeFrom:#cp850 into:#koi7" would recode from the Windows codepage 850 into cyrillic koi7.

aString base64Encoded

aString base64Decoded

aString base64DecodedString

Encode / decode into/from base64 encoding.

Example:

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

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

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

 'äöü' base64Encoded base64DecodedString
 => 'äöü'

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

Hashing

See Cryptographic API Functions.

---

Copyright © 2014-2024 eXept Software AG