Datové struktury a makra


CTEXTREF	EQU	80000000h	; flag - constant text (hardcoded)
CTEXTREFHIGH	EQU	80h		; constant text, high byte
TEXTBIGPOS	EQU	7FFF0000h	; big positive position (with reserve)

; ------------- Text string data

struc		TEXTDATA

TEXT_Ref:	resd	1		; 0: reference counter (read-only < 0)
TEXT_Length:	resd	1		; 4: text length (in bytes)
TEXT_Text:				; 8: text (in UTF-8)

endstruc				; size: 8 + text length

Základem textových řetězců je struktura TEXTDATA obsahující jak samostný text, tak i evidenční informace. Jsou to data textového řetězce. Proměnná obsahující ukazatel na data textového řetězce je vlastníkem textu.

Položka TEXT_Ref je referenční čítač představující počet vlastníků dat textového řetězce. Každý nový vlastník zvýší referenční čítač, odebrání vlastníka čítač sníží. Pokud čítač dosáhne nuly, nejsou data textového řetězce vlastněna již žádným vlastníkem a mohou být zrušena.

Položka TEXT_Length je délka textového řetězce v bajtech. TEXT_Text je začátek textu v datech textového řetězce. Text je v kódu UTF.8.

Konstanta CTEXTREF je hodnota referenčního čítače označující konstantní textová data. Tento text je zpravidla uložen v oblasti jen pro čtení a není programem modifikován. Pokud má být změněn obsah textové proměnné s konstantními textovými daty, je nejdříve provedena duplikace dat. Konstanta CTEXTREFHIGH je nejvyšší bajt konstanty CTEXTREF a používá se k rychlému testu, zda se jedná o konstantní textová data.

TEXTBIGPOS je pomocný ukazatel pozice v textu dostatečně velký na to, aby byl vždy větší než možná délka textu.


; ------------- Text string

struc		TEXT
		resd	1		; 0: pointer to TEXTDATA structure
endstruc				; size: 4 bytes

Struktura TEXT je objekt textu. Obsahuje ukazatel na data textového řetězce. Připojením dat textového řetězce k objektu textu se zvýší referenční čítač vlastníků dat textového řetězce, odpojením se referenční čítač sníží.


; ------------- Macro - text string variable (%1 = pointer to TEXTDATA)

%macro		TEXTSTR 1
		dd	%1		; pointer to TEXTDATA
%endmacro

Makro TEXTSTR vytvoří textovou proměnnou. Parametrem makra je ukazatel na textová data TEXTDATA.


; ------------- Multi-Language text string (with language identifier)

struc		LANGTEXT
		resb	TEXT_size	; 0: text string
LANGTEXT_Lang:	resb	LANG_size	; 4: language identifier LANG
LANGTEXT_Num:	resw	1		; 6: number of languages in
					;    multi-language text array, it is
					;    valid only in first text entry,
					;    it may not be 0 in first entry
endstruc				; size: 8 bytes

; ------------- Macro - multi-language text string variable
; %1 = pointer to TEXTDATA, %2 = language main identifier, %3 sub-language
; identifier, %4 = number of languages in array (only first entry is valid)

%macro		LANGTEXTSTR 4
		dd	%1		; pointer to TEXTDATA
		LANGINI	%2,%3		; language identifier LANG
		dw	%4		; number of languages in array
%endmacro

; Sample of multi-language text:
;
; SampleName:	LANGTEXTSTR SampleTextEN,LANG_ENGLISH,SUBLANG_ENGLISH_US,3
; 		LANGTEXTSTR SampleTextCZ,LANG_CZECH,  SUBLANG_DEFAULT,   0
; 		LANGTEXTSTR SampleTextGE,LANG_GERMAN, SUBLANG_GERMAN,    0
;
; SampleTextEN:	CTEXTDATA 'Text sample'
; SampleTextCZ:	CTEXTDATA 'Priklad textu'
; SampleTextGE:	CTEXTDATA 'Text Beispiel'

Struktura LANGTEXT je jazykový text, který kromě textové proměnné obsahuje též identifikátor jazyku, ve kterém je text psaný. Identifikátor jazyku je obsažen v položce LANGTEXT_Lang.

Struktura je používána obvykle jako pole jazykových textů v různých jazycích. Položka LANGTEXT_Num prvního jazykového textu obsahuje celkový počet prvků v poli. Při zobrazení textu uživateli je z pole vybrán text v tom jazyku, který je uživateli nejblíž. Makro LANGTEXTSTR vytvoří položku vícejazyčného textu.


; ------------- Macro - constant text string data (%1 = text in '')

%macro		CTEXTDATA 1+
		dd	CTEXTREF	; reference counter (= constant text)
		dd	%%L3-%%L2	; text length (in bytes)
%%L2:		db	%1		; text (in UTF-8)
%%L3:
		align	4, db 0
%endmacro

Makro CTEXTDATA vytvoří v programu data konstantního textového řetězce. Parametrem makra je text v jednoduchých uvozovkách (v kódu UTF-8). Referenční čítač je nastaven na hodnotu CTEXTREF a tím je zabráněno modifikaci textu.


; ------------- Macro - constant text string with data (%1 = text in '')

%macro		CTEXT 1+
		TEXTSTR %%L1		; text string variable
%%L1:		CTEXTDATA %1		; text string
		align	4, db 0
%endmacro

Makro CTEXT vytvoří v programu konstantní text. Parametrem makra je text v jednoduchých uvozovkách (v kódu UTF-8). Textová data jsou v konstantním tvaru. Pokud má dojít k modifikaci textu, původní textová data se odpojí, provede se jejich kopie do datového bufferu a teprve až tato kopie je modifikována.


; ------------- Macro - empty text string

%macro		EMPTYTEXT 0
		TEXTSTR EmptyTextData
%endmacro

Makro EMPTYTEXT vytvoří v programu prázdný text, tedy textovou proměnnou ukazující na prázdná textová data EmptyTextData.


; ------------- Macro - allocate text data buffer
; INPUT:	EAX = required size of text data buffer
; OUTPUT:	CY = memory error
;		EAX = address of memory block

%macro		TEXTBUFALLOC 0
		call	SysMemAlloc		; allocate system memory
%endmacro

Makro TEXTBUFALLOC slouží k alokaci datového bufferu pro funkce textových řetězců. Na vstupu funkce obsahuje registr EAX požadovanou velikost datového bufferu. Při nedostatku paměti je funkcí navrácen příznak CY, jinak je v registru EAX navrácen ukazatel na nový datový blok.


; ------------- Macro - free text data buffer
; INPUT:	EAX = address of text data buffer

%macro		TEXTBUFFREE 0
		call	SysMemFree		; free system memory
%endmacro

Makro TEXTBUFFREE slouží k uvolění datového bufferu ve funkcích textových řetězců. Na vstupu funkce obsahuje registr EAX ukazatel na datový blok.


; ------------- Macro - resize text data buffer
; INPUT:	EAX = required new size of text data buffer
;		EDX = old address of text data buffer
; OUTPUT:	CY = memory error (buffer not changed)
;		EDX = new address of text data buffer

%macro		TEXTBUFRESIZE 0
		call	SysMemRealloc		; reallocate system memory
%endmacro

Makro TEXTBUFRESIZE slouží ke změně velikosti datového bufferu ve funkcích textových řetězců. Na vstupu funkce obsahuje registr EAX požadovanou novou velikost datového bloku. Registr EDX obsahuje ukazatel na datový blok. Při chybě paměti je navrácen příznak CY a datový blok není změněn. Při úspěšné operaci obsahuje registr EDX buď nezměněnou adresu datového bloku nebo ukazatel na nový datový blok s novou velikostí.