Introducing ListLib - Add Powerful Functionalities to Tables | v[1.0.0]

Hey y’all!

Luau tables right now are very limited, but thanks to the blessing of OOP, I decided to fix that. Introducing…


:books: Documentation | :floppy_disk: Source Code



More Resources



Current DataTypes

There are only two as of right now, but I actually have one in production which may be shipped soon. The current ones are:

  • List - holds any datatype
  • NumList - more specialized with numbers

Note: all datatypes in ListLib are ordered arrays with numerical keys only.


Features Overview

Certain added functionalities include:

  • slicing
  • negative indexing
  • List merging (concatenation)
  • multiple insertion
  • operations (add, sub, mul, div, mod, pow on NumLists only)
  • comparisons (compare the contents, not the memory addresses)
  • reversing
  • replacing
  • value-based removing
  • aliases (“label” your Lists for context)
  • table events (added, changed, removed)
  • zipping (iterate through multiple iterable objects at once)
  • maths and stats (mean, five-point-summary, etc. with NumLists only)

Code Samples


Here are code samples showcasing certain top features of existing datatypes. They only show their specialized API, meaning NumList can still access functions of List since it’s inherited.

Lists
local MyList = List.new({"any", "datatype", 2, Vector3.new(), {}, true})

----------negative indexing
print(MyList[-3]) --Vector3

----------concatenation
print(MyList .. {"random", "stuff"})
--prints:
--List({"any", "datatype", 2, Vector3.new(), {}, true, random, stuff}

----------slicing
print(MyList(2, 4)) --List({datatype, 2, Vector3[...]})
print(MyList(2, 6, 2)) --List({datatype, Vector3[...], true})

----------reversing
print(MyList(1, MyList.Length, -1))
print(MyList:Reverse())
--both would print:
--List({true, {}, Vector3[...], 2, datatype, any})

----------replacing
MyList:Replace(2, 3)
print(MyList) --List({"any", "datatype", 3, Vector3.new(), {}, true}

----------changed event
MyList.Changed:Connect(function(index, oldVal, newVal)
    print('index ' .. index .. ' changed from ' .. oldVal .. ' to ' .. newVal)
end)

MyList[2] = "data types" --index 2 changed from datatype to data types

----------zipping
for i, v1, v2, v3 in MyList:Zip({9, 8, 7}, "string") do
    print(i, v1, v2, v3)
end
--prints:
--1 any 9 s
--2 datatype 8 t
--3 3 7 r
NumLists
----------convert from and to bases
--(we'll use this version later on)
local MyNumList = NumList.new({'1010', '1001', '1000', '0111', '0110', '0101'}, 2)
print(MyNumList) --NumList({10, 9, 8, 7, 6, 5})
print(MyNumList:ToBase(2)) --{'1010', '1001', '1000', '0111', '0110', '0101'}

----------create from a range of numbers with an optional step
local MyNumList2 = NumList.fromRange(1, 10, 2)
print(MyNumList2) --NumList({1, 3, 5, 7, 9})

----------create a normalized distribution with 10 values
local MyNumList3 = NumList.fromNormal(10, 5, 30)
print(MyNumList3:GetAvg()) --5
print(MyNumList3:GetStd()) --30

----------operations
print(MyNumList + 2) --NumList({12, 11, 10, 9, 8, 7})
print(MyNumList + {1, 2, 3, 4, 5, 6}) --NumList({11, 11, 11, 11, 11, 11})
print(MyNumList + {2, 2}) --error (not the same length)

----------comparisons (>, >=, <, <= comapres the sums)
local MyNumList_Clone = MyNumList:Clone()
local MyNumList_Comp = NumList.new({1, 2, 3, 4, 5, 6})

print(MyNumList == MyNumList_Clone) --true
prints(MyNumList > MyNumList_Comp) --true
prints(MyNumList < MyNumList_Comp) --false

----------maths and stats
--get individually
print(MyNumList:GetSum()) --45
print(MyNumList:GetMedian()) --7.5
print(MyNumList:GetStd()) --1.707...

--or get them all in a table
print(MyNumList:GetStats())
--[[
{

Avg = 7.5,
MAD = 1.5,
Max = 10,
Median = 7.5,
Min = 5,
Mode = "None",
Product = 151200,
Q1 = 6,
Q3 = 9,
Range = 5,
Std = 1.708,
Sum = 45

}
]]

Feedback & Concerns

You can learn the API in the documentation provided above, but if anything is unclear, post it right here! that rhymes

I’m also open to feedback on what to add to the Library, either a new datatype or more API, etc. Report any bugs and post your concerns here.

Rate the module:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10

0 voters

Thank you,
And have a great day!

Meta edits

Feb 12, 2021

  • changed topic title
  • added a code sample to the topic to showcase certain features in action
  • fixed documentation formatting in some places
  • added “Meta edits” (what inception lol)
  • added a more resources section
13 Likes