Class: FilteringStream

• Inheritance
• Description
• Related information
• Class protocol
  • instance creation
• Instance protocol
  • access - pull-reading
  • access - push-writing
  • accessing
  • misc
  • queries
• Examples

Inheritance:

   Object
   |
   +--Stream
      |
      +--PeekableStream
         |
         +--FilteringStream
            |
            +--FilteringLineStream
            |
            +--LineNumberReadStream

Package:

stx:libbasic2

Category:

Streams-Misc

Version:

rev: 1.26 date: 2016/11/08 08:24:51

user: stefan

file: FilteringStream.st directory: libbasic2

module: stx stc-classLibrary: libbasic2

Author:

Claus Gittinger

Description:

A FilteringStream can be connected to some input
(from which elements are read via the ReadStream protocol),
and/or to some output (to which elements are written via
the WriteStream protocol.

The FilteringStream itself performs filtering/processing
on the elements as they arrive, optionally suppressing
elements.

A FilteringStream can be operated in pull-mode, by asking
it for the next element; it will then ask its inputStream for
and element, process it and return it.

Or, in pushMode, by having someone else writing elements via
nextPut:; it will then process the element, and send it to its
output stream.

Mixing modes does not make sense, since if pulled, data will not
be written to the outputStream (unless the puller does it).

The connected streams need not be real streams; anything which
responds to the basic Stream protocol can be connected
(a Transcript, a RandomNumber generator or even a Plug will do as well).

Similar, but not quite the same as SelectingReadStream / CollectingReadStream.

[instance variables:]
    inputStream     <Stream>  the stream from which elements are read
    outputStream    <Stream>  the stream to which elements are written
    filter          <Block>   the filter block;
    unbound         <Boolean> if true, the stream is unbound.

Related information:

    ReadStream
    WriteStream

Class protocol:

 new

create and return a new filteringStream.
The resulting stream must be connected to some other stream,
before being used

 on: something

create and return a new filteringStream, which reads from
something (which must be convertable to a stream)

 readingFrom: aReadStream

create and return a new filteringStream, which reads from
another stream

 readingFrom: aReadStream writingTo: aWriteStream

create and return a new filteringStream, which reads from
aReadStream and writes to aWriteStream.

 writingTo: aWriteStream

create and return a new filteringStream, which writes to
another stream

Instance protocol:

 contents

 filterUpToEnd

pull input from inputStream up to the end,
push it filtered into the outputStream.

 next

pull input from inputStream and
push it filtered into the outputStream

 peek

peek ahead for the next character

 peekOrNil

peek ahead for the next character, or return nil

 nextPut: something

push something through the filter

 filter

return the filter

 filter: something

set the filter

 inputStream

return the inputStream

 inputStream: something

set the inputStream

 outputStream

return the outputStream

 outputStream: something

set the outputStream

 clearEOF

 close

when I am closed, close my input - if any

 atEnd

return true, if the receiver stream is at the end

 contentsSpecies

return the kind of collection I should return when asked
for multiple elements.

 isEmpty

(comment from inherited method)
return true, if the contents of the stream is empty

 isEncodedStream

 isReadable

 isWritable

return true, if writing is supported by the receiver.

 position

return the receiver streams position

 position0Based

return the receiver streams position

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

 position1Based

return the receiver streams position

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

 readStream

 size

not always correct, but probably better than 0.
Better use #isEmpty.

usage example(s):

self error:'size of input is unknown (due to filtering)'

Examples:

  |in pusher|

  in := 'Make.proto' asFilename readStream.
  pusher := FilteringStream readingFrom:in writingTo:Transcript.
  pusher filterUpToEnd

  |in filter|

  in := Random new.

  filter := FilteringStream readingFrom:in.
  filter filter:[:num | ((num >= 0.5) and:[num <= 0.6]) ifTrue:[num] ifFalse:[nil]].

  20 timesRepeat:[
      Transcript showCR:(filter next printString).
  ]

  |filter|

  filter := FilteringStream 
              readingFrom:#(1 2 3 4 5 6 7 8 9 10) readStream
              writingTo:#() writeStream.
  filter filter:[:num | num * 2].
  filter contents inspect.

  |num generator primeFilter addFilter|

  num := 1.
  generator := Plug new.
  generator respondTo:#next
                 with:[num := num + 1. num].
  generator respondTo:#atEnd
                 with:[false].

  addFilter := [:prime | |newFilter|
      newFilter := FilteringStream basicNew.
      newFilter filter:[:num | (num \\ prime) == 0 ifTrue:[
                                  nil
                               ] ifFalse:[
                                  num
                               ]
                       ].
      newFilter inputStream:primeFilter.
      primeFilter := newFilter
  ].

  addFilter value:2.
  primeFilter inputStream:generator.

  1000 timesRepeat:[
      |nextPrime|

      nextPrime := primeFilter next.
      addFilter value:nextPrime.
      Transcript showCR:nextPrime.
  ]