eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'CharacterArray':

Home

Documentation
www.exept.de
Everywhere
for:
[back]

Class: CharacterArray


Inheritance:

   Object
   |
   +--Collection
      |
      +--SequenceableCollection
         |
         +--ArrayedCollection
            |
            +--UninterpretedBytes
               |
               +--CharacterArray
                  |
                  +--FourByteString
                  |
                  +--String
                  |
                  +--Text
                  |
                  +--TwoByteString

Package:
stx:libbasic
Category:
Collections-Text
Version:
rev: 1.731 date: 2018/05/24 19:08:17
user: cg
file: CharacterArray.st directory: libbasic
module: stx stc-classLibrary: libbasic
Author:
Claus Gittinger

Description:


CharacterArray is a superclass for all kinds of Strings (i.e.
(singleByte-)Strings, TwoByteStrings, UnicodeStrings
and whatever may come in the future.

This class is abstract, meaning that there are no instances of it;
concrete subclasses define how the characters are stored (i.e. either as
single byte, two-byte or four byte strings).

All this class does is provide common protocol for concrete subclasses.

Notice:
    internally, ST/X uses a unicode encoding for ALL characters - both
    for individual chatacter entities and for strings of characters.
    When reading/writing files in different encodings, the conversion is
    done at read/write time by use of a CharacterEncoder instance.
    These know how to convert to a wide range of encodings.

Also notice:
    UTF8 and UTF16 are external encodings of a Unicode string; they are never
    used internally. When interacting with a UTF8 interface (OS-API or files),
    you should convert UTF8 into the internal full Unicode right at the interface.
    Do not keep UTF8 around internally as String instances.
    The reason is that UTF8 makes it harder to manipulate strings (for example
    to insert/extract substrings or to get its size. Of such operations would
    require a scan of the UTF8, which would complicate them).
    Of course, there may be rare exceptions to this, for example if a file's contents
    is treated as raw data, and the strings have to be copied/shuffled around only,
    without any real processing on it.


Related information:

    String
    TwoByteString
    Unicode16String
    Uniode32String
    StringCollection

Class protocol:

Compatibility-VW
o  fromIntegerArray: anArray
Answer a new instance of the receiver that is created from the argument, anArray.
usage example(s):
     String fromIntegerArray: #[8 127]

Signal constants
o  decodingFailedSignal
return the signal, raised when decoding of a string is not possible
due to invalid characters contained in the source.
This may happen for example, if a non EUC coded 8-bit string
is attempted to be decoded into a JIS string.

o  encodingFailedSignal
return the (query-) signal, raised when encoding of a string is not possible
due to invalid characters contained in the source.

cleanup
o  lowSpaceCleanup
cleanup in low-memory situations
usage example(s):
     CharacterArray lowSpaceCleanup

encoding & decoding
o  decodeFromUTF8: aStringOrByteCollection
given a string in UTF8 encoding,
return a new string containing the same characters, in Unicode encoding.
Returns either a normal String, a Unicode16String or a Unicode32String instance.
This is only useful, when reading from external sources or communicating with
other systems
(ST/X never uses utf8 internally, but always uses strings of fully decoded unicode characters).
This only handles up-to 30bit characters.
usage example(s):
     CharacterArray decodeFromUTF8:#[ 16r41 16r42 ]
     CharacterArray decodeFromUTF8:#[ 16rC6 16r8F ]
     CharacterArray decodeFromUTF8:#[ 16rEF 16rBF 16rBF ]

   rfc3629 examples:
     CharacterArray decodeFromUTF8:#[ 16r41 16rE2 16r89 16rA2 16rCE 16r91 16r2E ]
     CharacterArray decodeFromUTF8:#[ 16rED 16r95 16r9C 16rEA 16rB5 16rAD 16rEC 16r96 16rB4 ]
     CharacterArray decodeFromUTF8:#[ 16rE6 16r97 16rA5 16rE6 16r9C 16rAC 16rE8 16rAA 16r9E ]

   invalid:
     CharacterArray decodeFromUTF8:#[ 16rC0 16r80 ]
     CharacterArray decodeFromUTF8:#[ 16rE0 16r80 16r80 ]
     CharacterArray decodeFromUTF8:#[ 16rE0 16r81 16r02 ]

o  setupNormalizationMaps
returns a 2-stage map from ch2 -> ch1 -> mappedChar.
for unicode normalization
(i.e. for replacing combining char-sequences with regular characters).
ch2 is the combining charCode (eg. 0x0308), ch1 is the previous character (eg. $A),
mappedChar is the result (eg. $Ä).
Caveat:
possibly incomplete: only COMBINING_DIACRITICAL_MARKS are cared for.
Does not care for COMBINING_DIACRITICAL_MARKS_EXTENDED
and COMBINING_DIACRITICAL_MARKS_SUPPLEMENT.
However; those are used for German dialectology, ancient Greek and other similar
exotic uses. Probably noone will ever even notice that they are missing...
usage example(s):
     self setupNormalizationMaps

o  unicodeDenormalizationMap
returns a 2-stage map from ch2 -> ch1 -> mappedChar
for unicode normalization (i.e. for making combining chars regular ones).
Caveat:
possibly incomplete: only COMBINING_DIACRITICAL_MARKS are cared for.
Does not care for COMBINING_DIACRITICAL_MARKS_EXTENDED
and COMBINING_DIACRITICAL_MARKS_SUPPLEMENT.
However; those are used for German dialectology, ancient Greek and other similar
exotic uses. Probably noone will ever even notice that they are missing...
usage example(s):
     self unicodeDenormalizationMap

o  unicodeNormalizationMap
returns a 2-stage map from ch2 -> ch1 -> mappedChar
for unicode normalization (i.e. for making combining chars regular ones).
Caveat:
possibly incomplete: only COMBINING_DIACRITICAL_MARKS are cared for.
Does not care for COMBINING_DIACRITICAL_MARKS_EXTENDED
and COMBINING_DIACRITICAL_MARKS_SUPPLEMENT.
However; those are used for German dialectology, ancient Greek and other similar
exotic uses. Probably noone will ever even notice that they are missing...
usage example(s):
     self unicodeNormalizationMap

initialization
o  initialize
CharacterArray initialize

instance creation
o  basicNew
return a new empty string

o  fromBytes: aByteCollection
return an instance of the receiver class,
taking untranslated bytes from the argument, aByteCollection
in most-significant first order.
Only useful, when reading twoByteStrings from external sources.
usage example(s):
     Unicode16String fromBytes:#[16r02 16r20]
     Unicode16String fromBytes:#[16r02 16r20] MSB:true
     Unicode16String fromBytes:#[16r02 16r20] MSB:false

o  fromBytes: aByteCollection MSB: msb
return an instance of the receiver class,
taking untranslated bytes from the argument, aByteCollection
in the given byte order.
Only useful, when reading twoByteStrings from external sources.
usage example(s):
     Unicode16String fromBytes:#[16r02 16r20]

o  fromString: aString
return a copy of the argument, aString
usage example(s):
        Unicode16String fromString:'hello'
        String fromString:'hello' asUnicode16String
        Unicode16String fromString:'hello' asUnicode16String

o  fromStringCollection: aCollectionOfStrings
return new string formed by concatenating a copy of the argument, aString
usage example(s):
     String fromStringCollection:#('hello' 'world' 'how' 'about' 'this')

o  fromStringCollection: aCollectionOfStrings separatedBy: aSeparatorString
return new string formed by concatenating a copy of the argument, aString
usage example(s):
     String fromStringCollection:#('hello' 'world' 'how' 'about' 'this') separatedBy:' '
     String fromStringCollection:#('hello' 'world' 'how' 'about' 'this') separatedBy:'Ƞ'
     Text fromStringCollection:{'hello'. 'world'. 'how' allBold. 'about'. 'this'. 'äöü'} separatedBy:'Ƞ'

o  fromUTF8Bytes: aByteCollection
return a new string which represents the characters as decoded
from the utf8 encoded bytes, aByteCollection.
Returns either a normal String, or a TwoByteString instance.
Only useful, when reading twoByteStrings from external sources.
This only handles up-to 16bit characters

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  new
return a new empty string

o  readSmalltalkStringFrom: aStreamOrString onError: exceptionBlock
read & return the next String from the (character-)stream aStream;
skipping all whitespace first; return the value of exceptionBlock,
if no string can be read. The sequence of characters as read from the
stream must be one as stored via storeOn: or storeString.

o  writeStreamClass
the type of stream used in writeStream.
Here, we return CharacterWriteStream, which automatically changes
the underlying collection to a multiByte string (i.e. UnicodeString).
So you can stream wide characters into it.

pattern matching
o  matchEscapeCharacter
return the character used to escape a matchCharacter
(i.e. make it a regular character in a matchPattern)

o  matchScan: matchScanArray from: matchStart to: matchStop with: aString from: start to: stop caseSensitive: caseSensitive
helper for match; return true if the characters from start to stop in
aString are matching the scan in matchScan from matchStart to matchStop.
The matchScan is as created by asMatchScanArray.

This algorithm is not at all the most efficient;
for heavy duty pattern matching, an interface (primitive) to the regex
pattern matching package should be added.

o  matchScan: matchScanArray from: matchStart to: matchStop with: aString from: start to: stop ignoreCase: ignoreCase
helper for match; return true if the characters from start to stop in
aString are matching the scan in matchScan from matchStart to matchStop.
The matchScan is as created by asMatchScanArray.

This algorithm is not at all the most efficient;
for heavy duty pattern matching, an interface (primitive) to the regex
pattern matching package should be added.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  matchScanArrayFrom: aString
scan a pattern string and decompose it into a scanArray.
This is processed faster (especially with character ranges), and
can also be reused later. (if the same pattern is to be searched again)
usage example(s):
     String matchScanArrayFrom:'*ute*'
     String matchScanArrayFrom:'**ute**'
     String matchScanArrayFrom:'*uter'
     String matchScanArrayFrom:'\*uter'
     String matchScanArrayFrom:'[cC]#mpute[rR]'
     String matchScanArrayFrom:'[abcd]*'
     String matchScanArrayFrom:'[a-k]*'
     String matchScanArrayFrom:'*some*compl*ern*'
     String matchScanArrayFrom:'[a-'
     String matchScanArrayFrom:'[a-zA-Z]'
     String matchScanArrayFrom:'[a-z01234A-Z]'

o  matchScanArrayFrom: aString escapeCharacter: escape
scan a pattern string and decompose it into a scanArray.
This is processed faster (especially with character ranges), and
can also be reused later. (if the same pattern is to be searched again)
usage example(s):
     String matchScanArrayFrom:'*ute*'
     String matchScanArrayFrom:'**ute**'
     String matchScanArrayFrom:'*uter'
     String matchScanArrayFrom:'\*uter'
     String matchScanArrayFrom:'[cC]#mpute[rR]'
     String matchScanArrayFrom:'[abcd]*'
     String matchScanArrayFrom:'[a-k]*'
     String matchScanArrayFrom:'*some*compl*ern*'
     String matchScanArrayFrom:'[a-'
     String matchScanArrayFrom:'[a-zA-Z]'
     String matchScanArrayFrom:'[a-z01234A-Z]'

queries
o  isAbstract
Return if this class is an abstract class.
True is returned for CharacterArray here; false for subclasses.
Abstract subclasses must redefine this again.

o  speciesForCharacterSize: characterSize
answer the class, that is able to hold characters of size characterSize

utilities
o  withoutAmpersandEscapes: label
remove single ampersands;
replace double ampersands by single ones.
This is used to unescape menu-labels
(which use the ampersand as shortKey marker)
usage example(s):
     String withoutAmpersandEscapes:''
     String withoutAmpersandEscapes:'a'
     String withoutAmpersandEscapes:'abcd'
     String withoutAmpersandEscapes:'&abcd'
     String withoutAmpersandEscapes:'&abcd&'
     String withoutAmpersandEscapes:'&a&b&c&d'
     String withoutAmpersandEscapes:'&a&b&c&d&'
     String withoutAmpersandEscapes:'&&a&&b&&c&&d&&'
     String withoutAmpersandEscapes:'&&a&&b&&c&&d&'
     String withoutAmpersandEscapes:'&a&&b&&c&&d&'
     String withoutAmpersandEscapes:'a&&b&&c&&d'


Instance protocol:

Compatibility-ANSI
o  addLineDelimiters
Ansi compatibility - same as withCRs

Compatibility-Dolphin
o  copyExpanding: expandTable
return a copy of myself, with translations from the expandTable sliced in.
The argument is supposed to map from characters to either characters or strings.
Added for Dolphin compatibility

o  formatWith: aString
Compatibility method - do not use in new code.
same as #bindWith: for Dolphin compatibility
usage example(s):
     'hello%1world' formatWith:'123'

o  formatWith: arg1 with: arg2
Compatibility method - do not use in new code.
same as #bindWith: for Dolphin compatibility
usage example(s):
     'hello%1 %2world' formatWith:'123' with:234

o  formatWith: arg1 with: arg2 with: arg3
Compatibility method - do not use in new code.
same as #bindWith: for Dolphin compatibility
usage example(s):
     'hello%1 %2 %3world' formatWith:'123' with:234 with:345

o  lines
( an extension from the stx:libcompat package )
return the receiver as a collection of lines.
Added for Dolphin compatibility
usage example(s):
     'hello world' lines  

     'foo
bar
baz' lines

Compatibility-GNU
o  % anArrayOfOperands
return a copy of the receiver, where a '%i' escape
is replaced by the corresponding string from the argument array.
'i' may be between 1 and 9 (i.e. a maximum of 9 placeholders is allowed).
Added for GNU-ST compatibility.
usage example(s):
     'do you prefer %1 or rather %2 (not talking about %3) ?'
        % #('smalltalk' 'c++' 'c')

     'do you %(what) ?'
        % (Dictionary new at:#'what' put:'understand'; yourself)

Compatibility-ST/V
o  asArrayOfSubstrings
return an array of substrings from the receiver, interpreting
separators (i.e. spaces & newlines) as word-delimiters.
This has been added for ST/V compatibility
- the actual work is done in asCollectionOfWords.
(sigh: it is called #'subStrings' in V'Age, #'substrings' in Squeak
and #'asCollectionOfWords' in ST/X)
usage example(s):
     '1 one two three four 5 five' asArrayOfSubstrings
     '1
one
        two three four 5 five' asArrayOfSubstrings

o  equalsIgnoreCase: aString
This is an ST/V compatibility method and an alias for sameAs:.
usage example(s):
     'abc' equalsIgnoreCase: 'aBC'

o  replChar: oldChar with: newChar
return a copy of the receiver, with all oldChars replaced by newChar.
This is an ST/V compatibility method and an alias for copyReplaceAll.
usage example(s):
     '12345678901234567890' replChar:$0 with:$*

o  replChar: oldChar withString: newString
return a copy of the receiver, with all oldChars replaced
by newString (i.e. slice in the newString in place of the oldChar).
This is an ST/V compatibility method.
usage example(s):
     '12345678901234567890' replChar:$0 withString:'foo'
     'a string with spaces' replChar:$  withString:' foo '

o  replString: subString withString: newString
return a copy of the receiver, with all sequences of subString replaced
by newString (i.e. slice in the newString in place of the oldString).
This is an ST/V compatibility method and an alias for copyReplaceString.
usage example(s):
     '12345678901234567890' replString:'123' withString:'OneTwoThree'
     '12345678901234567890' replString:'123' withString:'*'
     '12345678901234567890' replString:'234' withString:'foo'

     ('a string with spaces' replChar:$  withString:' foo ')
        replString:'foo' withString:'bar'

o  subString: start to: end
same as copyFrom:to:
This is an ST/V compatibility method and an alias for copyFrom:to:.
usage example(s):
     '12345678901234567890' subString:3 to:8

o  trimBlanks
return a copy of the receiver without leading and trailing spaces.
This is an ST/V compatibility method and an alias for withoutSpaces.
usage example(s):
     '    spaces at beginning' trimBlanks
     'spaces at end    ' trimBlanks
     '    spaces at beginning and end     ' trimBlanks
     'no spaces' trimBlanks

Compatibility-Squeak
o  asBoldText
return self as a bold text

o  asDate
Many allowed forms, see Date.readFrom:
usage example(s):
     '30 Apr 1999' asDate dayName capitalized

o  asOneByteString
( an extension from the stx:libcompat package )
return the receiver converted to a 'normal' string.
Same as asSingleByteString - for Squeak/Pharo compatibility.

o  asUrl
( an extension from the stx:libcompat package )
Same as asURL - for Squeak/Pharo compatibility.

o  asWideString
( an extension from the stx:libcompat package )
return a two-byte string containing the same characters as the receiver.
Same as asTwoByteString - for Squeak/Pharo compatibility.
usage example(s):
     'abc' asWideString

o  capitalized
( an extension from the stx:libcompat package )
same as asUppercaseFirst for Squeak/Pharo compatibility
usage example(s):
     'hello' capitalized

o  caseInsensitiveLessOrEqual: aString
compare the receiver against the argument ignoring case differences
For Squeak/Pharo compatibility

o  caseSensitiveLessOrEqual: aString
compare the receiver against the argument caring for case differences
For Squeak/Pharo compatibility

o  charactersExactlyMatching: aString
return the number of characters I share as a prefix with the argument, aString
usage example(s):
     'abc' charactersExactlyMatching:'abc'
     'abc' charactersExactlyMatching:'abcd'
     'abcd' charactersExactlyMatching:'abc'
     'abc' charactersExactlyMatching:'abd'
     'abc' charactersExactlyMatching:'xxx'

o  convertToEncoding: nameOfEncoding
special case, because it is so common:
usage example(s):
     'hellöäü' convertToEncoding:'utf8'
     'hello' convertToEncoding:'cp1252'

o  endsWithDigit
Answer whether the receiver's final character represents a digit. 3/11/96 sw

o  findDelimiters: delimiters startingAt: start
Answer the index of the character within the receiver, starting at start,
that matches one of the delimiters.
If the receiver does not contain any of the delimiters, answer size + 1.

o  findString: key startingAt: start caseSensitive: caseSensitive

o  findTokens: delimiterOrDelimiters
cg: I am not sure, if this is really the squeak semantics (w.r.t. empty fields)
usage example(s):
     'a|b#c||e' findTokens:#($# $|)
     'a|b#c||e' findTokens:$|

o  includesSubString: aString
return true, if a substring is contained in the receiver.
The compare is case sensitive.
usage example(s):
     'hello world' includesSubString:'Hel'
     'hello world' includesSubString:'hel'
     'hello world' includesSubString:'llo'

o  includesSubString: aString caseSensitive: caseSensitive
sigh - an alias; added for Squeak/Pharo compatibility

o  includesSubstring: aString
sigh - an alias; added for Squeak/Pharo compatibility

o  includesSubstring: aString caseSensitive: caseSensitive
return true, if a substring is contained in the receiver.
The argument, caseSensitive controls if case is ignored in the compare.
usage example(s):
     'hello world' includesSubstring:'Hel' caseSensitive:true
     'hello world' includesSubstring:'Hel' caseSensitive:false

o  intervalFromStartLine: aStartLine startColumn: aStartColumn toEndLine: anEndLine endColumn: anEndColumn
( an extension from the stx:libcompat package )
Returns an interval spanning between startLine @ startColumn to endLine @ endColumn

o  intervalOfLine: aLineNumber
( an extension from the stx:libcompat package )
Answer an interval spanning between the first and the last character of the line from aLineNumber.
Use this to convert lineNr into a character range.

o  intervalOfLineCorrespondingToIndex: anIndex
( an extension from the stx:libcompat package )
Answer an interval spanning between the first and the last character of the line containing the given character index

o  isAllDigits
Answer whether the receiver's characters are all digits
usage example(s):
     'hello world' isAllDigits
     '12344' isAllDigits

o  lastSpacePosition
return the index of the last space character; 0 if there is none.
Added for Squeak/Pharo compatibility

o  lineIndicesDo: aBlock
( an extension from the stx:libcompat package )
execute aBlock with 3 arguments for each line:
- start index of line
- end index of line without line delimiter
- end index of line including line delimiter(s) CR, LF or CRLF

o  linesDo: aBlock
evaluate the argument, aBlock for all lines,
up to the end

o  openInWorkspaceWithTitle: aTitleString
( an extension from the stx:libcompat package )
Added for Squeak/Pharo compatibility

o  padded: leftOrRight to: paddedSize with: padCharacter
pad left (leftOrRight == #left) or right
usage example(s):
     'hello' padded:#right to:10 with:$.
     'hello' padded:#left to:10 with:$.

o  skipDelimiters: delimiters startingAt: start
Answer the index of the character within the receiver, starting at start,
that does NOT match one of the delimiters.
If the receiver does not contain any of the delimiters, answer size + 1.
Assumes the delimiters to be a non-empty string.
usage example(s):
     '123***7890' skipDelimiters:'*' startingAt:4
     '123***7890' skipDelimiters:'*' startingAt:3
     '123***7890' skipDelimiters:'*' startingAt:10
     '123*******' skipDelimiters:'*' startingAt:10

o  substrings
return a collection consisting of all words contained in the receiver.
Words are separated by whitespace.
This has been added for Squeak compatibility.
(sigh: it is called #'subStrings' in V'Age, and #'asCollectionOfWords' in ST/X)
usage example(s):
     'foo bar baz' substrings

o  substringsSeparatedBy: separatorCharacter
return a collection consisting of all words contained in the receiver.
Words are separated by the given separator character.
This has been added for Squeak/Pharo compatibility.
(sigh: it is called #'subStrings:' in V'Age,
and #'asCollectionOfSubstringsSeparatedBy' in ST/X)
usage example(s):
     'foo bar, baz' substringsSeparatedBy:$,
     '1.2.3.4' substringsSeparatedBy:$.

o  translated
( an extension from the stx:libcompat package )
Dummy - Added for Squeak/Pharo compatibility

o  truncateTo: smallSize
return myself or a copy shortened to smallSize. 1/18/96 sw
usage example(s):
     'hello world' truncateTo:5
     'hello' truncateTo:10

     'hello world' copyTo:5
     'hello' copyTo:10

o  unescapePercents
( an extension from the stx:libcompat package )
decode %xx form. This is the opposite of #encodeForHTTP

o  unescapePercentsWithTextEncoding: encodingName
( an extension from the stx:libcompat package )
decode string including %XX form

o  withBlanksTrimmed
Return a copy of the receiver from which leading and trailing whitespace have been trimmed.
Notice the bad naming - it is trimming separators, not just blanks.
Added for Squeak compatibility and an alias for withoutSeparators
usage example(s):
     '  hello    world    ' withBlanksTrimmed

o  withNoLineLongerThan: aNumber
Answer a string with the same content as receiver, but rewrapped so that no line has more characters than the given number
usage example(s):
     #(5 7 20) collect:
        [:i | 'Fred the bear went down to the brook to read his book in silence' withNoLineLongerThan: i]

o  withSqueakLineEndings
assume the string is textual, and that CR, LF, and CRLF are all
valid line endings. Replace each occurrence with a single CR

o  withoutLeading: char
return a copy of myself without leading a char.
Returns an empty string, if the receiver consist only of a char.
usage example(s):
     '****foo****' withoutLeading: $*
     'foo****'     withoutLeading: $*
     '*'           withoutLeading: $*
     ''            withoutLeading: $*
     '****foo'     withoutLeading: $*
     '*******'     withoutLeading: $*
     'foo'         withoutLeading: $*
     'f***o***o'   withoutLeading: $*
     ('**' , Character tab asString , '*foo***') withoutLeading: $* inspect

o  withoutTrailing: char
return a copy of myself without trailing char.
Returns an empty string, if the receiver consist only of char.
usage example(s):
     '    foo....' withoutTrailing:$.
     'foo....'     withoutTrailing:$.
     '    foo'     withoutTrailing:$.
     '.......'     withoutTrailing:$.
     'foo'         withoutTrailing:$.

Compatibility-V'Age
o  addLineDelimiter
replace all '\'-characters by line delimiter (cr) - characters.
This has been added for VisualAge compatibility.

o  bindWith: aString
return a copy of the receiver, where a '%1' escape is
replaced by aString.
This has been added for VisualAge compatibility.
usage example(s):
     'do you like %1 ?' bindWith:'smalltalk'
     'do you like %(foo) ?' bindWithArguments:(Dictionary new at:'foo' put:'smalltalk'; yourself)

o  bindWith: string1 with: string2
return a copy of the receiver, where a '%1' escape is
replaced by string1 and '%2' is replaced by string2.
This has been added for VisualAge compatibility.
usage example(s):
     'do you prefer %1 or rather %2 ?'
        bindWith:'smalltalk' with:'c++'

o  bindWith: str1 with: str2 with: str3
return a copy of the receiver, where a '%1', '%2' and '%3' escapes
are replaced by str1, str2 and str3 respectively.
This has been added for VisualAge compatibility.
usage example(s):
     'do you prefer %1 or rather %2 (not talking about %3) ?'
        bindWith:'smalltalk' with:'c++' with:'c'

o  bindWith: str1 with: str2 with: str3 with: str4
return a copy of the receiver, where a '%1', '%2', '%3' and '%4' escapes
are replaced by str1, str2, str3 and str4 respectively.
This has been added for VisualAge compatibility.
usage example(s):
     'do you prefer %1 or rather %2 (not talking about %3 or even %4) ?'
        bindWith:'smalltalk' with:'c++' with:'c' with:'assembler'

o  bindWith: str1 with: str2 with: str3 with: str4 with: str5
return a copy of the receiver, where a '%1' .. '%5' escapes
are replaced by str1 .. str5 respectively.
This has been added for VisualAge compatibility.

o  bindWith: str1 with: str2 with: str3 with: str4 with: str5 with: str6
return a copy of the receiver, where a '%1' .. '%6' escapes
are replaced by str1 .. str6 respectively.
This has been added for VisualAge compatibility.

o  bindWith: str1 with: str2 with: str3 with: str4 with: str5 with: str6 with: str7
return a copy of the receiver, where a '%1' .. '%7' escapes
are replaced by str1 .. str7 respectively.
This has been added for VisualAge compatibility.

o  bindWith: str1 with: str2 with: str3 with: str4 with: str5 with: str6 with: str7 with: str8
return a copy of the receiver, where a '%1' .. '%8' escapes
are replaced by str1 .. str8 respectively.
This has been added for VisualAge compatibility.

o  bindWith: str1 with: str2 with: str3 with: str4 with: str5 with: str6 with: str7 with: str8 with: str9
return a copy of the receiver, where a '%1' .. '%9' escapes
are replaced by str1 .. str9 respectively.
This has been added for VisualAge compatibility.

o  bindWithArguments: argumentsCollection
return a copy of the receiver, where a '%i' escape
is replaced by the corresponding string from the argument array.
'i' may be between 1 and 9 (i.e. a maximum of 9 placeholders is allowed)
or %(key); the argumentsCollection must then be a dictionary.
To get an integer-indexed placeHolder followed by another digit,
or an index > 9, you must use %(digit).
This has been added for VisualAge compatibility.
usage example(s):
     'do you prefer %1 or rather %2 (not talking about %3) ?'
        bindWithArguments:#('smalltalk' 'c++' 'c')

     'do you %(what) ?'
        bindWithArguments:(Dictionary new at:#'what' put:'understand'; yourself)

o  indexOfString: aString
VSE and V'age compatibility

o  indexOfString: aString ifAbsent: exceptionValue
VSE and V'age compatibility
usage example(s):
     'abcdefabcdef' indexOfString:'fab' ifAbsent:[999]
     'abcdefabcdef' indexOfString:'xxx' ifAbsent:[999]

o  indexOfString: aString startingAt: startIndex
VSE and V'age compatibility

o  indexOfString: aString startingAt: startIndex ifAbsent: exceptionalValue
VSE and V'age compatibility

o  subStrings
return a collection consisting of all words contained in the receiver.
Words are separated by whitespace.
This has been added for VisualAge compatibility.
(sigh: it is called #'subbtrings' in Squeak, and #'asCollectionOfWords' in ST/X)
usage example(s):
     'hello world, this is smalltalk' subStrings

o  subStrings: separatorCharacterOrString
return a collection consisting of all words contained in the receiver.
Words are separated by separatorCharacter.
This is similar to split: (squeak) and asCollectionOfSubstringsSeparatedBy: (st/x)
and has been added for VisualAge compatibility.
usage example(s):
     'foo:bar:baz:smalltalk' subStrings:$:
     'foo:bar:baz:smalltalk' subStrings:':'
     'foo.bar,baz-smalltalk' subStrings:'.,-'

o  trimSeparators
return a copy of the receiver without leading and trailing whiteSpace.
Added for VisualAge compatibility (an alias for withoutSeparators)

Compatibility-VW
o  asComposedText
( an extension from the stx:libcompat package )
ST-80 compatibility
- ST/X does not (as today) support composedTexts.

o  asLogicalFileSpecification

o  asQualifiedReference
( an extension from the stx:libcompat package )

o  expandMacros
ST80 compatibility - expand '<..>' macros with
argument strings. Similar to #bindWith:.
Read the comment in #expandMacrosWithArguments: about
limited compatibility issues.
usage example(s):
     'hellofoo' expandMacros

o  expandMacrosWith: arg
ST80 compatibility - expand '<..>' macros with
argument strings. Similar to #bindWith:.
Read the comment in #expandMacrosWithArguments: about
limited compatibility issues.

o  expandMacrosWith: arg1 with: arg2
ST80 compatibility - expand '<..>' macros with
argument strings. Similar to #bindWith:.
Read the comment in #expandMacrosWithArguments: about
limited compatibility issues.

o  expandMacrosWith: arg1 with: arg2 with: arg3
ST80 compatibility - expand '<..>' macros with
argument strings. Similar to #bindWith:.
Read the comment in #expandMacrosWithArguments: about
limited compatibility issues.

o  expandMacrosWith: arg1 with: arg2 with: arg3 with: arg4
ST80 compatibility - expand '<..>' macros with
argument strings. Similar to #bindWith:.
Read the comment in #expandMacrosWithArguments: about
limited compatibility issues.

o  expandMacrosWithArguments: argArray
ST80 compatibility - expand '<..>' macros with
argument strings. Similar to #bindWith:.
WARNING: possibly not all ST80 expansions are supported here.

o  isCharacters
true, if the receiver is a string-like thing.
added for visual works compatibility

JavaScript support
o  charAt0: index
( an extension from the stx:libjavascript package )
returns the n'th character, using a 0-based indexing scheme (sigh)

o  charAt1: index
( an extension from the stx:libjavascript package )
returns the n'th character, using a 1-based indexing scheme (sigh)

o  charCodeAt0: index
( an extension from the stx:libjavascript package )
returns the code of the n'th character, using a 0-based indexing scheme (sigh)

o  charCodeAt1: index
( an extension from the stx:libjavascript package )
returns the code of the n'th character, using a 1-based indexing scheme (sigh)

o  indexOf0: aCharacter
( an extension from the stx:libjavascript package )
returns the index of aCharacter, using a 0-based indexing scheme; -1 if not found (sigh)

o  indexOf1: aCharacter
( an extension from the stx:libjavascript package )
returns the index of aCharacter, using a 1-based indexing scheme; 0 if not found (sigh)

o  js_add: something
( an extension from the stx:libjavascript package )
For JavaScript only:
Generated for +-operator in javascript.

o  js_addFromNumber: aNumber
( an extension from the stx:libjavascript package )
For JavaScript only:
Generated for +-operator in javascript.

o  js_addFromString: aString
( an extension from the stx:libjavascript package )
For JavaScript only:
Generated for +-operator in javascript.

o  js_addFromTime: aTime
( an extension from the stx:libjavascript package )
For JavaScript only:
Generated for +-operator in javascript.

o  js_indexOf: aCharacterOrSubstring
( an extension from the stx:libjavascript package )
JS: collection.indexOf(character)
JS: collection.indexOf(substring)
returns the index of anElement/substring, using a 0-based indexing scheme; -1 if not found (sigh).
Selector-xlation to allow redefinition in CharacterArray, which supports substring searching.

o  js_indexOf: aCharacterOrSubstring _: startIndex
( an extension from the stx:libjavascript package )
JS: collection.indexOf(character, startIndex)
JS: collection.indexOf(substring, startIndex)
returns the index of anElement, using a 0-based indexing scheme; -1 if not found (sigh).
Selector-xlation to allow redefinition in CharacterArray, which supports substring searching.

o  js_lastIndexOf: aCharacterOrSubstring
( an extension from the stx:libjavascript package )
JS: collection.lastIndexOf(character)
JS: collection.lastIndexOf(substring)
returns the index of the last occurrence of anElement/substring, using a 0-based indexing scheme; -1 if not found (sigh).
Selector-xlation to allow redefinition in CharacterArray, which supports substring searching.

o  js_lastIndexOf: aCharacterOrSubstring _: startIndex
( an extension from the stx:libjavascript package )
JS: collection.lastIndexOf(character, startIndex)
JS: collection.lastIndexOf(substring, startIndex)
returns the index of the last occurrence of anElement/substring, using a 0-based indexing scheme; -1 if not found (sigh).
Selector-xlation to allow redefinition in CharacterArray, which supports substring searching.

o  lastIndexOf0: aCharacter
( an extension from the stx:libjavascript package )
returns the last index of aCharacter, using a 0-based indexing scheme; -1 if not found (sigh)

o  lastIndexOf1: aCharacter
( an extension from the stx:libjavascript package )
returns the last index of aCharacter, using a 1-based indexing scheme; 0 if not found (sigh)

o  quote
( an extension from the stx:libjavascript package )
wraps the receiver into quotes.
This is the JavaScript standard quote function.
usage example(s):
     JavaScriptParser evaluate:'''hello''.quote'

o  split: separator
( an extension from the stx:libjavascript package )
splits into an array of substrings

o  substr0: index
( an extension from the stx:libjavascript package )
extracts a rest-substring, using a 0-based indexing scheme (sigh)

o  substr0: index _: count
( an extension from the stx:libjavascript package )
extracts a substring, using a 0-based indexing scheme (sigh)

o  substr1: index
( an extension from the stx:libjavascript package )
extracts a rest-substring, using a 1-based indexing scheme (sigh)

o  substr1: index _: count
( an extension from the stx:libjavascript package )
extracts a substring, using a 1-based indexing scheme (sigh)

o  substring0: index1
( an extension from the stx:libjavascript package )
extracts a substring, using a 0-based indexing scheme (sigh)

o  substring0: index1 _: index2
( an extension from the stx:libjavascript package )
extracts a substring, using a 0-based indexing scheme (sigh)

o  substring1: index1
( an extension from the stx:libjavascript package )
extracts a substring, using a 1-based indexing scheme (sigh)

o  substring1: index1 _: index2
( an extension from the stx:libjavascript package )
extracts a substring, using a 1-based indexing scheme (sigh)

o  toLowerCase
( an extension from the stx:libjavascript package )
returns a copy of the receiver with all chars in lower case
usage example(s):
     JavaScriptParser
	evaluate:'''HeLLo''.toLowerCase'

o  toUpperCase
( an extension from the stx:libjavascript package )
returns a copy of the receiver with all chars in upper case
usage example(s):
     JavaScriptParser
	evaluate:'''HeLLo''.toUpperCase'

o  trim
( an extension from the stx:libjavascript package )
returns a copy of the receiver with all leading and trailing whiteSpace removed
usage example(s):
     JavaScriptParser
	evaluate:'''    He LLo   ''.trim'

o  trimLeft
( an extension from the stx:libjavascript package )
returns a copy of the receiver with all leading whiteSpace removed
usage example(s):
     JavaScriptParser
	evaluate:'''    HeLLo   ''.trimLeft'

o  trimRight
( an extension from the stx:libjavascript package )
returns a copy of the receiver with all trailing whiteSpace removed
usage example(s):
     JavaScriptParser
	evaluate:'''    HeLLo   ''.trimRight'

o  typeof
( an extension from the stx:libjavascript package )
return a string describing what I am
usage example(s):
     JavaScriptParser
	evaluate:'''hello''.typeof()'

     JavaScriptParser
	evaluate:'1234.typeof()'

o  unquote
removes double quotes from the receiver.
This is the JavaScript standard unquote function.
usage example(s):
     'hello' quote unquote

     JavaScriptParser evaluate:'''hello''.quote.unquote'

o  unquote: quoteCharacter
removes quoteCharacter from either end of the receiver.
usage example(s):
     '*hello*' unquote:$*

character searching
o  includesMatchCharacters
return true if the receiver includes any GLOB meta-match characters (i.e. $* or $#)
for match operations; false if not.
Here, do not care for $\ escapes
usage example(s):
     '*foo' includesMatchCharacters
     '\*foo' includesMatchCharacters
     '\*foo' includesUnescapedMatchCharacters
     '*foo' includesMatchCharacters
     '\\*foo' includesMatchCharacters
     'foo*' includesMatchCharacters
     'foo\*' includesMatchCharacters
     'foo\' includesMatchCharacters

o  includesSeparator
return true, if the receiver contains any whitespace characters
usage example(s):
     'hello world' includesSeparator
     'helloworld' includesSeparator

o  includesUnescapedMatchCharacters
return true if the receiver really includes any meta characters (i.e. $* or $#)
for match operations; false if not.
Here, care for $\ escapes
usage example(s):
     '*foo' includesUnescapedMatchCharacters
     '\*foo' includesUnescapedMatchCharacters
     '\\foo' includesUnescapedMatchCharacters
     '\\\$foo' includesUnescapedMatchCharacters
     '*foo' includesUnescapedMatchCharacters
     '\\*foo' includesUnescapedMatchCharacters
     'foo*' includesUnescapedMatchCharacters
     'foo\*' includesUnescapedMatchCharacters
     'foo\' includesUnescapedMatchCharacters

o  indexOfControlCharacterStartingAt: startIndex
return the index of the next control character;
that is a character with asciiValue < 32.
Start the search at startIndex, searching forward.
Return 0 if none is found.
usage example(s):
     'hello world' asTwoByteString            indexOfControlCharacterStartingAt:1
     'hello world\foo' withCRsasTwoByteString indexOfControlCharacterStartingAt:1

o  indexOfNonSeparator
return the index of the first non-whitespace character.
return 0 if no non-separator was found
usage example(s):
     '    hello world' indexOfNonSeparator
     '    ' indexOfNonSeparator
     'a   ' indexOfNonSeparator
     'abc' indexOfNonSeparator
     ' ' indexOfNonSeparator
     '' indexOfNonSeparator

o  indexOfNonSeparatorStartingAt: startIndex
return the index of the next non-whitespace character,
starting the search at startIndex, searching forward;
return 0 if no non-separator was found
usage example(s):
     '    hello world' indexOfNonSeparatorStartingAt:1
     '    ' indexOfNonSeparatorStartingAt:1
     'a   ' indexOfNonSeparatorStartingAt:2

o  indexOfSeparator
return the index of the first whitespace character;
starting the search at the beginning, searching forward;
return 0 if no separator was found
usage example(s):
     'hello world' indexOfSeparator
     'helloworld' indexOfSeparator
     'hello   ' indexOfSeparator
     '   hello' indexOfSeparator

o  indexOfSeparatorOrEndStartingAt: startIndex
return the index of the next whitespace character,
starting the search at startIndex, searching forward;
return the index of one beyond the end of the receiver if no separator was found.
To extract the word, copy from startIndex to the returned index-1
usage example(s):
     'hello world' indexOfSeparatorOrEndStartingAt:3
     ' hello world' indexOfSeparatorOrEndStartingAt:3
     'hello world ' indexOfSeparatorOrEndStartingAt:3
     'hello world ' indexOfSeparatorOrEndStartingAt:6
     'hello world ' indexOfSeparatorOrEndStartingAt:7
     'helloworld ' indexOfSeparatorOrEndStartingAt:7
     'helloworld' indexOfSeparatorOrEndStartingAt:7
     'helloworld' indexOfSeparatorStartingAt:7

o  indexOfSeparatorStartingAt: startIndex
return the index of the next whitespace character,
starting the search at startIndex, searching forward;
return 0 if no separator was found
usage example(s):
     'hello world' indexOfSeparatorStartingAt:3
     ' hello world' indexOfSeparatorStartingAt:3
     'hello world ' indexOfSeparatorStartingAt:3
     'hello world ' indexOfSeparatorStartingAt:6
     'hello world ' indexOfSeparatorStartingAt:7
     'helloworld ' indexOfSeparatorStartingAt:7
     'helloworld' indexOfSeparatorStartingAt:7

o  lastIndexOfSeparator
return the last index of a whitespace character (space or tab).
(i.e. start the search at the end and search backwards);
Returns 0 if no separator is found.
usage example(s):
     'hello world' lastIndexOfSeparator
     'helloworld' lastIndexOfSeparator
     'hel lo wor ld' lastIndexOfSeparator
     'hel   ' lastIndexOfSeparator 6

o  lastIndexOfSeparatorStartingAt: startIndex
return the index of the previous whitespace character,
starting the search at startIndex (and searching backwards);
returns 0 if no separator was found
usage example(s):
     'hello world' lastIndexOfSeparatorStartingAt:3
     'hello world' lastIndexOfSeparatorStartingAt:7
     'helloworld' lastIndexOfSeparatorStartingAt:7
     ' helloworld' lastIndexOfSeparatorStartingAt:7

comparing
o  < aString
Compare the receiver with the argument and return true if the
receiver is greater than the argument. Otherwise return false.
This comparison is based on the elements ascii code -
i.e. upper/lowercase & upper/lowercase & national characters are NOT treated specially.

o  = aString
Compare the receiver with the argument and return true if the
receiver is equal to the argument. Otherwise return false.

This compare does NOT ignore case differences,
therefore 'foo' = 'Foo' will return false.
Since this is incompatible to ST-80 (at least, V2.x) , this may change.
usage example(s):
     'foo' = 'Foo'
     'foo' = 'bar'
     'foo' = 'foo'
     'foo' = 'foo' asText
     'foo' asText = 'foo'
     'foo' asText = 'foo' asText

o  > aString
Compare the receiver with the argument and return true if the
receiver is greater than the argument. Otherwise return false.
This comparison is based on the elements ascii code -
i.e. upper/lowercase & upper/lowercase & national characters are NOT treated specially.

o  after: aString
Compare the receiver with the argument and return true if the
receiver should come after the argument in a sorted list.
Otherwise return false.
NOTE: The comparison should be language specific, depending on the value of
LC_COLLATE, which is initialized from the environment.

Currently it is for Strings, but not for UnicodeStrings...

STUPID:
#after has a completely different meaning in SeqColl ...

o  compareAsVersionNumberWith: aStringOrCollection
Compare the receiver with the argument and return 1 if the receiver is
greater, 0 if equal and -1 if less than the argument in a sorted list.
Compare as version numbers in the form a.b.c... .
usage example(s):
     self assert:('1' compareAsVersionNumberWith:'2') < 0.
     self assert:('2' compareAsVersionNumberWith:'1') > 0.
     self assert:('1.1' compareAsVersionNumberWith:'2.1.2') < 0.
     self assert:('2.1' compareAsVersionNumberWith:'1.2.3') > 0.
     self assert:('1' compareAsVersionNumberWith:'1.1') < 0.
     self assert:('1.1' compareAsVersionNumberWith:'1') > 0.
     self assert:('1.1' compareAsVersionNumberWith:'1.2') < 0.
     self assert:('1.10' compareAsVersionNumberWith:'1.2') > 0.
     self assert:('1.2.3.4' compareAsVersionNumberWith:'1.2.3.5') < 0.
     self assert:('1.2.3.4' compareAsVersionNumberWith:'1.2.3.3') > 0.
     self assert:('1.2.3.4' compareAsVersionNumberWith:'1.2.3') > 0.
     self assert:('1.2.3.4' compareAsVersionNumberWith:'1.2.3.4') = 0.
     self assert:('1.2.3.4' compareAsVersionNumberWith:'01.002.03.004') = 0.
     self assert:('1.2.3.4' compareAsVersionNumberWith:#(1 2 3 4)) = 0.
     self assert:('1.2.3.4' compareAsVersionNumberWith:#('1' 2 3 4)) = 0.

o  compareCaselessWith: aString
Compare the receiver against the argument, ignoring case.
Return 1 if the receiver is greater, 0 if equal and -1 if less than the argument.

This comparison is based on the elements ascii code -
i.e. national characters are NOT treated specially.
'foo' compareWith: 'Foo' will return 0

o  compareCollatingWith: aString
Compare the receiver with the argument and return 1 if the receiver is
greater, 0 if equal and -1 if less than the argument in a sorted list.
The comparison is language specific, depending on the value of
LC_COLLATE, which is in the shell environment.

o  compareWith: aString
Compare the receiver with the argument and return 1 if the receiver is
greater, 0 if equal and -1 if less than the argument.
This comparison is based on the elements' codepoints -
i.e. upper/lowercase & national characters are NOT treated specially.
'foo' compareWith: 'Foo' will return 1.
while 'foo' sameAs:'Foo' will return true

o  endsWith: aStringOrCharacter
return true, if the receiver ends with something, aStringOrCharacter.
If aStringOrCharacter is empty, true is returned
usage example(s):
     'hello world' endsWith:'world'
     'hello world' asText allBold endsWith:'world'
     'hello world' endsWith:''
     'hello world' asText allBold endsWith:''

o  hammingDistanceTo: aString
return the hamming distance (the number of characters which are different).
In information theory, the Hamming distance between two strings of equal length
is the number of positions for which the corresponding symbols are different.
Put another way, it measures the minimum number of substitutions required to change
one into the other, or the number of errors that transformed one string into the other.
usage example(s):
     'roses' hammingDistanceTo:'toned'
     'roses' hammingDistanceTo:'doses'

o  hash
return an integer useful as a hash-key
usage example(s):
whenever changing, also care for String>>hash.
usage example(s):
Set allSubInstancesDo:[:s | s rehash]
usage example(s):
     'a' hash
     'a' asUnicode16String hash
     'a' asUnicode32String hash
     'aa' hash
     'aa' asUnicode16String hash
     'aa' asUnicode32String hash
     'ab' hash
     'ab' asUnicode16String hash
     'ab' asUnicode32String hash
     'ab' hash
     'ab' asArray hash

o  hash_dragonBook
return an integer useful as a hash-key

o  hash_fnv1a
return an integer useful as a hash-key.
This method uses the fnv-1a algorithm
(which is actually a very good one).
Attention: stops when a 0-codepoint is encountered
(for compatibility with the hash used by the VM)
Also: on 64bit CPUs, only small 4-byte hashvalues are returned,
(so hash values are independent from the architecture)
usage example(s):
     'abc' hash_fnv1a
     'abc' asUnicode16String hash_fnv1a
     'abc' asUnicode32String hash_fnv1a

     'foofooHelloWorld' hash_fnv1a
     'foofooHelloWorld' asUnicode16String hash_fnv1a
     'foofooHelloWorld' asUnicode32String hash_fnv1a

     'blablaHelloWorld' hash_fnv1a
     'blablaHelloWorld' asUnicode16String hash_fnv1a
     'blablaHelloWorld' asUnicode32String hash_fnv1a

o  hash_java
return an integer useful as a hash-key.
This method uses the same algorithm as used in
the java virtual machine
(which is actually not a very good one).
usage example(s):
     'abc' hash_java
     'foofooHelloWorld' hash_java
     'blablaHelloWorld' hash_java

o  hash_sdbm
return an integer useful as a hash-key.
This method implements the sdbm algorithm.

o  levenshteinTo: aString
return the levenshtein distance to the argument, aString;
this value corresponds to the number of replacements that have to be
made to get aString from the receiver.
See IEEE transactions on Computers 1976 Pg 172 ff.
usage example(s):
     in the following, we assume that omiting a character
     is less of an error than inserting an extra character.
     Therefore the different insertion (i) and deletion (d) values.
        s: substitution weight (4)
        k: keyboard weight (k) (typing a nearby key) - or nil (then use s)
        c: case weight (4)                           - or nil (then use s)
        e: exchange weight (8)                       - or nil (then use s*2)
        i: insertion of extra character weight (2)
        d: delete of a character weight (6)

     Notice that the standard levenshtein uses the same weight for insertion and deletion,
     and is computed by:
        'flaw' levenshteinTo:'lawn' s:2 k:nil c:nil i:1 d:1
usage example(s):
     'computer' levenshteinTo:'computer'
     'cOmputer' levenshteinTo:'computer'
     'cOmpuTer' levenshteinTo:'computer'
     'cimputer' levenshteinTo:'computer'
     'cumputer' levenshteinTo:'computer'

     'cmputer' levenshteinTo:'computer'
     'coomputer' levenshteinTo:'computer'

     'ocmprt' levenshteinTo:'computer'
     'computer' levenshteinTo:'computer'
     'ocmputer' levenshteinTo:'computer'
     'cmputer' levenshteinTo:'computer'
     'computer' levenshteinTo:'cmputer'
     'Computer' levenshteinTo:'computer'

     'compiter' levenshteinTo:'computer'
     'compoter' levenshteinTo:'computer'

     'comptuer' levenshteinTo:'computer'

o  levenshteinTo: aString s: substWeight k: kbdTypoWeight c: caseWeight i: insrtWeight d: deleteWeight
parametrized levenshtein.
return the levenshtein distance to the argument, aString;
this value corrensponds to the number of replacements that have to be
made to get aString from the receiver.
The arguments are the costs for
s:substitution,
k:keyboard type (substitution),
c:case-change,
i:insertion
d:deletion
of a character.
See IEEE transactions on Computers 1976 Pg 172 ff

o  sameAs: aString
Compare the receiver with the argument like =, but ignore case differences.
Return true or false.
usage example(s):
     'foo' sameAs: 'Foo'
     'foo' sameAs: 'bar'
     'foo' sameAs: 'foo'

o  sameAs: aString caseSensitive: caseSensitive
Compare the receiver with the argument.
If caseSensitive is false, this is the same as #sameAs:,
if false, this is the same as #=.
usage example(s):
     'foo' sameAs:'Foo' caseSensitive:false
     'foo' sameAs:'foo' caseSensitive:true

o  sameAs: aString ignoreCase: ignoreCase
Compare the receiver with the argument.
If ignoreCase is true, this is the same as #sameAs:,
if false, this is the same as #=.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  sameCharacters: aString
count & return the number of characters which are the same
(ignoring case and emphasis) in the receiver and the argument, aString.
usage example(s):
     'foobarbaz' sameCharacters: 'foo'
     'foobarbaz' sameCharacters: 'Foo'
     'foobarbaz' sameCharacters: 'baz'

o  sameEmphasisAs: aStringOrText
compare the receiver's and the argument's emphasis
usage example(s):
     'hello' asText sameEmphasisAs: 'hello'
     'hello' asText sameEmphasisAs: 'hello' asText
     'hello' asText allBold sameEmphasisAs: 'hello'
     'hello' asText allBold sameEmphasisAs: 'fooba' asText allBold
     'hello' asText allBold sameEmphasisAs: 'fooba' asText allItalic

o  sameStringAndEmphasisAs: aStringOrText
compare both emphasis and string of the receiver and the argument
usage example(s):
     'hello' asText sameEmphasisAs: 'hello'
     'hello' asText sameEmphasisAs: 'hello' asText
     'hello' asText allBold sameEmphasisAs: 'hello'
     'hello' asText allBold sameEmphasisAs: 'fooba' asText allBold
     'hello' asText allBold sameEmphasisAs: 'fooba' asText allItalic

     'hello' sameEmphasisAs: 'hello' asText
     'hello' sameEmphasisAs: 'hello' asText allBold
     'hello' sameEmphasisAs: 'fooba'
     'hello' sameEmphasisAs: 'fooba' asText
     'hello' sameEmphasisAs: 'fooba' asText allBold
     'hello' sameEmphasisAs: 'fooba' asText allItalic

     'hello' asText sameStringAndEmphasisAs: 'hello'
     'hello' asText sameStringAndEmphasisAs: 'hello' asText
     'hello' asText allBold sameStringAndEmphasisAs: 'hello'
     'hello' asText allBold sameStringAndEmphasisAs: 'fooba' asText allBold
     'hello' asText allBold sameStringAndEmphasisAs: 'fooba' asText allItalic

     'hello' sameStringAndEmphasisAs: 'hello' asText
     'hello' sameStringAndEmphasisAs: 'hello' asText allBold
     'hello' sameStringAndEmphasisAs: 'fooba'
     'hello' sameStringAndEmphasisAs: 'fooba' asText
     'hello' sameStringAndEmphasisAs: 'fooba' asText allBold
     'hello' sameStringAndEmphasisAs: 'fooba' asText allItalic

o  spellAgainst: aString
return an integer between 0 and 100 indicating how similar
the argument is to the receiver. No case conversion is done.
This algorithm is much simpler (but also less exact) than the
levenshtein distance. Experiment which is better for your
application.
usage example(s):
     'Smalltalk' spellAgainst: 'Smalltlak'
     'Smalltalk' spellAgainst: 'smalltlak'
     'Smalltalk' spellAgainst: 'smalltalk'
     'Smalltalk' spellAgainst: 'smalltlk'
     'Smalltalk' spellAgainst: 'Smalltolk'

o  startsWith: aStringOrCharacter
return true, if the receiver starts with something, aStringOrCharacter.
If the argument is empty, true is returned.
Notice, that this is similar to, but slightly different from VW's and Squeak's beginsWith:,
which are both inconsistent w.r.t. an empty argument.
usage example(s):
     'abcde' startsWith:#($a $b $c)
     'abcde' startsWith:'abc'
     'abcd' startsWith:'abcde'
     'abcde' startsWith:'abd'
     'hello world' startsWith:'hello'
     'hello world' asText allBold startsWith:'hello'
     'hello world' asText allBold startsWith:''

converting
o  asAsciiZ
if the receiver does not end with a 0-valued character, return a copy of it,
with an additional 0-character. Otherwise return the receiver. This is sometimes
needed when a string has to be passed to C, which needs 0-terminated strings.
Notice, that all singleByte strings are already 0-terminated in ST/X, whereas wide
strings are not.
usage example(s):
     'abc' asAsciiZ
     'abc' asWideString asAsciiZ

o  asByteArray
depending on the size of the characters in the receiver,
return a byteArray containing single-, double- or even 4-bytewise values.
The size of the returned byteArray will be the strings size multiplied by the
size required for the largest character.
Attention: The bytes are in native byte order.
Caveat: better use utf8Encoded, to get reproducible results

o  asByteArrayMSB: msb
depending on the size of the characters in the receiver,
return a byteArray containing single-, double- or even 4-bytewise values.
The size of the returned byteArray will be the strings size multiplied by the
size required for the largest character.
Caveat: better use utf8Encoded, to get reproducible results

o  asCanonicalizedFilename
return a Filename with pathname taken from the receiver.
The filename is canonicalized, meaning that it cares for trailing directory separators,
'.' components etc.
usage example(s):
on windows:
     'c:\foo\bar' asFilename
     'c:\foo\bar\' asFilename
     'c:\foo\bar\..\baz' asFilename
     'c:\foo\bar\..\baz\.' asFilename
     'c:\foo\bar' asCanonicalizedFilename
     'c:\foo\bar\' asCanonicalizedFilename
     'c:\foo\bar\..\baz' asCanonicalizedFilename
     'c:\foo\bar\..\baz\.' asCanonicalizedFilename
    
    on unix:
     '/foo/bar' asFilename
     '/foo/bar/' asFilename
     '/foo/bar/../baz' asFilename
     '/foo/bar/../baz/.' asFilename
     '/foo/bar' asCanonicalizedFilename
     '/foo/bar/' asCanonicalizedFilename
     '/foo/bar/../baz' asCanonicalizedFilename
     '/foo/bar/../baz/.' asCanonicalizedFilename

o  asCollectionOfLines
return a collection containing the lines (separated by cr)
of the receiver. If multiple cr's occur in a row, the result will
contain empty strings.
If the string ends with a cr, an empty line will be found as last element of the resulting collection.
See also #asCollectionOfLinesWithReturn
(would have rather changed this method instead of adding another one, but a lot of code already uses
this method and we did not want to risk any incompatibilities)
usage example(s):
     '1 one\2 two\3 three\4 four\5 five' withCRs asCollectionOfLines
     '1 one\\\\2 two\3 three' withCRs asCollectionOfLines

     ('foo \r\nbar\nbaz\t\r\n\r\nbla' printf:#())
        asCollectionOfLines collect:[:l | (l endsWith:Character return) ifTrue:[l copyButLast:1] ifFalse:l]

o  asCollectionOfLinesWithReturn
return a collection containing the lines (separated by cr)
of the receiver. If multiple cr's occur in a row, the result will
contain empty strings.
usage example(s):
     '1\2\3' withCRs asCollectionOfLines
     '1\2\3\' withCRs asCollectionOfLines
     '1\2\3' withCRs asCollectionOfLinesWithReturn
     '1\2\3\' withCRs asCollectionOfLinesWithReturn
     '' withCRs asCollectionOfLinesWithReturn

o  asCollectionOfSubstringsSeparatedBy: aCharacter
return a collection containing substrings (separated by aCharacter)
of the receiver.
If aCharacter occurs multiple times in a row, the result will contain empty strings.
If the receiver ends with aCharacter, an empty string with be the last result element.
usage example(s):
     '1 one:2 two:3 three:4 four:5 five' asCollectionOfSubstringsSeparatedBy:$:
     '1 one:2 two:3 three:4 four:5 five:' asCollectionOfSubstringsSeparatedBy:$:
     '1 one 2 two 3 three 4 four 5 five' asCollectionOfSubstringsSeparatedBy:Character space

o  asCollectionOfSubstringsSeparatedBy: aCharacter exceptIn: ch
return a collection containing the substrings (separated by aCharacter)
of the receiver. If aCharacter occurs multiple times in a row,
the result will contain empty strings.
The separation is not done, inside a matching pair of ch-substrings.
Can be used to tokenize csv-like strings, which may or may not be enclosed in quotes.
usage example(s):
     'asd''f;d''dd;s' asCollectionOfSubstringsSeparatedBy:$; exceptIn:$'
usage example(s):
'asd "hello bla" foo "bla bla" bar' asCollectionOfSubstringsSeparatedBy:$  exceptIn:$"

o  asCollectionOfSubstringsSeparatedBy: aFieldSeparatorString textSeparator: aTextSeparatorOrNil
return a collection containing the words (separated by aFieldSeparatorString) of the receiver.
Individual words might be enclosed in aTextSeparator characters, in case they contain blanks or fieldSeparators.
Typically used for CSV line parsing, with a $; as aFieldSeparator and $'' (dquote) as textSeparator.
usage example(s):
     self assert:(('#First#, #Second,SecondAdd#, #Third#' asCollectionOfSubstringsSeparatedBy:',' textSeparator: $#)
                  sameContentsAs:#('First' 'Second,SecondAdd' 'Third')).
     self assert:(('#Fir##st#, #Second,SecondAdd#, #Third#' asCollectionOfSubstringsSeparatedBy:',' textSeparator: $#)
                  sameContentsAs:#('Fir#st' 'Second,SecondAdd' 'Third')).
     self assert:(('#Fir##st#, Second,SecondAdd, #Third#' asCollectionOfSubstringsSeparatedBy:',' textSeparator: $#)
                  sameContentsAs:#('Fir#st' 'Second' 'SecondAdd' 'Third')).
     self assert:(('First,Second,Third,,' asCollectionOfSubstringsSeparatedBy:',' textSeparator:nil)
                   sameContentsAs:#('First' 'Second' 'Third' '' '')).
     self assert:(('First,Second,Third,,' asCollectionOfSubstringsSeparatedBy:',' textSeparator:'#')
                   sameContentsAs:#('First' 'Second' 'Third' '' '')).

o  asCollectionOfSubstringsSeparatedByAll: aSeparatorString
return a collection containing the lines (separated by aSeparatorString)
of the receiver. If aSeparatorString occurs multiple times in a row,
the result will contain empty strings.
usage example(s):
     '1::2::3::4::5::' asCollectionOfSubstringsSeparatedByAll:'::'

o  asCollectionOfSubstringsSeparatedByAny: aCollectionOfSeparators
return a collection containing the words (separated by any character
from aCollectionOfSeparators) of the receiver.
This allows breaking up strings using any character as separator.
usage example(s):
     'hello:world:isnt:this nice' asCollectionOfSubstringsSeparatedByAny:#($:)
     'hello:world:isnt:this nice' asCollectionOfSubstringsSeparatedByAny:':'
     'hello:world:isnt:this nice' asCollectionOfSubstringsSeparatedByAny:(Array with:$: with:Character space)
     'hello:world:isnt:this nice' asCollectionOfSubstringsSeparatedByAny:': '
     'h1e2l3l4o' asCollectionOfSubstringsSeparatedByAny:($1 to: $9)

o  asCollectionOfWords
return a collection containing the words (separated by whitespace)
of the receiver. Multiple occurrences of whitespace characters will
be treated like one - i.e. whitespace is skipped.
(sigh: it is called #'subStrings' in V'Age, and #'substrings' in Squeak)
usage example(s):
     'hello world isnt this nice' asCollectionOfWords
     '    hello    world   isnt   this   nice  ' asCollectionOfWords
     'hello' asCollectionOfWords
     '' asCollectionOfWords
     '      ' asCollectionOfWords
     ' foo bar__baz__bla__ bar ' asCollectionOfWords
     ' foo __bar__baz__bla__ bar ' asCollectionOfWords

o  asCollectionOfWordsDo: aBlock
evaluate aBlock for each word (separated by whitespace) of the receiver.
Multiple occurrences of whitespace characters will be treated like one
- i.e. whitespace is skipped.
Returns the number of words (i.e. the number of invocations of aBlock).
usage example(s):
     'hello world isnt this nice' asCollectionOfWordsDo:[:w | Transcript showCR:w]
     '    hello    world   isnt   this   nice  ' asCollectionOfWordsDo:[:w | Transcript showCR:w]
     'hello' asCollectionOfWordsDo:[:w | Transcript showCR:w]
     '' asCollectionOfWordsDo:[:w | Transcript showCR:w]
     '      ' asCollectionOfWordsDo:[:w | Transcript showCR:w]

o  asFilename
return a Filename with pathname taken from the receiver

o  asFixedPoint
read a fixedPoint number from the receiver.
Notice, that errors may occur during the read,
so you better setup some signal handler when using this method.
usage example(s):
     '0.123' asFixedPoint
     '12345' asFixedPoint
     '(1/5)' asFixedPoint
     'foo' asFixedPoint
     Object errorSignal handle:[:ex | ex return:0] do:['foo' asFixedPoint]

o  asFixedPoint: scale
read a fixedPoint number with scale number of post-decimal digits
from the receiver. Scale controls the number of displayed digits,
not the number of actually valid digits.
Notice, that errors may occur during the read,
so you better setup some signal handler when using this method.
usage example(s):
     '0.123' asFixedPoint:2
     '123456' asFixedPoint:2
     ('3.14157' asFixedPoint:1) asFixedPoint:5
     '3.14157' asFixedPoint:2
     'foo' asFixedPoint:2

o  asFloat
read a float number from the receiver.
Notice, that errors may occur during the read,
so you better setup some exception handler when using this method.
usage example(s):
     '0.123' asFloat
     '12345' asFloat
     '(1/5)' asFloat
     Object errorSignal handle:[:ex | ex return:0] do:['foo' asFloat]

o  asInteger
convert the receiver into an integer.
Notice, that errors may occur during the read,
so you better setup some exception handler when using this method.
Also notice, that this method here is more strict than the code found
in other smalltalks.
For less strict integer reading, use Integer readFrom:aString
usage example(s):
     '12345678901234567890' asInteger
     '-1234' asInteger

     The following raises an error:
         '0.123' asInteger              <- reader finds more after reading 0

     whereas the less strict readFrom does not:
         Integer readFrom:'0.123'       <- reader stops at ., returning 0

     '0.123' asInteger
     '0.123' asNumber    <- returns what you expect
     Object errorSignal handle:[:ex | ex return:0] do:['foo' asInteger]

o  asLowercase
return a copy of myself in lowercase letters
usage example(s):
     'HelloWorld' asLowercase
     'HelloWorld' asUnicode16String asLowercase
     'HelloWorld' asLowercaseFirst
     'HelloWorld' asUppercase
     'HelloWorldÿ' asUppercase
     'HelloWorldŸ' asLowercase - currently returns an U16 string; should this be u8?

o  asLowercaseFirst
return a copy of myself where the first character is converted to lowercase.
If the first character is already lowercase, or there is no uppercase for it, return the
receiver.
usage example(s):
     'HelloWorld' asLowercase
     'HelloWorld' asLowercaseFirst

o  asLowercaseLast
return a copy of myself where the last character is
converted to lowercase.
usage example(s):
     'HelloWorld' asLowercase
     'HelloWorlD' asLowercaseLast

o  asMimeType
( an extension from the stx:libview2 package )
return myself as a mimeType instance
usage example(s):
     'text/html' asMimeType isTextType
     'text/html' asMimeType isImage
     'image/gif' asMimeType isImage
     'image/gif' asMimeType asMimeType

o  asMutator
return a corresponding setter method's selector.
I.e. #foo asMutator returns #foo:

o  asNumber
read a number from the receiver.
Notice, that (in contrast to ST-80) errors may occur during the read,
so you better setup some signal handler when using this method.
Also notice, that this is meant to read end-user numbers from a string;
it does not handle smalltalk numbers (i.e. radix).
To read a smalltalk number, use Number >> readSmalltalkFrom:.
This may change if ANSI specifies it.
usage example(s):
     '123'     asNumber
     '123.567' asNumber
     '(5/6)'   asNumber
     'foo'     asNumber
     '123a'    asNumber
     Object errorSignal handle:[:ex | ex returnWith:0] do:['foo' asNumber]

o  asNumberFromFormatString: ignored
read a number from the receiver, ignoring any nonDigit characters.
This is typically used to convert from strings which include
dollar-signs or millenium digits. However, this method also ignores
the decimal point (if any) and therefore should be used with care.
usage example(s):
     'USD 123' asNumberFromFormatString:'foo'
     'DM 123'  asNumberFromFormatString:'foo'
     '123'     asNumberFromFormatString:'foo'
     '123.567' asNumberFromFormatString:'foo'
     '(5/6)'   asNumberFromFormatString:'foo'
     'foo'     asNumberFromFormatString:'foo'

o  asPackageId
given a package-string as receiver, return a packageId object.
packageIds hide the details of module/directory handling inside the path.
See PackageId for the required format of those strings.
usage example(s):
     'stx:libbasic' asPackageId

o  asSingleByteStringIfPossible
if possible, return the receiver converted to a 'normal' string.
It is only possible, if there are no characters with codePoints above 255 in the receiver.
If not possible, the (wideString) receiver is returned.
usage example(s):
     'hello' asSingleByteStringIfPossible
     'hello' asText asSingleByteStringIfPossible
     'hello' asUnicodeString asText asSingleByteStringIfPossible
     'hello' asUnicodeString asSingleByteStringIfPossible

o  asSingleByteStringReplaceInvalidWith: replacementCharacter
return the receiver converted to a 'normal' string,
with invalid characters replaced by replacementCharacter.
Can be used to convert from 16-bit strings to 8-bit strings
and replace characters above code-255 with some replacement.

o  asString
return myself - I am a string

o  asStringCollection
return a collection of lines from myself.
usage example(s):
     'hello\world\1\2\3' withCRs asStringCollection first    

o  asSymbol
Return a unique symbol with the name taken from the receiver's characters.
The receiver must be a singleByte-String.
TwoByte- and FourByteSymbols are (currently ?) not allowed.

o  asSymbolIfInterned
If a symbol with the receiver's characters is already known, return it.
Otherwise, return nil.
This can be used to query for an existing symbol and is the same as:
self knownAsSymbol ifTrue:[self asSymbol] ifFalse:[nil]
but slightly faster, since the symbol lookup operation is only performed once.
The receiver must be a singleByte-String.
TwoByte- and FourByteSymbols are (currently ?) not allowed.
usage example(s):
     (Unicode16String with:(Character value:16rFFFF)) asSymbolIfInterned
     'new' asUnicodeString asSymbolIfInterned
     'new' asText asSymbolIfInterned
     'new' asUnicodeString asText asSymbolIfInterned

o  asSymbolIfInternedOrSelf
If a symbol with the receiver's characters is already known, return it.
Otherwise, return self.
This can be used to query for an existing symbol and is the same as:
self knownAsSymbol ifTrue:[self asSymbol] ifFalse:[self]
but slightly faster, since the symbol lookup operation is only performed once.
The receiver must be a singleByte-String.
TwoByte- and FourByteSymbols are (currently ?) not allowed.
usage example(s):
     (Unicode16String with:(Character value:16rFFFF)) asSymbolIfInternedOrSelf
     'new' asUnicodeString asSymbolIfInternedOrSelf
     'new' asText asSymbolIfInternedOrSelf
     'new' asUnicodeString asText asSymbolIfInternedOrSelf

o  asText
return a Text-object (string with emphasis) from myself.

o  asTimestamp
convert the receiver into an Timestamp.
Notice, that errors may occur during the read,
so you better setup some exception handler when using this method.
usage example(s):
     '2014-11-10 21:30:22.444' asTimestamp
     '2014-11-10 21:30:22.444Z' asTimestamp
     '2014-11-10 21:30:22.444+0200' asTimestamp

o  asTitlecase
return a version of the receiver, where the first character is converted to titlecase,
and everything else to lowercase.
See the comment in Character on what titlecase is.
usage example(s):
     'helloWorld' asTitlecase
     'HelloWorld' asTitlecase
     'HELLOWORLD' asTitlecase
     'helloworld' asTitlecase

o  asTitlecaseFirst
return a version of the receiver, where the first character is converted to titlecase.
Titlecase is much like uppercase for most characters, with the exception of some combined
(2-character glyphs), which consist of an upper- and lower-case characters.
If the first character is already titlecase, or there is no titlecasepercase for it, return the
receiver.
usage example(s):
     'helloWorld' asTitlecaseFirst
     'HelloWorld' asTitlecaseFirst

o  asTwoByteString
return the receiver converted to a two-byte string.
Will be obsolete soon - use asUnicode16String.

o  asURI
return an URI with string taken from the receiver

o  asURL
return an URL-object from myself.
usage example(s):
     'http://www.exept.de:80/index.html' asURL host
     'http://www.exept.de:80/index.html' asURL port
     'http://www.exept.de:80/index.html' asURL method
     'http://www.exept.de:80/index.html' asURL path

o  asUUID
return self as a UUID
usage example(s):
     UUID genUUID asString asUUID
     '{EAB22AC0-30C1-11CF-A7EB-0000C05BAE0B}' asUUID
     '{EAB22AC0-30C1-11CF-A7EB-0000C05BAE0B}' asUnicodeString asUUID
     'EAB22AC0-30C1-11CF-A7EB-0000C05BAE0B' asUUID
     'EAB22AC0-30C1-11CF-A7EB-0000C05BAE0B quatsch' asUUID
     'quark EAB22AC0-30C1-11CF-A7EB-0000C05BAE0B' asUUID

o  asUnicode16String
return the receiver in a two-byte per character representation.
Normally, the internal ST/X representation should be transparent and not
of the programmer's concern; except when strings are passed to the outside world,
such as wide-string ffi calls or file contents.
usage example(s):
        'abc' asUnicode16String

o  asUnicode16StringZ
return the receiver in a two-byte per character representation.
Make sure that is zero terminated (last char is 16r0000).
Normally, the internal ST/X representation should be transparent and not
of the programmer's concern; except when strings are passed to the outside world,
such as wide-string ffi calls or file contents.
usage example(s):
        '' asUnicode16StringZ
        'abc' asUnicode16StringZ
        'abc' asUnicode16String asUnicode16StringZ

o  asUnicode32String
return the receiver in a four-byte per character representation.
Normally, the internal ST/X representation should be transparent and not
of the programmer's concern; except when strings are passed to the outside world,
such as wide-string ffi calls or file contents.

o  asUnicodeString
return the receiver in a two-byte per character representation.
Normally, the internal ST/X representation should be transparent and not
of the programmer's concern; except when strings are passed to the outside world,
such as wide-string ffi calls or file contents.
usage example(s):
     'Hello World' asUnicodeString

o  asUnixFilename
return a UnixFilename with pathname taken from the receiver

o  asUppercase
return a copy of myself in uppercase letters
usage example(s):
     'helloWorld' asUppercase
     'helloWorld' asUppercaseFirst
     (Character value:16rB5) asString asUppercase   -- needs 16 bits !
     (Character value:16rFF) asString asUppercase   -- needs 16 bits !

o  asUppercaseFirst
return a version of the receiver, where the first character is converted to uppercase.
If the first character is already uppercase, or there is no uppercase for it, return the
receiver.
usage example(s):
     'helloWorld' asUppercase
     'helloWorld' asUppercaseFirst
     'HelloWorld' asUppercaseFirst

o  asUppercaseLast
return a copy of myself where the last character is
converted to uppercase.
usage example(s):
     'HelloWorld' asUppercase
     'HelloWorld' asUppercaseLast

o  asUtcTimestamp
convert the receiver into an UtcTimestamp (Time is interpreted in the UTC timezone).
Notice, that errors may occur during the read,
so you better setup some exception handler when using this method.
usage example(s):
     '2014-11-10 21:30:22.444' asUtcTimestamp

o  literalArrayEncoding
encode myself as an array literal, from which a copy of the receiver
can be reconstructed with #decodeAsLiteralArray.

o  scanf: dataStreamOrString
( an extension from the stx:libbasic2 package )
Return a Collection of objects found in the Character Stream
<dataStream> as interpreted according to the receiver.
The receiver is assumed to be a conversion control string as
specified in the Unix C-language manual page for scanf(3).
For copyright information, see goodies/String-printf_scanf.chg
usage example(s):
     '%d %x' scanf:(ReadStream on:'1234 ff00')
     '%d %s' scanf:(ReadStream on:'1234 ff00')
     '%d %b' scanf:(ReadStream on:'1234 1111')
     '%d %f' scanf:(ReadStream on:'1234 1111')
     '%d %f' scanf:(ReadStream on:'1234 1111.2345')
     '%d %q' scanf:(ReadStream on:'1234 1111.2345')

o  sscanf: string
( an extension from the stx:libbasic2 package )
Return a Collection of objects found in <string> as
interpreted according to the receiver.
The receiver is assumed to be a conversion control string as
specified in the Unix C-language manual page for scanf(3).
For copyright information, see goodies/String-printf_scanf.chg
usage example(s):
     '%d %x' sscanf:'1234 ff00'
     '%d %x %b' sscanf:'1234 ff00 1001'

o  string
return the receiver - for ST-80 compatibility

copying
o  , aStringOrCharacterOrAnyOther
redefined to allow characters and mixed strings to be appended.
This is nonStandard, but convenient
usage example(s):
     'hello' , $1
     'hello' , '1'
     'hello' , (' world' asText allBold)
     'hello' , (JISEncodedString fromString:' world')
     (JISEncodedString fromString:'hello') , ' world'

     Transcript showCR:
         (Text string:'hello' emphasis:#italic) , (Text string:' world' emphasis:#bold)

     'hello',123,'world'
     'hello' allBold,123,'world'
     'hello',123,'world' allBold

o  ,, aString
concatenate with a newLine in between
usage example(s):
     hello ,, world
     'hello' ,, 'world'

o  chopTo: maxLen
if the receiver's size is less or equal to maxLen, return it.
Otherwise, return a copy of the receiver, where some characters
in the middle have been removed for a total string length
of maxLen.
usage example(s):
     '12345678901234'   chopTo:15
     '123456789012345'  chopTo:15
     '1234567890123456' chopTo:15
     'aShortString' chopTo:15
     'aVeryLongNameForAStringThatShouldBeShortened' chopTo:15

o  contractAtBeginningTo: maxLen
if the receiver's size is less or equal to maxLen, return it.
Otherwise, return a copy of the receiver, where some characters
at the beginning have been replaced by '...' for a total string length
of maxLen. Can be used to abbreviate long entries in tables.
usage example(s):
     '12345678901234' contractAtBeginningTo:15
     '123456789012345' contractAtBeginningTo:15
     '1234567890123456' contractAtBeginningTo:15
     'aShortString' contractAtBeginningTo:15
     'aVeryLongNameForAStringThatShouldBeShortened' contractAtBeginningTo:15

o  contractAtEndTo: maxLen
if the receiver's size is less or equal to maxLen, return it.
Otherwise, return a copy of the receiver, where some characters
at the end have been replaced by '...' for a total string length
of maxLen. Can be used to abbreviate long entries in tables.
usage example(s):
     '12345678901234' contractAtEndTo:15
     '123456789012345' contractAtEndTo:15
     '1234567890123456' contractAtEndTo:15
     'aShortString' contractAtEndTo:15
     'aVeryLongNameForAStringThatShouldBeShortened' contractAtEndTo:15

o  contractLeftTo: maxLen
if the receiver's size is less or equal to maxLen, return it.
Otherwise, return a copy of the receiver, where some characters
near the first quarter have been replaced by '...' for a total string length
of maxLen.
Very similar to contractTo:, but better to abbreviate long filename entries,
where the right part is of more use than the left.
usage example(s):
     '12345678901234' contractLeftTo:15
     '123456789012345' contractLeftTo:15
     '1234567890123456' contractLeftTo:15
     'aShortString' contractLeftTo:15
     'aVeryLongNameForAStringThatShouldBeShortened' contractLeftTo:15
     'C:\Dokumente und Einstellungen\cg\work\bosch\dapas\hw_schnittstellen\DAPAS__HpibDLL.st' contractLeftTo:40

o  contractTo: maxLen
if the receiver's size is less or equal to maxLen, return it.
Otherwise, return a copy of the receiver, where some characters
in the middle have been replaced by '...' for a total string length
of maxLen. Can be used to abbreviate long entries in tables.
usage example(s):
     '12345678901234' contractTo:15
     '123456789012345' contractTo:15
     '1234567890123456' contractTo:15
     '12345678901234567' contractTo:15
     '123456789012345678' contractTo:15
     'aShortString' contractTo:15
     'aVeryLongNameForAStringThatShouldBeShortened' contractTo:15
     'C:\Dokumente und Einstellungen\cg\work\bosch\dapas\hw_schnittstellen\DAPAS__HpibDLL.st' contractTo:40
     ('1234567890123456789012345678901234567' contractTo:30) size
     ('1234567890123456789012345678901234567' contractTo:29) size

o  copyReplaceAll: oldElement with: newElement
return a copy of the receiver as a string, where all elements equal to oldElement
have been replaced by newElement.

o  copyReplaceString: subString withString: newString
return a copy of the receiver, with all sequences of subString replaced
by newString (i.e. slice in the newString in place of the oldString).
usage example(s):
     '12345678901234567890' copyReplaceString:'123' withString:'OneTwoThree'
     '12345678901234567890' copyReplaceString:'123' withString:'*'
     '12345678901234567890' copyReplaceString:'234' withString:'foo'
     '12345678901234567890' asUnicode16String copyReplaceString:'234' asUnicode16String withString:'foo'
     '12345678901234567890' asUnicode16String copyReplaceString:'234' withString:'foo'
     '12345678901234567890' asUnicode16String copyReplaceString:'234' withString:'foo' asUnicode16String

     ('a string with spaces' copyReplaceAll:$  withAll:' foo ')
        copyReplaceString:'foo' withString:'bar'

o  copyWith: aCharacter
return a new string containing the receiver's characters
and the single new character, aCharacter.
This is different from concatentation, which expects another string
as argument, but equivalent to copy-and-addLast.
The code below cares for different width characters
(i.e. when appending a 16bit char to an 8bit string)

o  restAfter: keyword withoutSeparators: strip
compare the left of the receiver with keyword,
if it matches return the right.
Finally, if strip is true, remove whiteSpace.
This method is used to match and extract lines of the form:
something: rest
where we are interested in rest, but only if the receiver string
begins with something.

You may wonder why such a specialized method exists here
- this is so common when processing mailboxes,
rcs files, nntp/pop3 responses, that is was considered worth
a special method here to avoid having the code below a hundred
times in variuos places.
usage example(s):
     'foo: hello world' restAfter:'foo:' withoutSeparators:true
     'funny: something' restAfter:'foo:' withoutSeparators:true

     'foo:     hello world    ' restAfter:'foo:' withoutSeparators:true
     'foo:     hello world    ' restAfter:'foo:' withoutSeparators:false

o  splitAtString: subString withoutSeparators: strip
If the receiver is of the form:
<left><subString><right>
return a collection containing left and right only.
If strip is true, remove whiteSpace in the returned substrings.
usage example(s):
     'hello -> world' splitAtString:'->' withoutSeparators:false
     'hello -> world' splitAtString:'->' withoutSeparators:true
     'hello -> ' splitAtString:'->' withoutSeparators:true
     'hello > error' splitAtString:'->' withoutSeparators:true

displaying
o  displayOn: aGC x: x y: y from: start to: stop
display the receiver on a GC

o  displayOn: aGC x: x y: y from: start to: stop opaque: opaque
display the receiver on a GC

o  displayOn: aGc x: x y: y opaque: opaque
display the receiver in a graphicsContext - this method allows
strings to be used like DisplayObjects.

o  displayOpaqueOn: aGC x: x y: y from: start to: stop
display the receiver on a GC

emphasis
o  actionForAll: aBlock
change the action block of all characters.
Some widgets use this like a href if clicked onto the text.

o  allBold
return a text object representing the receiver, but all boldified
usage example(s):
     Transcript showCR:'hello' asText allBold
     Transcript showCR:'hello' allBold

o  allItalic
return a text object representing the receiver, but all in italic
usage example(s):
     Transcript showCR:'hello' asText allItalic
     Transcript showCR:'hello' allItalic

o  allStrikedOut
return a text object representing the receiver, but all in strikeout
usage example(s):
     Transcript showCR:'hello' asText allStrikedOut
     Transcript showCR:'hello' allStrikedOut

o  allUnderlined
return a text object representing the receiver, but all with underline
usage example(s):
     Transcript showCR:'hello' asText allUnderlined
     Transcript showCR:'hello' allUnderlined

o  asActionLinkTo: aBlock
change the action block of all characters and colorize as a link.
Some widgets use this like a href if clicked onto the text
(for example, the system-browser's info at the bottom is such a widget).

o  colorizeAllWith: aColor
return a text object representing the receiver, but all colorized
usage example(s):
     Transcript showCR:('hello' colorizeAllWith:Color red)
     Transcript showCR:('world' colorizeAllWith:Color green darkened)

o  colorizeAllWith: fgColor on: bgColor
return a text object representing the receiver, but all colorized with
both fg and background color
usage example(s):
     Transcript showCR:('hello' colorizeAllWith:Color red on:Color yellow)
     Transcript showCR:('world' colorizeAllWith:Color red)

o  emphasis
return the emphasis.
Since characterArrays do not hold any emphasis information,
nil (no emphasis) is returned here.

o  emphasis: emphasisCollection
Transcript showCR:('hello' emphasis:#(bold bold bold bold bold))

o  emphasisAt: characterIndex
return the emphasis at some index.
Since characterArrays do not hold any emphasis information,
nil (no emphasis) is returned here.

o  emphasisAtPoint: aPoint on: aGC
return the emphasis at a given point, or nil if there is none

o  emphasisCollection
return the emphasis.
Since characterArrays do not hold any emphasis information,
nil (no emphasis) is returned here.

o  emphasiseFrom: start to: stop with: newEmphasis
set to the emphasis within some range. return the receiver
usage example(s):
     'hello' emphasiseFrom:2 with:#italic

     Transcript showCR:('hello' emphasiseFrom:2 with:#italic)

o  emphasiseFrom: start with: newEmphasis
set to the emphasis within some range. return the receiver
usage example(s):
     'hello' emphasiseFrom:2 with:#italic

     Transcript showCR:('hello' emphasiseFrom:2 with:#italic)

o  emphasizeAllWith: emphasis
return a text object representing the receiver, but all emphasized
usage example(s):
     Transcript showCR:('hello' emphasizeAllWith:#bold)
     Transcript showCR:('hello' emphasizeAllWith:(#color -> Color red))
     Transcript showCR:('hello' emphasizeAllWith:(#color -> Color red))

o  makeSelectorBoldIn: aClass
the receiver represents some source code for a method in aClass.
Change myself to boldify the selector.
Not yet implemented (could easily use the syntaxHighlighter for this ...).
For protocol compatibility with other smalltalks

o  withColor: aColorOrColorSymbol
return a text object representing the receiver, but all colorized.
Usage of a colorSymbol is considered bad style (provided for backward compatibility);
please change to pass a proper color
(makes it easier to find color uses)
usage example(s):
     Transcript showCR:('hello' withColor:#red)
     Transcript showCR:('world' withColor:#blue)
     Transcript showCR:('hello' withColor:Color red)
     Transcript showCR:('world' withColor:Color green darkened)

o  withColor: foregroundColorOrColorSymbol on: backgroundColorOrColorSymbol
return a text object representing the receiver, but all colorized with both fg and bg.
Usage of a colorSymbol is considered bad style (provided for backward compatibility);
please change to pass a proper color
(makes it easier to find color uses)
usage example(s):
     Transcript showCR:('hello' withColor:#red on:#blue)
     Transcript showCR:('hello' withColor:Color red on:Color blue)

o  withoutAnyColorEmphasis
for protocol compatibility with Text

o  withoutBackgroundColorEmphasis
for protocol compatibility with Text

o  withoutEmphasis: emphasisToRemove
for protocol compatibility with Text

o  withoutForegroundColorEmphasis
for protocol compatibility with Text

encoding & decoding
o  asDenormalizedUnicodeString
return a new string containing the same characters, as a denormalized Unicode string.
This replaces diacritical chars (umlauts, accented chars etc) by
a sequence with combination characters.
(i.e. a plain character followed by a combining diacritical in the 0x03xx range)
usage example(s):
     'Ö' asDenormalizedUnicodeString 
     'aÖÄx' asDenormalizedUnicodeString 
     'abc' asDenormalizedUnicodeString 
     'ṩ' asDenormalizedUnicodeString 

o  asNormalizedUnicodeString
return a new string containing the same characters, as a normalized Unicode string.
This replaces combination characters by corresponding single characters.
(i.e. diaresis and other combining diacriticals in the 0x03xx range).
Caveat:
possibly incomplete: only COMBINING_DIACRITICAL_MARKS are cared for.
Does not care for COMBINING_DIACRITICAL_MARKS_EXTENDED
and COMBINING_DIACRITICAL_MARKS_SUPPLEMENT.
However; those are used for German dialectology, ancient Greek and other similar
exotic uses. Probably noone will ever even notice that they are missing...
usage example(s):
     self unicodeNormalizationMap
     ('O' , (Character value:16r0308)) asNormalizedUnicodeString -> 'Ö'
     ('O' , (Character value:16r0308) ,
      'A' , (Character value:16r0308)) asNormalizedUnicodeString -> 'ÖÄ'
     ('s' , (Character value:16r0323) , (Character value:16r0307)) asNormalizedUnicodeString -> 'ṩ'
     ('s' , (Character value:16r0307) , (Character value:16r0323)) asNormalizedUnicodeString -> 'ṩ'

o  decodeAsLiteralArray
given a literalEncoding in the receiver,
create & return the corresponding object.
The inverse operation to #literalArrayEncoding.

o  decodeFrom: encodingSymbol
given the receiver encoded as described by encodingSymbol,
convert it into internal ST/X (unicode) encoding and return a corresponding CharacterArray.

o  encodeFrom: oldEncoding into: newEncoding
'äüö' encodeFrom:#iso8859 into:#utf8
('äüö' encodeFrom:#iso8859 into:#utf8) encodeFrom:#utf8 into:#unicode

o  encodeInto: newEncoding
'äüö' encodeInto:#utf8
('äüö' encodeInto:#utf8) decodeFrom:#utf8

o  rot13
Usenet: from `rotate alphabet 13 places']
The simple Caesar-cypher encryption that replaces each English
letter with the one 13 places forward or back along the alphabet,
so that 'The butler did it!' becomes 'Gur ohgyre qvq vg!'
Most Usenet news reading and posting programs include a rot13 feature.
It is used to enclose the text in a sealed wrapper that the reader must choose
to open -- e.g., for posting things that might offend some readers, or spoilers.
A major advantage of rot13 over rot(N) for other N is that it
is self-inverse, so the same code can be used for encoding and decoding.
usage example(s):
     'hello world' rot13
     'hello world' rot13 rot13

o  rot: n
Usenet: from `rotate alphabet N places']
The simple Caesar-cypher encryption that replaces each English
letter with the one N places forward or back along the alphabet,
so that 'The butler did it!' becomes 'Gur ohgyre qvq vg!' by rot 13
Most Usenet news reading and posting programs include a rot13 feature.
It is used to enclose the text in a sealed wrapper that the reader must choose
to open -- e.g., for posting things that might offend some readers, or spoilers.
A major advantage of rot13 over rot(N) for other N is that it
is self-inverse, so the same code can be used for encoding and decoding.
usage example(s):
     'hello world' rot:13
     ('hello world' rot:13) rot:13

o  utf16Encoded
Return my UTF-16 representation as a new TwoByteString
usage example(s):
     'abcde1234' utf16Encoded
     'abcdeäöüß' utf16Encoded

o  utf8Encoded
return the UTF-8 representation of a Unicode string.
The resulting string is only useful to be stored on some external file,
or sent to a communaction channel.
Not for being used inside ST/X.
usage example(s):
     'hello' utf8Encoded asByteArray                             #[104 101 108 108 111]
     (Character value:16r40) asString utf8Encoded asByteArray    #[64]
     (Character value:16r7F) asString utf8Encoded asByteArray    #[127]
     (Character value:16r80) asString utf8Encoded asByteArray    #[194 128]
     (Character value:16rFF) asString utf8Encoded asByteArray    #[195 191]
     (Character value:16r100) asString utf8Encoded asByteArray   #[196 128]
     (Character value:16r200) asString utf8Encoded asByteArray   #[200 128]
     (Character value:16r400) asString utf8Encoded asByteArray   #[208 128]
     (Character value:16r800) asString utf8Encoded asByteArray   #[224 160 128]
     (Character value:16r1000) asString utf8Encoded asByteArray  #[225 128 128]
     (Character value:16r2000) asString utf8Encoded asByteArray  #[226 128 128]
     (Character value:16r4000) asString utf8Encoded asByteArray  #[228 128 128]
     (Character value:16r8000) asString utf8Encoded asByteArray  #[232 128 128]
     (Character value:16rFFFF) asString utf8Encoded asByteArray  #[239 191 191]
     (Character value:16r1FFFF) asString utf8Encoded asByteArray #[240 159 191 191]
     (Character value:16r3FFFF) asString utf8Encoded asByteArray #[240 191 191 191]
     (Character value:16rFFFFF) asString utf8Encoded asByteArray #[243 191 191 191]
     (Character value:16r3FFFFF) asString utf8Encoded asByteArray #[248 143 191 191 191]

     'abcde1234' asUnicode32String utf8Encoded
     'abcdeäöüß' asUnicode32String utf8Encoded

o  utf8EncodedOn: aStream
write the UTF-8 representation of myself to aStream.

filling and replacing
o  clearContents
to be used with cryptographic keys, to wipe their contents after use

inspecting
o  inspector2TabBytes
( an extension from the stx:libtool package )
ouch - ever tried to inspect a 5Mb string?

o  inspector2TabDiff
( an extension from the stx:libtool package )

o  inspector2TabHTML
( an extension from the stx:libtool package )
use Smalltalk >> at:, to prevent HTMLDocumentView becoming a prereq of libbasic

o  inspector2TabText
( an extension from the stx:libtool package )

o  inspector2TabXMLTree
( an extension from the stx:libtool package )
extra tab to be shown in an inspector2.

o  inspector2Tabs
( an extension from the stx:libtool package )

o  inspectorExtraAttributes
( an extension from the stx:libtool package )
extra (pseudo instvar) entries to be shown in an inspector.

o  inspectorValueStringInListFor: anInspector
( an extension from the stx:libtool package )
returns a string to be shown in the inspector's list

matching - glob expressions
o  compoundMatch: aString
like match, but the receiver may be a compound match pattern,
consisting of multiple simple GLOB patterns, separated by semicolons.
This is usable with fileName pattern fields.

NOTICE: match-meta character interpretation is like in unix-matching (glob),
NOT the ST-80 meaning.
NOTICE: this is GLOB, which is different from regex matching (see matchesRegex:)
NOTICE: the receiver is the match pattern
usage example(s):
     'f*' match:'foo'
     'b*' match:'foo'
     'f*;b*' match:'foo'
     'f*;b*' match:'bar'
     'f*;b*' compoundMatch:'foo'
     'f*;b*' compoundMatch:'bar'

o  compoundMatch: aString caseSensitive: caseSensitive
like match, but the receiver may be a compound match pattern,
consisting of multiple simple GLOB patterns, separated by semicolons.
This is usable with fileName pattern fields.

NOTICE: match-meta character interpretation is like in unix-matching (glob),
NOT the ST-80 meaning.
NOTICE: this is GLOB, which is different from regex matching (see matchesRegex:)
NOTICE: the receiver is the match pattern
usage example(s):
     'f*' match:'foo'
     'b*' match:'foo'
     'f*;b*' match:'foo'
     'f*;b*' match:'bar'
     'f*;b*' compoundMatch:'foo'
     'f*;b*' compoundMatch:'bar'
     'f*;b*' compoundMatch:'Foo' caseSensitive:false
     'f*;b*' compoundMatch:'Bar' caseSensitive:false
     'f*;b*' compoundMatch:'ccc' caseSensitive:false

o  compoundMatch: aString caseSensitive: caseSensitive withoutSeparators: withoutSeparators
like match, but the receiver may be a compound match pattern,
consisting of multiple simple GLOB patterns, separated by semicolons.
If withoutSeparators is true, spaces around individual patterns are stripped off.
This is usable with fileName pattern fields.

NOTICE: match-meta character interpretation is like in unix-matching (glob),
NOT the ST-80 meaning.
NOTICE: this is GLOB, which is different from regex matching (see matchesRegex:)
NOTICE: the receiver is the match pattern
usage example(s):
     'f*' match:'foo'
     'b*' match:'foo'
     'f*;b*' match:'foo'
     'f*;b*' match:'bar'
     'f*;b*' compoundMatch:'foo'
     'f*;b*' compoundMatch:'bar'
     'f*;b*' compoundMatch:'Foo' caseSensitive:false
     'f*;b*' compoundMatch:'Bar' caseSensitive:false
     'f*;b*' compoundMatch:'ccc' caseSensitive:false

     'f* ; b*' compoundMatch:'foo'
     'f* ; b*' compoundMatch:'foo' caseSensitive:true withoutSeparators:true

o  compoundMatch: aString ignoreCase: ignoreCase
like match, but the receiver may be a compound match pattern,
consisting of multiple simple GLOB patterns, separated by semicolons.
This is usable with fileName pattern fields.

NOTICE: match-meta character interpretation is like in unix-matching (glob),
NOT the ST-80 meaning.
NOTICE: this is GLOB, which is different from regex matching (see matchesRegex:)
NOTICE: the receiver is the match pattern

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  findMatchString: matchString
like findString/indexOfSubCollection, but allowing GLOB match patterns.
find matchstring; if found, return the index;
if not found, return 0.

NOTICE: match-meta character interpretation is like in unix-matching,
NOT the ST-80 meaning.
NOTICE: this GLOB, which is different from regex matching (see matchesRegex:)
NOTICE: the argument is the match pattern
usage example(s):
      1234567890123
     'hello world bla foo baz' findMatchString:'b* '

o  findMatchString: matchString startingAt: index
like findString, but allowing GLOB match patterns.
find matchstring, starting at index. if found, return the index;
if not found, return 0.

NOTICE: match-meta character interpretation is like in unix-matching (glob),
NOT the ST-80 meaning.
NOTICE: this is GLOB, which is different from regex matching (see matchesRegex:)
NOTICE: the argument is the match pattern

o  findMatchString: matchString startingAt: index caseSensitive: caseSensitive ifAbsent: exceptionBlock
like findString, but allowing GLOB match patterns.
find matchstring, starting at index. if found, return the index;
if not found, return the result of evaluating exceptionBlock.
This is a q&d hack - not very efficient.

NOTICE: match-meta character interpretation is like in unix-matching (glob),
NOT the ST-80 meaning.
NOTICE: this is GLOB, which is different from regex matching (see matchesRegex:)
NOTICE: the argument is the match pattern
usage example(s):
     'one two three four' findMatchString:'o[nu]'
     'one two three four' findMatchString:'o[nu]' startingAt:3
     'one two three four one' findMatchString:'ONE' startingAt:3 caseSensitive:false ifAbsent:0
     'one two three four one' findMatchString:'ONE' startingAt:3 caseSensitive:true ifAbsent:0
     'one two three four ONE' findMatchString:'O#E' startingAt:1 caseSensitive:false ifAbsent:0
     'one two three four ONE' findMatchString:'O#E' startingAt:1 caseSensitive:true ifAbsent:0
      12345678901234567890

o  findMatchString: matchString startingAt: index ignoreCase: ignoreCase ifAbsent: exceptionBlock
like findString, but allowing GLOB match patterns.
find matchstring, starting at index. if found, return the index;
if not found, return the result of evaluating exceptionBlock.
This is a q&d hack - not very efficient.

NOTICE: match-meta character interpretation is like in unix-matching (glob),
NOT the ST-80 meaning.
NOTICE: this is GLOB, which is different from regex matching (see matchesRegex:)
NOTICE: the argument is the match pattern

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  globPatternAsRegexPattern
taking the receiver as a GLOB pattern,
return a corresponding regex pattern.
As regex does provide information about the matching substring,
it may be useful to apply a regex after a GLOB match,
in order to highlight matching substrings (eg. in a CodeView after a search).
If it turns out to be better, we may convert all GLOB searches to regex and use it right away.
(currently, it is not sure, if GLOB is not better for most simple searches, as they are encountered
in typical real life)
usage example(s):
     'hello' globPatternAsRegexPattern
     'hello*' globPatternAsRegexPattern
     '*hello*' globPatternAsRegexPattern
     'h###' globPatternAsRegexPattern
     'h[0-9]' globPatternAsRegexPattern
     'h[0-9][0-9][0-9]' globPatternAsRegexPattern
     'h[0-9]*' globPatternAsRegexPattern
     'h[-+]*' globPatternAsRegexPattern

     'hello world' matches:'h*w'
     'hello world' matchesRegex:('h*w' globPatternAsRegexPattern)
     'hello world' matches:'h*d'
     'hello world' matchesRegex:('h*d' globPatternAsRegexPattern)

o  includesMatchString: matchString
like includesString, but allowing GLOB match patterns.
find matchstring; if found, return true, otherwise return false.

NOTICE: match-meta character interpretation is like in unix-matching (glob),
NOT the ST-80 meaning.
NOTICE: this is GLOB, which is different from regex matching (see matchesRegex:)
NOTICE: the argument is the match pattern
usage example(s):
     'hello world' includesMatchString:'h*'
     'hello world' includesMatchString:'h[aeiou]llo'
     'hello world' includesMatchString:'wor*'
     'hello world' includesMatchString:'woR*'

o  includesMatchString: matchString caseSensitive: caseSensitive
like includesString, but allowing GLOB match patterns.
find matchstring; if found, return true, otherwise return false.

NOTICE: match-meta character interpretation is like in unix-matching (glob),
NOT the ST-80 meaning.
NOTICE: this is GLOB, which is different from regex matching (see matchesRegex:)
NOTICE: the argument is the match pattern
usage example(s):
     'hello world' includesMatchString:'h*' caseSensitive:true
     'hello world' includesMatchString:'h*' caseSensitive:false
     'Hello world' includesMatchString:'h*' caseSensitive:true
     'Hello world' includesMatchString:'h*' caseSensitive:false

     'hello world' includesMatchString:'h[aeiou]llo' caseSensitive:true
     'hello world' includesMatchString:'h[aeiou]llo' caseSensitive:false

     'hello world' includesMatchString:'wor*' caseSensitive:true
     'hello world' includesMatchString:'wor*' caseSensitive:false

     'hello world' includesMatchString:'woR*' caseSensitive:true
     'hello world' includesMatchString:'woR*' caseSensitive:false

o  match: aString
return true if aString matches self, where self may contain GLOB meta-match
characters $* (to match any string) or $# (to match any character).
or [...] to match a set of characters.
Lower/uppercase are considered different.
The escape character is the backQuote.

NOTICE: match-meta character interpretation is like in unix-matching (glob),
NOT the ST-80 meaning.
NOTICE: this is GLOB, which is different from regex matching (see matchesRegex:)
NOTICE: the receiver is the match pattern
usage example(s):
     '#f#' match:'afc'
     '#f#' match:'aec'
     '#f#' match:'ae'
     '#f#' match:'a'
     '#f#' match:'f'
     '#f#' match:'ff'

     '\*f*' match:'f'
     '\*f*' match:'*f'
     '*\*f*' match:'*f'
     '*f*' match:'*f'
     '*ute*' match:'computer'
     '*uter' match:'computer'
     'uter*' match:'computer'
     '*ute*' match:''
     '[abcd]*' match:'computer'
     '[abcd]*' match:'komputer'
     '*some*compl*ern*' match:'this is some more complicated pattern match'
     '*some*compl*ern*' match:'this is another complicated pattern match'
     '*-hh' match:'anton-h'

o  match: aString caseSensitive: caseSensitive
return true if aString matches self, where self may contain GLOB meta-match
characters $* (to match any string) or $# (to match any character)
or [...] to match a set of characters.
If caseSensitive is false, lower/uppercase are considered the same.
The escape character is the backQuote.

NOTICE: match-meta character interpretation is like in unix-matching (glob),
NOT the ST-80 meaning.
NOTICE: this is GLOB, which is different from regex matching (see matchesRegex:)
NOTICE: the receiver is the match pattern
usage example(s):
     '*ute*' match:'COMPUTER' caseSensitive:false
     '*uter' match:'COMPUTER' caseSensitive:true
     '[abcd]*' match:'computer' caseSensitive:true
     '[abcd]*' match:'Computer' caseSensitive:true
     '[a-k]*' match:'komputer' caseSensitive:true
     '[a-k]*' match:'zomputer' caseSensitive:true
     '[a-k]*' match:'Komputer' caseSensitive:true
     '[a-k]*' match:'Komputer' caseSensitive:false
     '*some*compl*ern*' match:'this is some more complicated pattern match' caseSensitive:false
     '*some*compl*ern*' match:'this is another complicated pattern match' caseSensitive:false

     Time millisecondsToRun:[
        Symbol allInstancesDo:[:sym |
            '[ab]*' match:sym caseSensitive:true
        ]
     ].
     Time millisecondsToRun:[
        Symbol allInstancesDo:[:sym |
            '*at:*' match:sym caseSensitive:true
        ]
     ].

o  match: aString caseSensitive: caseSensitive escapeCharacter: escape
return true if aString matches self, where self may contain GLOB meta-match
characters $* (to match any string) or $# (to match any character)
or [...] to match a set of characters.
If caseSensitive is false, lower/uppercase are considered the same.

NOTICE: match-meta character interpretation is like in unix-matching (glob),
NOT the ST-80 meaning.
NOTICE: this is GLOB, which is different from regex matching (see matchesRegex:)
NOTICE: the receiver is the match pattern
usage example(s):
     '*ute*' match:'COMPUTER' caseSensitive:false
     '*uter' match:'COMPUTER' caseSensitive:true
     '[abcd]*' match:'computer' caseSensitive:true
     '[abcd]*' match:'Computer' caseSensitive:true
     '[a-k]*' match:'komputer' caseSensitive:true
     '[a-k]*' match:'zomputer' caseSensitive:true
     '[a-k]*' match:'Komputer' caseSensitive:true
     '[a-k]*' match:'Komputer' caseSensitive:false
     '*some*compl*ern*' match:'this is some more complicated pattern match' caseSensitive:false
     '*some*compl*ern*' match:'this is another complicated pattern match' caseSensitive:false

     Time millisecondsToRun:[
        Symbol allInstancesDo:[:sym |
            '[ab]*' match:sym caseSensitive:true
        ]
     ].
     Time millisecondsToRun:[
        Symbol allInstancesDo:[:sym |
            '*at:*' match:sym caseSensitive:true
        ]
     ].

o  match: aString escapeCharacter: escape
return true if aString matches self, where self may contain GLOB meta-match
characters $* (to match any string) or $# (to match any character).
or [...] to match a set of characters.
Lower/uppercase are considered different.

NOTICE: match-meta character interpretation is like in unix-matching (glob),
NOT the ST-80 meaning.
NOTICE: this is GLOB, which is different from regex matching (see matchesRegex:)
NOTICE: the receiver is the match pattern
usage example(s):
     'a\b\c\*' match:'a\b\c\d'
     'a\b\c\*' match:'a\b\c\d' escapeCharacter:nil

o  match: aString from: start to: stop caseSensitive: caseSensitive
return true if part of aString matches myself,
where self may contain GLOB meta-match
characters $* (to match any string) or $# (to match any character)
or [...] to match a set of characters.
If caseSensitive is false, lower/uppercase are considered the same.
The escape character is the backQuote.

NOTICE: match-meta character interpretation is like in unix-matching (glob),
NOT the ST-80 meaning.
NOTICE: this is GLOB, which is different from regex matching (see matchesRegex:)
NOTICE: the receiver is the match pattern
usage example(s):
     '*ute*' match:'12345COMPUTER' from:1 to:5 caseSensitive:false
     '*ute*' match:'12345COMPUTER' from:6 to:13 caseSensitive:false

o  match: aString from: start to: stop caseSensitive: caseSensitive escapeCharacter: escape
return true if part of aString matches myself,
where self may contain GLOB meta-match
characters $* (to match any string) or $# (to match any character)
or [...] to match a set of characters.
If caseSensitive is false, lower/uppercase are considered the same.

NOTICE: match-meta character interpretation is like in unix-matching (glob),
NOT the ST-80 meaning.
NOTICE: this is GLOB, which is different from regex matching (see matchesRegex:)
NOTICE: the receiver is the match pattern
usage example(s):
     '*ute*' match:'12345COMPUTER' from:1 to:5 caseSensitive:false
     '*ute*' match:'12345COMPUTER' from:6 to:13 caseSensitive:false

o  match: aString from: start to: stop ignoreCase: ignoreCase
return true if part of aString matches myself,
where self may contain GLOB meta-match
characters $* (to match any string) or $# (to match any character)
or [...] to match a set of characters.
If ignoreCase is true, lower/uppercase are considered the same.
The escape character is the backQuote.

NOTICE: match-meta character interpretation is like in unix-matching (glob),
NOT the ST-80 meaning.
NOTICE: this is GLOB, which is different from regex matching (see matchesRegex:)
NOTICE: the receiver is the match pattern

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  match: aString from: start to: stop ignoreCase: ignoreCase escapeCharacter: escape
return true if part of aString matches myself,
where self may contain GLOB meta-match
characters $* (to match any string) or $# (to match any character)
or [...] to match a set of characters.
If ignoreCase is true, lower/uppercase are considered the same.

NOTICE: match-meta character interpretation is like in unix-matching (glob),
NOT the ST-80 meaning.
NOTICE: this is GLOB, which is different from regex matching (see matchesRegex:)
NOTICE: the receiver is the match pattern

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  match: aString ignoreCase: ignoreCase
return true if aString matches self, where self may contain GLOB meta-match
characters $* (to match any string) or $# (to match any character)
or [...] to match a set of characters.
If ignoreCase is true, lower/uppercase are considered the same.
The escape character is the backQuote.

NOTICE: match-meta character interpretation is like in unix-matching (glob),
NOT the ST-80 meaning.
NOTICE: this is GLOB, which is different from regex matching (see matchesRegex:)
NOTICE: the receiver is the match pattern

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  match: aString ignoreCase: ignoreCase escapeCharacter: escape
return true if aString matches self, where self may contain GLOB meta-match
characters $* (to match any string) or $# (to match any character)
or [...] to match a set of characters.
If ignoreCase is true, lower/uppercase are considered the same.

NOTICE: match-meta character interpretation is like in unix-matching (glob),
NOT the ST-80 meaning.
NOTICE: this is GLOB, which is different from regex matching (see matchesRegex:)
NOTICE: the receiver is the match pattern

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  matches: aPatternString
return true if the receiver matches aString, where aPatternString may contain GLOB meta-match
characters $* (to match any string) or $# (to match any character).
or [...] to match a set of characters.
Lower/uppercase are considered different.

NOTICE: match-meta character interpretation is like in unix-matching (glob),
NOT the ST-80 meaning.
NOTICE: this is GLOB, which is different from regex matching (see matchesRegex:)
NOTICE: the receiver is the match pattern

o  matches: aPatternString caseSensitive: caseSensitive
return true if the receiver matches aString, where aPatternString may contain GLOB meta-match
characters $* (to match any string) or $# (to match any character).
or [...] to match a set of characters.

NOTICE: match-meta character interpretation is like in unix-matching (glob),
NOT the ST-80 meaning.
NOTICE: this is GLOB, which is different from regex matching (see matchesRegex:)
NOTICE: the receiver is the match pattern

o  matches: aPatternString ignoreCase: ignoreCase
return true if the receiver matches aString, where aPatternString may contain GLOB meta-match
characters $* (to match any string) or $# (to match any character).
or [...] to match a set of characters.
Lower/uppercase are considered different.

NOTICE: match-meta character interpretation is like in unix-matching (glob),
NOT the ST-80 meaning.
NOTICE: this is GLOB, which is different from regex matching (see matchesRegex:)
NOTICE: the receiver is the match pattern

** This is an obsolete interface - do not use it (it may vanish in future versions) **

matching - phonetic
o  asKoelnerPhoneticCode
( an extension from the stx:libbasic2 package )
return a koelner phonetic code.
The koelnerPhonetic code is for the german language what the soundex code is for english;
it returns simular strings for similar sounding words.
There are some differences to soundex, though:
its length is not limited to 4, but depends on the length of the original string;
it does not start with the first character of the input.

Caveat: this phonetic code is especially suited for german words.
Please have a look at the other phonetic comparison operators found
in PhoneticStringUtilities.
usage example(s):
     #(
	'Müller'
	'Miller'
	'Mueller'
	'Mühler'
	'Mühlherr'
	'Mülherr'
	'Myler'
	'Millar'
	'Myller'
	'Müllar'
	'Müler'
	'Muehler'
	'Mülller'
	'Müllerr'
	'Muehlherr'
	'Muellar'
	'Mueler'
	'Mülleer'
	'Mueller'
	'Nüller'
	'Nyller'
	'Niler'
	'Czerny'
	'Tscherny'
	'Czernie'
	'Tschernie'
	'Schernie'
	'Scherny'
	'Scherno'
	'Czerne'
	'Zerny'
	'Tzernie'
	'Breschnew'
     ) do:[:w |
	 Transcript show:w; show:'->'; showCR:(w asKoelnerPhoneticCode)
     ].
usage example(s):
     'Breschnew' asKoelnerPhoneticCode -> '17863'
     'Breschnew' asKoelnerPhoneticCode -> '17863'
     'Breschneff' asKoelnerPhoneticCode -> '17863'
     'Braeschneff' asKoelnerPhoneticCode -> '17863'
     'Braessneff' asKoelnerPhoneticCode -> '17863'
     'Pressneff' asKoelnerPhoneticCode -> '17863'
     'Presznäph' asKoelnerPhoneticCode -> '17863'

o  asSoundexCode
( an extension from the stx:libbasic2 package )
return a soundex phonetic code or nil.
Soundex returns similar codes for similar sounding words, making it a useful
tool when searching for words where the correct spelling is unknown.
(read Knuth or search the web if you don't know what a soundex code is).

Caveat: 'similar sounding words' means: 'similar sounding in ENGLISH'
Please have a look at the other phonetic comparison operators found
in PhoneticStringUtilities.
usage example(s):
     'claus' asSoundexCode
     'clause' asSoundexCode
     'close' asSoundexCode
     'smalltalk' asSoundexCode
     'smaltalk' asSoundexCode
     'smaltak' asSoundexCode
     'smaltok' asSoundexCode
     'smoltok' asSoundexCode
     'aa' asSoundexCode
     'by' asSoundexCode
     'bab' asSoundexCode
     'bob' asSoundexCode
     'bop' asSoundexCode

padded copying
o  centerPaddedTo: newSize
return a new string consisting of the receiver's characters,
plus spaces up to length and center the receiver's characters in
the resulting string.
If the receiver's size is equal or greater than the length argument,
the original receiver is returned unchanged.
usage example(s):
     'foo' centerPaddedTo:10
     123 printString centerPaddedTo:10

o  centerPaddedTo: size with: padCharacter
return a new string of length size, which contains the receiver
centered (i.e. padded on both sides).
Characters are filled with padCharacter.
If the receiver's size is equal or greater than the length argument,
the original receiver is returned unchanged.
usage example(s):
     'foo' centerPaddedTo:11 with:$.
     'fooBar' centerPaddedTo:5 with:$.
     123 printString centerPaddedTo:10 with:$.
     (' ' , 123 printString) centerPaddedTo:10 with:$.
     (Float pi printString) centerPaddedTo:15 with:(Character space)
     (Float pi printString) centerPaddedTo:15 with:$-
     (' ' , Float pi class name) centerPaddedTo:15 with:$.

o  decimalPaddedTo: size and: afterPeriod at: decimalCharacter
return a new string of overall length size, which contains the receiver
aligned at the decimal-period column and afterPeriod characters to the right
of the period. The periodCharacter is passed as arguments (allowing for US and European formats
to be padded).
If the receiver's size is equal or greater than the length argument,
the original receiver is returned unchanged.
(sounds complicated ? -> see examples below).
usage example(s):
     '123' decimalPaddedTo:10 and:3 at:$.      -> '   123    '
     '123' decimalPaddedTo:10 and:3 at:$.      -> '   123.000'
     '123.' decimalPaddedTo:10 and:3 at:$.     -> '   123.000'
     '123.1' decimalPaddedTo:10 and:3 at:$.    -> '   123.100'
     '123.1' decimalPaddedTo:10 and:3 at:$.    -> '   123.1  '
     '123.123' decimalPaddedTo:10 and:3 at:$.  -> '   123.123'

o  decimalPaddedTo: size and: afterPeriod at: decimalCharacter withLeft: leftPadChar right: rightPadChar
return a new string of overall length size, which contains the receiver
aligned at the decimal-period column and afterPeriod characters to the right
of the period.
Characters on the left are filled with leftPadChar.
If rightPadChar is nil, characters on the right are filled with leftPadCharacter too;
otherwise, if missing, a decimal point is added and right characters filled with this.
If the receiver's size is equal or greater than the length argument,
the original receiver is returned unchanged.
(sounds complicated ? -> see examples below).
usage example(s):
     '123' decimalPaddedTo:10 and:3 at:$. withLeft:(Character space) right:nil     -> '   123    '
     '123' decimalPaddedTo:10 and:3 at:$. withLeft:(Character space) right:$0      -> '   123.000'
     '123.' decimalPaddedTo:10 and:3 at:$. withLeft:(Character space) right:$0     -> '   123.000'
     '123.1' decimalPaddedTo:10 and:3 at:$. withLeft:(Character space) right:$0    -> '   123.100'
     '123.1' decimalPaddedTo:10 and:3 at:$. withLeft:(Character space) right:nil   -> '   123.1  '
     '123.123' decimalPaddedTo:10 and:3 at:$. withLeft:(Character space) right:$0  -> '   123.123'

o  leftPaddedTo: size
return a new string of length size, which contains the receiver
right-adjusted (i.e. padded on the left).
Characters on the left are filled with spaces.
If the receiver's size is equal or greater than the length argument,
the original receiver is returned unchanged.
usage example(s):
     'foo' leftPaddedTo:10
     'fooBar' leftPaddedTo:5
     123 printString leftPaddedTo:10

o  paddedTo: newSize
return a new string consisting of the receiver's characters,
plus spaces up to length.
If the receiver's size is equal or greater than the length argument,
the original receiver is returned unchanged.
usage example(s):
     'foo' paddedTo:10
     123 printString paddedTo:10
     '12345678901234' paddedTo:10

printing & storing
o  article
return an article string for the receiver.
The original code only looked at the first character being a vowel;
this has been enhanced by some heuristics - not perfect, still.
usage example(s):
        'uboot' article.
        'xmas' article.
        'alarm' article.
        'baby' article.
        'sql' article.
        'scr' article.
        'screen' article.
        'scrollbar' article.
        'scrs' article.
        'cvs' article.
        'cvssource' article.
        'symbol' article.
        'string' article.
        'rbparser' article.

o  basicStoreString
return a String for storing myself
usage example(s):
     '''immutable'' string' asImmutableString basicStoreString
     'immutable string' asImmutableString basicStoreString

o  displayOn: aGCOrStream
Compatibility
append a printed desription on some stream (Dolphin, Squeak)
OR:
display the receiver in a graphicsContext at 0@0 (ST80).
This method allows for any object to be displayed in some view
(although the fallBack is to display its printString ...)

o  printOn: aStream
print the receiver on aStream

o  printString
return a string for printing - that's myself

o  printWithQuotesDoubledOn: aStream
put the raw storeString of myself on aStream

o  printXmlQuotedOn: aStream
convert aString to a valid XML string
that can be used for attributes, text, comments an PIs
TODO: care for 16bit UNICODE string and escape chars ...

o  printXmlTextQuotedOn: aStream
convert aString to a valid XML string
that can be used for XML text.
Here line formatting characters are not escaped.
TODO: care for 16bit UNICODE string and escape chars ...

o  printf: args
( an extension from the stx:libbasic2 package )
Format and print the receiver with <args> formatted in C style,
as specified in the Unix C-language manual page for printf(3).
Return the resulting string (i.e actually, this is more like an sprintf).
For smalltalk specific formats,
see documentation in PrintfScanf >> format_printf.
For copyright information, see goodies/String-printf_scanf.chg
usage example(s):
     ('%05x %d %f %o' printf:{ 123. 234*5. 1.234. 8r377 } )    
     Transcript showCR:('%05x %d %f %o' printf:{ 123. 234*5. 1.234. 8r377 } )
usage example(s):
     Transcript showCR: 'Some examples:'!

     Transcript show:'''%#x %#X %03o%*.*s'' printf: #(16rABCD 16rEF 5 9 5 ''ghijklmn'') = .'.
     Transcript show: ('%#x %#X %03o%*.*s' printf: #(16rABCD 16rEF 5 9 5 'ghijklmn')).
     Transcript showCR: '.'

     Transcript show: '''%- 10.4s%.2e'' printf: (Array with: ''abcdefghijkl'' with: Float pi) = .'.
     Transcript show: ('%- 10.4s%.2e' printf: (Array with: 'abcdefghijkl' with: Float pi)).
     Transcript showCR: '.'

     Transcript show: '''%8.3f'' printf: (Array with: 200 sqrt negated) = .'.
     Transcript show: ('%8.3f' printf: (Array with: 200 sqrt negated)).
     Transcript showCR: '.'

     Transcript show: '''%c'' printf: #(16r41) = .'.
     Transcript show: ('%c' printf: #(16r41)).
     Transcript showCR: '.'

     Transcript show: '''%f%2s%s%s%s'' sscanf: ''237.0 this is a test'' = '.
     Transcript showCR: ('%f%2s%s%s%s'  sscanf: '237.0 this is a test') printString.

     Transcript show: '''%d%f%s'' sscanf: ''25 54.32e-01 monday'' = '.
     Transcript showCR: ('%d%f%s' sscanf: '25 54.32e-01 monday') printString.

     Transcript show: '''%f%*f %8[A-F0-9]%c%d 0x%x%f'' sscanf: ''12.45 1048.73 AE40Z527 0x75BCD15 34'' = '.
     Transcript showCR: ('%f%*f %8[A-F0-9]%c%d 0x%x%f' sscanf: '12.45 1048.73 AE40Z527 0x75BCD15 34') printString.

o  printf: args on: outStream
( an extension from the stx:libbasic2 package )
Format and print the receiver on <outStream> with <args>
formatted in C style, as specified in the Unix C-language manual page for printf(3).
For smalltalk specific formats,
see documentation in PrintfScanf >> format_printf.
For copyright information, see goodies/String-printf_scanf.chg

o  printfWith: arg1
( an extension from the stx:libbasic2 package )
Format and print the receiver with <arg1> formatted in C style,
as specified in the Unix C-language manual page for printf(3).
Return the resulting string (i.e actually, this is more like an sprintf).
For smalltalk specific formats,
see documentation in PrintfScanf >> format_printf
usage example(s):
     ('%05x' printfWith:123)
     Transcript showCR:('%05x' printfWith:123)

o  printfWith: arg1 with: arg2
( an extension from the stx:libbasic2 package )
Format and print the receiver with <argI> formatted in C style,
as specified in the Unix C-language manual page for printf(3).
Return the resulting string (i.e actually, this is more like an sprintf).
For smalltalk specific formats, see documentation in PrintfScanf >> format_printf.
usage example(s):
     Transcript showCR:('%d %05x' printfWith:123 with:234)

o  printfWith: arg1 with: arg2 with: arg3
( an extension from the stx:libbasic2 package )
Format and print the receiver with <argI> formatted in C style,
as specified in the Unix C-language manual page for printf(3).
Return the resulting string (i.e actually, this is more like an sprintf).
For smalltalk specific formats, see documentation in PrintfScanf >> format_printf.
usage example(s):
     Transcript showCR:('%d %05x %08o' printfWith:123 with:234 with:345)

o  printfWith: arg1 with: arg2 with: arg3 with: arg4
( an extension from the stx:libbasic2 package )
Format and print the receiver with <argI> formatted in C style,
as specified in the Unix C-language manual page for printf(3).
Return the resulting string (i.e actually, this is more like an sprintf).
For smalltalk specific formats, see documentation in PrintfScanf >> format_printf.
usage example(s):
     Transcript showCR:('%d %05x %08o %b' printfWith:123 with:234 with:345 with:123)

o  printfWith: arg1 with: arg2 with: arg3 with: arg4 with: arg5
( an extension from the stx:libbasic2 package )
Format and print the receiver with <argI> formatted in C style,
as specified in the Unix C-language manual page for printf(3).
Return the resulting string (i.e actually, this is more like an sprintf).
For smalltalk specific formats, see documentation in PrintfScanf >> format_printf.
usage example(s):
     Transcript showCR:('%d %05x %08o %b' printfWith:123 with:234 with:345 with:123)

o  printf_formatArgCount
( an extension from the stx:libbasic2 package )
Return the number of arguments required/produced if the receiver is interpreted
as a printf/scanf format control string.
For smalltalk specific formats, see documentation in PrintfScanf.
For copyright information, see goodies/String-printf_scanf.chg

o  printf_printOn: outStream withData: args
( an extension from the stx:libbasic2 package )
Format and print the receiver on <outStream> with <args>
formatted in C style, as specified in the Unix C-language manual page for printf(3).

For copyright information, see goodies/String-printf_scanf.chg

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  xmlQuotedPrintString
convert aString to a valid XML string
that can be used for attributes, text, comments an PIs
TODO: care for 16bit UNICODE string and escape chars ...

private
o  printf_printArgFrom: formatStream to: outStream withData: argStream
( an extension from the stx:libbasic2 package )
Interpret the required number of arguments from <argStream>
according to the formatting information in <formatStream>.
Place the interpretation on <outStream>.
The interpretation is C printf(3) style, as
specified in the Unix C-language manual page for printf(3).
<formatStream> is assumed to be positioned just past
$%, and a complete control string is assumed available.

Return when the conversion control string is consumed.
Leave <formatStream> pointing past the last character in the conversion control string.

This code assumes that <formatStream> is formatted according to
specification, and error checking is minimal. Unexpected
results will be obtained by illegal control strings, or when
argument types do not match conversion codes, but it probably
won't dump core, like C does in such cases!

For copyright information, see goodies/String-printf_scanf.chg

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  scanf_scanArgFrom: dataStream to: collection format: format
( an extension from the stx:libbasic2 package )
Add to <collection> an object who's representation is found
in <dataStream> interpreted according to the conversion
control string in the Stream <format>.
<format> is assumed to be positioned just past a $%, and a complete control
string is assumed available.

Return when the conversion control string is consumed. Leave
<format> pointing past the last character in the conversion
control string, leave <dataStream> pointing past any width
specified in <format>, or at the first character that doesn't
make sense for the <format>.

For copyright information, see goodies/String-printf_scanf.chg

** This is an obsolete interface - do not use it (it may vanish in future versions) **

queries
o  bitsPerCharacter
return the underlying string's bitsPerCharacter
(i.e. is it a regular String or a TwoByteString)
usage example(s):
     'hello' bitsPerCharacter
     'hello' asText allBold bitsPerCharacter

o  bytesPerCharacter
return the underlying string's required
bytesPerCharacter
(i.e. is it a regular String or a TwoByteString)
usage example(s):
     'hello' bytesPerCharacter
     'hello' asUnicode16String bytesPerCharacter
     'hello' asText allBold bytesPerCharacter

o  containsNon8BitElements
return true, if the underlying string contains elements larger than a single byte

o  continuesWith: aString startingAt: startIndex
return true, if the receiver beginning at startIndex
contains the characters in aString.
Returns false if the search reaches the end of the receiver
before all characters have been compared.
usage example(s):
     'hello world' continuesWith:'world' startingAt:6
     'hello world' continuesWith:'world' startingAt:7
     'hello' continuesWith:'llo' startingAt:3
     'hello' continuesWith:'llow' startingAt:3

o  countWords
return the number of words, which are separated by separators
usage example(s):
     'hello world isnt this nice' countWords'

o  defaultElement

o  encoding
return the strings encoding, as a symbol.
Here, by default, we assume unicode-encoding.
Notice, that ISO-8859-1 is a true subset of unicode,
and that singleByteStrings are therefore both unicode AND
8859-1 encoded.

o  hasChangeOfEmphasis
return true, if the receiver contains non-empty emphasis information
i.e. any non-normal (=emphasized) characters

o  hasIcon
for LabelAndIcon compatibility

o  hasImage
for LabelAndIcon compatibility

o  heightOn: aGC
return the size of the receiver in device units if displayed on aGC
usage example(s):
     'hello world' heightOn:(View new)

o  isLowercaseFirst
return true, if the first character is a lowercase character.
usage example(s):
     'helloWorld' isLowercaseFirst
     'HelloWorld' isLowercaseFirst

o  isUppercaseFirst
return true, if the first character is an uppercase character.
usage example(s):
     'helloWorld' isUppercaseFirst
     'HelloWorld' isUppercaseFirst

o  keywords
assuming the receiver is a keyword message selector,
return the individual keywords (i.e. break it up at colons)
and return these as a collection.
For binary and unary selectors, the result may be nonsense (an array containing the receiver).
usage example(s):
     #at:put: keywords
     #at: keywords
     #+ keywords
     #size keywords

o  knownAsSymbol
for now, only single character strings are allowed as symbols.
This method is redefined in String.

o  leftIndent
if the receiver starts with spaces, return the number of spaces
at the left - otherwise, return 0.
If the receiver consists of spaces only, return the receiver's size.
usage example(s):
     '    hello' leftIndent
     'foo      ' leftIndent
     '         ' leftIndent

o  nameSpaceSelectorParts
Answer the namespace and baseSelector parts of a namespace selector.
Namespace selectors are those generated by sends from a method in a different
namespace; they are prefixed by ':'<ns>'::'.
You cannot easily change this algorithm here, as it is also known by the VM's lookup function.
Experimental

o  speciesForSubcollection
answer the class, when splitting instances into subcollections

o  stringSpecies
return the underlying strings bitsPerCharacter
(i.e. is it a regular String or a TwoByteString)
usage example(s):
     'hello' stringSpecies
     'hello' asText allBold stringSpecies

o  widthFrom: startIndex to: endIndex on: aGC
return ths size of part of the receiver in device units if displayed on aGC
usage example(s):
     'hello world' widthFrom:1 to:5 on:(View new)
     'hello' widthOn:(View new)

o  widthOn: aGC
return ths size of the receiver in device units if displayed on aGC
usage example(s):
     'hello world' widthOn:(View new)

special string converting
o  asUnixFilenameString
return a new string consisting of receiver's characters
with all \-characters replaced by /-characters.
If there are no backslashes, return the original
usage example(s):
     'hello\world' asUnixFilenameString

o  expandPlaceholders: escapeCharacter with: argArrayOrDictionary
this is the generic version of the old %-escaping method, allowing for an arbitrary
escape character to be used (typically $$ or $% are effectively used).
Return a copy of the receiver, where all %i escapes are
replaced by corresponding arguments' printStrings from the argArrayOrDictionary.
I.e. 'hello %1; how is %2' expandPlaceholdersWith:#('world' 'this') results
in the new string 'hello world; how is this'.
As an extension, the argument may also be a dictionary, providing
values for symbolic keys.
In this case, %a .. %z and %(...) are also allowed.
(%1..%9 require a numeric key in the dictionary, however)
To get a '%' character, use a '%%'-escape.
To get an integer-indexed placeHolder followed by another digit,
or an index > 9, you must use %(digit).
See also bindWith:... for VisualAge compatibility.

o  expandPlaceholders: escapeCharacter with: argArrayOrDictionary on: aStream
this is the generic version of the old %-escaping method, allowing for an arbitrary
escape character to be used (typically $$ or $% are effectively used).

Write the receiver to aStream, where all %i escapes are
replaced by corresponding arguments' printStrings from the argArrayOrDictionary.
I.e. 'hello %1; how is %2' expandPlaceholdersWith:#('world' 'this') results
in the new string 'hello world; how is this'.

As an extension, the argument may also be a dictionary, providing values for symbolic keys.
In this case, %a .. %z and %(...) are also allowed.
(%1..%9 require a numeric key in the dictionary, however)
Also, the values in argArrayOrDictionary may be blocks.

To get a '%' character, use a '%%'-escape.
To get an integer-indexed placeHolder followed by another digit,
or an index > 9, you must use %(digit).

See also bindWith:... for VisualAge compatibility.
Use %<cr> to insert a CR and %<tab> to insert a TAB.
usage example(s):
     String streamContents:[:s|
        'hello %1' expandPlaceholders:$% with:#('world') on:s.
        s cr.
        'hello $1; how is $2' expandPlaceholders:$$ with:#('world' 'this') on:s.
        s cr.
        'hello %2; how is %1' expandPlaceholders:$% with:#('world' 'this') on:s.
        s cr.
        '%1 plus %2 gives %3 ' expandPlaceholders:$% with:#(4 5 9) on:s.
        s cr.
        '%%(1)0 gives %(1)0' expandPlaceholders:$% with:#(123) on:s.
        s cr.
        '%%10 gives %10' expandPlaceholders:$% with:#(123) on:s.
        s cr.
        '%%(10) gives %(10) %%next line' expandPlaceholders:$% with:#(123) on:s.
        s cr.
        '%%test gives %test' expandPlaceholders:$% with:#(123) on:s.
        s cr.
        '|%%|%%1|%%| gives |%|%1|%|' expandPlaceholders:$% with:#(foo) on:s.
     ]

o  expandPlaceholdersWith: argArrayOrDictionary
return a copy of the receiver, where all %i escapes are
replaced by corresponding arguments' printStrings from the argArrayOrDictionary.
I.e. 'hello %1; how is %2' expandPlaceholdersWith:#('world' 'this') results
in the new string 'hello world; how is this'.

As an extension, the argument may also be a dictionary, providing
values for symbolic keys.
In this case, %a .. %z and %(...) are also allowed.
(%1..%9 require a numeric key in the dictionary, however)
Also, the values in argArrayOrDictionary may be blocks.

To get a '%' character, use a '%%'-escape.
To get an integer-indexed placeHolder followed by another digit,
or an index > 9, you must use %(digit).
See also bindWith:... for VisualAge compatibility.
usage example(s):
     'hello %1' expandPlaceholdersWith:#('world')
     'hello %1; how is %2' expandPlaceholdersWith:#('world' 'this')
     'hello %2; how is %1' expandPlaceholdersWith:#('world' 'this')
     '%1 plus %2 gives %3 ' expandPlaceholdersWith:#(4 5 9)
     '%%(1)0 gives %(1)0' expandPlaceholdersWith:#(123)
     '%%10 gives %10' expandPlaceholdersWith:#(123)
     '%%(10) gives %(10)' expandPlaceholdersWith:#(123)
     '%test gives %1' expandPlaceholdersWith:#(123)
     'bla %1 bla' expandPlaceholdersWith:{ 'hello' allBold }
     'bla %1 bla' expandPlaceholdersWith:{ 'hello' }
     ('bla %1 bla' withColor:Color red)
        expandPlaceholdersWith:{ 'hello' }
     ('bla %1 bla' withColor:Color red)
        expandPlaceholdersWith:{ 'hello' withColor:Color blue }

o  expandPlaceholdersWith: argArrayOrDictionary on: aStream
write the receiver to aStream, where all %i escapes are
replaced by corresponding arguments' printStrings from the argArrayOrDictionary.
I.e. 'hello %1; how is %2' expandPlaceholdersWith:#('world' 'this') results
in the new string 'hello world; how is this'.

As an extension, the argument may also be a dictionary, providing
values for symbolic keys.
In this case, %a .. %z and %(...) are also allowed.
(%1..%9 require a numeric key in the dictionary, however)
Also, the values in argArrayOrDictionary may be blocks.

To get a '%' character, use a '%%'-escape.
To get an integer-indexed placeHolder followed by another digit,
or an index > 9, you must use %(digit).

See also bindWith:... for VisualAge compatibility.
Use %<cr> to insert a CR and %<tab> to insert a TAB.
usage example(s):
     String streamContents:[:s|
        'hello %1' expandPlaceholdersWith:#('world') on:s.
        s cr.
        'hello %1; how is %2' expandPlaceholdersWith:#('world' 'this') on:s.
        s cr.
        'hello %2; how is %1' expandPlaceholdersWith:#('world' 'this') on:s.
        s cr.
        '%1 plus %2 gives %3 ' expandPlaceholdersWith:#(4 5 9) on:s.
        s cr.
        '%%(1)0 gives %(1)0' expandPlaceholdersWith:#(123) on:s.
        s cr.
        '%%10 gives %10' expandPlaceholdersWith:#(123) on:s.
        s cr.
        '%%(10) gives %(10) %%next line' expandPlaceholdersWith:#(123) on:s.
        s cr.
        '%test gives %1' expandPlaceholdersWith:#(123) on:s.
     ]

o  extractPlaceHolders: escapeCharacter
returns a list of placeholder keys of the form %i,
where i is either a single digit (as in %1, %2)
or a single letter (as in %a, %z)
or a word-key, as in %(one), %(fooBar).
For numeric keys, the returned collection contains integers;
for non-numeric ones, it includes strings.
usage example(s):
     self assert:('hello %1 and %2' extractPlaceHolders:$%) asSet = #(1 2) asSet
     self assert:('hello %9 and %(10)' extractPlaceHolders:$%) asSet = #(9 10) asSet
     self assert:('hello %a and %(foo) and %1' extractPlaceHolders:$%) asSet = #(1 'a' 'foo') asSet
     self assert:('hello %a and %(foo) and %1' extractPlaceHolders:$$) asSet = #() asSet

o  firstLine
return the first line of a multiline string
usage example(s):
     'hello' firstLine
     '1\2\3' withCRs firstLine
     '\1\2\3' withCRs firstLine

o  tokensBasedOn: aCharacter
this is an ST-80 alias for the ST/X method
asCollectionOfSubstringsSeparatedBy:
usage example(s):
     'hello:world:isnt:this nice' tokensBasedOn:$:
     'foo,bar,baz' tokensBasedOn:$,
     '/etc/passwd' asFilename readStream nextLine tokensBasedOn:$:

o  withCEscapes
return a new string consisting of receiver's characters
with all special and unprintable characters replaced by \X-character escapes.
(similar to the way C-language literal Strings are represented).
The resulting string will contain only 7-bit ascii characters.
Emphasis is not supported.
The following escapes are generated:
\' single quote character
\dQuote double quote character
\r return character
\r return character
\n newline character
\t tab character
\\ the \ character itself
\xnn two digit hex number defining the characters ascii value
\unnnn four digit hex number defining the characters ascii value
\Unnnnnnnn eight digit hex number defining the characters ascii value
This is the opposite of withoutCEscapes.

Sigh: this is named completely wrong (opposite naming of withCRs/witoutCRs),
but it cannot be changed easily, as these methods are already used heavily

usage example(s):
     'hello\n\tworld' withoutCEscapes.
     'hello\nworld\na\n\tnice\n\t\tstring' withoutCEscapes withCEscapes.
     ('hello ',(Character value:16r1234),' world') withCEscapes

o  withCRs
return a new string consisting of the receiver's characters
with all \-characters replaced by cr-characters.
If there are no backslashes, return the original
usage example(s):
     'hello\world' withCRs

o  withEscapes
has been renamed; the name withEscapes is misleading

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  withMatchEscapes
return a copy of the receiver with all match characters escaped
by $\ characters (to be usable as a match string).
Return the receiver, if there are none.
usage example(s):
     '*foo' withMatchEscapes
     '\*foo' withMatchEscapes
     '*foo' withMatchEscapes
     '\\*foo' withMatchEscapes
     'foo*' withMatchEscapes
     'foo\*' withMatchEscapes
     'foo\' withMatchEscapes
     'f*o*o' withMatchEscapes

o  withSeparatorsCompacted
return a new string with each sequence of whiteSpace replaced by a single space character.
Preserves a leading/trailing space.
usage example(s):
     'hello wwww'         withSeparatorsCompacted
     'hello    wwww'      withSeparatorsCompacted
     '  hello wwww'       withSeparatorsCompacted
     '  hello wwww   '    withSeparatorsCompacted
     '  hello    wwww   ' withSeparatorsCompacted
     'hel   lo www   w'   withSeparatorsCompacted

o  withSeparatorsReplacedBy: replacementCharacter
return a new string with each separator (whitespace) replaced by replacementCharacter.
Typically used with space as replacementCharacter
usage example(s):
     'hello wwww'         withSeparatorsReplacedBy:$*
     'hello ww ww'        withSeparatorsReplacedBy:$*
     '  hello wwww'       withSeparatorsReplacedBy:$*
     'hel   lo www   w'   withSeparatorsReplacedBy:$*
     'hel
 lo www
w'   withSeparatorsReplacedBy:$*

o  withTabs
return a string consisting of the receiver's characters
where leading spaces are replaced by tabulator characters (assuming 8-col tabs).
Notice: if the receiver does not contain any tabs, it is returned unchanged;
otherwise a new string is returned.
Limitation: only the very first spaces are replaced
(i.e. if the receiver contains newLine characters,
no tabs are inserted after those lineBreaks)
usage example(s):
     '12345678901234567890' withTabs
     '       8901234567890' withTabs
     '        901234567890' withTabs
     '               67890' withTabs
     '                7890' withTabs
     '                 890' withTabs

o  withTabsExpanded
return a string consisting of the receiver's characters,
where all tabulator characters are expanded into spaces (assuming 8-col tabs).
Notice: if the receiver does not contain any tabs, it is returned unchanged;
otherwise a new string is returned.
This does handle multiline strings.
usage example(s):
     ('1' , Character tab asString , 'x') withTabsExpanded
     ('12345' , Character tab asString , 'x') withTabsExpanded
     ('123456' , Character tab asString , 'x') withTabsExpanded
     ('1234567' , Character tab asString , 'x') withTabsExpanded
     ('12345678' , Character tab asString , 'x') withTabsExpanded
     ('123456789' , Character tab asString , 'x') withTabsExpanded

     (String with:Character tab
             with:Character tab
             with:$1) withTabsExpanded

     (String with:Character tab
             with:$1
             with:Character tab
             with:$2) withTabsExpanded

     (String with:Character tab
             with:$1
             with:Character cr
             with:Character tab
             with:$2) withTabsExpanded

o  withTabsExpanded: numSpaces
return a string consisting of the receiver's characters,
where all tabulator characters are expanded into spaces (assuming numSpaces-col tabs).
Notice: if the receiver does not contain any tabs, it is returned unchanged;
otherwise a new string is returned.
This does handle multiline strings.
usage example(s):
     ('1' , Character tab asString , 'x') withTabsExpanded
     ('1' , Character tab asString , 'x') withTabsExpanded:4
     ('12345' , Character tab asString , 'x') withTabsExpanded
     ('123456' , Character tab asString , 'x') withTabsExpanded
     ('1234567' , Character tab asString , 'x') withTabsExpanded
     ('12345678' , Character tab asString , 'x') withTabsExpanded
     ('123456789' , Character tab asString , 'x') withTabsExpanded

     (String with:Character tab
             with:Character tab
             with:$1) withTabsExpanded

     (String with:Character tab
             with:$1
             with:Character tab
             with:$2) withTabsExpanded

     (String with:Character tab
             with:$1
             with:Character cr
             with:Character tab
             with:$2) withTabsExpanded

o  withoutAllSpaces
return a copy of the receiver with all whitespace removed
usage example(s):
     'hello wwww'  withoutAllSpaces
     'hel   lo www   w'  withoutAllSpaces

o  withoutCEscapes
return a new string consisting of receiver's characters
with all \X-character escapes replaced by corresponding characters.
(similar to the way C-language Strings are converted).
The following escapes are supported:
\r return character
\n newline character
\b backspace character
\f formfeed character
\t tab character
\e escape character
\\ the \ character itself
\nnn three digit octal number defining the characters ascii value
\xnn two digit hex number defining the characters ascii value
\unnnn four digit hex number defining the characters unicode value
\Unnnnnnnn eight digit hex number defining the characters unicode value
\other other

Notice, that \' is NOT a valid escape, since the general syntax of
string constants is not affected by this method.

Although easily implementable, this is NOT done automatically
by the compiler (due to a lack of a language standard for this).
However, the compiler may detect sends of #withEscapes to string literals
and place a modified string constant into the binary/byte-code.
Therefore, no runtime penalty will be payed for using these escapes.
(not in pre 2.11 versions)

This is the opposite of withCEscapes.

Sigh: this is named completely wrong (opposite naming of withCRs/witoutCRs),
but it cannot be changed easily, as these methods are already used heavily

usage example(s):
     'hello world' withoutCEscapes
     'hello\world' withoutCEscapes
     'hello\world\' withoutCEscapes
     'hello world\' withoutCEscapes
     'hello\tworld' withoutCEscapes
     'hello\nworld\na\n\tnice\n\t\tstring' withoutCEscapes
     'hello\tworld\n' withoutCEscapes
     'hello\010world' withoutCEscapes
     'hello\r\nworld' withoutCEscapes
     'hello\r\n\x08world' withoutCEscapes
     '0\x080' withoutCEscapes
     '0\u12340' withoutCEscapes
     '0\U123456780' withoutCEscapes
     '0\0a' withoutCEscapes
     '0\00a' withoutCEscapes
     '0\000a' withoutCEscapes
     '0\0000a' withoutCEscapes
     '0\00000a' withoutCEscapes
     '0\03770' withoutCEscapes

o  withoutCRs
return a new collection consisting of receiver's elements
with all cr-characters replaced by \-characters.
This is the reverse operation of withCRs.
usage example(s):
     'hello
world' withoutCRs

o  withoutLeadingSeparators
return a copy of myself without leading separators.
Notice: this does remove tabs, newline or any other whitespace.
Returns an empty string, if the receiver consist only of whitespace.
usage example(s):
     '    foo    ' withoutLeadingSeparators
     'foo    '     withoutLeadingSeparators
     '    foo'     withoutLeadingSeparators
     '       '     withoutLeadingSeparators
     'foo'         withoutLeadingSeparators
     ('  ' , Character tab asString , ' foo   ') withoutLeadingSeparators inspect

o  withoutMatchEscapes
return a copy of the receiver with all $\ removed or
the receiver, if there are none.
usage example(s):
     '*foo' withoutMatchEscapes
     '\*foo' withoutMatchEscapes
     '*foo' withoutMatchEscapes
     '\\*foo' withoutMatchEscapes
     'foo*' withoutMatchEscapes
     'foo\*' withoutMatchEscapes
     'foo\' withoutMatchEscapes
     'f\*o\*o' withoutMatchEscapes

o  withoutPrefix: aString
if the receiver startsWith aString, return a copy without it.
Otherwise return the receiver
usage example(s):
     'helloworld' withoutPrefix:'hello'
     'helloworld' withoutPrefix:'foo'

o  withoutQuotes
remove quotes ($" and $') from the front and end of myself (if matching)"
usage example(s):
'"hello"' withoutQuotes
usage example(s):
'''hello''' withoutQuotes
usage example(s):
'hello' withoutQuotes
usage example(s):
'"hello' withoutQuotes
usage example(s):
'hello"' withoutQuotes

o  withoutSeparators
return a copy of myself without leading and trailing whitespace.
(but whiteSpace in-between is preserved)
Whitespace is space, tab, newline, formfeed.
Use withoutSpaces, if you want to remove spaces only.
usage example(s):
     '    foo    ' withoutSeparators
     '    foo' withoutSeparators
     'foo    ' withoutSeparators
     '       ' withoutSeparators
     ('  foo' , Character tab asString , '    ') withoutSeparators inspect
     '    foo    ' asUnicode16String withoutSeparators

o  withoutSpaces
return a copy of myself without leading and trailing spaces.
(but spaces in-between are preserved)
Notice: this does NOT remove tabs, newline or any other whitespace.
Use withoutSeparators for this.
usage example(s):
     '    foo    ' withoutSpaces
     'foo    '     withoutSpaces
     '    foo'     withoutSpaces
     '       '     withoutSpaces
     'a     b'     withoutSpaces
     ('  foo' , Character tab asString , '    ') withoutSpaces inspect

o  withoutSuffix: aString
if the receiver endsWith aString, return a copy without it.
Otherwise return the receiver
usage example(s):
     'helloworld' withoutSuffix:'world'
     'helloworld' withoutSuffix:'foo'

o  withoutTrailingSeparators
return a copy of myself without trailing separators.
Notice: this does remove tabs, newline or any other whitespace.
Returns an empty string, if the receiver consist only of whitespace.
usage example(s):
     '    foo    ' withoutTrailingSeparators
     'foo    '     withoutTrailingSeparators
     '    foo'     withoutTrailingSeparators
     '       '     withoutTrailingSeparators
     'foo'         withoutTrailingSeparators
     ('  ' , Character tab asString , ' foo   ') withoutTrailingSeparators inspect
     ('   foo' , Character tab asString) withoutTrailingSeparators inspect

substring searching
o  findRangeOfString: subString
find a substring. if found, return the start- and endIndex;
if not found, return an empty interval.
usage example(s):
     'hello world' findRangeOfString:'llo'
     'hello world' findRangeOfString:'ole'

o  findString: subString
find a substring. if found, return the index;
if not found, return 0.
usage example(s):
     'hello world' findString:'llo'
     'hello world' findString:'ole'

o  findString: subString caseSensitive: caseSensitive
find a substring. if found, return the index;
if not found, return 0.
usage example(s):
     'hello world' findString:'LLo' caseSensitive:true
     'hello world' findString:'LLo' caseSensitive:false

o  findString: subString ifAbsent: exceptionBlock
find a substring. If found, return the index;
if not found, return the result of evaluating exceptionBlock.

o  findString: subString ignoreCase: ignoreCase
find a substring. if found, return the index;
if not found, return 0.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  findString: subString startingAt: index
find a substring, starting at index. if found, return the index;
if not found, return 0.
usage example(s):
     'hello yello' findString:'llo' startingAt:1
     'hello yello' findString:'llo' startingAt:5
     'hello yello' findString:'llo' startingAt:15

o  findString: subString startingAt: index ifAbsent: exceptionBlock
find a substring, starting at index. if found, return the index;
if not found, return the result of evaluating exceptionBlock.

o  findString: subString startingAt: index ifAbsent: exceptionBlock caseSensitive: caseSensitive
find a substring, starting at index. if found, return the index;
if not found, return the result of evaluating exceptionBlock.

o  includesString: aString
return true, if a substring is contained in the receiver
usage example(s):
     'hello world' includesString:'hel'
     'hello world' includesString:'rld'
     'hello world' includesString:'llo'
     'hello world' includesString:'LLO'
     'hello world' includesString:''

o  includesString: aString caseSensitive: caseSensitive
return true, if a substring is contained in the receiver
usage example(s):
     'hello world' includesString:'hel' caseSensitive:true
     'hello world' includesString:'HEL' caseSensitive:true
     'hello world' includesString:'HEL' caseSensitive:false

     'hello world' includesString:'wor' caseSensitive:true
     'hello world' includesString:'WOR' caseSensitive:true
     'hello world' includesString:'WOR' caseSensitive:false

o  indexOfSubCollection: subString caseSensitive: caseSensitive
find a substring, starting at index. if found, return the index;
if not found, return the result of evaluating exceptionBlock.

o  indexOfSubCollection: subString startingAt: index ifAbsent: exceptionBlock
find a substring, starting at index. if found, return the index;
if not found, return the result of evaluating exceptionBlock.

o  indexOfSubCollection: subString startingAt: index ifAbsent: exceptionBlock caseSensitive: caseSensitive
find a substring, starting at index. if found, return the index;
if not found, return the result of evaluating exceptionBlock.
This is a q&d hack - not very efficient
usage example(s):
        'АБВГДЕЖ' asLowercase indexOfSubCollection:'ВГДЕ' startingAt:1 ifAbsent:nil caseSensitive:false.
        'АБВГДЕЖ' indexOfSubCollection:'ВГДЕ' startingAt:1 ifAbsent:nil caseSensitive:true.

o  indexOfSubCollection: subString startingAt: index ifAbsent: exceptionBlock caseSensitive: caseSensitive ignoreDiacritics: ignoreDiacritics
find a substring, starting at index. if found, return the index;
if not found, return the result of evaluating exceptionBlock.
This is a q&d hack - not very efficient
(see implementation in string, for a much faster algorithm)
usage example(s):
     'bla depot bla dépots' indexOfSubCollection:'dep' startingAt:1 ifAbsent:0 caseSensitive:false ignoreDiacritics:true. 5
     'bla depot bla dépots' indexOfSubCollection:'dep' startingAt:6 ifAbsent:0 caseSensitive:false ignoreDiacritics:true. 0

     'bla depot bla dépots' indexOfSubCollection:'dep' startingAt:1 ifAbsent:0 caseSensitive:false ignoreDiacritics:false. 5
     'bla depot bla dépots' indexOfSubCollection:'dep' startingAt:6 ifAbsent:0 caseSensitive:false ignoreDiacritics:false. 0

o  lastIndexOfString: aString
VSE and V'age compatibility
usage example(s):
123456789012
    'abcdefabcdef' lastIndexOfString:'abc'
    'abcdefabcdef' lastIndexOfString:'abc' startingAt:6
    'abcdefabcdef' lastIndexOfString:'xxx' startingAt:6

o  lastIndexOfString: aString ifAbsent: exceptionValue
VSE and V'age compatibility
usage example(s):
123456789012
    'abcdefabcdef' lastIndexOfString:'abc' ifAbsent:[999]
    'abcdefabcdef' lastIndexOfString:'xxx' ifAbsent:[999]

o  lastIndexOfString: aString startingAt: startIndex
VSE and V'age compatibility
usage example(s):
123456789012
    'abcdefabcdef' lastIndexOfString:'abc'
    'abcdefabcdef' lastIndexOfString:'abc' startingAt:6

o  lastIndexOfString: aString startingAt: startIndex ifAbsent: exceptionValue
VSE and V'age compatibility
usage example(s):
123456789012
    'abcdefabcdef' lastIndexOfString:'abc'
    'abcdefabcdef' lastIndexOfString:'abc' startingAt:6
    'abcdefabcdef' lastIndexOfString:'xxx' startingAt:6 ifAbsent:999

o  rangeOfSubCollection: subString startingAt: start ifAbsent: exceptionValue caseSensitive: caseSensitive
find a substring. if found, return the start- and endIndex;
if not found, return the value of exceptionValue.

testing
o  argumentCount
treating the receiver as a message selector, return how many arguments would it take (ANSI)
usage example(s):
     'foo:bar:' argumentCount
     #foo:bar: argumentCount
     'hello' argumentCount
     '+' argumentCount
     '++' argumentCount
     '+++' argumentCount
     '|' argumentCount
     '?' argumentCount
     '_' argumentCount
     '_:' argumentCount
     '_:_:' argumentCount
     '<->' argumentCount
     '<' argumentCount
     #'<' argumentCount

o  characterSize
answer the size in bits of my largest character (actually only 7, 8, 16 or 32)
usage example(s):
     'hello' characterSize
     'hello' asUnicode32String characterSize
     'helloü' asUnicode32String characterSize
     'hello' asText allBold characterSize

o  contains8BitCharacters

o  containsNon7BitAscii
return true, if the underlying string contains 8BitCharacters (or widers)
(i.e. if it is non-ascii)
usage example(s):
     'hello' asUnicode32String containsNon7BitAscii
     'hello üöä' asUnicode32String containsNon7BitAscii
     'hello' asUnicode32String asText allBold containsNon7BitAscii
     'hello üö' asUnicode32String asText allBold containsNon7BitAscii

o  isAlphaNumeric
return true, if the receiver is some alphanumeric word;
i.e. consists of a letter followed by letters or digits.
usage example(s):
     'helloWorld' isAlphaNumeric
     'foo1234' isAlphaNumeric
     'f1234' isAlphaNumeric
     '1234' isAlphaNumeric
     '+' isAlphaNumeric

o  isBinarySelector
treating the receiver as a message selector, return true if it's a binary selector.
Notice, that st/x does not have a size <= 2 limit for unaries
usage example(s):
     'foo:bar:' isBinarySelector
     #foo:bar: isBinarySelector
     'hello' isBinarySelector
     '+' isBinarySelector
     '|' isBinarySelector
     '?' isBinarySelector
     ':' isBinarySelector
     'a:' isBinarySelector
     '->' isBinarySelector
     '<->' isBinarySelector
     '::' isBinarySelector

o  isBlank
return true, if the receiver contains spaces only
usage example(s):
     '' isBlank
     '   a    ' isBlank
     '        ' isBlank
     '        ' asUnicode16String isBlank

o  isInfix
return true, if the receiver is a binary message selector
usage example(s):
     #at:put: isInfix
     #at: isInfix
     #+ isInfix
     #size isInfix

o  isKeyword
return true, if the receiver is a keyword message selector.
This is a quick check, which only looks at the last character.
Should only be used, if we already know that the receiver forms a valid selector.
To check an arbitrary string, use isKeywordSelector.
Bad naming, but compatibility is asking for it.
usage example(s):
     #at:put: isKeyword
     #at: isKeyword
     #+ isKeyword
     #size isKeyword

o  isKeywordSelector
return true, iff there are only alphanumeric or underline characters separated by colons.
Must end with a colon.
You can use this to check an arbitrary string for being valid as a keyword.
If you have a valid selector at hand, and need to know if it is a keyword or not,
use #isKeyword, which is much faster.
usage example(s):
     self assert:(':' isKeywordSelector not).
     self assert:(':a' isKeywordSelector not).
     self assert:('1:' isKeywordSelector not).
     self assert:('a:' isKeywordSelector).
     self assert:('_:' isKeywordSelector).
     self assert:('_a:' isKeywordSelector).
     self assert:('_1:' isKeywordSelector).
     self assert:('_1::' isKeywordSelector not).
     self assert:('_:_:' isKeywordSelector).
     self assert:('a:b:' isKeywordSelector).
     self assert:('aa:bb:' isKeywordSelector).
     self assert:('aa:bb:a' isKeywordSelector not).
     self assert:('1:2:' isKeywordSelector not).

o  isNameSpaceSelector
Answer true if the receiver contains chars which form a nameSpace selector name.
These are of the form ':<ns>::<sel>', where ns is the NameSpace and sel is the regular selector.
For example, the #+ selector as seen by the Foo namespace would be actually #':Foo::+'.
This special format (a symbol starting with a colon) was chosen, because almost every other selector
is legal, and this can be checked quickly by just looking at the first character.
You cannot easily change this algorithm here, as it is also known by the VM's lookup function.

o  isNumeric
return true, if the receiver is some numeric word;
i.e. consists only of digits.
usage example(s):
     'helloWorld' isNumeric
     'foo1234' isNumeric
     'f1234' isNumeric
     '1234' isNumeric
     '+' isNumeric

o  isPlainString
return true, if the receiver is a plain string (without attributes);
true is returned here - redefinition of Object>>isPlainString.

o  isString
return true, if the receiver is some kind of string;
true is returned here - redefinition of Object>>isString.

o  isUnary
Answer true if the receiver is a unary selector.
That is not a check for being a valid selector, but instead relies on
the selector being valid.

o  isUnarySelector
Answer true if the receiver contains only chars in an ANSI unary method selector, false otherwise.

o  isUnicode16String

o  isUnicode32String
true if this is a 4-byte unicode string

o  isUnicodeString
true if this is a 2- or 4-byte unicode string
(i.e. not a single byte string).
Notice, that the name is misleading:
all strings are use unicode encoding

o  isValidSmalltalkIdentifier
return true, if the receiver's characters make up a valid smalltalk identifier
usage example(s):
     'foo' isValidSmalltalkIdentifier
     '1foo' isValidSmalltalkIdentifier
     '_foo' isValidSmalltalkIdentifier
     '_foo_bar_' isValidSmalltalkIdentifier
     'foo ' isValidSmalltalkIdentifier
     ' foo' isValidSmalltalkIdentifier

o  isWhitespace
return true, if the receiver is empty or contains only whitespace.
usage example(s):
     '' isWhitespace
     '   ' isWhitespace
     '   \    \' withCRs isWhitespace
     '   a\    \' withCRs isWhitespace
     '   \    \a' withCRs isWhitespace
     'a   \    \a' withCRs isWhitespace

o  isWideString
true if I require more than one byte per character

o  numArgs
treating the receiver as a message selector, return how many arguments would it take.
Please use argumentCount for ANSI compatibility.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  partsIfSelector
treat the receiver as a message selector, return a collection of parts.
Notice: this is more tolerant than Smalltalk's syntax would suggest;
especially it allows for empty keyword parts between colons.
This is not (and should not be checked here), to allow parsing of
degenerate selectors as appearing with objectiveC.
usage example(s):
     'foo:' partsIfSelector
     'foo:bar:' partsIfSelector
     'foo::::' partsIfSelector
     #foo:bar: partsIfSelector
     'hello' partsIfSelector
     '+' partsIfSelector

tracing
o  traceInto: aRequestor level: level from: referrer
double dispatch into tracer, passing my type implicitely in the selector

visiting
o  acceptVisitor: aVisitor with: aParameter
dispatch for visitor pattern; send #visitString:with: to aVisitor



ST/X 7.1.0.0; WebServer 1.663 at exept.de:8081; Fri, 20 Jul 2018 06:36:09 GMT