While this is visually what the function does, it actually creates a table with the array part pre-allocated to hold n things (where n is the first argument), optionally filled with the second argument.
The expected document would be something like "Creates a table with the array part pre-allocated to contain n elements, optionally filled with value". It might also be warranted to briefly touch upon the internals of Lua tables to specify what that actually means, but that description alone should work for a brief summary.
For IX team members unfamiliar with the internals of Lua, tables have an array part to them that has a certain size to it. When enough elements are added to that array, the array has to be resized, which can be expensive. This function creates a table that’s already resized to contain n elements behind the curtains, which lets developers avoid the resizing all together.
I understand that the internals of Lua may be considered beyond the scope of the developer hub, but given that this function was intended for a small percentage of developers, it should at least be documented properly.
I definitely concur with this. It’s handy to have explanations that are simple, but verbose enough to give someone experienced in the field understanding of what it does exactly.
In the case of Roblox, using Lua would inherently warrant not explaining the low-down details, but as a result of the newly implemented Luau engine’s functionality, it is imperative that these details get explained since Roblox’s system is now fundamentally different than that of stock Lua.
The key points to bring up is that:
table.createpre-allocates the specified number of elements. One good comparison is C#'s List<T> constructor: See List<T> Constructors: Int32 (and its remarks category just under it).
The proper way to address this is to mention that it is more performant to add n elements to a table created with table.create than it is to add n elements to an empty table.
Tables made with table.create are initialized as arrays, not tables.
One other important detail is to abstract between tables and arrays – tables are lookups - a key can be anything, a value can be anything. Arrays enforce that keys are ordinal values starting from 1 and ending at (number of elements).
I did think about this when I wrote this function description in the first place. At the time I figured it wasn’t important, but on second thought you all are right – this is a pretty important note for performance reasons. I’ll see to it that the description gets a few more details put in.
Do you think it would be worthwhile to have an article explaining the internals of Lua tables?
I’d say it would be worth it, if only for providing the knowledge and expanding on the use of table.create if people are confused or interested. It would also be nice to have that information on the devhub so it can be linked to someone asking instead of directing them to somewhere offsite.
I’ve updated the function description to be a little more technically oriented. I’m going out on a limb here because this function has a unique purpose.
