Class: NumberSet

• Inheritance
• Description
• Class protocol
  • input from a stream
  • instance creation
• Instance protocol
  • accessing
  • adding & removing
  • enumerating
  • printing
  • private
  • private accessing
  • queries

Inheritance:

   Object
   |
   +--Collection
      |
      +--SequenceableCollection
         |
         +--NumberSet

Package:

stx:libbasic2

Category:

Collections-Ordered

Version:

rev: 1.17 date: 2022/07/15 11:23:16

user: cg

file: NumberSet.st directory: libbasic2

module: stx stc-classLibrary: libbasic2

Description:

NumberSets are sets holding positive integers.

This class has been written especially to represent number-ranges as found in .newsrc-files,
and it supports reading/writing of that format (for example: '0-62,69,82,84,86,88,91').
It is space optimized for sparse sets of numbers, containing a mix of single numbers
and chunks of sequential sub ranges. 
When adding elements, holes between 2 subranges
are detected, and merged into single subranges.
It may need some care to be used in other situations.

The implementation uses an array of intervals or individual numbers.

Reading and writing is in .newsrc-format.


[timing:]
    Time millisecondsToRun:[
        10000 timesRepeat:[
            (NumberSet with:(0 to:255)) removeAllFoundIn:(10 to:20); yourself.
        ]
    ]

    Time millisecondsToRun:[
        10000 timesRepeat:[
            (Set withAll:(0 to:255)) removeAllFoundIn:(10 to:20); yourself.
        ]
    ] 
    
[example:]
    |s|

    s := NumberSet new.
    s add:123.
    s add:255.
    s add:124.
    s add:-5.
    s addAll:(125 to:188).
    s
    

copyright
COPYRIGHT (c) 1992 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:

 readFrom: aStringOrStream

read a NumberSet (in .newsrc format) from aStream.
return an empty NumberSet if nothing can be read (or wrong format)

Usage example(s):

NumberSet readFrom:('0-62,69,82,84,86,88,91' readStream). NumberSet readFrom:('abc' readStream).

Usage example(s):

|ns s string| ns := NumberSet new. ns add:1. ns add:2. ns add:3. ns add:5. s := '' writeStream. ns printOn:s. string := s contents. NumberSet readFrom:string.

 readFrom: aStringOrStream onError: exceptionalValue

read a NumberSet (in .newsrc format) from aStream.
return an empty NumberSet if nothing can be read (or wrong format)

Usage example(s):

NumberSet readFrom:('0-62,69,82,84,86,88,91' readStream).

Usage example(s):

|ns s string| ns := NumberSet new. ns add:1. ns add:2. ns add:3. ns add:5. s := '' writeStream. ns printOn:s. string := s contents. NumberSet readFrom:string.

 new: size

(comment from inherited method)
return an instance of myself with anInteger indexed variables

 with: aNumberOrInterval

return a new numberSet containing a single number
or the numbers from an interval

Usage example(s):

NumberSet with:69 NumberSet with:(1 to:50) NumberSet withAll:(1 to:50)

 withAll: aCollectionOfNumbersOrIntervals

return a new numberSet containing all elements from the argument collection,
which has either numbers or intervals as elements

Usage example(s):

NumberSet with:69 NumberSet with:(1 to:50) NumberSet withAll:(1 to:50) NumberSet withAll:{ 1 . 2 . 5 . (10 to:20) . (30 to:50) . 99 }

Instance protocol:

 lastOfFirstInterval

return the last element of the first interval.
Return nil if the receiver is empty.

 add: aNumber

add the argument, aNumber to the NumberSet

 remove: aNumber ifAbsent: aBlock

remove the argument, aNumber from the NumberSet

 do: aBlock

evaluate the argument, aBlock for each element in the numberSet

 displayOn: aStream

return a nice string for the inspector

Usage example(s):

(NumberSet readFrom:'1,2,4-10,15') displayOn:Transcript (NumberSet readFrom:'1,2,4-10,15') printOn:Transcript

 printOn: aStream

output the NumberSet (in .newsrc format) on aStream

 readFrom: aStringOrStream

read my value from aStream (in .newsrc format).
Raise an error if the format is invalid

Usage example(s):

NumberSet readFrom:'0-62,69,82,84,86,88,91' NumberSet readFrom:'0-62,69,82,84,86,88,91' readStream NumberSet new readFrom:('0-62,69,82,84,86,88,91' readStream) NumberSet new readFrom:'0-62,69,82,84,86,88,91' NumberSet readFromString:'0+62,69,82,84,86,88,91' -- raises an error NumberSet readFrom:'1+62,69,82,84,86,88,91' -- stops at '+'

 readFrom: aStringOrStream onError: exceptionalValue

read my value from aStream (in .newsrc format)

Usage example(s):

NumberSet readFrom:'0-62,69,82,84,86,88,91' NumberSet readFrom:'0-62,69,82,84,86,88,91' readStream NumberSet new readFrom:('0-62,69,82,84,86,88,91' readStream) NumberSet new readFrom:'0-62,69,82,84,86,88,91'

 tryMerge: index

try to make element at index and index + 1 be one element

 setFirst: aNumberOrInterval

set the first element

 first

answer the first i.e. lowest number in the set.
If the receiver is empty, return nil.

 includes: aNumber

answer true, if aNumber is in the set

 last

answer the last i.e. highest number in the set.
If the receiver is empty, return nil.

 size

return the number of elements in the Set