eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'StringCollection':

Home

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

Class: StringCollection


Inheritance:

   Object
   |
   +--Collection
      |
      +--SequenceableCollection
         |
         +--OrderedCollection
            |
            +--StringCollection
               |
               +--FileText

Package:
stx:libbasic
Category:
Collections-Text
Version:
rev: 1.73 date: 2023/11/23 09:53:41
user: cg
file: StringCollection.st directory: libbasic
module: stx stc-classLibrary: libbasic

Description:


StringCollection is a variable sized array of lines which are strings.
WARNING:
    This class is temporary (a historic leftover) - it may change or
    even vanish in the future. Use OrderedCollections or other standard
    classes to represent collections of strings.

StringCollection used to be called Text, but this is a very bad name
 - there is something totally different also named Text in ST-80 ...

copyright

COPYRIGHT (c) 1989 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.

Class protocol:

instance creation
o  from: aString
return a new text object with lines taken from the argument, aString

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

o  fromArray: anArray
return a new text object with lines taken from the argument, an array
of strings

o  fromString: aString
return a new text object with lines taken from the argument, aString

o  new: size
return a new string collection with size empty lines

Usage example(s):

  StringCollection new:10

o  newWithCapacity: size
return a new empty string collection with size capacity

Usage example(s):

  StringCollection newWithCapacity:10

o  newWithSize: size
return a new string collection with size empty lines


Instance protocol:

converting
o  asString
return myself as a string with embedded cr's,
AND with an additional <cr> at the end

Usage example(s):

        #('This' 'is' 'some' 'text') asStringCollection asString
        #('This' 22 'some' 'text') asStringCollection asString

o  asStringCollection
return the receiver as a stringCollection - that's easy

o  asStringWithoutFinalCR
return myself as a string with embedded cr's
BUT without an additional final CR

o  encodeFrom: oldEncoding into: newEncoding
encode each line

o  from: aString
setup my contents from the argument, aString.
Obsolete, as it conflicts with the from:index
message, as inherited from SeqCollection.
For a migration time, check which interface is wanted here,
and issue an obsoleteMessageWarning as required.

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

o  fromString: aString
setup my contents from the argument, aString.
aString should be delimited by newline or return characters

o  withoutCEscapes
return a copy of myself where C-escapes are expanded in every line

copying
o  copyEmpty: size
we have to redefine this, since 'self class new:size'
does allocate size nil lines (it does an implicit #grow: size).
In order to get #collect: working, we should not perform this implicit grow

o  copyEmptyAndGrow: size
performance optimization:
StringCollections are always grown to size after #new: (containing nil elements)

Usage example(s):

        #('some' 'text' 'bla') asStringCollection copyEmptyAndGrow:20

o  copyToEndInto: aStream
copy all of myself into aStream. Compatibility with Stream.
Note: this is by purpose (expeco compatibility) different from
self asString copyToEndInto:aStream.

o  withoutLeadingAndTrailingBlankLines
return a copy of the receiver with leading and trailing blank lines removed.
If there are no trailing blank lines, the original receiver is returned.
If all lines are blank, an empty string collection is returned.

Usage example(s):

'1
2
3' asStringCollection withoutLeadingAndTrailingBlankLines      

Usage example(s):

'

2
3

' asStringCollection withoutLeadingAndTrailingBlankLines       

o  withoutLeadingBlankLines
return a copy of the receiver with leading blank lines removed.
If there are no leading blank lines, the original receiver is returned.
If all lines are blank, an empty string collection is returned.

Usage example(s):

'1
2
3' asStringCollection withoutLeadingBlankLines     

Usage example(s):

'
2
3' asStringCollection withoutLeadingBlankLines       

Usage example(s):

'

' asStringCollection withoutLeadingBlankLines      

o  withoutTrailingBlankLines
return a copy of the receiver with trailing blank lines removed.
If there are no trailing blank lines, the original receiver is returned.
If all lines are blank, an empty string collection is returned.

Usage example(s):

'1
2
3' asStringCollection withoutTrailingBlankLines      

Usage example(s):

'
2
3
' asStringCollection withoutTrailingBlankLines       

Usage example(s):

'
2
3


' asStringCollection withoutTrailingBlankLines       

Usage example(s):

'

' asStringCollection withoutTrailingBlankLines      

enumerating
o  collect: aBlock
evaluate the argument, aBlock for every element in the collection
and return a collection of the results.

Redefined, to change the result collection to an OrderedCollection if
not all elements are valid for a StringCollection (must be string or nil).

Usage example(s):

     #('this' 'is' 'some' nil 'text') asStringCollection collect:[:i | i]
     #('this' true 'some' nil 'text') asStringCollection collect:[:i | i ]

o  collect: collectBlock thenSelect: selectBlock
combination of collect followed by select;
redefined to avoid the creation of an intermediate (garbage) collection.

Redefined, to change the result collection to an OrderedCollection if
not all elements are valid for a StringCollection (must be string or nil).

Usage example(s):

     #('this' 'is' 'some' nil 'text') asStringCollection collect:[:i | i] thenSelect:[:e| e notNil]
     #('this' true 'some' nil 'text') asStringCollection collect:[:i | i ] thenSelect:[:e| e notNil]

o  select: selectBlock thenCollect: collectBlock
combination of select followed by collect;
redefined to avoid the creation of an intermediate (garbage) collection.

Redefined, to change the result collection to an OrderedCollection if
not all elements are valid for a StringCollection (must be string or nil).

Usage example(s):

     #('this' 'is' 'some' nil 'text') asStringCollection select:[:e| e notNil] thenCollect:[:i | i]
     #('this' true 'some' nil 'text') asStringCollection select:[:e| e notNil] thenCollect:[:i | i]

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

printing & storing
o  printOn: aStream
print myself on aStream with embedded cr's

o  printString
return the receiver's printString

queries
o  encoding
the encoding; ask my first line

o  numberOfLines
return the number of lines of the receiver.
An alias for self size, for protocol compatibility with strings

o  stringSize
the size of the string if I was converted

removing
o  removeTrailingBlankLines
destructive removal of trailing blank lines

Usage example(s):

     c'1\n2\n3' asStringCollection removeTrailingBlankLines       => StringCollection('1' '2' '3')      
     c'\n2\n3' asStringCollection removeTrailingBlankLines        => StringCollection('' '2' '3')     
     c'\n2\n3\n\n\n' asStringCollection removeTrailingBlankLines  => StringCollection('' '2' '3')     
     c'\n\n' asStringCollection removeTrailingBlankLines          => StringCollection()

o  removeTrailingReturnsInEachLine
destructive removal of trailing CRs in each line

Usage example(s):

     c'1\r\n2\r\n3' asStringCollection                                  => StringCollection(c'1\r' c'2\r' '3')
     c'1\r\n2\r\n3' asStringCollection removeTrailingReturnsInEachLine  => StringCollection('1' '2' '3')      

searching
o  indexOfLineStartingWith: aStringOrCharacter
return the index of the first line starting with the argument, aString

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

o  withTabs
return a new stringCollection consisting of the receiver's lines,
where leading spaces are replaced by tabulator characters (assuming 8-col tabs).
Notice: lines which do not contain leading spaces, are copied by reference to the
new stringCollection (i.e. shared);
otherwise new strings is created.
Limitation: only the very first spaces are replaced

Usage example(s):

       ('        abcd            ') asStringCollection withTabs
       #('        abcd' '                 def  ') asStringCollection withTabs

o  withTabsExpanded
return a new stringCollection consisting of the receiver's lines,
where tabs are replaced by space characters (assuming 8-col tabs).
Notice: lines which do not contain any tab, are copied by reference to the
new stringCollection (i.e. shared);
otherwise new strings is created.

Usage example(s):

       |tab|
       tab := String with:Character tab.
       ('abcd', tab, 'tef', tab, 'tgh') asStringCollection withTabsExpanded

o  withTabsExpanded: n
return a new stringCollection consisting of the receiver's lines,
where tabs are replaced by space characters (assuming n-col tabs).
Notice: lines which do not contain any tab, are copied by reference to the
new stringCollection (i.e. shared);
otherwise new strings is created.

testing
o  isStringCollection
return true, if the receiver is some kind of stringCollection;
true is returned here - the method is redefined from Object.



ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Tue, 10 Dec 2024 20:19:28 GMT