{"id":"glitchymosh/limitedtable","name":"limitedtable","scope":"glitchymosh","platform":"roblox","description":"Constructor of Luau tables with size limits. Useful for interpreters, VMs and much more.","version":"1.2.0","latest":"1.2.0","versions":["1.2.0"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{},"integrity":"9d97ef4903af7df527c87442c9075318c09783e853427349fd5a4783765d905f","likes":0,"downloads":0,"install":"forest install glitchymosh/limitedtable","url":"https://forest.dev/p/roblox/glitchymosh/limitedtable","files":"https://api.forest.dev/ai/package/roblox/glitchymosh/limitedtable/files","readme":"# LimitedTable\r\n\r\nConstructor of [Luau](https://luau-lang.org) tables with size limits. Useful for interpreters, VMs and much more.\r\n\r\n## Installation\r\n\r\n### GitHub\r\n\r\nDownload the [latest .rbxm file](https://github.com/arythmitical/LimitedTable/releases/latest) from releases and insert it into Roblox Studio.\r\n\r\n### Creator Marketplace\r\n\r\n[Creator Marketplace Module](https://create.roblox.com/store/asset/103337933619557)\r\n\r\n### **[Wally](https://github.com/UpliftGames/wally)**\r\n\r\n1. Add LimitedTable to dependencies in `wally.toml` inside your project:\r\n\r\n    ```toml\r\n    limitedtable = \"glitchymosh/limitedtable@1.2.0\"\r\n    ```\r\n\r\n2. Update dependencies using shell:\r\n\r\n    ```bash\r\n    wally install\r\n    ```\r\n\r\n## Usage\r\n\r\n### Properties\r\n\r\n#### .maximumSize\r\n\r\n```lua\r\nLimitedTable.maximumSize: number\r\n```\r\n\r\nDetermines the maximum allowed size of data inside LimitedTable. This **must** be specified.\r\n\r\n#### .table\r\n\r\n```lua\r\nLimitedTable.table: { [any]: any }\r\n```\r\n\r\nThe real table with contents of LimitedTable *(aka LimitedTableTable)*. **Use only for getting values**.\r\n\r\n#### .sizeExceededMessage\r\n\r\n```lua\r\nLimitedTable.sizeExceededMessage: string | (table: LimitedTableTable) -> (),\r\n```\r\n\r\nDetermines the error message that will be raised when the maximum size is exceeded. Alternatively, it can be a **function** that will be invoked instead of raising an error.\r\n\r\nDefault: `maximum size of %s bytes exceeded`\r\n\r\n### Functions\r\n\r\n#### .new\r\n\r\n```lua\r\nfunction LimitedTable.new(\r\n    maximumSize: number,\r\n    errorMessage: (string | () -> ())?\r\n): LimitedTable\r\n```\r\n\r\nConstruct a new LimitedTable with given size limit of **`maximumSize`** bytes.\r\n\r\nWriting a value that exceeds LimitedTable's size will raise an error with **`errorMessage`**. If the `errorMessage` is a function, then that function will be called instead.\r\n\r\nExample:\r\n\r\n```lua\r\nlocal lt = LimitedTable.new(512000)\r\n\r\nlt.maximumSize += 64000\r\n\r\nlt.sizeExceededMessage = \"bum\"\r\nlt.sizeExceededMessage = function()\r\n    game.Players.LocalPlayer:Kick()\r\nend\r\n```\r\n\r\n#### isValid\r\n\r\n```lua\r\nfunction LimitedTable.isValid(\r\n    object: LimitedTable\r\n): boolean\r\n```\r\n\r\nChecks if the given **`object`** is a valid LimitedTable from this module.\r\n\r\nExample:\r\n\r\n```lua\r\nprint(LimitedTable.isValid(LimitedTable.new(512000))) --> true\r\nprint(LimitedTable.isValid({})) --> false\r\n```\r\n\r\n#### isTable\r\n\r\n```lua\r\nfunction LimitedTable.isTable(\r\n    object: LimitedTableTable\r\n): boolean\r\n```\r\n\r\nChecks if the given **`object`** is a valid LimitedTableTable from this module.\r\n\r\nExample:\r\n\r\n```lua\r\nprint(LimitedTable.isTable(LimitedTable.new(512000).table)) --> true\r\nprint(LimitedTable.isTable({})) --> false\r\n```\r\n\r\n#### getOwner\r\n\r\n```lua\r\nfunction LimitedTable.getOwner(\r\n    table: LimitedTableTable\r\n): LimitedTable?\r\n```\r\n\r\nReturns the LimitedTable that the **`table`** belongs to, or nil if not found.\r\n\r\nExample:\r\n\r\n```lua\r\nlocal lt = LimitedTable.new(512000)\r\nprint(LimitedTable.getOwner(lt.table) == lt) --> true\r\n\r\nlocal another = LimitedTable.new(512000)\r\nprint(LimitedTable.getOwner(lt.table) == another) --> false\r\n```\r\n\r\n#### :set\r\n\r\n```lua\r\nfunction LimitedTable:set(\r\n    key: any,\r\n    value: any,\r\n    table: LimitedTableTable?,\r\n    apply: boolean?\r\n): number\r\n```\r\n\r\nSets **`key`** of given **`table`** to **`value`** and returns the size of the changes.\r\n\r\n**`table`** defaults to `LimitedTable.table`. Optional parameter **`apply`** determines whether to apply given changes.\r\n\r\nExample:\r\n\r\n```lua\r\nlocal lt = LimitedTable.new(512000)\r\n\r\nlt:set(\"a\", \"hi\")\r\n\r\nlt:set(\"myArray\", {})\r\nlt:set(1, \"lol\", lt.table.myArray)\r\n\r\nlt:set(\"myArray\", {\r\n    \"milk\",\r\n    \"eggs\",\r\n    \"cheese\",\r\n})\r\n```\r\n\r\n#### :insert\r\n\r\n```lua\r\nfunction LimitedTable:insert(\r\n    value: any,\r\n    array: LimitedTableTable?,\r\n    position: number?,\r\n    apply: boolean?\r\n): number\r\n```\r\n\r\nInserts **`value`** at given **`position`** of **`array`** and returns the size of the changes. If **`position`** is not provided, inserts to the end of the **`array`**.\r\n\r\n**`array`** defaults to `LimitedTable.table`. Optional parameter **`apply`** determines whether to apply given changes.\r\n\r\nExample:\r\n\r\n```lua\r\nlocal lt = LimitedTable.new(512000)\r\n\r\nfor i = 1, 10 do\r\n    lt:insert(\"Hello, world!\")\r\nend\r\n\r\nlt:set(\"reversed\", {})\r\nfor i = 10, 1, -1 do\r\n    lt:insert(i, lt.table.reversed, 1)\r\nend\r\n```\r\n\r\n#### :remove\r\n\r\n```lua\r\nfunction LimitedTable:remove(\r\n    array: LimitedTableTable?,\r\n    position: number?,\r\n    apply: boolean?\r\n): number\r\n```\r\n\r\nRemoves element at given **`position`** from **`array`** and returns the size of the changes. If **`position`** is not provided, removes the last element from the **`array`**.\r\n\r\n**`array`** defaults to `LimitedTable.table`. Optional parameter **`apply`** determines whether to apply given changes.\r\n\r\nExample:\r\n\r\n```lua\r\nlocal lt = LimitedTable.new(512000)\r\nlt:set(\"myArray\", {\r\n    \"milk\",\r\n    \"eggs\",\r\n    \"cheese\",\r\n})\r\n\r\nlt:remove(lt.table.myArray) -- remove last element\r\nlt:remove(lt.table.myArray, 1)\r\n\r\nprint(lt.table.myArray) --> { \"eggs\" }\r\n```\r\n\r\n#### :cloneRaw\r\n\r\n```lua\r\nfunction LimitedTable:cloneRaw(\r\n    table: LimitedTableTable?\r\n): { [any]: any }\r\n```\r\n\r\nReturns a deep copy of **`table`**, with all LimitedTable tables replaced by normal ones.\r\n\r\n**`table`** defaults to `LimitedTable.table`.\r\n\r\nExample:\r\n\r\n```lua\r\nlocal lt = LimitedTable.new(512000)\r\nlt:set(\"t\", { 1, 2, 3 })\r\n\r\nlocal raw = lt:cloneRaw(lt.table.t)\r\nprint(raw) --> { 1, 2, 3 }\r\nprint(raw == lt.table.t) --> false\r\n```\r\n\r\n#### :destroy\r\n\r\n```lua\r\nfunction LimitedTable:destroy(): ()\r\n```\r\n\r\nDestroys LimitedTable. Make sure to clear up **all** references!\r\n\r\nExample:\r\n\r\n```lua\r\nlocal lt = LimitedTable.new(512000)\r\n\r\nlocal references = setmetatable(\r\n    { lt, lt.table },\r\n    { __mode = \"v\" }\r\n)\r\n\r\nlt:destroy()\r\nlt = nil\r\n\r\ntask.wait(5)\r\nprint(`deleted: {#references == 0}!`) --> true (unless something stupid happened)\r\n```\r\n\r\n## Example\r\n\r\nCheck out the example usage of LimitedTable! Clone the Git repo and build the example project:\r\n\r\n```bash\r\nrojo build --output LimitedTableExample.rbxl example.project.json\r\n```\r\n","readmeTruncated":false}