====== advtrains.decode_pos ======
//Decodes a Advtrains position string.//

//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.decode_pos(pts)
</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:encode_pos|advtrains.encode_pos]]''.

===== Parameters =====
  * ''pts'' //(string)//: a table index string created by ''[[dev:core:funref:encode_pos|advtrains.encode_pos]]''.

===== Returns =====
A Minetest position vector.

===== Errors and warnings =====
It gives a runtime error if the ''pts'' parameter:
  * is not at least 12 characters long
  * contains characters not part of the [[wp>Hexadecimal|hexadecimal notation]]

  ../mods/advtrains/advtrains/helpers.lua:373: attempt to perform arithmetic on a nil value
  stack traceback:
      ../mods/advtrains/advtrains/helpers.lua:373: in function 'dec'
      ../mods/advtrains/advtrains/helpers.lua:388: in function 'decode_pos'
      ???:?: in main chunk
      [C]: in ?


===== How it works internally =====
This function converts back strings created by ''[[dev:core:funref:encode_pos|advtrains.encode_pos]]'' to their original vector form. Y, X and Z coordinates are treated separately: the corresponding parts of the argument are extracted and passed to ''dec'', which converts the hexadecimal form of a number to its decimal form.
  - Y coordinate is encoded in characters 1 to 4.
  - X coordinate is encoded in characters 5 to 8.
  - Z coordinate is encoded in characters 9 to 12.

===== Examples =====
<code lua>
advtrains.decode_pos("800080008000") -- {x=0,y=0,z=0}
advtrains.decode_pos("807B7DC07F62") -- {x=-576,y=123,z=-158}
advtrains.decode_pos("1C401E5858F0") -- {x=-25000,y=-25536,z=-10000}
</code>

===== In source code =====
advtrains/helpers.lua, lines 383 to 389:

<file lua decode_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 function c(s,i) return dect[string.sub(s,i,i)] end

local function dec(s)
    return (c(s,1)*4096 + c(s,2)*256 + c(s,3)*16 + c(s,4))-32768
end
-- [...]

function advtrains.decode_pos(pts)
    if not pts or not #pts==6 then return nil end
    local stry = string.sub(pts, 1,4)
    local strx = string.sub(pts, 5,8)
    local strz = string.sub(pts, 9,12)
    return vector.new(dec(strx), dec(stry), dec(strz))
end

</file>