====== advtrains.encode_pos ======
//Encodes a Minetest position vector.//

//Note: this page has been written for Advtrains 2.0.1 TSS and Minetest 5.1.0. Examples and practices described in this page don't take advantage of improvements introduced in later releases.//

===== Syntax =====
<code lua>
advtrains.encode_pos(pos)
</code>

===== Extended description =====
This function creates a string from the given Minetest position vector, suitable for use as a table index.  
See also ''[[dev:core:funref:decode_pos|advtrains.decode_pos]]''.

===== Parameters =====
  * ''pos'' //(table)//: a Minetest position vector.

===== Returns =====
A string suitable for use as a table index, in the format ''YYYYXXXXZZZZ''.

===== How it works internally =====
This function uses the hexadecimal position of each coordinate. In other words:
  - The function adds 32,768 to the Y coordinate.
  - The  [[wp>Hexadecimal|hexadecimal notation]] of the coordinate is taken.
  - Steps 1 and 2 are repeated for X and Z coordinates. The result of Step 2 is appended to the return value.

===== Examples =====
<code lua>
advtrains.encode_pos({x= 0    ,y=0    ,z= 0    }) -- 800080008000
advtrains.encode_pos({x=-576  ,y=123  ,z=-158  }) -- 807B7DC07F62

-- Notice the overflow while encoding the Y coordinate!
advtrains.encode_pos({x=-25000,y=40000,z=-10000}) -- 1C401E5858F0
</code>

===== In source code =====
advtrains/helpers.lua, lines 378 to 380:

<file lua encode_pos.lua>
-- DEPENDENCY CODE
local hext = { [0]="0",[1]="1",[2]="2",[3]="3",[4]="4",[5]="5",[6]="6",[7]="7",[8]="8",[9]="9",[10]="A",[11]="B",[12]="C",[13]="D",[14]="E",[15]="F"}
local dect = { ["0"]=0,["1"]=1,["2"]=2,["3"]=3,["4"]=4,["5"]=5,["6"]=6,["7"]=7,["8"]=8,["9"]=9,["A"]=10,["B"]=11,["C"]=12,["D"]=13,["E"]=14,["F"]=15}

local f = atfloor -- = math.floor

local function hex(i)
    local x=i+32768
    local c4 = x % 16
    x = f(x / 16)
    local c3 = x % 16
    x = f(x / 16)
    local c2 = x % 16
    x = f(x / 16)
    local c1 = x % 16
    return (hext[c1]) .. (hext[c2]) .. (hext[c3]) .. (hext[c4])
end
-- [...]

function advtrains.encode_pos(pos)
    return hex(pos.y) .. hex(pos.x) .. hex(pos.z)
end
</file>