brl.stream

BlitzMax Forums/BlitzMax Module Tweaks/brl.stream
ProfJake
(Posted 2010) [#1]
I cleaned up the stream module a little bit.
The functionality is exactly the same, but now it is SuperStrict and a lot easier to read - cleaner code - in my opinion.
SuperStrict

Rem
	bbdoc: Streams/Streams
End Rem
Module BRL.Stream

ModuleInfo "Version: 1.10"
ModuleInfo "Author: Mark Sibly"
ModuleInfo "License: Blitz Shared Source Code"
ModuleInfo "Copyright: Blitz Research Ltd"
ModuleInfo "Modserver: BRL"

ModuleInfo "History: 1.10 Release"
ModuleInfo "History: Superstrict mode and cleaning up the source"
ModuleInfo "History: 1.09 Release"
ModuleInfo "History: Fixed 'excpetion' typos"
ModuleInfo "History: 1.08 Release"
ModuleInfo "History: Fixed resource leak in CasedFileName"
ModuleInfo "History: 1.07 Release"
ModuleInfo "History: OpenStream protocol:: now case insensitive"
ModuleInfo "History: Fixed ReadString with 0 length strings"
ModuleInfo "History: Removed LoadStream - use LoadByteArray instead"
ModuleInfo "History: Removed AddStreamFactory function"
ModuleInfo "History: Added url parameter to TStreamFactory CreateStream method"
ModuleInfo "History: 1.06 Release"
ModuleInfo "History: Added checks to CStream for reading from write only stream and vice versa"
ModuleInfo "History: 1.05 Release"
ModuleInfo "History: Fixed Eof bug"
ModuleInfo "History: 1.04 Release"
ModuleInfo "History: Added LoadString"
ModuleInfo "History: Added LoadByteArray"
ModuleInfo "History: Cleaned up docs a bit"

Import Pub.StdC

Rem
	bbdoc:	Base exception type thrown by streams
End Rem
Type TStreamException
End Type

Rem
	bbdoc:	Exception type thrown by streams in the event of read errors
	about:	#TStreamReadException is usually thrown when a stream operation failed to read enough
			bytes. For example, if the stream ReadInt method fails to read 4 bytes, it will throw
			a #TStreamReadException.
End Rem
Type TStreamReadException Extends TStreamException
	Method toString:String()
		Return "Error reading from stream."
	End Method
End Type

Rem
	bbdoc:	Exception type thrown by streams in the event of write errors
	about:	#TStreamWriteException is usually thrown when a stream operation failed to write enough
			bytes. For example, if the stream WriteInt method fails to write 4 bytes, it will throw
			a #TStreamWriteException.
End Rem
Type TStreamWriteException Extends TStreamException
	Method toString:String()
		Return "Error writing to stream."
	End Method
End Type

Rem
	bbdoc:	Base input/output type
	about:	To create your own stream types, you should extend TStream and implement
			at least these methods.

			You should also make sure your stream can handle multiple calls to the Close method.
End Rem
Type TIO
	Rem
		bbdoc:	Gets the stream's end of file status.
		returns:	True for end of file reached, otherwise False.
		about:	For seekable streams such as file streams, eof generally returns True if the file
				position equals the file size. This means that no more bytes can be read from the
				stream. However, it may still be possible to write bytes, in which case the file will
	 			'grow'.
	
				For communication type streams such as socket streams, Eof returns True if the stream
				has been shut down for some reason - either locally or by the remote host. In this case,
				no more bytes can be read from or written to the stream.
	End Rem
	Method eof:Int()
		Return Self.pos() = Self.size()
	End Method

	Rem
		bbdoc:	Gets the position of a seekable stream.
		returns:	Stream position as a byte offset, or -1 if stream is not seekable
	End Rem
	Method pos:Int()
		Return -1
	End Method

	Rem
		bbdoc:	Gets the size of a seekable stream.
		returns:	Size, in bytes, of seekable stream, or 0 if stream is not seekable
	End Rem
 	Method size:Int()
		Return 0
	End Method

	Rem
		bbdoc:	Seeks to a position in a seekable stream.
		returns:	New stream position, or -1 if stream is not seekable
	End Rem
	Method seek:Int(position:Int)
		Return -1
	End Method

	Rem
		bbdoc:	Flushes the stream.
		about:	Flushes any internal stream buffers.
	End Rem
	Method flush()
	End Method

	Rem
		bbdoc:	Closes the stream.
		about:	Closes the stream after flushing any internal stream buffers.
	End Rem
	Method close()
	End Method

	Rem
		bbdoc:	Reads at least 1 Byte from the stream.
		returns:	Number of bytes successfully read.
		about:	This method may 'block' if it is not possible to read at least one byte due to IO buffering.
	
				If this method returns 0, the stream has reached end of file.
	End Rem
	Method read:Int(buffer:Byte Ptr, count:Int)
		RuntimeError("Stream is not readable.")
		Return 0
	End Method

	Rem
		bbdoc:	Writes at least 1 Byte to the stream.
		returns:	Number of bytes successfully written.
		about:	This method may 'block' if it is not possible to write at least one byte due to IO buffering.
	
				If this method returns 0, the stream has reached end of file.
	End Rem
	Method write:Int(buffer:Byte Ptr, count:Int)
		RuntimeError("Stream is not writeable.")
		Return 0
	End Method

	Method Delete()
		Self.close()
	End Method

End Type

Rem
	bbdoc:	Data stream type
	about:	#TStream extends #TIO to provide methods for reading and writing various types of values
			to and from a stream.

			Note that methods dealing with strings - readLine, writeLine, readString and writeString -
			assume that strings are represented by bytes in the stream. In future, a more powerful
			TextStream type will be added capable of decoding text streams in multiple formats.
End Rem
Type TStream Extends TIO

	Rem
		bbdoc:	Reads bytes from the stream.
		about:	#ReadBytes reads @count bytes from the stream into the memory block specified by @buffer.
	
				If @count bytes were not successfully read, a #TStreamReadException is thrown. This typically
				occurs due to end of file.
	End Rem
	Method readBytes:Int(buffer:Byte Ptr, count:Int)
		Local oldCount:Int	= count
		While count > 0
			Local n:Int	= Self.read(buffer, count)
			If Not n Throw New TStreamReadException
			count:- n
			buffer:+ n
		Wend
		Return oldCount
	End Method

	Rem
		bbdoc:	Writes bytes to the stream.
		about:	#writeBytes writes @count bytes from the memory block specified by @buffer to the stream.
	
				If @count bytes were not successfully written, a #TStreamWriteException is thrown. This typically
				occurs due to end of file.
	End Rem
	Method writeBytes:Int(buffer:Byte Ptr, count:Int)
		Local oldCount:Int	= count
		While count > 0
			Local n:Int	= Self.write(buffer, count)
			If Not n Throw New TStreamWriteException
			count:- n
			buffer:+ n
		Wend
		Return oldCount
	End Method

	Rem
		bbdoc:	Skips bytes in the stream.
		about:	#SkipBytes read @count bytes from the stream and throws them away.
	
				If @count bytes were not successfully read, a #TStreamReadException is thrown. This typically
				occurs due to end of file.
	End Rem
	Method skipBytes:Int(count:Int)
		Local oldCount:Int	= count
		Local buffer:Byte[1024]
		While count > 0
			Local n:Int	= Self.read(buffer, Min(count, buffer.length))
			If Not n Throw New TStreamReadException
			count:- n
		Wend
		Return oldCount
	End Method

	Rem
		bbdoc:	Reads a Byte from the stream.
		returns:	The read value.
		about:	If a value could not be read (possibly due to end of file), a #TStreamReadException is thrown.
	End Rem
	Method ReadByte:Byte()
		Local value:Byte
		Self.readBytes(Varptr value, 1)
		Return value
	End Method

	Rem
		bbdoc:	Writes a Byte to the stream.
		about:	If the value could not be written (possibly due to end of file), a #TStreamWriteException is thrown.
	End Rem
	Method WriteByte(value:Byte)
		Local q:Byte	= value
		Self.writeBytes(Varptr q, 1)
	End Method

	Rem
		bbdoc:	Reads a Short (2 Bytes) from the stream.
		returns:	The read value.
		about:	If a value could not be read (possibly due to end of file), a #TStreamReadException is thrown.
	End Rem
	Method ReadShort:Short()
		Local value:Short
		Self.readBytes(Varptr value, 2)
		Return value
	End Method

	Rem
		bbdoc:	Writes a Short (2 Bytes) to the stream.
		about:	If the value could not be written (possibly due to end of file), a #TStreamWriteException is thrown.
	End Rem
	Method WriteShort(value:Short)
		Local q:Short	= value
		Self.writeBytes(Varptr q,2)
	End Method

	Rem
		bbdoc:	Reads an Int (4 Bytes) from the stream.
		returns:	The read value.
		about:	If a value could not be read (possibly due to end of file), a #TStreamReadException is thrown.
	End Rem
	Method ReadInt:Int()
		Local value:Int
		Self.readBytes(Varptr value, 4)
		Return value
	End Method
	
	Rem
		bbdoc:	Writes an Int (4 Bytes) to the stream.
		about:	If the value could not be written (possibly due to end of file), a #TStreamWriteException is thrown.
	End Rem
	Method WriteInt(value:Int)
		Local q:Int	= value
		Self.writeBytes(Varptr q, 4)
	End Method
	
	Rem
		bbdoc:	Reads a Long (8 Bytes) from the stream.
		returns:	The read value.
		about:	If a value could not be read (possibly due to end of file), a #TStreamReadException is thrown.
	End Rem
	Method ReadLong:Long()
		Local value:Long
		Self.readBytes(Varptr value, 8)
		Return value
	End Method
	
	Rem
		bbdoc:	Writes a Long (8 Bytes) to the stream.
		about:	If the value could not be written (possibly due to end of file), a #TStreamWriteException is thrown.
	End Rem
	Method WriteLong(value:Long)
		Local q:Long	= value
		Self.writeBytes(Varptr q, 8)
	End Method
	
	Rem
		bbdoc:	Reads a Float (4 Bytes) from the stream.
		returns:	The read value.
		about:	If a value could not be read (possibly due to end of file), a #TStreamReadException is thrown.
	End Rem
	Method ReadFloat:Float()
		Local value:Float
		Self.readBytes(Varptr value, 4)
		Return value
	End Method

	Rem
		bbdoc:	Writes a Float (4 Bytes) to the stream.
		about:	If the value could not be written (possibly due to end of file), a #TStreamWriteException is thrown.
	End Rem
	Method WriteFloat(value:Float)
		Local q:Float	= value
		Self.writeBytes(Varptr q, 4)
	End Method

	Rem
		bbdoc:	Read a Double (8 Bytes) from the stream.
		returns:	The read value.
		about:	If a value could not be read (possibly due to end of file), a #TStreamReadException is thrown.
	End Rem
	Method ReadDouble:Double()
		Local value:Double
		Self.readBytes(Varptr value, 8)
		Return value
	End Method

	Rem
		bbdoc:	Writes a Double (8 Bytes) to the stream.
		about:	If the value could not be written (possibly due to end of file), a #TStreamWriteException is thrown.
	End Rem
	Method WriteDouble(value:Double)
		Local q:Double	= value
		Self.writeBytes(Varptr q, 8)
	End Method
	
	Rem
		bbdoc:	Reads a line of text from the stream.
		about:	Bytes are read from the stream until a newline character (ASCII code 10) or null
				character (ASCII code 0) is read, or end of file is detected.
	
				Carriage return characters (ASCII code 13) are silently ignored.
	
				The bytes read are returned in the form of a string, excluding any terminating newline
				or null character.
	End Rem
	Method ReadLine:String()
		Local buffer:Byte[1024], sz:Int
		Repeat
			Local ch:Byte
			If Self.read(Varptr ch, 1) <> 1 Or ch = 0 Or ch = 10 Then Exit
			If ch = 13 Then Continue
			If sz = buffer.length Then buffer = buffer[.. sz*2]
			buffer[sz]	= ch
			sz:+1
		Forever
		Return String.fromBytes(buffer, sz)
	End Method

	Rem
		bbdoc:	Writes a line of text to the stream.
		returns:	True if line successfully written, else False.
		about:	A sequence of bytes is written to the stream (one for each character in @str)
				followed by the line terminating sequence "~r~n".
	End Rem
	Method WriteLine:Int(text:String)
		Local buffer:Byte Ptr	= text.toCString()
		Local ok:Int			= Self.write(buffer, text.length) = text.length And Self.write([13:Byte, 10:Byte], 2) = 2
		MemFree(buffer)
		Return ok
	End Method

	Rem
		bbdoc:	Reads characters from the stream.
		returns:	A String composed of @length bytes read from the stream.
		about:	A #TStreamReadException is thrown if not all bytes could be read.
	End Rem
	Method ReadString:String(length:Int)
		Assert length >= 0 Else "Illegal String length"
		Local buffer:Byte[length]
		Self.readBytes(buffer, length)
		Return String.fromBytes(buffer, length)
	End Method
	
	Rem
		bbdoc:	Writes characters to the stream.
		about:	A #TStreamWriteException is thrown if not all bytes could be written.
	End Rem
	Method WriteString(text:String)
		Local buffer:Byte Ptr	= text.toCString()
		Self.writeBytes(buffer, text.length)
		MemFree(buffer)
	End Method
	
	Method readObject:Object()
		Throw "Unable to read object"
	End Method
	
	Method writeObject(obj:Object)
		Throw "Unable to write object"
	End Method

End Type

Rem
	bbdoc:	Utility stream wrapper type
	about:	#TStreamWrapper 'wraps' an existing stream, redirecting all TIO method calls to the wrapped stream.

			This can be useful for writing stream 'filters' that modify the behaviour of existing streams.

			Note that the close method causes the underlying stream to be closed, which may not always
			be desirable. If necessary, you should override Close with a NOP version.
End Rem
Type TStreamWrapper Extends TStream

	Field _stream:TStream

	Rem
		bbdoc:	Sets the underlying stream.
		about:	Sets the stream to be 'wrapped'. All calls to TIO methods of this stream will be
				redirected to @stream.
	End Rem
	Method setStream(stream:TStream)
		_stream=stream
	End Method

	Method eof:Int()
		Return _stream.eof()
	End Method

	Method pos:Int()
		Return _stream.pos()
	End Method

	Method size:Int()
		Return _stream.size()
	End Method
	
	Method Seek:Int(position:Int)
		Return _stream.seek(position)
	End Method

	Method Flush()
		_stream.flush()
	End Method

	Method close()
		_stream.close()
	End Method

	Method read:Int(buffer:Byte Ptr, count:Int)
		Return _stream.read(buffer, count)
	End Method

	Method write:Int(buffer:Byte Ptr, count:Int)
		Return _stream.write(buffer, count)
	End Method
	
	Method ReadByte:Byte()
		Return _stream.ReadByte()
	End Method
	
	Method WriteByte(value:Byte)
		_stream.WriteByte(value)
	End Method
	
	Method ReadShort:Short()
		Return _stream.ReadShort()
	End Method
	
	Method WriteShort(value:Short)
		_stream.WriteShort(value)
	End Method
	
	Method ReadInt:Int()
		Return _stream.ReadInt()
	End Method
	
	Method WriteInt(value:Int)
		_stream.WriteInt(value:Int)
	End Method
	
	Method ReadFloat:Float()
		Return _stream.ReadFloat()
	End Method
	
	Method WriteFloat(value:Float)
		_stream.WriteFloat(value)
	End Method
	
	Method ReadDouble:Double()
		Return _stream.ReadDouble()
	End Method
	
	Method WriteDouble(value:Double)
		_stream.WriteDouble(value)
	End Method
	
	Method ReadLine:String()
		Return _stream.ReadLine()
	End Method
	
	Method WriteLine:Int(text:String)
		Return _stream.WriteLine(text)
	End Method
	
	Method ReadString:String(length:Int)
		Return _stream.ReadString(length)
	End Method
	
	Method WriteString(text:String)
		_stream.WriteString(text)
	End Method
	
	Method ReadObject:Object()
		Return _stream.readObject()
	End Method
	
	Method WriteObject(obj:Object)
		_stream.WriteObject(obj)
	End Method
	
End Type	

Type TStreamStream Extends TStreamWrapper

	Method close()
		Self.setStream(Null)
	End Method

	Function create:TStreamStream(stream:TStream)
		Local this:TStreamStream	= New TStreamStream
		this.setStream(stream)
		Return this
	End Function
	
End Type

Rem
	bbdoc: Standard C file stream type
End Rem
Type TCStream Extends TStream

	Const MODE_READ:Int	= 1
	Const MODE_WRITE:Int	= 2
	
	Field _pos:Int, _size:Int, _cstream:Int, _mode:Int

	Method pos:Int()
		Return Self._pos
	End Method

	Method size:Int()
		Return Self._size
	End Method

	Method seek:Int(position:Int)
		Assert Self._cstream Else "Attempt to seek closed stream."
		fseek_(Self._cstream, position, SEEK_SET_)
		Self._pos		= ftell_(Self._cstream)
		Return Self._pos
	End Method

	Method read:Int(buffer:Byte Ptr, count:Int)
		Assert Self._cstream Else "Attempt to read from closed stream."
		Assert Self._mode & MODE_READ Else "Attempt to read from write-only stream."
		count		= fread_(buffer, 1, count, Self._cstream)	
		Self._pos:+ count
		Return count
	End Method

	Method write:Int(buffer:Byte Ptr, count:Int)
		Assert Self._cstream Else "Attempt to write to closed stream."
		Assert Self._mode & MODE_WRITE Else "Attempt to write to read-only stream."
		count		= fwrite_(buffer, 1, count, Self._cstream)
		Self._pos:+ count
		If Self._pos > Self._size Then Self._size = Self._pos
		Return count
	End Method

	Method flush()
		If Self._cstream Then fflush_(Self._cstream)
	End Method

	Method close()
		If Not Self._cstream Return
		Self.flush()
		fclose_(Self._cstream)
		Self._pos		=0
		Self._size	=0
		Self._cstream	=0
	End Method
	
	Method Delete()
		close
	End Method

	Rem
		bbdoc: Creates a TCStream from a 'C' filename.
	End Rem
	Function OpenFile:TCStream(path:String, readable:Int, writeable:Int)
	
	' Set both mode variables
		Local mode:String, _mode:Int
		
		If readable And writeable
			mode		= "r+b"
			_mode	= MODE_READ|MODE_WRITE
		Else If writeable
			mode		= "wb"
			_mode	= MODE_WRITE
		Else
			mode		= "rb"
			_mode	= MODE_READ
		EndIf
		path			= path.Replace( "\","/" )
		
	' Init the cstream
		Local cstream:Int
		
		cstream		= fopen_(path, mode)
?Linux
		If (Not cstream) And (Not writeable)
			path		= CasedFileName(path)
			If path Then cstream = fopen_(path, mode)
		EndIf
?
		If cstream Return CreateWithCStream(cstream, _mode)
	End Function

	Rem
		bbdoc: Creates a TCStream from a 'C' stream handle.
	End Rem
	Function CreateWithCStream:TCStream(cstream:Int, mode:Int)
		Local stream:TCStream	= New TCStream
		stream._cstream		= cstream
		stream._pos			= ftell_(cstream)
		fseek_(cstream, 0, SEEK_END_)
		stream._size			= ftell_(cstream)
		fseek_(cstream, stream._pos, SEEK_SET_)
		stream._mode			= mode
		Return stream
	End Function

End Type

Private
	Global StreamFactories:TStreamFactory
Public

Rem
	bbdoc:	Base stream factory type
	about:	Stream factories are used by the #OpenStream, #ReadStream and #WriteStream functions
			to create streams based on a 'url object'.

			URL objects are usually strings, in which case the url is divided into 2 parts - a 
			protocol and a path. These are separated by a double colon string - "::".

			To create your own stream factories, you should extend the TStreamFactory type and
			implement the CreateStream method.

			To install your stream factory, simply create an instance of it using 'New'.
End Rem
Type TStreamFactory
	Field _succ:TStreamFactory
	
	Method New()
		Self._succ		= StreamFactories
		StreamFactories	= Self
	End Method

	Rem
		bbdoc:	Creates a stream based on an URL object.
		about:	Types which extends TStreamFactory must implement this method.
	
				@url contains the original url object as supplied to #OpenStream, #ReadStream or 
				#WriteStream.
	
				If @url is a string, @proto contains the url protocol - for example, the "incbin" part
				of "incbin::myfile".
	
				If @url is a string, @path contains the remainder of the url - for example, the "myfile"
				part of "incbin::myfile".
	
				If @url is not a string, both @proto and @path will be Null.
	End Rem
	Method createStream:TStream(url:Object, proto:String, path:String, readable:Int, writeable:Int) Abstract

End Type

Rem
	bbdoc:	Opens a stream for reading/writing.
	returns:	A stream object.
	about:	All streams created by #OpenStream, #ReadStream or #WriteStream should eventually be
			closed using #CloseStream.
End Rem
Function OpenStream:TStream(url:Object, readable:Int = True, writeable:Int = True)

	Local stream:TStream	= TStream(url)
	If stream Then
		Return TStreamStream.create(stream)
	EndIf

	Local str:String		= String(url), proto:String, path:String
	If str Then
		Local i:Int		= str.find("::", 0)
		If i = -1 Then Return TCStream.OpenFile(str, readable, writeable)
		proto			= str[ ..i].toLower()
		path				= str[i+2 ..]
	EndIf

	Local factory:TStreamFactory	= StreamFactories
	
	While factory
		Local stream:TStream		= factory.createStream(url, proto, path, readable, writeable)
		If stream Then Return stream
		factory					= factory._succ
	Wend
End Function

Rem
	bbdoc:	Opens a stream for reading.
	returns:	A stream object.
	about:	All streams created by #OpenStream, #ReadStream or #WriteStream should eventually
			be closed using #CloseStream.
			
			<p>@Note: Does exactly the same as #OpenStream(url, True, False).</p>
End Rem
Function ReadStream:TStream(url:Object)
	Return OpenStream(url, True, False)
End Function

Rem
	bbdoc:	Opens a stream for writing.
	returns:	A stream object.
	about:	All streams created by #OpenStream, #ReadStream or #WriteStream should eventually
			be closed using #CloseStream.
			
			<p>@Note: Does exactly the same as #OpenStream(url, False, True).</p>
End Rem
Function WriteStream:TStream(url:Object)
	Return OpenStream(url, False, True)
End Function

Rem
	bbdoc:	Gets a stream's end of file status.
	returns:	True if stream is at end of file.
End Rem
Function eof:Int(stream:TStream)
	Return stream.eof()
End Function

Rem
	bbdoc:	Gets the current position of a seekable stream.
	returns:	Current stream position, or -1 if stream is not seekable.
End Rem
Function StreamPos:Int(stream:TStream)
	Return stream.pos()
End Function

Rem
	bbdoc:	Gets the current size of a seekable stream.
	returns:	Current stream size in bytes, or -1 if stream is not seekable.
End Rem
Function StreamSize:Int(stream:TStream)
	Return stream.size()
End Function

Rem
	bbdoc:	Sets a seekable stream's position.
	returns:	New stream position, or -1 if stream is not seekable.
End Rem
Function SeekStream:Int(stream:TStream, position:Int)
	Return stream.seek(position)
End Function

Rem
	bbdoc:	Flushes a stream.
	about:	#FlushStream writes any outstanding buffered data to @stream.
End Rem
Function FlushStream(stream:TStream)
	stream.flush()
End Function

Rem
	bbdoc:	Closes a stream.
	about:	All streams should be closed when they are no longer required. 
			Closing a stream also flushes the stream before it closes.
End Rem
Function CloseStream(stream:TStream)
	stream.close()
End Function

Rem
	bbdoc:	Reads a Byte value from a stream.
	returns:	A Byte value.
	about:	#ReadByte reads a single Byte from @stream.
			A TStreamReadException is thrown if there is not enough data available.
End Rem
Function ReadByte:Byte(stream:TStream)
	Return stream.ReadByte()
End Function

Rem
	bbdoc:	Reads a Short value from a stream.
	returns:	A Short value.
	about:	#ReadShort reads 2 Bytes from @stream.
			A #TStreamReadException is thrown if there is not enough data available.
End Rem
Function ReadShort:Short(stream:TStream)
	Return stream.ReadShort()
End Function

Rem
	bbdoc:	Read an Int value from a stream.
	returns:	An Int value.
	about:	#ReadInt reads 4 Bytes from @stream.
			A #TStreamReadException is thrown if there is not enough data available.
End Rem
Function ReadInt:Int(stream:TStream)
	Return stream.ReadInt()
End Function

Rem
	bbdoc:	Reads a Long value from a stream.
	returns:	A Long value
	about:	#ReadLong reads 8 bytes from @stream.
			A #TStreamReadException is thrown if there is not enough data available.
End Rem
Function ReadLong:Long(stream:TStream)
	Return stream.ReadLong()
End Function

Rem
	bbdoc:	Reads a Float value from a stream.
	returns:	A Float value.
	about:	#ReadFloat reads 4 bytes from @stream.
			A #TStreamReadException is thrown if there is not enough data available.
End Rem
Function ReadFloat:Float(stream:TStream)
	Return stream.ReadFloat()
End Function

Rem
	bbdoc:	Read a Double value from a stream.
	returns:	A Double value.
	about:	#ReadDouble reads 8 Bytes from @stream.
			A #TStreamWriteException is thrown if there is not enough data available.
End Rem
Function ReadDouble:Double(stream:TStream)
	Return stream.ReadDouble()
End Function

Rem
	bbdoc:	Writes a Byte value to a stream.
	about:	#WriteByte writes a single Byte to @stream.
			A #TStreamWriteException is thrown if the Byte could not be written
End Rem
Function WriteByte(stream:TStream, value:Byte)
	stream.WriteByte(value)
End Function

Rem
	bbdoc:	Writes a Short value to a stream.
	about:	#WriteShort writes 2 bytes to @stream.
			A #TStreamWriteException is thrown if not all bytes could be written
End Rem
Function WriteShort(stream:TStream, value:Short)
	stream.WriteShort(value)
End Function

Rem
	bbdoc:	Writes an Int value to a stream.
	about:	#WriteInt writes 4 bytes to @stream.
			A #TStreamWriteException is thrown if not all bytes could be written
End Rem
Function WriteInt(stream:TStream, value:Int)
	stream.WriteInt(value)
End Function

Rem
	bbdoc:	Writes a Long value to a stream.
	about:	#WriteLong writes 8 bytes to @stream.
			A #TStreamWriteException is thrown if not all bytes could be written
End Rem
Function WriteLong(stream:TStream, value:Long)
	stream.WriteLong(value)
End Function

Rem
	bbdoc:	Writes a Float value to a stream.
	about:	#WriteFloat writes 4 bytes to @stream.
			A #TStreamWriteException is thrown if not all bytes could be written.
End Rem
Function WriteFloat(stream:TStream, value:Float)
	stream.WriteFloat(value)
End Function

Rem
	bbdoc:	Writes a Double value to a stream.
	about:	#WriteDouble writes 8 bytes to @stream.
			A #TStreamWriteException is thrown if not all bytes could be written.
End Rem
Function WriteDouble(stream:TStream, value:Double)
	stream.WriteDouble(value)
End Function

Rem
	bbdoc:	Reads a String from a stream.
	returns:	A String of length @length.
	about:	A #TStreamReadException is thrown if not all bytes could be read.
End Rem
Function ReadString:String(stream:TStream, length:Int)
	Return stream.ReadString(length)
End Function

Rem
	bbdoc:	Writes a String to a stream.
	about:	Each character in @text is written to @stream.

			A #TStreamWriteException is thrown if not all bytes could be written.
End Rem
Function WriteString(stream:TStream, text:String)
	stream.WriteString(text)
End Function

Rem
	bbdoc:	Reads a line of text from a stream.
	returns:	A line of text as a string.
	about:	Bytes are read from @stream until a newline character (ASCII code 10) or null
			character (ASCII code 0) is read, or end of file is detected.

			Carriage Return characters (ASCII code 13) are silently ignored.

			The bytes read are returned in the form of a string, excluding any terminating newline
			or null character.
End Rem
Function ReadLine:String(stream:TStream)
	Return stream.ReadLine()
End Function

Rem
	bbdoc:	Writes a line of text to a stream.
	returns:	True if line successfully written, else False.
	about:	A sequence of bytes is written to the stream (one for each character in @text)
			followed by the line terminating sequence "~r~n".
End Rem
Function WriteLine:Int(stream:TStream, text:String)
	Return stream.WriteLine(text)
End Function

Rem
	bbdoc:	Loads a String from a stream.
	returns:	A String.
	about:	The specified @url is opened for reading, and each byte in the resultant stream 
			(until eof of file is reached) is read into a string.

			A #TStreamReadException is thrown if the stream could not be read.
End Rem
Function LoadString:String(url:Object)
	Local buffer:Byte[]	= LoadByteArray(url)
	Return String.fromBytes(buffer, buffer.length )
End Function

Rem
	bbdoc:	Saves a String to a stream.
	about:	The specified @url is opened for writing, and each character of @text is written to the
			resultant stream.

			A #TStreamWriteException is thrown if not all bytes could be written.
End Rem
Function SaveString(text:String, url:Object)
	Local stream:TStream		= OpenStream(url, True, False)
	If Not stream Then Throw New TStreamWriteException
	
	Local textCString:Byte Ptr	= text.ToCString()
	stream.WriteBytes(textCString, text.length)	'Should be in a try block...or t is leaked!
	MemFree(textCString)
	stream.close()
End Function

Function loadObject:Object(url:Object)
	Local stream:TStream		= OpenStream(url, False, True)
	If Not stream Then Throw New TStreamReadException
	
	Local obj:Object			= stream.ReadObject()
	stream.close()
	Return obj
End Function

Function saveObject(obj:Object, url:Object)
	Local stream:TStream		= OpenStream(url, True, False)
	If Not stream Then Throw New TStreamWriteException
	
	stream.writeObject(obj)
	stream.close()
End Function

Rem
	bbdoc:	Loads a Byte array from a stream.
	returns: A Byte array.
	about:	The specified @url is opened for reading, and each byte in the resultant stream 
			(until eof of reached) is read into a byte array.
End Rem
Function LoadByteArray:Byte[](url:Object)
	Local stream:TStream		= OpenStream(url, False, True)
	If Not stream Then Throw New TStreamReadException
	
	Local data:Byte[1024], size:Int
	While Not stream.eof()
		If size = data.length Then data = data[.. size * 3 / 2]
		size:+ stream.read((Byte Ptr data) + size, data.length - size)
	Wend
	stream.close()
	Return data[.. size]
End Function

Rem
	bbdoc:	Saves a Byte array to a stream.
	about:	The specified @url is opened for writing, and each element of @byteArray is written to the
			resultant stream.

			A #TStreamWriteException is thrown if not all bytes could be written.
End Rem
Function SaveByteArray(byteArray:Byte[], url:Object)
	Local stream:TStream		= OpenStream(url, True, False)
	If Not stream Then Throw New TStreamWriteException
	
	stream.writeBytes(byteArray, byteArray.length)
	stream.close()
End Function

Rem
	bbdoc:	Copies stream contents to another stream.
	about:	#CopyStream copies bytes from @fromStream to @toStream Until @fromStream reaches end of file.

			A #TStreamWriteException is thrown if not all bytes could be written.
End Rem
Function CopyStream(fromStream:TStream, toStream:TStream, bufferSize:Int = 4096)
	Assert bufferSize > 0
	Local buffer:Byte[bufferSize]
	While Not fromStream.eof()
		toStream.writeBytes(buffer, fromStream.read(buffer, bufferSize))
	Wend
End Function

Rem
	bbdoc:	Copies bytes from one stream to another.
	about:	#CopyBytes copies @count bytes from @fromStream to @toStream.

			A #TStreamReadException is thrown if not all bytes could be read, and a
			#TStreamWriteException is thrown if not all bytes could be written.
End Rem
Function CopyBytes(fromStream:TStream, toStream:TStream, count:Int, bufferSize:Int = 4096)
	Assert count >= 0 And bufferSize > 0
	Local buffer:Byte[bufferSize]
	While count
		Local n:Int	= Min(count, bufferSize)
		fromStream.readBytes(buffer, n)
		toStream.writeBytes(buffer, n)
		count:- n
	Wend
End Function

Rem
	bbdoc:	Returns a case sensitive filename if it exists from a case insensitive file path.
End Rem
Function CasedFileName:String(path:String)
	Local dir:Int, sub:String, s:String, f:String, folder:String, p:Int
	Local mode:Int, size:Int, mtime:Int, ctime:Int
        
	If Not stat_(path, mode, size, mtime, ctime) Then
		mode:& S_IFMT_
		If mode = S_IFREG_ Or mode = S_IFDIR_ Then Return path
	EndIf
	
	folder			= "."
	For p = Len(path)-2 To 0 Step -1
		If path[p] = 47 Then Exit
	Next
	
	If p > 0 Then
		sub			= path[.. p]
		sub			= CasedFileName(sub)
		If Not sub Then Return Null
		path			= path[Len(sub)+1 ..]
		folder		= sub
	EndIf
	
	s				= path.toLower()
	dir				= opendir_(folder)
	If dir Then
		While True
			f		= readdir_(dir)
			If Not f Then Exit
			If s = f.toLower() Then
				If sub Then
					f = sub + "/" + f
				EndIf
				closedir_(dir)
				Return f
			EndIf
		Wend
		closedir_(dir)
	EndIf
End Function
Do you know if Mark takes these changes and put them into the official modules if they're good enough?
plash
(Posted 2010) [#2]
Well he's not going to use code that renames members (even if it's just the case of names). You should have stuck to the naming scheme already in-place, and the tabulation on the docs is horrible.
ProfJake
(Posted 2010) [#3]
The question was more general anyway.

But why do you think the tabulation is horrible? Tabulation in general or just in this case?
(I used the default MaxIDE in Mac OS X)

What do you suggest?
markcw
(Posted 2010) [#4]
Mark uses Strict all the time as obviously, he prefers it. Same for the tabs.

As a general rule if you're co-editing some source you shouldn't change the 'house style' ie. the formatting rules prefered by the original author. You should only fix mistakes and leave everything else alone, the "if it's not broke don't fix it" rule.

So as far as I can see, nothing you did there was an improvement. Not trying to be harsh but the only thing brl.stream actually needs is some good example code.
ProfJake
(Posted 2010) [#5]
But isn't SuperStrict supposed to be a little bit faster, as well as a lot cleaner?
markcw
(Posted 2010) [#6]
Nope, SuperStrict is definitely not "faster" than Strict.

Strict enforces variable scope declarations and SuperStrict enforces data type declarations. They are only compiler directives, so it's just down to personal preference.
plash
(Posted 2010) [#7]
Nope, SuperStrict is definitely not "faster" than Strict.
I'm not entirely sure on that part. I can see SuperStrict code being parsed faster, though.

If given the permission and means to effectively overhaul all the docs and cleanup code, I would switch the code to SuperStrict in a heartbeat.
Sometimes it isn't even clear (until you poke around at the code) whether a function or method returns a value or not due to Strict's implicit Int-typing (and especially so for type members, as they tend to get the short-end of documentation).