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.

Accessing

size

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

aString size

aString.size() [JS]

Example:

 'hello world' size
 => 11

at:

Returns the character at an index.

aString at: index

aString[ índex ] [JS]

Example:

 'hello world' at:2
 => $e

Copying

copyFrom:to:

Copies characters from a start index to an end index.

aString copyFrom: startIndex to: endIndex

aString.copyFrom_to( startIndex, endIndex ) [JS]

Example:

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

copyFrom:count:

Copies a number of characters starting at the given index.

aString copyFrom: startIndex count: numChars

aString.copyFrom_count( startIndex, numChars ) [JS]

Example:

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

copyFrom:

Copies from the given index to the end.

aString copyFrom:' startIndex

aString.copyFrom( startIndex ) [JS]

Example:

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

copyTo:

Copies from the start to the given index.

aString copyTo: endIndex

aString.copyTo( endIndex ) [JS]

Example:

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

copyLast:

Copies the last count characters.

aString copyLast: count

aString.copyLast( count ) [JS]

Example:

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

copyButFirst:

Copies except for the first count characters.

aString copyButFirst: count

aString.copyButFirst( count ) [JS]

Example:

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

copyButLast:

Copies except for the last count characters.

aString copyButLast: count

aString.copyButLast( count ) [JS]

Example:

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

copyBetween:and:caseSensitive:

Finds two substrings and copies the part between them.

aString copyBetween: leftString and: rightString caseSensitive: boolean

aString.copyBetween_and_caseSensitive( leftString, rightString, boolean ) [JS]

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 '

copyReplaceString:withString:

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 '

withoutPrefix:[caseSensitive:]

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

aString withoutPrefix: prefixString [ caseSensitive: boolean' ]'

aString.withoutPrefix( prefixString ) [JS]

Example:

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

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

withoutSuffix:[caseSensitive:]

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

aString withoutSuffix: suffixString [ caseSensitive: boolean' ]'

aString.withoutSuffix( suffixString ) [JS]

Example:

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

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

Concatenation

, (comma)

string1 , string2

string1 + string2 [JS]

Example:

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

Splitting

splitBy:

Splits a string into pieces, given a splitting character.

aString splitBy: aCharacter

aString.splitBy( aCharacter ) [JS]

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

splitOn:

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.

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]

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

asLowercase

aString1 asLowercase

string1.asLowercase() [JS]

Example:

 'HELLO' asLowercase
 => 'hello'

asUppercase

aString1 asUppercase

string1.asUppercase() [JS]

Example:

 'hello' asUppercase
 => 'HELLO'

asUppercaseFirst

aString1 asUppercaseFirst

string1.asUppercaseFirst() [JS]

Example:

 'hello' asUppercaseFirst
 => 'Hello'

Comparing

sameAs:

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

string1 sameAs: string2

string1.sameAs( string2 ) [JS]

Example:

 'HELLO' sameAs: 'HeLlo'
 => true

 'HELxO' sameAs: 'HeLlo'
 => false

 'HELLO' caselessEqual: 'HeLlo'
 => true

caselessBefore: / caselessAfter:

Compare two strings, ignoring case.

string1 caselessBefore: string2

string1 caselessAfter: string2

string1.caselessBefore( string2 ) [JS]

string1.caselessAfter( string2 ) [JS]

Example:

 'HELLO' caselessBefore: 'world'
 => true

 'bce' caselessBefore: 'abc'
 => false

startsWith:[caseSensitive:]

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

string1 startsWith: prefixString

string1 startsWith: prefixString caseSensitive: boolean

string1.startsWith( prefixString ) [JS]

string1.startsWith_caseSensitive( prefixString, boolean ) [JS]

Example:

 'hello' startsWith: 'hel'
 =>true

 'Hello' startsWith: 'hel'
 =>false

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

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

endsWith:[caseSensitive:]

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

string1 endsWith: prefixString

string1 endsWith: prefixString caseSensitive: boolean

string1.endsWith( prefixString ) [JS]

string1.endsWith_caseSensitive( prefixString, boolean ) [JS]

Example:

 'hello' endsWith: 'lo'
 =>true

 'Hello' endsWith: 'Lo'
 =>false

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

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

Searching

indexOf: / lastIndexOf:

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

aString indexOf: aCharacter

aString lastIndexOf: aCharacter

aString.indexOf( aCharacter ) [JS]

aString.lastIndexOf( aCharacter ) [JS]

Example:

 'HELLO' indexOf: $L
 => 3

 'HELLO' indexOf: $x
 => 0

 'HELLO' lastIndexOf: $L
 => 4

indexOf:startingAt: / lastIndexOf:startingAt:

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

aString indexOf: aCharacter startingAt: startIndex

aString lastIndexOf: aCharacter startingAt: startIndex

aString.indexOf_startingAt( aCharacter, startIndex ) [JS]

aString.lastIndexOf_startingAt( aCharacter, startIndex ) [JS]

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

indexOfAny:[startingAt:] / lastIndexOfAny:[startingAt:]

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.

aString indexOfAny: aCollectionOfCharacters [ startingAt: startIndex ]

aString lastIndexOfAny: aCollectionOfCharacters [ startingAt: startIndex ]

aString.indexOfAny( aCollectionOfCharacters ) [JS]

aString.indexOfAny_startingAt( aCollectionOfCharacters, startIndex ) [JS]

aString.lastIndexOfAny( aCollectionOfCharacters ) [JS]

aString.lastIndexOfAny_startingAt( aCollectionOfCharacters, startIndex ) [JS]

Example:

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

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

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

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

indexOfSeparator / indexOfSeparatorStartingAt:

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

aString indexOfSeparator

aString indexOfSeparatorStartingAt: startIndex

aString.indexOfSeparator() [JS]

aString.indexOfSeparatorStartingAt( startIndex ) [JS]

Example:

 'HELLO WORLD' indexOfSeparator
 => 6

 'HELLO WORLD' indexOfSeparatorStartingAt: 7
 => 0

indexOfString:[startingAt:] / lastIndexOfString:[startingAt:]

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

aString indexOfString: aSubstring [ startingAt: startIndex ]

aString lastIndexOfString: aSubstring [ startingAt: startIndex ]

aString.indexOfString( aSubstring ) [JS]

aString.lastIndexOfString( aSubstring ) [JS]

Example:

 'HELLO' indexOfString:'LL'
 => 3

 'HELLO' indexOfString: 'LX'
 => 0

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

Pattern Matching

matches:[caseSensitive:]

True if a string matches a GLOB match pattern.

aString matches: patternString [ caseSensitive: boolean ]
 
aString.matches( patternString ) [JS]

aString.matches_caseSensitive( patternString,  boolean ) [JS]

Example:

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

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

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

matchesRegex:[caseSensitive:]

True if a string matches a regex pattern.

aString matchesRegex: patternString [ caseSensitive: boolean ]
 
aString.matchesRegex( patternString ) [JS]

aString.matchesRegex_caseSensitive( patternString,  boolean ) [JS]

Example:

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

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

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

Converting

asByteArray

Returns a byte array containing the codePoints (ISO8859 codes). The characters must be within the ISO8859 range 0x00 .. 0xFF.

aString asByteArray
 
aString.asByteArray() [JS]

Example:

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

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

asFilename

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

aString asFilename
 
aString.asFilename() [JS]

Example:

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

 '/etc' asFilename exists
 => true

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.

aStringWithMultipleLines asCollectionOfLines
 
aStringWithMultipleLines.asCollectionOfLines() [JS]

Example:

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

Encoding / Decoding

utf8Encoded / utf8Decoded

Encode / decode into/from utf8 encoding.

aString utf8Encoded
 
aString.utf8Encoded() [JS]

Example:

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

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

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

base64Encoded / base64Decoded

Encode / decode into/from base64 encoding.

aString base64Encoded
 
aString.base64Encoded() [JS]

Example:

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

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

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

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

---

Copyright © 2014-2024 eXept Software AG