高階緩衝區資料解析器，支援多型態資料讀取、標記、插入與迭代。更多...

#include <Scanner.h>

類別ufm::util::Scanner的繼承圖:

公開方法(Public Methods)
	Scanner (ufm::lang::Memory buffer) noexcept
	使用現有緩衝區構造 Scanner 物件。

	Scanner (int bufferSize=128)
	使用指定緩衝區大小構造 Scanner 物件。

	Scanner (Scanner &&other) noexcept
	移動建構子。

virtual	~Scanner (void) override
	解構子，釋放資源。

virtual int	remaining (void) const override
	取得緩衝區剩餘空閒字節數。

virtual int	putByte (const char data) override
	輸入單一字節至緩衝區

virtual int	put (ufm::lang::Readable &readable) override
	從 Readable 物件附加資料至緩衝區

virtual int	put (const void *pointer, int length) override
	從記憶體指標附加資料至緩衝區

virtual void	mark (void) override
	設定流標記位置。

virtual void	reset (void) override
	重置流位置至上次標記點。

void	compact (void)
	將未讀取資料移至緩衝區開頭，釋放已消耗空間。

void	clear (void)
	清除 Scanner 緩衝區並重置狀態。

int	setCursor (int insert)
	設定下次寫入資料的插入位置。

int	getCursor (void)
	取得目前的插入位置。

bool	cursorRight (void)
	將游標向右移動一個位置。

bool	cursorLeft (void)
	將游標向左移動一個位置。

bool	backspace (void)
	回退指定字元數。

bool	deleteChar (void)
	刪除當前游標位置的字元。

公開方法(Public Methods) 繼承自 ufm::util::LineReader
	LineReader (ufm::lang::Memory buffer) noexcept
	使用現有緩衝區構造 LineReader 物件

	LineReader (int bufferSize=128) noexcept
	使用指定緩衝區大小構造 LineReader 物件

	LineReader (LineReader &&other) noexcept
	移動建構子

virtual	~LineReader (void) override
	解構子，釋放資源

virtual void	forEach (ufm::func::Consumer< const char & > &action) override
	遍歷集合中所有元素，對每個元素執行指定操作。若所有元素處理完畢或操作中發生異常則停止。

virtual const char *	elementAt (int index) const override
	獲取集合中指定索引處的元素。

virtual int	nextIndex (int index) const override
	返回當前索引的下一個有效索引。

virtual ufm::util::Iterator< const char >	begin (void) override
	取得目前插入位置。

virtual ufm::util::Iterator< const char >	end (void) override
	取得 Scanner 結尾迭代器。

int	nextTokenLength (int limit=0)
	取得下一個 token 的長度。

bool	hasNextToken (int limit=0)
	判斷緩衝區是否有下一個 token。

bool	hasNext (void) const
	判斷緩衝區是否有下一個字元。

bool	hasNextChar (char ch)
	判斷緩衝區是否有指定字元。

bool	hasNextBoolean (void)
	判斷緩衝區是否有可解析的布林值（true/false）。

bool	hasNextInteger (int limit=0)
	判斷緩衝區是否有可解析的整數。

bool	hasNextFloat (int limit=0)
	判斷緩衝區是否有可解析的浮點數。

int	hasNextLine (int limit=0)
	判斷緩衝區是否有完整的一行（遇到換行符）。

bool	nextBoolean (bool &result)
	讀取下一個布林值（true/false），並移除。

int	nextLine (ufm::lang::Appendable &appendable, int limit=0)
	讀取下一行字串，並寫入指定 appendable。

int	nextLine (void *pointer, int length)
	讀取下一行字串，寫入指定記憶體區。

bool	nextInteger (int &result, int limit=0)
	讀取下一個整數，並移除。

bool	nextFloat (float &result, int limit=0)
	讀取下一個浮點數，並移除。

bool	nextChar (char &result)
	讀取下一個字元，並移除。

int	next (ufm::lang::Appendable &appendable, int limit=0)
	讀取下一個字串，並寫入指定 appendable。

int	skip (char pattern, int limit=0)
	跳過直到遇到指定字元或達到限制。

int	skipAll (void)
	跳過指定長度的字元。

int	skipNextToken (int limit=0)
	跳過當前字串直到分隔符。

int	skipNextLine (int limit=0)
	跳過當前行直到下一行（遇到換行符）。

int	avariable (void) const
	取得緩衝區可讀取的位元組數。

公開方法(Public Methods) 繼承自 ufm::lang::Object
void *	operator new (size_t n)
	使用運算子 new 分配記憶體

void *	operator new (size_t n, void *p)
	在指定記憶體上調用運算子 new

virtual ufm::lang::Object &	getObject (void) override
	取得對應的 Object 物件

void	delay (int milliseconds) const
	延遲指定的毫秒數進行執行緒等待

bool	equals (Object *object) const
	判斷與另一物件是否為相同參照（指標型態比較）

bool	equals (Object &object) const
	判斷與另一物件是否為相同參照（參照型態比較）

void	wait (void) const
	使當前線程等待直到被通知

bool	wait (int timeout) const
	等待通知或超時

bool	yield (void) const
	讓執行緒讓渡控制權給同優先權的下一個執行緒

int	lock (void) const
	核心鎖定，鎖定期間禁止線程切換

int	unlock (void) const
	核心解鎖

ufm::sys::Thread *	currentThread (void) const
	取得當前執行緒指標

virtual int	hashcode (void) const
	返回對象的哈希碼值。支持這種方法是為了散列表，如HashMap提供的那樣。

公開方法(Public Methods) 繼承自 ufm::lang::Interface
virtual	~Interface (void)=default
	虛擬析構函式

公開方法(Public Methods) 繼承自 ufm::lang::NonCopyable
	NonCopyable (void)=default
	建構一個新的 NonCopyable 物件

	NonCopyable (const NonCopyable &other)=delete
	禁止複製建構子

NonCopyable &	operator= (const NonCopyable &other)=delete
	禁止複製賦值運算子

公開方法(Public Methods) 繼承自 ufm::lang::Appendable
int	put (ufm::lang::Readable &&readable)
	從右值 Readable 附加資料

bool	isFull (void) const
	檢查緩衝區是否已滿

保護屬性
int	vInsert
	下次插入資料的緩衝區索引位置

int	vMark
	標記位置，用於重置操作

保護屬性繼承自 ufm::util::LineReader
ufm::lang::Memory	vBuffer

int	vHead
	當前讀取位置索引

int	vTail
	緩衝區尾部索引

詳細描述

高階緩衝區資料解析器，支援多型態資料讀取、標記、插入與迭代。

Scanner 提供從緩衝區讀取、解析、插入、標記、回溯等多種功能，可處理字元、字串、數值、布林等型態，並支援資料流的標記與重置。其設計適合用於 UART、檔案、網路等資料流的高效解析，並可搭配 Iterator 進行區段遍歷。

主要特色：

支援多型態資料讀取（字元、字串、整數、浮點、布林）
可插入資料至緩衝區
提供標記與重置功能，方便回溯資料流
內建迭代器，可遍歷緩衝區有效資料
可自訂緩衝區大小或使用外部緩衝區

典型用途：

逐行/逐字解析資料流
協助協定解析、指令分割、資料回溯
快速判斷、插入、回溯、遍歷緩衝區資料

作者: ZxyKira

版權聲明: (c) 2020 ZxyKira @license MIT

自: 1.0.0

建構子與解構子說明文件

◆ Scanner() [1/3]

ufm::util::Scanner::Scanner ( ufm::lang::Memory buffer )

noexcept

使用現有緩衝區構造 Scanner 物件。

此建構子會使用提供的記憶體緩衝區來初始化 Scanner， Scanner 將直接操作此緩衝區進行資料讀取和解析。

參數

buffer 指定要讀取的緩衝區記憶體物件

◆ Scanner() [2/3]

ufm::util::Scanner::Scanner ( int bufferSize = 128 )

inline

使用指定緩衝區大小構造 Scanner 物件。

此建構子會自動分配指定大小的記憶體緩衝區，並初始化 Scanner 用於資料解析操作。

參數

bufferSize 緩衝區大小，預設為 128 位元組

◆ Scanner() [3/3]

ufm::util::Scanner::Scanner ( Scanner && other )

inlinenoexcept

移動建構子。

此建構子會從另一個 Scanner 物件移動資源，並將來源物件的狀態（包括插入位置和標記位置）轉移到新物件。

參數

other 來源 Scanner 物件（右值參考）

◆ ~Scanner()

virtual ufm::util::Scanner::~Scanner ( void )

overridevirtual

解構子，釋放資源。

清理 Scanner 物件並釋放相關資源，確保記憶體緩衝區得到適當的清理。

函式成員說明文件

◆ backspace()

bool ufm::util::Scanner::backspace ( void )

回退指定字元數。

此方法會將讀取指標（head）往回移動指定字元數，等同於"未讀取"這些字元，使它們可以再次被讀取。常用於解析過程中需要退回某些已讀取字元的場景。

參數

count 要回退的字元數，必須為正數且不超過已讀取的字元數

傳回值: int 回退後讀取指標的新位置

◆ clear()

void ufm::util::Scanner::clear ( void )

清除 Scanner 緩衝區並重置狀態。

此方法會清空內部緩衝區，重置 head、tail 指標，使 Scanner 可重新接收新資料。

◆ compact()

void ufm::util::Scanner::compact ( void )

將未讀取資料移至緩衝區開頭，釋放已消耗空間。

此方法會將尚未讀取的有效資料搬移到緩衝區最前面（索引0），以回收已讀取或消耗的空間，並更新指標（如 head、tail）。

範例： [x x x a b c - - -] (head=3, tail=6) ↓ compact() [a b c - - - - - -] (head=0, tail=3)

通常在部分資料已消耗後呼叫，以最大化可用空間。

◆ cursorLeft()

bool ufm::util::Scanner::cursorLeft ( void )

inline

將游標向左移動一個位置。

此方法會嘗試將插入位置向左移動一個字元位置，如果移動成功則返回 true，否則返回 false。通常用於編輯器或文字處理功能中的游標控制。

傳回值: true 游標成功向左移動; false 游標無法向左移動（可能已達緩衝區邊界）

◆ cursorRight()

bool ufm::util::Scanner::cursorRight ( void )

inline

將游標向右移動一個位置。

此方法會嘗試將插入位置向右移動一個字元位置，如果移動成功則返回 true，否則返回 false。通常用於編輯器或文字處理功能中的游標控制。

傳回值: true 游標成功向右移動; false 游標無法向右移動（可能已達緩衝區邊界）

◆ deleteChar()

bool ufm::util::Scanner::deleteChar ( void )

刪除當前游標位置的字元。

此方法會刪除游標所在位置的字元，並將後續字元向左移動，以填補被刪除的位置。若游標已在緩衝區末尾則無操作。

傳回值: true 若成功刪除字元並更新緩衝區; false 若無法刪除（如游標已在末尾）

◆ getCursor()

int ufm::util::Scanner::getCursor ( void )

inline

取得目前的插入位置。

此方法返回下次寫入資料的索引位置，可用於確認目前緩衝區的寫入狀態。

傳回值: int 當前插入位置

◆ mark()

virtual void ufm::util::Scanner::mark ( void )

overridevirtual

設定流標記位置。

此方法用於設定當前讀取位置的標記點，之後可以使用 reset() 方法重置到此標記位置。標記功能對於需要回溯讀取的解析場景非常有用，例如在嘗試解析失敗後回到原始位置重新嘗試。

註: 標記位置必須在有效的緩衝區範圍內

實作 ufm::lang::Markable.

◆ put() [1/2]

virtual int ufm::util::Scanner::put	(	const void *	pointer,
		int	length )

overridevirtual

從記憶體指標附加資料至緩衝區

根據指定長度，將 pointer 指向的資料寫入緩衝區

參數

pointer	資料來源位址
length	要寫入的字節數

傳回值: int 實際寫入的字節數

實作 ufm::lang::Appendable.

◆ put() [2/2]

virtual int ufm::util::Scanner::put ( ufm::lang::Readable & readable )

overridevirtual

從 Readable 物件附加資料至緩衝區

迴圈從 readable 讀取並寫入緩衝區，直到耗盡或空間不足

參數

readable 可讀資料來源

傳回值: int 實際寫入的字節數

實作 ufm::lang::Appendable.

◆ putByte()

virtual int ufm::util::Scanner::putByte ( const char data )

overridevirtual

輸入單一字節至緩衝區

參數

data 要寫入的字節

傳回值: int 寫入後緩衝區剩餘空間（字節數）

實作 ufm::lang::Appendable.

◆ remaining()

virtual int ufm::util::Scanner::remaining ( void ) const

overridevirtual

取得緩衝區剩餘空閒字節數。

傳回值: int 剩餘的空閒字節數。

實作 ufm::lang::Appendable.

◆ reset()

virtual void ufm::util::Scanner::reset ( void )

overridevirtual

重置流位置至上次標記點。

此方法會將讀取位置重置到上次呼叫 mark() 方法設定的標記點，使得可以重新讀取從該位置開始的資料。這對於解析錯誤後的回溯處理非常有用。

註: 必須先呼叫 mark() 方法設定標記點，且標記點必須仍在有效範圍內

參閱: mark()

實作 ufm::lang::Markable.

◆ setCursor()

int ufm::util::Scanner::setCursor ( int insert )

設定下次寫入資料的插入位置。

此方法僅設定緩衝區下次插入資料的索引位置，不會實際寫入資料，僅做準備。

參數

insert 下次插入資料的索引位置

傳回值: int 先前的插入位置

此類別(class) 文件是由下列檔案中產生:

Scanner.h

公開方法(Public Methods)

保護屬性

詳細描述

建構子與解構子說明文件

◆ Scanner() [1/3]

◆ Scanner() [2/3]

◆ Scanner() [3/3]

◆ ~Scanner()

函式成員說明文件

◆ backspace()

◆ clear()

◆ compact()

◆ cursorLeft()

◆ cursorRight()

◆ deleteChar()

◆ getCursor()

◆ mark()

◆ put() [1/2]

◆ put() [2/2]

◆ putByte()

◆ remaining()

◆ reset()

◆ setCursor()