BlitzMax/Modules/Streams/Streams
流用於以順序方式讀取或寫入資料。
BlitzMax 支援許多型別的流，包括標準檔案流（用於讀取和寫入檔案）、銀行流（用於讀取和寫入銀行）以及 位元組序流（用於交換流資料的位元組順序）。
流通常使用 OpenStream、ReadStream 或 WriteStream 建立。但是，某些型別的流提供自己的建立流方法。例如，銀行流使用 CreateBankStream 命令建立。
OpenStream、ReadStream 和 WriteStream 都需要一個 url 引數，該引數用於“定位”流。url 通常是一個字串值。
如果 url 包含字串“::”，則表示正在指定流 協議。如果不是，則假定 url 是一個簡單的檔名。
外部模組可以向系統新增自己的流協議，使您能夠將流用於各種用途。例如，“incbin::” 協議允許您從一個二進位制檔案讀取資料，該檔案已使用 Incbin 命令嵌入到應用程式中。
其他協議包括“http::” 用於透過網路讀取和寫入資料，“littleendian::” 和 “bigendian::” 用於交換流的位元組順序。
要寫入流，請使用一個“Write”樣式命令，例如 WriteByte。
要從流中讀取，請使用一個“Read”樣式命令，例如 ReadByte。
某些型別的流（例如，檔案流和銀行流）支援 隨機訪問。這意味著您可以使用 SeekStream 命令修改流中下一個讀或寫的位置。您還可以使用 StreamPos 命令檢視您在這些流中的位置。
完成使用流後，您應始終使用 CloseStream 關閉它。如果未這樣做，可能會導致資源洩漏，或阻止流在將來成功開啟。
流丟擲的基本異常型別
流在發生讀取錯誤時丟擲的異常型別
當流操作無法讀取足夠位元組時，通常會丟擲 TStreamReadException。例如，如果流 ReadInt 方法無法讀取 4 個位元組，它將丟擲 TStreamReadException。
流在發生寫入錯誤時丟擲的異常型別
當流操作無法寫入足夠位元組時，通常會丟擲 TStreamWriteException。例如，如果流 WriteInt 方法無法寫入 4 個位元組，它將丟擲 TStreamWriteException。
基本輸入/輸出型別
要建立自己的流型別，您應擴充套件 TStream 並至少實現以下方法。
您還應確保您的流能夠處理對 Close 方法的多次呼叫。
- Eof
- Pos
- Size
- Seek
- Flush
- Close
- Read
- Write
方法 Eof()
描述: 獲取流檔案結束狀態
返回值: 檔案結束時為 True，否則為 False
資訊: 對於可定址流（如檔案流），Eof 通常在檔案位置等於檔案大小時返回 True。這意味著無法從流中讀取更多位元組。但是，您仍然可以寫入位元組，在這種情況下，檔案將“增長”。
對於通訊型別的流（如套接字流），如果流因某種原因而關閉（無論是在本地還是由遠端主機關閉），Eof 將返回 True。在這種情況下，無法再從流中讀取或寫入位元組。
方法 Pos()
描述: 獲取可定址流的位置
返回值: 流位置（以位元組偏移量表示），如果流不可定址，則返回 -1
方法 Size()
描述: 獲取可定址流的大小
返回值: 可定址流的大小（以位元組為單位），如果流不可定址，則返回 0
方法 Seek( pos )
描述: 定址到可定址流中的位置
返回值: 新的流位置，如果流不可定址，則返回 -1
方法 Flush()
描述: 重新整理流
資訊: 重新整理所有內部流緩衝區。
方法 Close()
描述: 關閉流
資訊: 重新整理所有內部流緩衝區後關閉流。
方法 Read( buf:Byte Ptr,count )
描述: 從流中讀取至少 1 個位元組
返回值: 成功讀取的位元組數
資訊: 如果由於 IO 緩衝而無法讀取至少一個位元組，此方法可能會“阻塞”。
如果此方法返回 0，則流已到達檔案末尾。
方法 Write( buf:Byte Ptr,count )
描述: 寫入至少 1 個位元組到流中
返回: 成功寫入的位元組數
資訊: 如果由於 IO 緩衝而無法寫入至少一個位元組，此方法可能會“阻塞”。
如果此方法返回 0，則流已到達檔案末尾。
TStream
[edit | edit source]資料流型別
TStream 擴充套件 TIO 以提供用於將各種型別的值讀入和寫出流的方法。
請注意，處理字串的方法 - ReadLine、WriteLine、ReadString 和 WriteString - 假設字串在流中以位元組表示。將來，將新增一個功能更強大的 TextStream 型別，它能夠以多種格式解碼文字流。
- ReadBytes
- WriteBytes
- SkipBytes
- ReadByte
- WriteByte
- ReadShort
- WriteShort
- ReadInt
- WriteInt
- ReadLong
- WriteLong
- ReadFloat
- WriteFloat
- ReadDouble
- WriteDouble
- ReadLine
- WriteLine
- ReadString
- WriteString
TStream: 方法
[edit | edit source]方法 ReadBytes( buf:Byte Ptr,count )
描述: 從流中讀取位元組
資訊: ReadBytes 從流中讀取 count 個位元組到 buf 指定的記憶體塊中。
如果 count 個位元組沒有成功讀取，則會丟擲 TStreamReadException。這通常是由於檔案結束造成的。
方法 WriteBytes( buf:Byte Ptr,count )
描述: 將位元組寫入流
資訊: WriteBytes 將 count 個位元組從 buf 指定的記憶體塊寫入流。
如果 count 個位元組沒有成功寫入，則會丟擲 TStreamWriteException。這通常是由於檔案結束造成的。
方法 SkipBytes( count )
描述: 跳過流中的位元組
資訊: SkipBytes 從流中讀取 count 個位元組並將其丟棄。
如果 count 個位元組沒有成功讀取，則會丟擲 TStreamReadException。這通常是由於檔案結束造成的。
方法 ReadByte()
描述: 從流中讀取一個位元組
返回: 讀取的值
資訊: 如果無法讀取值（可能是由於檔案結束），則會丟擲 TStreamReadException。
方法 WriteByte( n )
描述: 將一個位元組寫入流
資訊: 如果無法寫入值（可能是由於檔案結束），則會丟擲 TStreamWriteException。
方法 ReadShort()
描述: 從流中讀取一個短整型（兩個位元組）
返回: 讀取的值
資訊: 如果無法讀取值（可能是由於檔案結束），則會丟擲 TStreamReadException。
方法 WriteShort( n )
描述: 將一個短整型（兩個位元組）寫入流
資訊: 如果無法寫入值（可能是由於檔案結束），則會丟擲 TStreamWriteException。
方法 ReadInt()
描述: 從流中讀取一個整型（四個位元組）
返回: 讀取的值
資訊: 如果無法讀取值（可能是由於檔案結束），則會丟擲 TStreamReadException。
方法 WriteInt( n )
描述: 將一個整型（四個位元組）寫入流
資訊: 如果無法寫入值（可能是由於檔案結束），則會丟擲 TStreamWriteException。
方法 ReadLong:Long()
描述: 從流中讀取一個長整型（八個位元組）
返回: 讀取的值
資訊: 如果無法讀取值（可能是由於檔案結束），則會丟擲 TStreamReadException。
方法 WriteLong( n:Long )
描述: 將一個長整型（八個位元組）寫入流
資訊: 如果無法寫入值（可能是由於檔案結束），則會丟擲 TStreamWriteException。
方法 ReadFloat#()
描述: 從流中讀取一個浮點數（四個位元組）
返回: 讀取的值
資訊: 如果無法讀取值（可能是由於檔案結束），則會丟擲 TStreamReadException。
方法 WriteFloat( n# )
描述: 將一個浮點數（四個位元組）寫入流
資訊: 如果無法寫入值（可能是由於檔案結束），則會丟擲 TStreamWriteException。
方法 ReadDouble!()
描述: 從流中讀取一個雙精度浮點數（八個位元組）
返回: 讀取的值
資訊: 如果無法讀取值（可能是由於檔案結束），則會丟擲 TStreamReadException。
方法 WriteDouble( n! )
描述: 將一個雙精度浮點數（八個位元組）寫入流
資訊: 如果無法寫入值（可能是由於檔案結束），則會丟擲 TStreamWriteException。
方法 ReadLine$()
描述: 從流中讀取一行文字
資訊: 從流中讀取位元組，直到讀取換行符（ASCII 碼 10）或空字元（ASCII 碼 0），或者檢測到檔案結束。
回車符（ASCII 碼 13）會靜默忽略。
讀取的位元組以字串形式返回，不包括任何終止換行符或空字元。
方法 WriteLine( str$ )
描述: 將一行文字寫入流
返回: 如果成功寫入行，則為 True，否則為 False
資訊: 將位元組序列寫入流（str 中的每個字元一個），然後是行終止序列 "~r~n"。
方法 ReadString$( length )
描述: 從流中讀取字元
返回: 由從流中讀取的 length 個位元組組成的字串
資訊: 如果無法讀取所有位元組，則會丟擲 TStreamReadException。
方法 WriteString( str$ )
描述: 將字元寫入流
資訊: 如果無法寫入所有位元組，則會丟擲 TStreamWriteException。
TStreamWrapper
[edit | edit source]實用程式流包裝器型別
TStreamWrapper '包裝' 現有流，將所有 TIO 方法呼叫重定向到包裝的流。
這對於編寫修改現有流行為的流 '過濾器' 很有用。
請注意，Close 方法會導致底層流關閉，這並不總是可取的。如果需要，您應該使用 NOP 版本覆蓋 Close。
- SetStream
TStreamWrapper: 方法
[edit | edit source]方法 SetStream( stream:TStream )
描述: 設定底層流
資訊: 設定要 '包裝' 的流。對該流的所有 TIO 方法呼叫都將重定向到 stream。
TCStream
[edit | edit source]標準 C 檔案流型別
- OpenFile
- CreateWithCStream
TCStream: 函式
[edit | edit source]函式 OpenFile:TCStream( path$,readable,writeable )
描述: 從 'C' 檔名建立 TCStream
函式 CreateWithCStream:TCStream( cstream,mode )
描述: 從 'C' 流控制代碼建立 TCStream
TStreamFactory
[edit | edit source]基本流工廠型別
流工廠由 OpenStream、ReadStream 和 WriteStream 函式使用，用於根據 'url 物件' 建立流。
Url 物件通常是字串，在這種情況下，url 被分成兩個部分 - 協議和路徑。它們由雙冒號字串 "::" 分隔。
要建立自己的流工廠，您應該擴充套件 TStreamFactory 型別並實現 CreateStream 方法。
要安裝您的流工廠，只需使用 'New' 建立它的例項即可。
- CreateStream
TStreamFactory: 方法
[edit | edit source]方法 CreateStream:TStream( url:Object,proto$,path$,readable,writeable )
描述: 根據 url 物件建立流
資訊: 擴充套件 TStreamFactory 的型別必須實現此方法。
url 包含傳遞給 OpenStream、ReadStream 或 WriteStream 的原始 url 物件。
如果 url 是一個字串，則 proto 包含 url 協議 - 例如，"incbin::myfile" 中的 "incbin" 部分。
如果 url 是一個字串，則 path 包含 url 的其餘部分 - 例如，"incbin::myfile" 中的 "myfile" 部分。
如果 url 不是字串，則 proto 和 path 都將為 Null。
函式
[edit | edit source]OpenStream
[edit | edit source]函式 OpenStream:TStream( url:Object,readable=True,writeable=True )
描述: 開啟一個用於讀寫操作的流
返回: 流物件
資訊: 所有由 OpenStream、ReadStream 或 WriteStream 建立的流最終都應該使用 CloseStream 關閉。
Function ReadStream:TStream( url:Object )
描述: 開啟一個流用於讀取
返回: 流物件
資訊: 所有由 OpenStream、ReadStream 或 WriteStream 建立的流最終都應該使用 CloseStream 關閉。
示例:
' readstream.bmx
' opens a read stream to the blitzbasic.com website and
' dumps the homepage to the console using readline and print
in=ReadStream("http::blitzbasic.com")
If Not in RuntimeError "Failed to open a ReadStream to file http::www.blitzbasic.com"
While Not Eof(in)
Print ReadLine(in)
Wend
CloseStream in
Function WriteStream:TStream( url:Object )
描述: 開啟一個流用於寫入
返回: 流物件
資訊: 所有由 OpenStream、ReadStream 或 WriteStream 建立的流最終都應該使用 CloseStream 關閉。
示例:
' writestream.bmx
' opens a write stream to the file mygame.ini and
' outputs a simple text file using WriteLine
out=WriteStream("mygame.ini")
if not out RuntimeError "Failed to open a WriteStream to file mygame.ini"
WriteLine out,"[display]"
WriteLine out,"width=800"
WriteLine out,"height=600"
WriteLine out,"depth=32"
WriteLine out,""
WriteLine out,"[highscores]"
WriteLine out,"AXE=1000"
WriteLine out,"HAL=950"
WriteLine out,"MAK=920"
CloseStream out
print "File mygame.ini created, bytes="+FileSize("mygame.ini")
Function Eof( stream:TStream )
描述: 獲取流檔案結束狀態
返回值: 如果流處於檔案末尾則為 True
Function StreamPos( stream:TStream )
描述: 獲取可定位流的當前位置
返回值: 當前流位置，如果流不可定位則為 -1
Function StreamSize( stream:TStream )
描述: 獲取可定位流的當前大小
返回值: 當前流大小（以位元組為單位），如果流不可定位則為 -1
Function SeekStream( stream:TStream,pos )
描述: 設定可定位流的流位置
返回值: 新的流位置，如果流不可定位則為 -1
Function FlushStream( stream:TStream )
描述: 重新整理流
資訊: FlushStream 將任何未完成的緩衝資料寫入 stream。
Function CloseStream( stream:TStream )
描述: 關閉流
資訊: 所有流在不再需要時都應關閉。關閉流也會在關閉之前重新整理流。
Function ReadByte( stream:TStream )
描述: 從流中讀取一個位元組
返回值: 一個位元組值
資訊: ReadByte 從 stream 中讀取一個位元組。如果可用資料不足，則丟擲 TStreamReadException。
Function ReadShort( stream:TStream )
描述: 從流中讀取一個短整型
返回值: 一個短整型值
資訊: ReadShort 從 stream 中讀取 2 個位元組。如果可用資料不足，則丟擲 TStreamReadException。
Function ReadInt( stream:TStream )
描述: 從流中讀取一個整型
返回值: 一個整型值
資訊: ReadInt 從 stream 中讀取 4 個位元組。如果可用資料不足，則丟擲 TStreamReadException。
Function ReadLong:Long( stream:TStream )
描述: 從流中讀取一個長整型
返回值: 一個長整型值
資訊: ReadLong 從 stream 中讀取 8 個位元組。如果可用資料不足，則丟擲 TStreamReadException。
Function ReadFloat#( stream:TStream )
描述: 從流中讀取一個單精度浮點數
返回值: 一個單精度浮點數
資訊: ReadFloat 從 stream 中讀取 4 個位元組。如果可用資料不足，則丟擲 TStreamReadException。
Function ReadDouble!( stream:TStream )
描述: 從流中讀取一個雙精度浮點數
返回值: 一個雙精度浮點數
資訊: ReadDouble 從 stream 中讀取 8 個位元組。如果可用資料不足，則丟擲 TStreamWriteException。
Function WriteByte( stream:TStream,n )
描述: 向流中寫入一個位元組
資訊: WriteByte 向 stream 中寫入一個位元組。如果位元組無法寫入，則丟擲 TStreamWriteException
Function WriteShort( stream:TStream,n )
描述: 向流中寫入一個短整型
資訊: WriteShort 向 stream 中寫入 2 個位元組。如果無法寫入所有位元組，則丟擲 TStreamWriteException
Function WriteInt( stream:TStream,n )
描述: 向流中寫入一個整型
資訊: WriteInt 向 stream 中寫入 4 個位元組。如果無法寫入所有位元組，則丟擲 TStreamWriteException
Function WriteLong( stream:TStream,n:Long )
描述: 向流中寫入一個長整型
資訊: WriteLong 向 stream 中寫入 8 個位元組。如果無法寫入所有位元組，則丟擲 TStreamWriteException
Function WriteFloat( stream:TStream,n# )
描述: 向流中寫入一個單精度浮點數
資訊: WriteFloat 向 stream 中寫入 4 個位元組。如果無法寫入所有位元組，則丟擲 TStreamWriteException
Function WriteDouble( stream:TStream,n! )
描述: 將一個 Double 寫入流
資訊: WriteDouble 將 8 個位元組寫入 stream。如果無法寫入所有位元組，則會丟擲 TStreamWriteException
Function ReadString$( stream:TStream,length )
描述: 從流中讀取一個字串
返回值: 長度為 length 的字串
資訊: 如果無法讀取所有位元組，則會丟擲 TStreamReadException。
Function WriteString( stream:TStream,str$ )
描述: 將一個字串寫入流
資訊: str 中的每個字元都將寫入 stream。
如果無法寫入所有位元組，則會丟擲 TStreamWriteException。
Function ReadLine$( stream:TStream )
描述: 從流中讀取一行文字
返回值: 一個字串
資訊: 從 stream 中讀取位元組，直到遇到換行符（ASCII 碼 10）或空字元（ASCII 碼 0），或者檢測到檔案結尾。
回車符（ASCII 碼 13）將被靜默忽略。
讀取的位元組以字串形式返回，不包括任何終止換行符或空字元。
Function WriteLine( stream:TStream,str$ )
描述: 將一行文字寫入流
返回: 如果成功寫入行，則為 True，否則為 False
資訊: 將位元組序列寫入流（str 中的每個字元一個），然後是行終止序列 "~r~n"。
Function LoadString$( url:Object )
描述: 從流中載入一個字串
返回值: 一個字串
資訊: 開啟指定的 url 以供讀取，並將結果流中的每個位元組（直到檔案結束）讀入一個字串。
如果無法讀取流，則會丟擲 TStreamReadException。
Function SaveString( str$,url:Object )
描述: 將一個字串儲存到流
資訊: 開啟指定的 url 以供寫入，並將 str 的每個字元寫入結果流。
如果無法寫入所有位元組，則會丟擲 TStreamWriteException。
Function LoadByteArray:Byte[]( url:Object )
描述: 從流中載入一個位元組陣列
返回值: 一個位元組陣列
資訊: 開啟指定的 url 以供讀取，並將結果流中的每個位元組（直到檔案結束）讀入一個位元組陣列。
Function SaveByteArray( byteArray:Byte[],url:Object )
描述: 將一個位元組陣列儲存到流
資訊: 開啟指定的 url 以供寫入，並將 byteArray 的每個元素寫入結果流。
如果無法寫入所有位元組，則會丟擲 TStreamWriteException。
Function CopyStream( fromStream:TStream,toStream:TStream,bufSize=4096 )
描述: 將流內容複製到另一個流
資訊: CopyStream 將位元組從 fromStream 複製到 toStream，直到 fromStream 達到檔案結尾。
如果無法寫入所有位元組，則會丟擲 TStreamWriteException。
Function CopyBytes( fromStream:TStream,toStream:TStream,count,bufSize=4096 )
描述: 將位元組從一個流複製到另一個流
資訊: CopyBytes 將 count 個位元組從 fromStream 複製到 toStream。
如果無法讀取所有位元組，則會丟擲 TStreamReadException，如果無法寫入所有位元組，則會丟擲 TStreamWriteException。
Function CasedFileName$(path$)
描述: 如果存在，則從不區分大小寫的檔案路徑返回區分大小寫的檔名。