longBit

[ Work in progress ]

longBit

Essa curiosa biblioteca foi pensada e criada com o intuito de "aumentar" a capacidade de armazenamento persistente do Tic80.
Ela fornece funções capazes de "dividir" o espaço de memória manipulado pela função pmem.

Functions

• boot
• clear
• getBool
• getClass
• getAll
• getNum
• setAll
• setClass
• setMem
• swapClass

"Sub-Memórias"

Ao "dividir" os espaços de memória, torna-se possível armazenar até nove caracteres (apenas numéricos). Tais espaços são chamados de "sub-memórias" (no contexto dessa biblioteca), logo:

• 14 ocupa duas sub-memórias.
• 60870 ocupa cinco sub-memórias
• 1194261537 excede o limite, por isso não pode ser armazenado.

O valor mais alto que pode ser armazenado em espaço "inteiros" é 4294967295, já nas sub-memórias é 999999999.

Algumas funções exigem a especificação do índice de uma sub-memória (1-9), nesses casos é importante lembrar como as sub-memórias são organizadas. Para tornar a explicação mais fácil, considere esse exemplo:

Tipo	Valor
Índice	1
Classe	"player_xy"
Valor	104070888

Este espaço é ocupado por dois valores, respectivos as posições X e Y do jogador, além de possuir três espaços vazios (......888). Logo:

• Para acessar X é necessário usar o índice 1.
• Para acessar Y é necessário usar o índice 4.

Isso acontece porque os valores são tratados de maneira individual, mesmo que não sejam.

Não há a necessidade de solicitar de maneira individual os valores responsáveis por compôr um numeral maior que nove, já que há a posibilidade de especificar o comprimento dos valores em todas as funções que exigem um índice de sub-memória.

Classes

Este é o nome dado ao "apelido" atribuído a espaços de memória (especificos), definidos através da função longBit.setClass().

Sendo essa uma forma de substituir os índices numéricos por palavras chave, assim facilitando a legibilidade do código e a distinção de diferentes espaços de memória.

Por exemplo, ao invés de usar 1 para se referir ao espaço reservado para configurações, pode-se usar "configurations" ou "conf" ou qualquer outra cadeia de caracteres, a gosto do usuário (vulgo programador).

---

Back to top

---

longBit.boot

• Uso: Armazena vários valores nos espaços especificados, caso este esteja vazio (0) ou a (re)atribuição seja forçada.
• Retorno: Nenhum.

Structure

longBit.boot(memID, force, max, init, empty)

Parameter	Type	Description	Default
memID	table	Valores que serão adicionados	Mandatory
force	boolean	Força a reatribuição dos valores à memórias diferentes de zero	false
init	number	Primeiro índice de memória à receber um valor	0
empty	number	Valor usado para preencher espaços vazios à direita	0

About the highlighted parameters

• memID: como forma de evitar a anulação de zero(s) à esquerda (ex: 006102 -> 6102), todos os valores dessa tabela devem ser cadeias de caracteres. Todas devem ser formadas apenas por caracteres numéricos.

Examples

-- BOOT is called a single time, before of the TIC.

function BOOT()
	
	local values = {
		"0000000000", -- configirations
		"120068100",  -- player: x, y, hp
		"0"           -- achievements
	}
	
	longBit.boot(values, nil, nil, DEBUG)
	
end

---

Back to top

---

longBit.clear

• Uso: Descarta as informações armazenadas nas memórias e/ou descarta as classes definidas.
• Retorno: Nenhum.

Structure

longBit.clear(_type, max, init)

Parameter	Type	Description	Default
_type	string	Tipo de valor que será limpo	Mandatory
max	number	Última memória/classe à ser limpa	255
init	number	Primeira memória/classe à ser limpa	0

About the highlighted parameters

• _type: especifica o que deve ser limpo.
• • all: limpa todas as classes e memórias.
• • classes: limpa todas as classes.
• • memory: limpa todas as memórias.
• • lessClass: limpa todas as memórias que não possuem classe.

Examples

local function restartMEM(btnID, keyID, cursorClick)
	local keyboard = (not keyID) and 0 or keyp(keyID)
	local gamepad  = (not btnID) and 0 or btnp(btnID)
	
	if keyboard or gamepad or cursorClick then
		longBit.clear("all")
	end
	
end

function BOOT()
	-- debug condition
	restartMEM(nil, nil, true)
	
	-- set configurations
	longBit.boot("00110", nil, nil, nil, 8)
	
	-- [...]

---

Back to top

---

longBit.getBool

• Uso: Obtém um valor armazenado em uma sub-memória e o compara com 1 ou outro valor.
• Retorno: O resultado da comparação booleana.

Structure

longBit.getBool(itemID, className, equal)

Parameter	Type	Description	Default
itemID	number	Índice da sub-memória	Mandatory
className	string	Classe da memória	Mandatory
equal	number	Valor que será comparado	1

Examples

-- [...] TIC

	-- achievements
	local icon = 0
	for i = 1, 9 do
		
		-- compare with one
		if longBit.getBool(i, "achiv") then
			icon = 384 + i
		else
			icon = 384
		end
		
		-- draw
		spr(icon, 15, 112, 7)
		
	end

-- [...]

---

Back to top

---

longBit.getClass

• Uso: Obtém o nome de uma classe e, opcionalmente, verifica se ela foi pré-definido, gerando um erro caso contrário.
• Retorno: O nome da classe obtida.

Structure

longBit.getClass(id, wasDefined)

Parameter	Type	Description	Default
id	number	Índice da classe	Mandatory
wasDefined	boolean	Verifica se a classe existe	false

About the highlighted parameters

• wasDefined: Caso seja true e não exista uma classe definida para o índice especificado, gerará um erro no console.

Examples

function BOOT()

	-- start classes
	longBit.setClass({"Stats", "Score", "Progress"})

	-- check class (debug)
	trace("\nClasses:\n", 4)
	
	for i = 0, 2 do
		-- stop the program
		longBit.getClass(i, true) -- the index is printed
	end
	
	trace("")

-- [...] TIC

	if mouseClick and mouseClickCooldown == 0 then
		mouseClickCooldown = 5
		local class = ""
		local value = 0
		
		-- informations
		for x = 0, 2 do
		
			for y = 1, 9 do
				class = longBit.getClass(x)
				
				value = longBit.getNum(y, class)
			
				print(value, 10 + 25 * x, 15 + 8 * y, 12)
			end
			
		end
		
	end


-- [...]

---

Back to top

---

longBit.getAll

• Uso: Exibe todo o conteúdo armazenado em uma memória.
• Retorno: Nenhum.

Structure

longBit.getAll(className)

Parameter	Type	Description	Default
className	string	Classe da memória que será visualizada	Mandatory

Examples

local function debugMemory()
	
	local value = 0
	local classes = {"conf", "achi", "skin", "gadt"} -- refrences
	
	for i = 1, #classes do
		-- obtain values
		value = longBit.getAll(classes[i])
		
		-- draw a list
		print(value, 0, 10 * (i - 1), 4)
	end
	
end

---

Back to top

---

longBit.getNum

• Uso: Obtém um valor armazenado em uma determinada sub-memória.
• Retorno: Retorna o valor encontrado.

Structure

longBit.getNum(itemID, className, lenght)

Parameter	Type	Description	Default
itemID	number	Índice da sub-memória	Mandatory
className	string	Classe da memória	Mandatory
lenght	number	Comprimento do valor	1

About the highlighted parameters

• lenght: Este parâmetro permite a obtenção de valores maiores que nove, os quais ocupam mais de uma sub-memória.

Examples

local function obtainMemValues()
	-- [...]

	local joystick = {
		longBit.getNum(1, "joystick", 3), -- x
		longBit.getNum(4, "joystick", 3), -- y
		longBit.getNum(7, "joystick", 2), -- scale
		longBit.getNum(9, "joystick")     -- style
	}
	
	-- [...]
	
	return player, joystick, skins, stats, achievements, configurations
end

---

Back to top

---

longBit.setAll

• Uso: Grava um valor em memórias interias, desconsiderando sub-memórias já existente no mesmo.
• Retorno: Nenhum.

Structure

longBit.setAll(newValue, className, itself)

Parameter	Type	Description	Default
newValue	number	Um número entre 0 e 4294967295	Mandatory
className	string	Classe da memória	Mandatory
itself	boolean	Soma o valor da memória com newValue	false

Examples

local function updateScore(values)

	-- debug
	if #values ~= 5 then
		trace("Value not specified (updateScore)")
		exit()
	end
	
	-- references
	local classes = {"red", "blue", "yellow", "green", "purple"}
	
	-- add values to memory
	for i = 1, #classes do
		longBit.setAll(values[i], classes[i], true)
	end

end

---

Back to top

---

longBit.setClass

• Uso: Define uma série de classes para uma série de memórias.
• Retorno: Nenhum.

Structure

longBit.setClass(class, max, init)

Parameter	Type	Description	Default
className	table	Classes a serem atribuídas	Mandatory
max	number	Índice da última memória à receber uma classe	#class - 1
init	number	Índice da primeira memória à receber uma classe	0

Examples

function BOOT()
	-- start memory and its classes
	local values, classes
	
	values = {
		"0", "0", -- it will filled with zeros
		"1416",   -- music, music volume, sound, sound volume
		"064104", -- player: x, y
	}
	
	classes = {"score", "skins", "options", "player"}
	
	longBit.boot(values)
	longBit.setClass(classes)

-- [...]

---

Back to top

---

longBit.setMem

• Uso: Regrava em uma ou mais sub-memórias.
• Retorno: Nenhum.

Structure

longBit.setMem(newValue, itemID, className, lenght)

Parameter	Type	Description	Default
newValue	number	Valor que será gravado	Mandatory
itemID	number	Índice da sub-memória	Mandatory
className	string	Classe da memória	Mandatory
lenght	number	Comprimento do valor	1

About the highlighted parameters

• lenght: Este parâmetro permite a obtenção de valores maiores que nove, os quais ocupam mais de uma sub-memória.

Examples

local function savePlayer(cond, x, y, damage, speed)
	
	if cond then
	
		longBit.setMem(x,      1, "player", 3)
		longBit.setMem(y,      4, "player", 3)
		longBit.setMem(damage, 7, "player", 2)
		longBit.setMem(speed,  9, "player")
	
	end

end

---

Back to top

---

longBit.swapClass

• Uso: Regrava o nome de uma classe e,opcionalmente, verifica se ela foi pré-definido.
• Retorno: Nenhum.

Structure

longBit.swapClass(newName, id, wasDefined)

Parameter	Type	Description	Default
className	string	Nome que será gravado	Mandatory
id	number	Índice da classe	Mandatory
wasDefined	boolean	Verifica se a classe existe	false

About the highlighted parameters

• wasDefined: Caso seja true e não exista uma classe definida para o índice especificado, gerará um erro no console.

Examples

local function corruptNight(text) -- "good" or "evil"
	
	-- classes names
	local names = {"villagers", "criters", "torrets", "pets"}
	
	for i = 1, #names do
	
		-- add suffix
		names[i] = names[i].."-"..text
	
		-- update classes
		longBit.swapClass(names[i], i + 4, true) -- temporary "true", for debug

	ens

end

---

Back to top

---