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.75 date: 2023/05/15 22:26:11
user: cg
file: Interval.st directory: libbasic
module: stx stc-classLibrary: libbasic

Description:


Intervals represent a collection (or range) of numeric or character 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:
    (10 to: 20)         
    (10 to: 20) asArray 

    (20 to:10 by:-2)      
    (20 to:10 by:-2) asArray    

    ($a to:$z)                
    ($a to:$z) asString          

    ($a to:$z),($A to:$Z)       
    (($a to:$z),($A to:$Z)) asString 
    (($a to:$z),'bla')      
    ('bla',($a to:$z))       
    ((Character value:16r100) to:(Character value:16r120))           
    ((Character value:16r100) to:(Character value:16r120)) asString      

    (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  

[complexity:]
     fetch by index:       O(1)
     store by index:       -
     adding:               -
     removing:             -
     includes:             O(1)
     min/max:              O(1)
     size:                 O(1)


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:

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
(comment from inherited method)
return true if the receiver and aCollection represent collections
with equal contents, and if they are of the same species.

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 returns 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.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Mon, 18 Nov 2024 04:31:37 GMT