"

 COPYRIGHT (c) 1994 by Claus Gittinger

	      All Rights Reserved

 This software is furnished under a license and may be used

 only in accordance with the terms of that license and with the

 inclusion of the above copyright notice.   This software may not

 be provided or otherwise made available to, or used by, any

 other person.  No title to or ownership of the software is

 hereby transferred.

"

ByteArray subclass:#CharacterArray

       instanceVariableNames:''

       classVariableNames:'PreviousMatch'

       poolDictionaries:''

       category:'Collections-Text'

!

CharacterArray comment:'

COPYRIGHT (c) 1994 by Claus Gittinger

	      All Rights Reserved

'!

!CharacterArray class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 1994 by Claus Gittinger

	      All Rights Reserved

 This software is furnished under a license and may be used

 only in accordance with the terms of that license and with the

 inclusion of the above copyright notice.   This software may not

 be provided or otherwise made available to, or used by, any

 other person.  No title to or ownership of the software is

 hereby transferred.

"

!

version

"

"

!

documentation

"

    CharacterArray is a superclass for all kinds of Strings (i.e.

    (singleByte-)Strings, TwoByteStrings and whatever comes in the future.

    As the name already implies, this class is abstract, meaning that there are

    no instances of it. All this class does is provide common protocol for 

    concrete subclasses.

"

! !

!CharacterArray class methodsFor:'instance creation'!

basicNew

    "return a new empty string"

    ^ self basicNew:0

!

new

    "return a new empty string"

    ^ self basicNew:0

!

fromString:aString

    "return a copy of the argument, aString"

    ^ (self basicNew:(aString size)) replaceFrom:1 with:aString

    "TwoByteString fromString:'hello'"

! !

!CharacterArray methodsFor:'converting'!

string

    ^ self

!

asUppercase

    "return a copy of myself in uppercase letters"

    |newStr

     mySize "{ Class: SmallInteger }" |

    mySize := self size.

    newStr := self species new:mySize.

    1 to:mySize do:[:i |

	newStr at:i put:(self at:i) asUppercase

    ].

    ^ newStr

    "

     'helloWorld' asUppercase      

     'helloWorld' asUppercaseFirst 

    "

!

asLowercase

    "return a copy of myself in lowercase letters"

    |newStr

     mySize "{ Class: SmallInteger }" |

    mySize := self size.

    newStr := self species new:mySize.

    1 to:mySize do:[:i |

	newStr at:i put:(self at:i) asLowercase

    ].

    ^ newStr

    "

     'HelloWorld' asLowercase   

     'HelloWorld' asLowercaseFirst   

    "

!

asUppercaseFirst

    "return a copy of myself where the first character is

     converted to uppercase."

    |newString sz|

    sz := self size.

    newString := self copyFrom:1 to:sz.

    sz > 0 ifTrue:[

	newString at:1 put:(newString at:1) asUppercase

    ].

    ^ newString

    "

     'helloWorld' asUppercase      

     'helloWorld' asUppercaseFirst 

     'HelloWorld' asUppercaseFirst   

    "

!

asLowercaseFirst

    "return a copy of myself where the first character is

     converted to lowercase."

    |newString sz|

    sz := self size.

    newString := self copyFrom:1 to:sz.

    sz > 0 ifTrue:[

	newString at:1 put:(newString at:1) asLowercase

    ].

    ^ newString

    "

     'HelloWorld' asLowercase   

     'HelloWorld' asLowercaseFirst   

    "

!

asString

    "return myself - I am a string"

    ^ self

!

asTwoByteString

    "return the receiver converted to a two-byte string"

    ^ TwoByteString fromString:self

!

asSingleByteString

    "return the receiver converted to a 'normal' string"

    ^ String fromString:self

!

asStringCollection

    "return a collection of lines from myself."

    ^ StringCollection from:self

!

asComposedText

    ^ ComposedText fromString:self

!

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.

     This may change if ANSI specifies it."

"/ ST-80 behavior:

"/  ^ Number readFromString:self onError:0

    ^ Number readFromString:self

    "

     '123'     asNumber

     '123.567' asNumber

     '(5/6)'   asNumber

     'foo'     asNumber

     Object errorSignal handle:[:ex | ex returnWith:0] do:['foo' asNumber] 

    "

!

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."

    |tempString|

    tempString := self collect:[:char | char isDigit].

    ^ Number readFromString:tempString onError:0

    "

     'USD 123' asNumberFromFormatString:'foo'

     'DM 123'  asNumberFromFormatString:'foo'

     '123'     asNumberFromFormatString:'foo'

     '123.567' asNumberFromFormatString:'foo'

     '(5/6)'   asNumberFromFormatString:'foo'

     'foo'     asNumberFromFormatString:'foo'

    "

!

asInteger

    "read an integer from the receiver.

     Notice, that errors may occur during the read, so you better

     setup some signal handler when using this method."

    ^ Integer readFromString:self

    "

     '12345678901234567890' asInteger

     '-1234' asInteger

     '0.123' asInteger   <- reader stops at ., returning 0 here

     '0.123' asNumber    <- returns what you expect

     Object errorSignal handle:[:ex | ex returnWith:0] do:['foo' asInteger] 

    "

!

asFloat

    "read a float number from the receiver.

     Notice, that errors may occur during the read, so you better

     setup some signal handler when using this method."

    ^ (Number readFromString:self) asFloat

    "

     '0.123' asFloat 

     '12345' asFloat

     '(1/5)' asFloat

     Object errorSignal handle:[:ex | ex returnWith:0] do:['foo' asFloat] 

    "

!

asFilename

    "return a Filename with pathname taken from the receiver"

    ^ Filename named:self

!

asCollectionOfWords

    "return a collection containing the words (separated by whitespace) 

     of the receiver. Multiple occurences of whitespace characters will

     be treated like one - i.e. whitespace is skipped."

    |words

     start  "{ Class:SmallInteger }" 

     stop   "{ Class:SmallInteger }" 

     mySize "{ Class:SmallInteger }"|

    words := OrderedCollection new.

    start := 1.

    mySize := self size.

    [start <= mySize] whileTrue:[

	start := self indexOfNonSeparatorStartingAt:start.

	start == 0 ifTrue:[

	    ^ words

	].

	stop := self indexOfSeparatorStartingAt:start.

	stop == 0 ifTrue:[

	    words add:(self copyFrom:start to:mySize).

	    ^ words

	].

	words add:(self copyFrom:start to:(stop - 1)).

	start := stop

    ].

    ^ words

    "

     'hello world isnt this nice' asCollectionOfWords

     '    hello    world   isnt   this   nice  ' asCollectionOfWords

     'hello' asCollectionOfWords

     '' asCollectionOfWords

     '      ' asCollectionOfWords

    "

!

asCollectionOfSubstringsSeparatedBy:aCharacter

    "return a collection containing the lines (separated by aCharacter) 

     of the receiver. If aCharacter occurs multiple times in a row, 

     the result will contain empty strings."

    |lines myClass

     numberOfLines "{ Class:SmallInteger }"

     startIndex    "{ Class:SmallInteger }"

     stopIndex     "{ Class:SmallInteger }" |

    "

     count first, to avoid regrowing of the OC

    "

    numberOfLines := (self occurrencesOf:aCharacter) + 1.

    lines := OrderedCollection new:numberOfLines.

    myClass := self species.

    startIndex := 1.

    1 to:numberOfLines do:[:lineNr |

	stopIndex := self indexOf:aCharacter startingAt:startIndex.

	stopIndex == 0 ifTrue:[

	    stopIndex := self size

	] ifFalse: [

	    stopIndex := stopIndex - 1.

	].

	(stopIndex < startIndex) ifTrue: [

	    lines add:(myClass new:0)

	] ifFalse: [

	    lines add:(self copyFrom:startIndex to:stopIndex)

	].

	startIndex := stopIndex + 2

    ].

    ^ lines

    "

     '1 one:2 two:3 three:4 four:5 five' withCRs asCollectionOfSubstringsSeparatedBy:$: 

     '1 one 2 two 3 three 4 four 5 five' withCRs asCollectionOfSubstringsSeparatedBy:Character space

    "

!

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."

    ^ self asCollectionOfSubstringsSeparatedBy:Character cr

    "

     '1 one\2 two\3 three\4 four\5 five' withCRs asCollectionOfLines

     '1 one\\\\2 two\3 three' withCRs asCollectionOfLines  

    "

!

asArrayOfSubstrings

    "return an array of substrings from the receiver, interpreting

     separators (i.e. spaces & newlines) as word-delimiters.

     This is a compatibility method - the actual work is done in

     asCollectionOfWords."

    ^ self asCollectionOfWords asArray

    "

     '1 one two three four 5 five' asArrayOfSubstrings  

    "

!

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."

    |words

     start  "{ Class:SmallInteger }" 

     stop   "{ Class:SmallInteger }" 

     mySize "{ Class:SmallInteger }"|

    words := OrderedCollection new.

    start := 1.

    mySize := self size.

    [start <= mySize] whileTrue:[

	"skip multiple separators"

	[aCollectionOfSeparators includes:(self at:start)] whileTrue:[

	    start := start + 1 .

	    start > mySize ifTrue:[

		^ words

	    ].

	].

	stop := self indexOfAny:aCollectionOfSeparators startingAt:start.

	stop == 0 ifTrue:[

	    words add:(self copyFrom:start to:mySize).

	    ^ words

	].

	words add:(self copyFrom:start to:(stop - 1)).

	start := stop

    ].

    ^ words

    "

     'hello:world:isnt:this nice' asCollectionOfSubstringsSeparatedByAny:#($:)

     'hello:world:isnt:this nice' asCollectionOfSubstringsSeparatedByAny:(Array with:$: with:Character space) 

     'h1e2l3l4o' asCollectionOfSubstringsSeparatedByAny:($1 to: $9) 

    "

!

tokensBasedOn:aCharacter

    "this is an ST-80 alias for the ST/X method

	asCollectionOfSubstringsSeparatedBy:"

    ^ self asCollectionOfSubstringsSeparatedBy:aCharacter

    "

     'hello:world:isnt:this nice' tokensBasedOn:$:

     'foo,bar,baz' tokensBasedOn:$,

     '/etc/passwd' asFilename readStream nextLine tokensBasedOn:$:

    "

! !

!CharacterArray methodsFor:'special string converting'!

chopTo:maxLen

    "if the receivers 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."

    |sz n1 n2|

    (sz := self size) > maxLen ifTrue:[

	n1 := n2 := maxLen // 2.

	maxLen odd ifTrue:[

	    n2 := n1 + 1

	].

	^ (self copyFrom:1 to:n1) , (self copyFrom:sz - n2 + 1)

    ]

    "

     '12345678901234'   chopTo:15            

     '123456789012345'  chopTo:15         

     '1234567890123456' chopTo:15      

     'aShortString' chopTo:15 

     'aVeryLongNameForAStringThatShouldBeShortened' chopTo:15 

    "

!

contractTo:maxLen

    "if the receivers 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."

    (sz := self size) > maxLen ifTrue:[

	halfSize := maxLen // 2.

	^ self copyReplaceFrom:halfSize - 1

			    to:sz - maxLen + halfSize + 1

			    with:'...'

    ]

    "

     '12345678901234' contractTo:15          

     '123456789012345' contractTo:15          

     '1234567890123456' contractTo:15        

     'aShortString' contractTo:15 

     'aVeryLongNameForAStringThatShouldBeShortened' contractTo:15 

    "

!

contractAtEndTo:maxLen

    "if the receivers 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."

    |sz|

    (sz := self size) > maxLen ifTrue:[

	^ self copyReplaceFrom:maxLen - 3

			    with:'...'

    ]

    "

     '12345678901234' contractAtEndTo:15          

     '123456789012345' contractAtEndTo:15          

     '1234567890123456' contractAtEndTo:15