BinToTextBuf - Zformátování čísla BIN do bufferu

Funkce BinToTextBuf zkonvertuje 64-bitové celé číslo bez znaménka na text ve formátovaném binárním (dvojkovém) tvaru.


; -----------------------------------------------------------------------------
;                    Convert BIN number into text buffer
; -----------------------------------------------------------------------------
; INPUT:	EDX:EAX = number
;		EBX = formatting parameters FORMPAR
;		ECX = pointer to nationality descriptor NATIONAL
;		ESI = remaining free space in buffer
;		EDI = destination buffer
; OUTPUT:	ESI = next remaining free space in buffer
;		EDI = next destination buffer
; NOTES:	On AMD 1.6 GHz it takes approx. "8*digits+45" nanoseconds.
; -----------------------------------------------------------------------------
; Local variables (ebp+N are read-only variables):
%define		BINNumL    ebp+16	; (4) number LOW
%define		BINNat     ebp+8	; (4) pointer to nationality NATIONAL
%define		BINNumH    ebp+4	; (4) number HIGH
%define		BINForm    ebp-4	; (4) formatting parameters FORMPAR
%define		BINLen     ebp-8	; (4) text length

%define		BINStack  8		; stack size

Na vstupu funkce obsahuje registrový pár EDX:EAX číslo bez znaménka ke konverzi, registr EBX obsahuje formátovací parametry FORMPAR (ne ukazatel), registr ECX ukazatel na popisovač národnostních informací NATIONAL, registr ESI čítač zbylého místa v cílovém bufferu a registr EDI ukazatel do cílového bufferu. Na výstupu z funkce jsou registry ESI a EDI posunuty na novou ukládací pozici.

Funkce používá lokální proměnné s bázovým registrem EBP. Proměnné s kladným offsetem (BINNumL, BINNat a BINNumH) jsou použity jen pro čtení, jejich obsah není modifikován. BINNumL je nižší dvojslovo vstupního čísla (vstupní registr EAX). BINNat je ukazatel na národnostní informace NATIONAL (vstupní registr ECX). BINNumH je vyšší dvojslovo vstupního čísla (vstupní registr EDX). BINForm jsou formátovací parametry FORMPAR (vstupní registr EBX). BINLen je délka ukládaného textu. BINStack je velikost lokálních proměnných v zásobníku.


; ------------- Macro - store one BIN digit
; Uses: EDX:EBX=number, ESI=free space-1, EDI=end of destination
; Destroys: AL

%macro		BINTOTEXTBUFDIG 0

		inc	esi		; shift free space counter
		mov	al,bl		; EAX <- number
		jle	%%L1		; position is behind end of buffer
		and	al,1		; mask low bit
		add	al,"0"		; convert to ASCII character
		mov	[edi],al	; store character
%%L1:		shr	edx,1		; shift number HIGH 1 bit right
                rcr	ebx,1		; shift number LOW 1 bit right
		dec	edi		; shift destination pointer
%endmacro

Pomocné makro BINTOTEXTBUFDIG je používáno uvnitř funkce k uložení jedné BIN číslice. Makro modifikuje vstupní číslo v registrovém páru EDX:EBX. V registru ESI je čítač volného místa v cílovém bufferu snížený o 1. EDI je ukazatel konce dat v cílovém bufferu (číslo se ukládá odzadu). Obsah registru AL se funkcí zničí.

Inkrementací čítače volného místa v registru ESI se provede test, zda je ukazatel do cílového bufferu platný. Není-li čítač kladný, ukazuje ukazatel za konec cílového bufferu, v tom případě se přeskočí část ukládající další znak.

Z registru BL se obdrží nejnižší bajt dekódovaného čísla a zamaskováním číslem 1 se připraví nejnižší bit čísla, který bude další číslicí dekódovaného čísla. Přičtením ASCII znaku "0" se číslo zkonvertuje na ASCII číslici, která se uloží do cílového bufferu.

Ukazatel cílového bufferu se sníží a rotací dvojregistru EDX:EBX o 1 bit doprava se číslo posune o jednu číslici k vyšším řádům.


; ------------- Check remaining free space in buffer

BinToTextBuf:	or	esi,esi		; check remaining space
		jle	short BinToTextBufN9 ; not enough free space

; ------------- Push registers

		push	eax		; push EAX number LOW
		push	ebx		; push EBX
		push	ecx		; push ECX pointer to nationality
		push	edx		; push EDX number HIGH
		push	ebp		; push EBP
		mov	ebp,esp		; EBP <- push ESP
		sub	esp,BINStack	; ESP <- create local variables

; ------------- Prepare local variables

		mov	[BINForm],ebx	; formatting parameters FORMPAR

Na začátku funkce BinToTextBuf je nejdříve proveden test volného místa v cílovém bufferu. Není-li v cílovém bufferu volné místo, funkce se ihned ukončí.

Po úschově registrů se vytvoří v zásobníku místo pro lokální proměnné. Do proměnné BINForm se uschovají formátovací parametry z registru EBX.


; ------------- Get text length without spaces (-> EDX)

		call	Bin0ToTextBufN	; get text length without spaces
		mov	[BINLen],eax	; store text length
		xchg	eax,edx		; EDX <- push text length

Ke zformátování čísla v bufferu je potřeba nejdříve znát délku čísla. Délka čísla se zjistí funkcí Bin0ToTextBufN, která na rozdíl od funkce BinToTextBufN ignoruje parametr minimální šířky pole s údajem. Délka čísla se uchová do proměnné BINLen a do registru EDX.


; ------------- Store leading spaces

		bt	ebx,FORMFLAG_Left_b ; left-justify?
		jc	BinToTextBuf22	; left-justify, no leading spaces
		movzx	ecx,bh		; ECX <- minimal width of field
		sub	ecx,edx		; ECX <- remaining spaces
		jle	BinToTextBuf22	; no spaces left
		bt	ebx,FORMFLAG_Cent_b ; center?
		jnc	BinToTextBuf2	; no, right-justify
		shr	ecx,1		; ECX <- spaces / 2, round down
		jz	BinToTextBuf22	; no spaces left
BinToTextBuf2:	mov	al," "		; AL <- space
BinToTextBuf21:	dec	esi		; decrease space counter
		stosb			; store one space
		jz	short BinToTextBuf24 ; buffer is full
		loop	BinToTextBuf21	; next character

Není-li číslo zarovnáno doleva (příznakový bit FORMFLAG_Left_b), je nutno před číslo doplnit úvodní mezery. Do registru ECX se připraví z registru BH (což je parametr FORMPAR_Width z popisovače formátovacích parametrů) požadovaná šířka pole. Odečtením délky textu z registru EDX se obdrží zbývající šířka pro okraje. Je-li to kladné číslo, bude se pokračovat dále. Má-li být text centrován, použije se pouze polovina mezer se zaokrouhlením dolů.

V cyklu se ukládají znaky mezer do cílového bufferu. Počet mezer je v registru ECX. Dekrementací registru ESI se ověřuje, zda bude v bufferu místo pro další znak. Pokud čítač ESI dosáhne nuly, dosáhlo se konce cílového bufferu a funkce se ukončí.


; ------------- Store prefix

BinToTextBuf22:	mov	ecx,edx		; ECX <- text length
		bt	ebx,FORMFLAG_Alt_b ; use prefix?
		jnc	BinToTextBuf3	; not using prefix
		mov	al,"0"		; AL <- character "0"
		dec	esi		; decrease counter of free space
		stosb			; store first character
		jz	short BinToTextBuf24 ; buffer is full
		dec	ecx		; ECX <- text length - 1
		mov	al,"b"		; AL <- character "b"
		dec	esi		; decrease counter of free space
		stosb			; store second character
BinToTextBuf24:	jz	BinToTextBuf9	; buffer is full
		dec	ecx		; ECX <- text length - 1

; ------------- Suffix correction

BinToTextBuf3:	bt	ebx,FORMFLAG_Alt2_b ; use suffix?
		sbb	ecx,byte 0	; ECX <- decrease if suffix

Volitelně se může před začátek čísla uložit prefix "0b" (je-li nastaven příznakový bit FORMFLAG_Alt_b). Postupně se ukládají znaky "0" a "b", přičemž je dekrementací čítače v registru ESI sledováno volné místo k uložení dalšího znaku. Dosáhne-li čítač nuly, funkce se ukončí. Současně s ukládáním prefixu se v registru ECX dekrementuje údaj zbývající délky textu o 2.

Po uložení prefixu se testem příznakového bitu FORMFLAG_Alt2_b zjistí, zda se bude ukládat sufix "b". Pokud ano, sníží se údaj zbývající délky textu o 1.


; ------------- Prepare registers to convert number

		mov	ebx,[BINNumL]	; EBX <- number LOW
		add	edi,ecx		; EDI <- last character + 1
		mov	edx,[BINNumH]	; EDX <- number HIGH
		sub	esi,ecx		; ESI <- subtract length
		or	ecx,ecx		; check text length
		jle	BinToTextBuf81	; no characters

; ------------- Push registers 2

		push	esi		; push ESI
		push	edi		; push EDI
		dec	edi		; EDI <- set pointer to last character

Při přípravě registrů ke konverzi se do dvojregistru EDX:EBX načte konvertované číslo. Přičtením zbývající délky textu čísla k EDI a odečtením od ESI se ukládací ukazatel posune za konec ukládaného textu. Není-li délka textu v registru ECX platné kladné číslo, přeskočí se část pro ukládání čísla.

Po úschově zápisových ukazatelů ESI a EDI se dekrementací EDI nastaví ukládací ukazatel na poslední znak čísla.


; ------------- Convert number without thousand separator
; EDX:EBX=number, ESI=free space-1, EDI=end of destination, ECX=num. of chars

		bt	dword [BINForm],FORMFLAG_Thsn_b; thousand separator?
		jc	BinToTextBuf5	; use thousand separator
BinToTextBuf42:	BINTOTEXTBUFDIG		; store one digit into buffer
		loop	BinToTextBuf42	; next digit
		jmp	BinToTextBuf8

Není-li nastaven příznakový bit FORMFLAG_Thsn_b, bude se číslo dekódovat bez oddělovačů řádů. Během konverze obsahuje registrový pár EDX:EBX konvertované číslo, registr ESI čítač volného místa - 1, registr EDI ukazatel na konec ukládaného textu a registr ECX čítač znaků k uložení. K dekódování čísla se používá makro BINTOTEXTBUFDIG, které je opakovaně voláno ve smyčce s čítačem ECX.


; ------------- Convert number with thousand separator
; EDX:EBX=number, ESI=free space-1, EDI=end of destination, ECX=num. of chars,
; AH=order counter, EAX.byte2=thousand separator

BinToTextBuf5:	mov	eax,[BINNat]	; EAX <- pointer to nationality
		mov	al,[eax+NAT_ThsndSep] ; AL <- thousand separator
		shl	eax,16		; shift character
		mov	ah,9		; AH <- 9, init order counter
BinToTextBuf52:	dec	ah		; count order counter
		jnz	BinToTextBuf55	; no thousand separator
		TOTEXTBUFSEP		; store 1-byte thousand separator
		dec	ecx		; decrease character counter
		mov	ah,8		; AH <- 8, init order counter
		jz	BinToTextBuf8	; no next character
BinToTextBuf55:	BINTOTEXTBUFDIG		; store one digit into buffer
		loop	BinToTextBuf52	; next digit

Při konverzi čísla s oddělovači řádů obsahuje registrový pár EDX:EBX konvertované číslo, registr ESI čítač volného místa - 1, registr EDI ukazatel na konec ukládaného textu, registr ECX čítač znaků k uložení, registr AH čítač řádů a třetí bajt registru EAX (tj. bity 16 až 23) znak oddělovače řádů.

Do třetího bajtu registru EAX se připraví znak oddělovače řádů - do registru EAX se načte z BINNat ukazatel na popisovač národnostních informací, z něj z NAT_ThsndSep do registru AL znak oddělovače řádů, který se rotací o 16 bitů posune na pozici 3. bajtu. Do registru AH se připraví čítač řádů.

K dekódování čísla se používá makro BINTOTEXTBUFDIG, které je opakovaně voláno ve smyčce s čítačem ECX. Na začátku smyčky je dekrementován čítač řádů v registru AH. Pokud dosáhne nuly, uloží se znak oddělovače pomocí makra TOTEXTBUFSEP, sníží se čítač zbývajících znaků a do registru AH se připravý nový čítač řádů.


; ------------- Pop registers 2

BinToTextBuf8:	pop	edi		; pop EDI
		pop	esi		; pop ESI

; ------------- Limit offset

BinToTextBuf81:	or	esi,esi		; buffer overflow?
		jg	BinToTextBuf82	; buffer is OK
		add	edi,esi		; EDI <- correct address
		xor	esi,esi		; limit free space to 0
		jmp	short BinToTextBuf9

Po dekódování textu čísla se navrátí ukládací registry ESI a EDI, které ukazovaly za konec ukládaného čísla. Ukazatele se upraví tak, aby nepřesahovaly konec bufferu - tj. přesahující ukládací ukazatel EDI se přičtením čítače ESI posune na konec a poté se čítač zbylého místa vynuluje.


; ------------- Store suffix

BinToTextBuf82:	test	byte [BINForm+FORMPAR_Flags2],FORMFLAG2_Alt2 ; suffix?
		jz	BinToTextBuf83	; not using suffix
		mov	al,"b"		; AL <- suffix
		stosb			; store suffix
		dec	esi		; decrease space counter
		jz	BinToTextBuf9	; no free space

Je-li nastaven v registru formátovacích parametrů příznakový bit FORMFLAG2_Alt2, uloží se za konec čísla sufix "b". Po uložení sufixu se dekrementací čítače volného místa ESI zkontroluje zbývající volné místo, při dosažení konce bufferu se funkce ukončí.


; ------------- Store trailing spaces

BinToTextBuf83:	mov	eax,[BINLen]	; EAX <- text length
		movzx	ecx,byte [BINForm+FORMPAR_Width] ; ECX <- minimal width
		sub	ecx,eax		; ECX <- remaining spaces
		jle	BinToTextBuf9	; no spaces remain
		test	byte [BINForm+FORMPAR_Flags1],FORMFLAG1_Left ; left?
		jnz	BinToTextBuf84	; left-justify
		test	byte [BINForm+FORMPAR_Flags2],FORMFLAG2_Cent ; center?
		jz	BinToTextBuf9	; no center
		shr	ecx,1		; ECX <- spaces / 2
		adc	cl,ch		; ECX <- round up
		jz	BinToTextBuf9	; no spaces
BinToTextBuf84:	mov	al," "		; AL <- space
BinToTextBuf85:	stosb			; store one space
		dec	esi		; decrease space counter
		loopnz	BinToTextBuf85	; next character

; ------------- Pop registers

BinToTextBuf9:	mov	esp,ebp		; pop ESP
		pop	ebp		; pop EBP
		pop	edx		; pop EDX
		pop	ecx		; pop ECX
		pop	ebx		; pop EBX
		pop	eax		; pop EAX
		ret

Poslední operací je uložení mezer za koncem čísla. Do registru EAX je načtena délka textu (bez mezer), do registru ECX požadovaná šířka pole, odečtením zůstane v registru ECX počet zbývajících mezer. Pokud žádné mezery pro okraje nezbyly, funkce se ukončí.

Je-li nastaven příznakový bit FORMFLAG1_Left, je číslo zarovnáno doleva, ihned se přejde k ukládání mezer za číslo. Není-li tento příznak nastaven a není-li nastaven ani příznakový bit FORMFLAG2_Cent, bylo číslo zarovnáno doprava a mezery tedy již byly uloženy dříve, takže se funkce ukončí. Jinak platí, že číslo je centrováno. Do registru ECX se připraví poloviční počet mezer, ale tentokrát se zaokrouhlí nahoru (aby se zachytila případná lichá mezera).

Následuje ukládání mezer do bufferu. Počet mezer je dán čítačem v registru ECX. Současně se sleduje zbývající volné místo v cílovém bufferu čítáním registru ESI. Pokud dosáhne nuly, bylo dosaženo konce bufferu a smyčka se ukončí.

BinToTextBufN		Délka textu formátovaného čísla BIN
FormToTextBuf		Zformátování textu do bufferu