IndexTopClassesSummaryConstants

File SMJavaCollections.mys

Collection and Map inspired from Java programming language.

As a Java developer since more than 20 years, I'm used to work with Collection and Map which offer powerful methods.
Here there are in Lua!

SMJavaCollections.mys is automatically included when you Include "SMUtils".

Differences between table and Collection

Better than long explanations, here are code/algorithm that demonstrate the differences.

ActiontableCollectionNotes
Creation t = {} c = Collection:new(elementType, sortFunction) where elementType is "number", "string" or "table"
Add tinsert(t, data) c:add(data) In the same table, you can insert numbers, strings and others types.
Collection avoid this: more restrictive, less bugs.
Add a set of data 
for i=1,getn(datas) do
  tinsert(t, datas[i])
end
 c:addAll(anotherCollection)
Read print(t[2]) print(c:get(2)) With Collection, the data is guaranteed to have the type you want.
Remove data at index 2 tremove(t, 2) c:removeAt(2)
Remove first "banana" 
for i=1,getn(t) do
  if t[i]=="banana" then
    tremove(t, i)
    break
  end
end
 c:remove("banana")
Remove all "bananas" Loop backward, move efficient
for i=getn(t),1,-1 do
  if t[i]=="banana" then
    tremove(t, i)
  end
end
 c:removeAll("bananas")
Get size getn(t) c:size()
Replace at index 2 t[2] = "apple" c:replaceAt(2, "apple")
Sort sort(t, sortFunction) Nothing to do Datas are sorted at insertion, if Collection is created with a sorting function
Does it contain "apricot"?
  • Sort if needed, and loop untile "apricot" or a greater data is found
  • or loop the whole table untile "apricot" is found or end is reached
 c:contains("apricot")
Don't add "banana" if already in table Loop. if no "banana" found then insert.
local found = false
for i=1,getn(t) do
  if t[i]=="banana" then found=true; break; end
end
if found==false then
  tinsert(t, "banana")
end
 Nothing to do At creation time, Collection may be a "set", i.e. a Collection of unique datas
Get index of "apple"
  1. Sort if needed
  2. loop until first "apple" found or end reached
 c:indexOf("apple")
Get the first / last data
  1. Sort if needed
  2. t[1] or t[getn(t)]
 c:first() or c:last()
Get greatest/least data
  • Sort and return t[1] / t[getn(t)]
  • Or loop thought all data to find greatest / least
 c:last() / c:first() for sorted Collection only
Get all data before/after (or including) "banana"
  1. Sort if needed
  2. Loop until "banana" is found
  3. Add previous/next datas to a table and return it.
 c:head("banana", inclusive) or c:tail("banana", inclusive) where inclusive is a boolean.
Browse for i=1,getn(t) do print(t[i]) end
Backward browsing:
for i=getn(t),1,-1 do... 
c:iterator()
while c:hasNext() do
  print(c:next())
end

Backward browsing: c:reverseIterator()

As you can notice, very simple operation are easier to write using table, but complex ones are really more friendly using Collection.
Collection should save you time, make your script more maintainables, and reduce errors because of type-protection of inserted datas.

Note on performance: Collection is backed on native Lua table. It's fast, but just a little bit less than working with tables.
If you are really concerned by CPU and memory optimization and perform a lot of simple operation on many tables, you may prefer table to Collection.
If you are concerned by easy-to-read code and ready-to-use functions, Collection is for you.

For example, Collection is usless for building a large table of digital waveform (44100 numbers per second of sound).

Classes

ClassSummary
CollectionCollection empowers table: unicity, sort and type-protection of datas (elements).
MapMap is a Collection of keys with associated value for each key.

Summary

ConstantTypeSummary
SORT_ASCENDING(a, b)functionNatural ascending ordering function
SORT_DESCENDING(a, b)functionNatural descending ordering function

Constants

function SORT_ASCENDING(a, b)

Natural ascending ordering function

ParameterTypeDefaultDescription
a  a
b  b
Usage 

my_collection = Collection:new("string", true, SORT_ASCENDING)

function SORT_DESCENDING(a, b)

Natural descending ordering function

ParameterTypeDefaultDescription
a  a
b  b
Usage 

my_collection = Collection:new("string", true, SORT_DESCENDING)