Encoding Primitive types

In this tutorial we will take a look at all the primitive types that can be encoded in the TIER format. All of the mappings we will be using in this tutorial can be found in the tier.primitive submodule.

Numbers

TIER contains many different number encodings. All number encodings map from a lua number value to a particular kind of encoded number.

local tier  = require"tier"
local primitive = tier.primitive

local file = io.open("Numbers.dat")
tier:encode(file, primitive.byte, 0)
tier:encode(file, primitive.int16, 1)  
tier:encode(file, primitive.int32, 2)
tier:encode(file, primitive.int64, 3)
tier:encode(file, primitive.uin16, 4)
tier:encode(file, primitive.uint32, 5)
tier:encode(file, primitive.uint64, 6)
tier:encode(file, primitive.float, 7)
tier:encode(file, primitive.double, 8)
tier:encode(file, primitive.varint, 9)
tier:encode(file, primitive.varintzz, 10)
file:close()

Of the above number types varint and varintzz requires some additional explanation. The TIER format has the possibility of encoding integers with a variable number of bytes that depends on the value of the number. The larger the value the larger the number. The variable integer format used by TIER is the same format that is used in Google Protocol Buffers. The varint type is better at encoding unsigned integers and the varintzz can encode negative numbers more efficiently. More about variable integer encoding can be found in the TIER specification

Characters

local tier = require"tier"
local primitive = tier.primitive

local file = io.open("Characters.dat")
tier:encode(file, primitive.char, "A")
tier:encode(file, primitive.wchar, "\255a")
file:close()

###Strings The following mappings map between lua strings and encoded strings or characters.

local tier = require"tier"
local primitive = tier.primitive

local file =  io.open("Strings.dat")
tier:encode(file, primitive.stream, "This is a stream")
tier:encode(file, primitive.string, "This is a string")
--Wide chars are not that useful from a pure Lua stand point
--But can be very useful if communicating with languages
--whose string types are based on UTF-16.
tier:encode(file, primitive.wchar, "\255a\255p\255a")
file:close()

In tier the char type represents a UTF-8 encoded character and a wchar represents a UTF-16 encoded character. The string type is an array of UTF-8 characters and wstring is an array of UTF-16 characters. In lua all strings are represented as an byte array and the encoding is external therefore wstrings are represented as strings that are byte arrays with a length that is twice that of the wstring length. The stream type is an array of bytes (the bytes can be zero). It is represented as a string in Lua since that is the prefered option to store binary data in Lua.

Null and Void

There are maybe surprisingly two different kinds of empty values in TIER.

local tier = require"tier"
local primitive = tier.primitive

local file = io.open("Empty.dat")
tier:encode(file, primitive.null, nil)
tier:encode(file, primitive.void) 
file:close()

Semantically void means "no value" and null means "nil", they encode nothing to the output but are useful when when constructing more complex aggregate types.

Booleans

The boolean value maps from a lua boolean to a encode bool.

local tier = require"tier"
local primitive = tier.primitive

local file = io.open("Booleans.dat")
tier:encode(file, primitive.boolean, true)
tier:encode(file, primitive.boolean, false)
file:close()

Booleans are encoded as the byte 0 for false and 1 for true.

This marks the end for this tutorial. In the next tutorial Encoding Lists it is show how we can encode arrays and lists of values.