hg/stx-libbasic: comparison Collection.st

equal deleted inserted replaced

-:af82888ceb72
+:1f5aa87f6170
-"{ Encoding: utf8 }"
 "
 COPYRIGHT (c) 1989 by Claus Gittinger
 All Rights Reserved
 This software is furnished under a license and may be used
 Kludges around the stupid definition of OrderedCollection>>new:"
 ^ self newWithSize:n
 ! !
 !Collection class methodsFor:'Signal constants'!
 emptyCollectionSignal
 "return the signal used to report non-allowed operation on empty collections"
 !
 isAbstract
 "Return if this class is an abstract class.
 True is returned for Collection here; false for subclasses.
-Abstract subclasses must redefine again."
+Abstract subclasses must redefine this again."
 ^ self == Collection
 ! !
 !Collection methodsFor:'Compatibility-ANSI'!
 '' ifEmpty: [ Time now printString ]
 "
 !
 ifEmpty:ifEmptyValue ifNotEmpty:ifNotEmptyValue
+"return ifNotEmptyValue if not empty, ifEmptyValue otherwise"
 |action|
 action := self isEmpty ifTrue:[ ifEmptyValue ] ifFalse:[ ifNotEmptyValue ].
 action isBlock ifTrue:[
 ].
 ^ action value
 !
 ifEmpty:ifEmptyValue ifNotEmptyDo:ifNotEmptyValue
+"return ifNotEmptyValue if not empty, ifEmptyValue otherwise"
 ^ self ifEmpty:ifEmptyValue ifNotEmpty:ifNotEmptyValue
 !
 ifEmptyDo:ifEmptyValue ifNotEmpty:ifNotEmptyValue
+"return ifNotEmptyValue if not empty, ifEmptyValue otherwise"
 ^ self ifEmpty:ifEmptyValue ifNotEmpty:ifNotEmptyValue
 !
 ifNotEmpty:ifNotEmptyValue
+"return ifNotEmptyValue if not empty, nil otherwise"
 ^ self ifEmpty:nil ifNotEmpty:ifNotEmptyValue
 !
 ifNotEmptyDo:ifNotEmptyValue
+"return ifNotEmptyValue if not empty, nil otherwise"
 ^ self ifEmpty:nil ifNotEmpty:ifNotEmptyValue
 !
 ifNotEmptyDo:ifNotEmptyValue ifEmpty:ifEmptyValue
+"return ifNotEmptyValue if not empty, ifEmptyValue otherwise"
 ^ self ifEmpty:ifEmptyValue ifNotEmpty:ifNotEmptyValue
 !
 intersection:aCollection
+"same as intersect: for Squeak compatibility"
 ^ self intersect:aCollection
 "Created: / 22-10-2008 / 21:29:27 / cg"
 ! !
 !Collection methodsFor:'accessing'!
 anElement
 "return any element from the collection,
 (see also: #removeAllFoundIn:, which does not raise an error).
 Notice: for some collections (those not tuned for
 resizing themself) this may be very slow.
 If the number of removed elements is big compared to to
-the receivers size, it may be better to copy the
+the receiver's size, it may be better to copy the
 ones which are not to be removed into a new collection."
 aCollection do:[:element | self remove:element].
 ^ aCollection
 (see also: #removeAllFoundIn:, which does not raise an error).
 Notice: for some collections (those not tuned for
 resizing themself) this may be very slow.
 If the number of removed elements is big compared to to
-the receivers size, it may be better to copy the
+the receiver's size, it may be better to copy the
 ones which are not to be removed into a new collection."
 aCollection do:[:element | self removeIdentical:element].
 ^ aCollection
 "Modified: / 13-09-2006 / 11:17:42 / cg"
 !
 detect:checkBlock thenCompute:evalBlock
 "evaluate the argument, aBlock for each element in the receiver until
-chloeckBck returns true; in this case return the value from evalBlock
+checkBck returns true; in this case return the value from evalBlock
 applied to the element which caused the true evaluation.
 If none of the evaluations returns true, report an error"
 ^ self detect:checkBlock thenCompute:evalBlock ifNone:[self errorNotFound]
 "
 !
 detect:checkBlock thenCompute:evalBlock ifNone:exceptionValue
 "evaluate the argument, aBlock for each element in the receiver until
-chloeckBck returns true; in this case return the value from evalBlock
+checkBck returns true; in this case return the value from evalBlock
 applied to the element which caused the true evaluation.
 If none of the evaluations returns true, return the value from exceptionValue."
 ^ evalBlock value:(self detect:checkBlock ifNone:[^ exceptionValue value]).
 "
 !
 detectMax: aBlock
 "Evaluate aBlock with each of the receiver's elements as the argument.
 Answer the element for which aBlock evaluates to the highest magnitude.
 If the receiver collection is empty, return nil.
 This method might also be called elect:."
 | maxElement maxValue |
 self do: [:each |
 | val |
 val := aBlock value: each.
-"Note that there is no way to get the first element that works
+"Note that there is no way to get the first element
-for all kinds of Collections.
+which works for all kinds of Collections.
-Must test every one (maxValue is nil for the first element)."
+Must therefore test every one (maxValue is nil for the first element)."
 (maxValue == nil or:[val > maxValue]) ifTrue: [
 maxElement := each.
 maxValue := val
 ]
 ].
 "Created: / 20-08-2011 / 21:34:49 / cg"
 !
 detectMin: aBlock
 "Evaluate aBlock with each of the receiver's elements as the argument.
 Answer the element for which aBlock evaluates to the lowest number.
 If the receiver collection is empty, return nil."
 | minElement minValue |
 self do: [:each |
 | val |
 val := aBlock value: each.
-"Note that there is no way to get the first element that works
+"Note that there is no way to get the first element
-for all kinds of Collections.
+which works for all kinds of Collections.
-Must test every one (maxValue is nil for the first element)."
+Must therefore test every one (minValue is nil for the first element)."
 (minValue == nil or:[val < minValue]) ifTrue: [
 minElement := each.
 minValue := val
 ]
 ].
 doWhileTrue:aBlock
 "evaluate the argument, aBlock for each element,
 until the block evaluates to false.
 Answer true, if all the elements have been processed,
 false otherwise."
 self do:[:el |
 (aBlock value:el) ifFalse:[
 ^ false.
 ]
 "Modified: 20.4.1996 / 11:33:50 / cg"
 !
 keysAndValuesDo:aTwoArgBlock
 "evaluate the argument, aBlock for every element in the collection,
-passing both index and element as arguments."
+passing both index and element as arguments.
+Blocked here - must be redefined in subclasses which have keyed elements"
 ^ self errorNotKeyed
 !
 keysAndValuesReverseDo:aTwoArgBlock
 "evaluate the argument, aBlock in reverse order for every element in the collection,
-passing both index and element as arguments."
+passing both index and element as arguments.
+Blocked here - must be redefined in subclasses which have keyed elements"
 ^ self errorNotKeyed
 "Created: 9.5.1996 / 00:58:24 / cg"
 !
 keysAndValuesSelect:selectBlockWith2Args thenCollect:collectBlockWith2Args
+"first call the selectBlockWith2Args, passsing it each key and element,
+if that returns true, call the collectBlockWith2Args, also with key and element,
+and collect the resulting values in an OrderedCollection."
 |collected|
 collected := OrderedCollection new.
 self keysAndValuesDo:[:eachKey :eachValue |
 (selectBlockWith2Args value:eachKey value:eachValue) ifTrue:[
 ].
 ].
 ^ collected
 "
-#(10 20 30 40) keysAndValuesSelect:[:idx :val | idx > 2] thenCollect:[:idx :val | idx->val]
+#(10 20 30 40)
+keysAndValuesSelect:[:idx :val | idx > 2]
+thenCollect:[:idx :val | idx->val]
 "
 !
 keysDo:aBlock
 "evaluate the argument, aBlock for every key in the collection."
 "Created: / 07-08-2010 / 16:26:15 / cg"
 !
 select:selectBlock thenDo:doBlock
-"combination of select followed by do
+"combination of select followed by do.
 The same as if two separate select:+do: messages were sent,
 but avoids the creation of intermediate collections,
 so this is nicer for big collections."
 self do:[:eachElement |
 ]
 ].
 "
 #(1 2 3 4 5 6 7) select:[:i | i even] thenDo:[:i | Transcript showCR:i]
+"
+!
+selectWithIndex:aTwoArgBlock
+"return a new collection with all elements from the receiver,
+for which the argument aBlock evaluates to true.
+aTwoArgBlock is called with value and index as arguments."
+|newCollection|
+newCollection := self species new.
+self doWithIndex:[:eachValue :eachKey |
+(aTwoArgBlock value:eachValue value:eachKey) ifTrue:[newCollection add:eachValue].
+].
+^ newCollection
+"
+#(10 20 30 40) selectWithIndex:[:e :i | i odd]
+#(10 20 30 40) selectWithIndex:[:e :i | i even]
 "
 !
 triplesDo:aThreeArgBlock
 "evaluate the argument, aThreeArgBlock for every element in the collection,
 aStream nextPutAll:(s contents).
 ].
 aStream nextPut:$)
 "
-#(1 2 3 'hello' $a $ü) printOn:Transcript
+#(1 2 3 'hello' $a $�) printOn:Transcript
 (Array new:100000) printOn:Transcript
 (Array new:100000) printOn:Stdout
 (Array new:100000) printString size
 (Dictionary new at:#hello put:'world';
 at:#foo put:'bar'; yourself) printOn:Transcript
 defaultElement
 ^  nil
 !
 isReadOnly
+"true if this is a readOnly (immutable) collection.
+Q1: should this be called isImmutable?
+Q2: who uses this?"
 ^ false
 !
 isWritable
+"true if this is not a readOnly (immutable) collection.
+Q1: should this be called isMutable?
+Q2: who uses this?"
 ^ self isReadOnly not
 !
 size
 "return the number of elements in the receiver.
 !
 includesAll:aCollection
 "return true, if the the receiver includes all elements of
 the argument, aCollection; false if any is missing.
-Notice: this method has O-square runtime behavior and may be
+Notice: this method has O� runtime behavior and may be
 slow for big receivers/args.
 Think about using a Set, or Dictionary."
 ^ aCollection conform:[:element | (self includes:element)]
 includesAny:searchCollection
 "return true, if the the receiver includes any elements of
 the argument, aCollection; false if it includes none.
 Notice:
-this method has O^2(N) runtime behavior and may be
+this method has O� runtime behavior and may be
 slow for big receivers/args.
 Think about using a Set or Dictionary.
 Some speedup is also possible, by arranging highly
 probable elements towards the beginning of aCollection,
 to avoid useless searches.
 includesAnyIdentical:aCollection
 "return true, if the the receiver includes any elements of
 the argument, aCollection; false if it includes none.
 Use identity compare for comparing.
-Notice: this method has O^2(N) runtime behavior and may be
+Notice: this method has O� runtime behavior and may be
 slow for big receivers/args.
 Think about using a Set or Dictionary.
 Some speedup is also possible, by arranging highly
 probable elements towards the beginning of aCollection,
 to avoid useless searches."

branch	jv
changeset 19478	1f5aa87f6170
parent 19331	59f77658de07
parent 19459	3bcd4f73da62
child 19610	a9a6940944a9