eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'ReadStream':

Home

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

Class: ReadStream


Inheritance:

   Object
   |
   +--Stream
      |
      +--PeekableStream
         |
         +--PositionableStream
            |
            +--ReadStream
               |
               +--FCGI::FCGIReadStream

Package:
stx:libbasic
Category:
Streams
Version:
rev: 1.109 date: 2023/10/12 16:20:42
user: stefan
file: ReadStream.st directory: libbasic
module: stx stc-classLibrary: libbasic

Description:


ReadStream defines protocol for reading streamwise over collections.

copyright

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

blocked instance creation
o  with: aCollection
with on readStream makes no sense
- what do you want to read from the end of a collection?

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


Instance protocol:

Compatibility-Squeak
o  next: n into: aCollection startingAt: startIndex
Read n objects into the given collection.
Return aCollection or a partial copy if less than
n elements have been read.

o  nextInto: aCollection
( an extension from the stx:libcompat package )
Read the next elements of the receiver into aCollection.
Return aCollection or a partial copy if less than aCollection
size elements have been read.

converting
o  readStream
return a readStream from the receiver. Since this is already
a readStream, return self.

o  readStreamOrNil
return a readStream from the receiver. Since this is already
a readStream, return self.

This method has been defined for protocol copmatibility with Filename

emphasis
o  emphasis
return the emphasis of the current (i.e. next returned by #next)
element. Streams on a string will return nil for all elements.
Streams on collections which nothing at all about emphasises,
will report an error.

Usage example(s):

     |t s|

     t := 'hello world' asText
		emphasizeFrom:1 to:5 with:#bold;
		emphasizeFrom:7 to:11 with:#italic.

     s := t readStream.
     [s atEnd] whileFalse:[
	Transcript show:(s emphasis); show:' '.
	Transcript show:''''; show:(s next); showCR:''''.
     ].

queries
o  collectionSize
return the overall number of elements in the streamed collection
(both already read and to be read).

o  copyFrom: beginning to: end

o  isReadable
return true, if reading is supported by the receiver.
Here, true is always returned.

o  isWritable
return true, if writing is supported by the receiver.
This has to be redefined in concrete subclasses.

o  remainingSize
return the number of remaining elements in the streamed collection.

o  size
return the number of remaining elements in the streamed collection.

Notice: VW and Squeak seem to return the overall size here,
which is an incompatibility that should be fixed.
However, fixing seems to break some existing applications,
so this will be delayed for some time...

ST/X provides two methods which are more explicit: collectionSize and remainingSize.
Change the sender to use either one, but no longer #size

reading
o  next
return the next element; advance read pointer.
return nil, if there is no next element.
- tuned for a bit more speed on String/ByteArray/Array-Streams

o  next: count
return the next count elements of the stream as aCollection,
which depends on the stream's type - (see #contentsSpecies).

Usage example(s):

     #[1 2 3 4 5 6 7 8 9] readStream
        next;
        next:5;
        next.

o  nextAlphaNumericWord
read the next word (i.e. up to non letter-or-digit).
return a string containing those characters.
Skips any non-alphanumeric chars first.
- tuned for speed on String-Streams for faster scanning

o  nextByte
return the next element as an integer between 0 and 255; advance read pointer.
- tuned for a bit more speed on String/ByteArray/Array-Streams

o  nextOrNil
return the next element; advance read pointer.
return nil, if there is no next element.
- tuned for a bit more speed on String/ByteArray/Array-Streams

o  nextPeek
advance read pointer return the peek element.
this is equivalent to (self next; peek).
- tuned for speed on String-Streams for faster scanning

o  nextPeekOrNil
advance read pointer return the peek element.
this is equivalent to (self next; peekOrNil).
- tuned for speed on String-Streams for faster scanning

o  nextUnicode16CharacterMSB: msb
#[16r00 16r51] readStream nextUnicode16CharacterMSB:true
#[16r00 16r51] readStream nextUnicode16CharacterMSB:false

o  nextUnicode16Characters: count MSB: msb
easily tuned, if heavily used

Usage example(s):

     #[16r00 16r51] readStream nextUnicode16Characters:1 MSB:true
     #[16r00 16r51] readStream nextUnicode16Characters:1 MSB:false

o  peek
return the next element; do NOT advance read pointer.
return nil, if there is no next element.
- tuned for a bit more speed on String/ByteArray/Array-Streams

o  peekOrNil
return the next element; do NOT advance read pointer.
return nil, if there is no next element.
This is much like #peek -
However, unlike #peek, this does not raise an atEnd-query signal - even
if handled. Instead, nil is returned immediately.

o  skipSeparators
skip all whitespace; next will return next non-white-space element.
Return the peeked character or nil, if the end-of-stream was reached.
- reimplemented for speed on String-Streams for faster scanning

o  skipSeparatorsExceptCR
skip all whitespace except newlines;
next will return next non-white-space element.
- reimplemented for speed on String-Streams for faster scanning

o  skipThrough: anObject
skip all objects up-to and including anObject.
Return the receiver if skip was successful,
otherwise (i.e. if not found) return nil and leave the stream positioned at the end.
On success, the next read operation will return the element after anObject.
- reimplemented for speed on String-Streams for faster scanning

o  upToEndDo: aBlock
read elements and evaluate aBlock for each up to the end

Usage example(s):

     'abcdef' readStream upToEndDo:[:ch | Transcript showCR:ch]
     #(1 2 3 4 5 6) readStream upToEndDo:[:el | Transcript showCR:el]

reading-numbers
o  nextDecimalInteger
read the next integer in radix 10.
Does NOT skip initial whitespace.
Does NOT care for an initial sign.
The stream's elements should be characters.

Be careful - this method returns 0 if not positioned on a digit initially
or if the end of the stream is encountered.

Tuned for speed on String-Streams for faster scanning

Usage example(s):

fall-back for non-string streams - we have to continue where
     above primitive left off, in case of a large integer ...
     (instead of doing a super nextDecimalInteger)

writing
o  nextPut: anElement
catch write access to readstreams - report an error



ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Sat, 21 Dec 2024 15:42:23 GMT