eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'Interval':
Home

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

Class: Interval

Inheritance:

   Object
   |
   +--Collection
      |
      +--SequenceableCollection
         |
         +--ReadOnlySequenceableCollection
            |
            +--Interval
Package:
stx:libbasic
Category:
Collections-Sequenceable
Version:
rev: 1.66 date: 2019/02/10 13:52:03
user: cg
file: Interval.st directory: libbasic
module: stx stc-classLibrary: libbasic
Author:
Claus Gittinger

Description:


Intervals represent a collection (or range) of numeric values specified by
a startValue, an endValue and a step. 
The interesting thing is that the elements are computed, not stored.
However, protocol-wise, intervals behave like any other (read-only) sequenceable collection.

For example, the interval (1 to:5) containes the elements (1 2 3 4 5) and
(1 to:6 by:2) contains (1 3 5).

The step may be negative, to count backward:
(5 to:1 by:-1) contains (5 4 3 2 1), and (6 to:1 by:-2) contains (6 4 2).


examples:

    (1 to:10) do:[:i | Transcript showCR:i]

  notice, that this is semantically equivalent to:

    1 to:10 do:[:i | Transcript showCR:i]

  however, the second is preferred, since loops using to:do: are
  much faster and do not create temporary garbage objects. 
  Therefore, Intervals are generally NOT used for this kind of loops.

    (1 to:10) asArray  

    (1 to:10 by:2) asOrderedCollection

Class protocol:

converting
o  decodeFromLiteralArray: anArray
create & return a new instance from information encoded in anArray.
Re-redefined, since the implementation in SequencableCollection creates instances with an initial
size, which is not allowed for intervals.

instance creation
o  from: start to: stop
return a new interval with elements from start to stop by 1

o  from: start to: stop by: step
return a new interval with elements from start to stop by step

Instance protocol:

accessing
o  at: index
return (i.e. compute) the index'th element

o  first
return the first element of the collection

o  increment
alias for #step; for ST-80 compatibility

o  last
return the last element of the collection

o  start
return the first number of the range

o  start: aNumber
set the first number of the range

o  step
return the step increment of the range.
OBSOLETE:
Please use #increment for ST-80 compatibility.

o  step: aNumber
set the step increment of the range

o  stop
return the end number of the range

o  stop: aNumber
set the end number of the range

bulk operations
o  sum
sum up all elements.

usage example(s): 

sum(1..n) is -------

usage example(s): 

     (1 to:10) sum         
     (1 to:10) asArray sum 

     (2 to:10) sum           
     (2 to:10) asArray sum   

     (5 to:10) sum    
     (5 to:10) asArray sum

comparing
o  = anInterval

o  hash
do not redefine: must generate same hash as SeqColl.

converting
o  asInterval

o  fromLiteralArrayEncoding: encoding
read my values from an encoding.
The encoding is supposed to be either of the form:
(#Interval start stop step)
This is the reverse operation to #literalArrayEncoding.

usage example(s): 

     Interval new fromLiteralArrayEncoding:((1 to:10) literalArrayEncoding)  
     Interval new fromLiteralArrayEncoding:((1 to:10 by:2) literalArrayEncoding) 
     Interval decodeFromLiteralArray:((1 to:10 by:2) literalArrayEncoding)

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

usage example(s): 

     (1 to:10) literalArrayEncoding      
     (1 to:10 by:2) literalArrayEncoding

converting-reindexed
o  from: startIndex
return a new collection representing the receiver's elements starting at startIndex.

usage example(s): 

     (1 to:100) from:2  

     (1 to:20 by:2) from:2           
     (1 to:20 by:2) asArray from:2    
     ((1 to:20 by:2) from:2) asArray

o  to: endIndex
return a new collection representing the receiver's elements upTo and including endIndex.

usage example(s): 

     (1 to:100) to:50    
     (1 to:100 by:2) to:50

enumerating
o  collect: aBlock
evaluate the argument, aBlock for every element in the collection
and return a collection of the results.
Redefined since the inherited method (SeqColl) accesses the receiver via at:,
which is slow for intervals

usage example(s): 

     (1 to:20 by:2) collect:[:i | i*i]

o  do: aBlock
evaluate the argument, aBlock for every element in the receiver-interval.
Redefined since SeqColl accesses the receiver with at:, which is slow for intervals.

usage example(s): 

     1e7 to:1e7+1 by:0.25 do:[:v | Transcript showCR:v]
     1.0 to:2.0 by:0.25 do:[:v | Transcript showCR:v]
     2.0 to:1.0 by:-0.25 do:[:v | Transcript showCR:v]
     $a to:$z do:[:v | Transcript showCR:v]

o  reverseDo: aBlock
evaluate the argument, aBlock for every element in the receiver-interval in
reverse order.
Redefined since SeqColl accesses the receiver with at:, which is slow for intervals.

usage example(s): 

     (1 to:10) do:[:el | Transcript showCR:el ].
     (1 to:10) reverseDo:[:el | Transcript showCR:el ].

o  select: aBlock
evaluate the argument, aBlock for every element in the collection
and return a collection of all elements for which the block return true.
Redefined since SeqColl accesses the receiver with at:, which is slow for intervals.

usage example(s): 

     (1 to:20) select:[:i | i even]

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

printing & storing
o  displayOn: aGCOrStream
what a kludge - Dolphin and Squeak mean: printOn: a stream;

o  printOn: aStream
append a printed representation to aStream

usage example(s): 

     (1 to:10) printOn:Transcript
     (1 to:10 by:2) printOn:Transcript
     (1 to:10) printString

o  storeOn: aStream
store a representation which can reconstruct the receiver to aStream

usage example(s): 

     (1 to:10) storeOn:Transcript
     (1 to:10 by:2) storeOn:Transcript

private
o  setFrom: startInteger to: stopInteger by: stepInteger
set start, stop and step components

o  species
return the type of collection to be returned by collect, select etc.

queries
o  includes: anElement
return true if anElement is in the interval (Numeric compare using =)

usage example(s): 

     (1 to:15) includes:0
     (1 to:15) includes:16
     (1 to:15) includes:1    
     (1 to:15) includes:15   
     (1 to:15) includes:5    
     (1 to:15) includes:14   
     (1 to:15) includes:4   
     (1 to:15) includes:4.0   
     (1 to:15) includes:4.4   

     (1 to:15 by:3) includes:0
     (1 to:15 by:3) includes:16
     (1 to:15 by:3) includes:1    
     (1 to:15 by:3) includes:15   
     (1 to:15 by:3) includes:5    
     (1 to:15 by:3) includes:4    
     (1 to:15 by:3) includes:13   
     (1 to:15 by:3) includes:14   
     (1 to:15 by:3) includes:4.0   
     (1 to:15 by:3) includes:4.4   

     (10 to:-10 by:-3) includes:11   
     (10 to:-10 by:-3) includes:10   
     (10 to:-10 by:-3) includes:9   
     (10 to:-10 by:-3) includes:8   
     (10 to:-10 by:-3) includes:7   
     (10 to:-10 by:-3) includes:4   
     (10 to:-10 by:-3) includes:0   
     (10 to:-10 by:-3) includes:-1   
     (10 to:-10 by:-3) includes:-2   
     (10 to:-10 by:-3) includes:-8     
     (10 to:-10 by:-3) includes:-9     
     (10 to:-10 by:-3) includes:-10    
     (10 to:-10 by:-3) includes:-11    
     (10 to:-10 by:-3) includes:-2.4   

     (-10 to:-20 by:-2) includes:-16   
     (-10 to:-20 by:-2) includes:-20   
     (-10 to:-20 by:-2) includes:-23   
     (-10 to:-20 by:-2) includes:-24

o  isEmpty
return true, if the receiver is empty

usage example(s): 

     self assert:(1 to:1) isEmpty not
     self assert:(1 to:0) isEmpty 
     self assert:(0 to:1) isEmpty not

     self assert:(1 to:1 by:-1) isEmpty not
     self assert:(1 to:0 by:-1) isEmpty not
     self assert:(0 to:1 by:-1) isEmpty

o  max
return the maximum value in the receiver collection,
redefined, since this can be easily computed.
Raises an error, if the receiver is empty.

usage example(s): 

     (0 to:15) max           
     (0 to:15 by:2) max      
     (0 to:15 by:8) max      
     (15 to:0) max           -> error
     (15 to:0 by:4) max      -> error      
     (-1 to:-15 by:-1) max    
     (-1 to:-15 by:-4) max    
     (-1 to:15 by:-1) max    -> error

o  min
return the minimum value in the receiver collection,
redefined, since this can be easily computed.
Raises an error, if the receiver is empty.

usage example(s): 

     (0 to:15) min           
     (0 to:15 by:2) min      
     (0 to:15 by:8) min      
     (15 to:0) min          -> error
     (15 to:0 by:4) min     -> error     
     (-1 to:-15 by:-1) min    
     (-1 to:-15 by:-4) min    
     (-1 to:15 by:-1) min   -> error

o  minMax
return the minimum and maximum values in the receiver collection
as a two element array.
Raises an error, if the receiver is empty.

usage example(s): 

     (0 to:15) minMax           
     (0 to:15 by:2) minMax      
     (0 to:15 by:8) minMax      
     (15 to:0) minMax          -> error
     (15 to:0 by:4) minMax     -> error     
     (-1 to:-15 by:-1) minMax    
     (-1 to:-15 by:-4) minMax    
     (-1 to:15 by:-1) minMax   -> error

o  size
return the number of elements in the collection

set operations
o  intersect: aCollection
return a new interval containing all elements of the receiver,
which are also contained in the argument collection

usage example(s): 

     (1 to:10) intersect:(4 to:20)      
     (1 to:10) intersect:(11 to:20)      
     (1 to:10) intersect:(10 to:20)      
     (4 to:20) intersect:(1 to:10)      
     (4 to:20) intersect:(1 to:10 by:2)

sorting & reordering
o  reversed
return a copy with elements in reverse order

usage example(s): 

this can be tricky, if stepping from start does not reach stop exactly.
     So what is the reverse of: (2 to:5 by: 2) ?
     I think, that the correct semantic is to behave transparent to the type
     of collection and generate the same elements as another collection would.
     In other words, the same as (1 to:5 by: 2) asOrderedCollection reversed
     would. That means, we get: #(4 2).
     This also means, that (2 to:5 by: 2) reversed reversed does not return the
     original, but another interval which generates the same elements ! (2 to:4 by: 2)

usage example(s): 

     (1 to:4) reversed asOrderedCollection   
     (1 to:4) reversed reversed asOrderedCollection 
     (1 to:4) asOrderedCollection reversed    
     (1 to:4) asOrderedCollection reversed reversed 

     (2 to:5 by: 2) asOrderedCollection     
     (2 to:5 by: 2) asOrderedCollection reversed    
     (2 to:5 by: 2) asOrderedCollection reversed reversed  
     (2 to:5 by: 2) reversed asOrderedCollection         
     (2 to:5 by: 2) reversed reversed asOrderedCollection   

     (1 to:2 by: 0.3) asOrderedCollection        
     (1 to:2 by: 0.3) asOrderedCollection reversed  
     (1 to:2 by: 0.3) asOrderedCollection reversed reversed  
     (1 to:2 by: 0.3) reversed asOrderedCollection     
     (1 to:2 by: 0.3) reversed reversed asOrderedCollection

visiting
o  acceptVisitor: aVisitor with: aParameter
dispatch for visitor pattern; send #visitInterval:with: to aVisitor.
this is special. Some encoders want to encode this as a sequenceable collection,
some want to encode a less expensive representation

ST/X 7.2.0.0; WebServer 1.670 at bd0aa1f87cdd.unknown:8081; Thu, 25 Apr 2024 11:33:58 GMT