eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'FilteringStream':

Home

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

Class: FilteringStream


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:

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

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

o  readingFrom: aReadStream
create and return a new filteringStream, which reads from
another stream

o  readingFrom: aReadStream writingTo: aWriteStream
create and return a new filteringStream, which reads from
aReadStream and writes to aWriteStream.

o  writingTo: aWriteStream
create and return a new filteringStream, which writes to
another stream


Instance protocol:

access - pull-reading
o  contents

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

o  next
pull input from inputStream and
push it filtered into the outputStream

o  peek
peek ahead for the next character

o  peekOrNil
peek ahead for the next character, or return nil

access - push-writing
o  nextPut: something
push something through the filter

accessing
o  filter
return the filter

o  filter: something
set the filter

o  inputStream
return the inputStream

o  inputStream: something
set the inputStream

o  outputStream
return the outputStream

o  outputStream: something
set the outputStream

misc
o  clearEOF

o  close
when I am closed, close my input - if any

queries
o  atEnd
return true, if the receiver stream is at the end

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

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

o  isEncodedStream

o  isReadable

o  isWritable
return true, if writing is supported by the receiver.

o  position
return the receiver streams position

o  position0Based
return the receiver streams position

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

o  position1Based
return the receiver streams position

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

o  readStream

o  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:


pushing the contents of a stream onto another stream (here, the Transcript) without a need to read everything into a buffer or to reinvent the read-loop: (notice, a FilteringLineStream does this with less overhead, due to the byte-wise reading done here)
  |in pusher|

  in := 'Make.proto' asFilename readStream.
  pusher := FilteringStream readingFrom:in writingTo:Transcript.
  pusher filterUpToEnd
filter random numbers in [0.5 .. 0.6]:
  |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).
  ]
compute the values times two
  |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.
filtering prime numbers (that's just a demo - not really useful, because we will end in a recursion error if many filters are stacked):
  |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.
  ]


ST/X 7.2.0.0; WebServer 1.670 at bd0aa1f87cdd.unknown:8081; Thu, 02 Dec 2021 04:07:04 GMT