Points Library (ssk.points.*)

This is a general Lua library for creating lists of points { x = value, y = value }.

These lists are used by the Line Factories, but may be useful in other contexts too.

Creating a Points List

You can create a new points list with this function, which returns a points instance.

ssk.points.new( ... )

... - Optional sequence of x, y values to initialized the points list with.


-- Create a points list with these points: 
--  { x = 10, y = 10 }
--  { x = 20, y = 20 }
--  { x = 15, y = 35 }
--
local pointsList = ssk.points.new( 10, 10, 20, 20, 15, 35 )

Tip: Points lists are numerically indexed tables, so you can do things like this:


for 1 = 1, #pointsList do
   print( "X @ index " .. i .. " == " .. tostring( pointsList[i].x ) )
   print( "Y @ index " .. i .. " == " .. tostring( pointsList[i].y ) )
end

Warning: Points lists cannot be saved to JSON because they have functions attached to them.

Points Instance Methods

Points list instances have all of these methods:

| | |-------------:|:-------------| | add(...) | Add new points using x, y pairs (...) | | insert(index, ...) | Insert x, y pairs in list ... to curent point list starting at index. | | get(index) | Returns point (as table) at index in list, or nil if no such index exists. | | remove(index) | Remove point (x, y pair) at index from list.| | push(...) | Add a new point(s) at end of list. | | peek() | Get point from end of list without removing it from the list. Returns nil if list is empty. | | pop() | Like peek(), but removes point from list at same time. | | push_head(...) | Add new point(s) to beginning of list. Synonym for add( 1, ... ). | | peek_head() | Get point from beginning (index 1) of the list. Returns nil if list is empty. | | pop_head( ) | Like peek_head(), but removes point from list at same time. |

Complete Points Example


-- 1. Create blank list
local pointsList = ssk.points.new( )

-- 2.  Add points
pointsList:add( 15, 35 )

-- Points list is now:
--  { x = 15, y = 35 }

-- 3. Insert points at index 1
pointsList:insert( 1, 10, 10, 20, 20 )

-- Points list is now:
--  { x = 10, y = 10 }
--  { x = 20, y = 20 }
--  { x = 15, y = 35 }

-- 4. Pop Head
pointsList:pop_head()

-- Points list is now:
--  { x = 20, y = 20 }
--  { x = 15, y = 35 }

-- 5. Pop Tail
pointsList:pop()

-- Points list is now:
--  { x = 20, y = 20 }

-- 6. Push Point to Tail
pointsList:push( 10, 10 )

-- Points list is now:
--  { x = 20, y = 20 }
--  { x = 10, y = 10 }

-- 7. Push Point to Head
pointsList:push_head( 15, 25 )

-- Points list is now:
--  { x = 15, y = 25 }
--  { x = 20, y = 20 }
--  { x = 10, y = 10 }

-- 8. Dump the Points
for i = 1, #pointsList do
    table.dump(pointsList:get(i), nil, "Index: " .. tostring(i) )
end

When executed, the above code prints (something like) this in the console:


22:01:20.583  Table Dump:
22:01:20.583  -----
22:01:20.583  x (string)                     == 15 (number)                   
22:01:20.583  y (string)                     == 25 (number)                   
22:01:20.583  Index: 1-----
22:01:20.583  
22:01:20.583  Table Dump:
22:01:20.583  -----
22:01:20.583  x (string)                     == 20 (number)                   
22:01:20.583  y (string)                     == 20 (number)                   
22:01:20.583  Index: 2-----
22:01:20.583  
22:01:20.583  Table Dump:
22:01:20.583  -----
22:01:20.583  x (string)                     == 10 (number)                   
22:01:20.583  y (string)                     == 10 (number)                   
22:01:20.583  Index: 3-----