-
Notifications
You must be signed in to change notification settings - Fork 0
Collections
Pushing data onto arrays is slow. Pushing data onto ds_lists is fast, but ds_lists aren't garbage collected and must be manually destroyed. Collections are my attempt to meet in the middle.
Arrays and lists store their contents in sequential order, which makes the things inside them very fast to access. However, if you were to extend them they need to stay in sequential order. For Arrays this means creating a new array which is one larger than the original array and copying the existing contents into it. As you can imagine, this is slow. ds_lists handle this differently, and allocate extra space which may be filled in later without needing to resize every time. This is obviously preferable, but ds_lists come with the drawback of having to be destroyed when you're finished using them if you don't want a memory leak, which I happen to not like.
That's the long way of saying collections are basically ds_lists re-implemented using arrays.
The demo that comes with collections includes a performance test so you can see how long it takes to perform basic operations on arrays vs lists vs collections, but the exact values will depend on your CPU and memory bandwidth/latency so they're not of much value between individuals.
Instead, here's the performance of lists and collections compared to an array. Lower numbers are obviously better.
| Task | Arrays | Lists | Collections |
|---|---|---|---|
| Adding (Pushing) | 1.00x | 0.012x | 0.33x |
| Delete Element | 1.00x | 0.988x | 1.45x |
| Get | 1.00x | 1.07x | 3.03x |
| Set | 1.00x | 0.941x | 3.32x |
As is often the case, using the YYC dramatically outperforms the VM, particularly with adding. Which is good, because that's the main point.
The main draw of this is fast addition and garbage collection.
Returns: new collection
Creates a new collection.
Returns: N/A
| Parameter | Type | Description |
|---|---|---|
| collection | ds_collection | The collection to add to |
| value... | * | The data to add to the collection |
Add stuff to the collection.
| Parameter | Type | Description |
|---|---|---|
| collection | ds_collection | The collection to convert to an array |
Returns: N/A
Returns an array containing everything in the collection.
| Parameter | Type | Description |
|---|---|---|
| collection | ds_collection | The collection to clear |
Returns: N/A
Clears the collection. Everything that used to be in it will be gone.
| Parameter | Type | Description |
|---|---|---|
| collection | ds_collection | The collection to delete from |
| index | int | The index in the collection to delete |
Returns: N/A
Removes the item at the specified index in the collection. Everything after will be shifted down.
| Parameter | Type | Description |
|---|---|---|
| collection | ds_collection | The collection to delete from |
| value | * | The value to search for and delete |
Returns: N/A
Searches the collection sequentially for the specified value. If found, it will be deleted. If there are more than one of the same item in the collection, the first one will be deleted.
| Parameter | Type | Description |
|---|---|---|
| collection | ds_collection | The collection to return a value from |
| index | int | The index in the collection to return the value of |
Returns: *
Returns the value stored at the specified index.
| Parameter | Type | Description |
|---|---|---|
| collection | ds_collection | The collection to pop the top element from |
Returns: *
Removes the last element form the collection, and returns it.
| Parameter | Type | Description |
|---|---|---|
| collection | ds_collection | The collection to set a value in |
| index | int | The index in the collection to set the value of |
| value | * | The value to be set |
Returns: N/A
God, I hate writing documentation.
| Parameter | Type | Description |
|---|---|---|
| collection | ds_collection | The collection to evaluate the size of |
Returns: integer
Returns the number of elements in the collection. (This is not necessarily the same as the amount of space allocated for the collection.)
Depending on your usage, you may wish to delete elements by setting them to undefined (and keeping a separate insertion index) without shifting the remaining elements down. (This is useful for things such as indexing instances or structs, where checking for undefined elements is trivial.)
There are a few settings you can mess with.
The starting size which collections are initialized to. The default is 100; this should be fine. Using a smaller initial size will cause collections to re-allocate memory more frequently.
Whether to show warnings for certain invalid operations (e.g. trying to read outside the bounds of a collection) or not. Turning these off will cause the program to crash with the expected error messages instead.