diff --git a/_data/stdlib_index.json b/_data/stdlib_index.json index 48feea3..db56c8d 100644 --- a/_data/stdlib_index.json +++ b/_data/stdlib_index.json @@ -108723,263 +108723,6 @@ } ] }, - { - "package": "ArrayList", - "category": "data", - "categoryLabel": "Data Structures", - "sourcePath": "wurst/data/ArrayList.wurst", - "githubUrl": "https://github.com/wurstscript/WurstStdlib2/blob/master/wurst/data/ArrayList.wurst", - "summary": "High-performance array-based list using static shared storage per type.\nIn most cases, a LinkedList is a better choice due to its flexibility.\nThis data structure is only recommended for performance-critical code\nand requires careful use to avoid fragmentation.\n\nWHEN TO USE:\n===========\nArrayList is faster than LinkedList for:\n- Iterating large lists (1000+ elements) - no node indirection\n- Index based operations - O(1) vs O(n)\n- When only appending elements to the end\n\nLinkedList is better for:\n- Insertion anywhere except the end of the list\n- Deletions while retaining order\n- Unknown size requirements\n- No resize performance risk\n\nTYPE SYSTEM IMPLICATIONS:\n========================\nEach ArrayList type gets its own static storage array.\n- ArrayList, ArrayList, ArrayList = 3 separate arrays\n- On the Jass target each type holds up to JASS_MAX_ARRAY_SIZE elements total across all\n instances (the Lua target grows dynamically and is not bounded by this)\n\nChoose wisely based on how many types you have.\n\nPERFORMANCE RULES:\n==================\n\n1. PRESIZE, DON'T RESIZE\n Bad: new ArrayList() // Might resize multiple times\n Good: new ArrayList(maxSize) // One allocation\n\n Why: Resize operations copy ALL elements to new memory. Expensive!\n\n2. REUSE, DON'T RECREATE\n Bad: In loop `let temp = new ArrayList() ... destroy temp`\n Good: `let temp = new ArrayList() ... temp.clear()` in loop\n\n Why: Allocation/Deallocation is moderately expensive and causes fragmentation\n\n3. ORDERED REMOVAL IS SLOW\n Bad: list.removeAt(i) // O(n) - shifts all elements\n Good: list.removeAtUnordered(i) // O(1) - swaps with last element\n\n Only use removeAtUnordered() if order doesn't matter\n\n4. ITERATE BY INDEX\n Good: for i = 0 to list.size()-1 // Zero allocation\n Good: list[i] // Indexing operator\n\n ArrayList has no iterator by design - index loops keep hot paths\n allocation-free.\n\n5. AVOID FREQUENT INSERTS AT START\n Bad: list.addtoStart(x) // O(n) every time\n Good: Use LinkedList or add in reverse order\n\nPERFORMANCE TABLE:\n==================\nOperation | ArrayList | LinkedList | Notes\n-------------------|-----------|------------|---------------------------\nadd(elem) | O(1)* | O(1) | *O(n) on resize!\naddtoStart(elem) | O(n) | O(1) | Shifts all elements\nget(index) | O(1) | O(n) | Major ArrayList advantage\nremoveAt(index) | O(n) | O(1) | Shifts remaining elements\nremoveAtUnordered | O(1) | N/A | Doesn't preserve order\nIterate all | Faster | Fast | LinkedList does double the work, but is still fast\nMemory per element | 1 slot | 3 slots | Element + 2 pointers\nCreate/destroy | Varies | High | AL might need memory management, LL needs to process Nodes\n\nMEMORY MANAGEMENT:\n==================\nArrayList uses section allocation in a shared static array per type.\nDestroyed lists return sections to a free pool for reuse.\nFree sections are compacted to reduce fragmentation.\n\nFragmentation occurs when lists grow - the old section becomes a gap.\nThis is why presizing matters: growth = copy to new location = wasted space.\n\nHard limit (wc3 / Jass native target): the shared store is a fixed-size array, so it is\nbounded by JASS_MAX_ARRAY_SIZE total slots per type across all live instances; exceeding\nit raises an error. On the Lua target the store is a dynamically growing table, so the\ncap does not apply - allocateStorage branches on the magic isLua constant and skips the\nerror. ArrayList's added value on Lua is keeping element types static instead of relying\non typecasting.", - "summaryFirstLine": "High-performance array-based list using static shared storage per type.", - "tags": [ - "collection", - "data", - "list" - ], - "imports": [], - "entities": [ - { - "kind": "class", - "name": "ArrayList", - "typeParams": "", - "receiver": null, - "signature": "public class ArrayList", - "doc": "", - "deprecated": { - "flag": false, - "message": null - }, - "configurable": false, - "members": [], - "enumMembers": [], - "line": 98 - }, - { - "kind": "function", - "name": "asArrayList", - "typeParams": "", - "receiver": null, - "signature": "public function asArrayList(vararg T ts) returns ArrayList", - "doc": "", - "deprecated": { - "flag": false, - "message": null - }, - "configurable": false, - "members": [], - "enumMembers": [], - "line": 610 - }, - { - "kind": "interface", - "name": "ArrayListPredicate", - "typeParams": "", - "receiver": null, - "signature": "public interface ArrayListPredicate", - "doc": "", - "deprecated": { - "flag": false, - "message": null - }, - "configurable": false, - "members": [], - "enumMembers": [], - "line": 620 - }, - { - "kind": "interface", - "name": "ALItrClosure", - "typeParams": "", - "receiver": null, - "signature": "public interface ALItrClosure", - "doc": "", - "deprecated": { - "flag": false, - "message": null - }, - "configurable": false, - "members": [], - "enumMembers": [], - "line": 623 - }, - { - "kind": "interface", - "name": "ArrayListUpdater", - "typeParams": "", - "receiver": null, - "signature": "public interface ArrayListUpdater", - "doc": "", - "deprecated": { - "flag": false, - "message": null - }, - "configurable": false, - "members": [], - "enumMembers": [], - "line": 626 - }, - { - "kind": "interface", - "name": "MapClosure", - "typeParams": "", - "receiver": null, - "signature": "public interface MapClosure", - "doc": "", - "deprecated": { - "flag": false, - "message": null - }, - "configurable": false, - "members": [], - "enumMembers": [], - "line": 629 - }, - { - "kind": "interface", - "name": "FoldClosure", - "typeParams": "", - "receiver": null, - "signature": "public interface FoldClosure", - "doc": "", - "deprecated": { - "flag": false, - "message": null - }, - "configurable": false, - "members": [], - "enumMembers": [], - "line": 632 - }, - { - "kind": "interface", - "name": "Comparator", - "typeParams": "", - "receiver": null, - "signature": "public interface Comparator", - "doc": "", - "deprecated": { - "flag": false, - "message": null - }, - "configurable": false, - "members": [], - "enumMembers": [], - "line": 635 - }, - { - "kind": "extension-function", - "name": "sort", - "typeParams": "", - "receiver": "ArrayList", - "signature": "public function ArrayList.sort()", - "doc": "", - "deprecated": { - "flag": false, - "message": null - }, - "configurable": false, - "members": [], - "enumMembers": [], - "line": 643 - }, - { - "kind": "extension-function", - "name": "sort", - "typeParams": "", - "receiver": "ArrayList", - "signature": "public function ArrayList.sort()", - "doc": "", - "deprecated": { - "flag": false, - "message": null - }, - "configurable": false, - "members": [], - "enumMembers": [], - "line": 647 - }, - { - "kind": "extension-function", - "name": "sort", - "typeParams": "", - "receiver": "ArrayList", - "signature": "public function ArrayList.sort()", - "doc": "", - "deprecated": { - "flag": false, - "message": null - }, - "configurable": false, - "members": [], - "enumMembers": [], - "line": 651 - }, - { - "kind": "extension-function", - "name": "joinBy", - "typeParams": "", - "receiver": "ArrayList", - "signature": "public function ArrayList.joinBy(string separator) returns string", - "doc": "Joins elements from a string list into one string using a separator", - "deprecated": { - "flag": false, - "message": null - }, - "configurable": false, - "members": [], - "enumMembers": [], - "line": 659 - }, - { - "kind": "extension-function", - "name": "join", - "typeParams": "", - "receiver": "ArrayList", - "signature": "public function ArrayList.join() returns string", - "doc": "Joins elements from a string list into one string", - "deprecated": { - "flag": false, - "message": null - }, - "configurable": false, - "members": [], - "enumMembers": [], - "line": 668 - }, - { - "kind": "extension-function", - "name": "op_index", - "typeParams": "", - "receiver": "ArrayList", - "signature": "public function ArrayList.op_index(int index) returns T", - "doc": "", - "deprecated": { - "flag": false, - "message": null - }, - "configurable": false, - "members": [], - "enumMembers": [], - "line": 672 - }, - { - "kind": "extension-function", - "name": "op_indexAssign", - "typeParams": "", - "receiver": "ArrayList", - "signature": "public function ArrayList.op_indexAssign(int index, T value)", - "doc": "", - "deprecated": { - "flag": false, - "message": null - }, - "configurable": false, - "members": [], - "enumMembers": [], - "line": 675 - } - ] - }, { "package": "BitSet", "category": "data", @@ -154542,7 +154285,40 @@ "message": null }, "configurable": false, - "members": [], + "members": [ + { + "kind": "function", + "name": "commandButton", + "typeParams": "", + "receiver": null, + "signature": "static function commandButton(int index) returns string", + "doc": "Name of a command card button, index 0 to 11 (1.32+): 0 is the top-left (0,0) button, 11 the\n\t\tbottom-right (3,2). Move/hide via these named frames, not ORIGIN_FRAME_COMMAND_BUTTON (moving\n\t\tthe origin frames glitches in 1.32+). NOTE: command buttons reappear/update on every unit\n\t\tselection, even while hidden via BlzHideOriginFrames - re-hide on selection if needed.", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 103 + }, + { + "kind": "function", + "name": "inventoryButton", + "typeParams": "", + "receiver": null, + "signature": "static function inventoryButton(int index) returns string", + "doc": "Name of an inventory item button, index 0 to 5 (1.32+). Move/hide via these named frames, not\n\t\tORIGIN_FRAME_ITEM_BUTTON (moving the origin frames glitches in 1.32+). NOTE: like command\n\t\tbuttons, they reappear/update on every unit selection.", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 268 + } + ], "enumMembers": [], "line": 58 }, @@ -154560,7 +154336,7 @@ "configurable": false, "members": [], "enumMembers": [], - "line": 476 + "line": 525 } ] }, diff --git a/_doc/stdlib/ref/_wurst/FramehandleNames.md b/_doc/stdlib/ref/_wurst/FramehandleNames.md index dab686c..ffe53ad 100644 --- a/_doc/stdlib/ref/_wurst/FramehandleNames.md +++ b/_doc/stdlib/ref/_wurst/FramehandleNames.md @@ -33,6 +33,18 @@ public class FramehandleDefaultNames These default frames can be obtained with getFrameByName(..) [BlzGetFrameByName] (the createContext (subframe-id) parameter is by default 0, some frames does contain subframes) +**Members:** + +- `static function commandButton(int index) returns string` + Name of a command card button, index 0 to 11 (1.32+): 0 is the top-left (0,0) button, 11 the + bottom-right (3,2). Move/hide via these named frames, not ORIGIN_FRAME_COMMAND_BUTTON (moving + the origin frames glitches in 1.32+). NOTE: command buttons reappear/update on every unit + selection, even while hidden via BlzHideOriginFrames - re-hide on selection if needed. +- `static function inventoryButton(int index) returns string` + Name of an inventory item button, index 0 to 5 (1.32+). Move/hide via these named frames, not + ORIGIN_FRAME_ITEM_BUTTON (moving the origin frames glitches in 1.32+). NOTE: like command + buttons, they reappear/update on every unit selection. + ### FramehandleNames ```wurst diff --git a/_doc/stdlib/ref/data/ArrayList.md b/_doc/stdlib/ref/data/ArrayList.md deleted file mode 100644 index dec1784..0000000 --- a/_doc/stdlib/ref/data/ArrayList.md +++ /dev/null @@ -1,204 +0,0 @@ ---- -title: ArrayList -layout: stdlibref -category: data -categoryLabel: Data Structures -tags: - - collection - - data - - list -source: 'https://github.com/wurstscript/WurstStdlib2/blob/master/wurst/data/ArrayList.wurst' -generated: true ---- - -High-performance array-based list using static shared storage per type. -In most cases, a LinkedList is a better choice due to its flexibility. -This data structure is only recommended for performance-critical code -and requires careful use to avoid fragmentation. - -WHEN TO USE: -=========== -ArrayList is faster than LinkedList for: -- Iterating large lists (1000+ elements) - no node indirection -- Index based operations - O(1) vs O(n) -- When only appending elements to the end - -LinkedList is better for: -- Insertion anywhere except the end of the list -- Deletions while retaining order -- Unknown size requirements -- No resize performance risk - -TYPE SYSTEM IMPLICATIONS: -======================== -Each ArrayList type gets its own static storage array. -- ArrayList, ArrayList, ArrayList = 3 separate arrays -- On the Jass target each type holds up to JASS_MAX_ARRAY_SIZE elements total across all - instances (the Lua target grows dynamically and is not bounded by this) - -Choose wisely based on how many types you have. - -PERFORMANCE RULES: -================== - -1. PRESIZE, DON'T RESIZE - Bad: new ArrayList() // Might resize multiple times - Good: new ArrayList(maxSize) // One allocation - - Why: Resize operations copy ALL elements to new memory. Expensive! - -2. REUSE, DON'T RECREATE - Bad: In loop `let temp = new ArrayList() ... destroy temp` - Good: `let temp = new ArrayList() ... temp.clear()` in loop - - Why: Allocation/Deallocation is moderately expensive and causes fragmentation - -3. ORDERED REMOVAL IS SLOW - Bad: list.removeAt(i) // O(n) - shifts all elements - Good: list.removeAtUnordered(i) // O(1) - swaps with last element - - Only use removeAtUnordered() if order doesn't matter - -4. ITERATE BY INDEX - Good: for i = 0 to list.size()-1 // Zero allocation - Good: list[i] // Indexing operator - - ArrayList has no iterator by design - index loops keep hot paths - allocation-free. - -5. AVOID FREQUENT INSERTS AT START - Bad: list.addtoStart(x) // O(n) every time - Good: Use LinkedList or add in reverse order - -PERFORMANCE TABLE: -================== -Operation | ArrayList | LinkedList | Notes --------------------|-----------|------------|--------------------------- -add(elem) | O(1)* | O(1) | *O(n) on resize! -addtoStart(elem) | O(n) | O(1) | Shifts all elements -get(index) | O(1) | O(n) | Major ArrayList advantage -removeAt(index) | O(n) | O(1) | Shifts remaining elements -removeAtUnordered | O(1) | N/A | Doesn't preserve order -Iterate all | Faster | Fast | LinkedList does double the work, but is still fast -Memory per element | 1 slot | 3 slots | Element + 2 pointers -Create/destroy | Varies | High | AL might need memory management, LL needs to process Nodes - -MEMORY MANAGEMENT: -================== -ArrayList uses section allocation in a shared static array per type. -Destroyed lists return sections to a free pool for reuse. -Free sections are compacted to reduce fragmentation. - -Fragmentation occurs when lists grow - the old section becomes a gap. -This is why presizing matters: growth = copy to new location = wasted space. - -Hard limit (wc3 / Jass native target): the shared store is a fixed-size array, so it is -bounded by JASS_MAX_ARRAY_SIZE total slots per type across all live instances; exceeding -it raises an error. On the Lua target the store is a dynamically growing table, so the -cap does not apply - allocateStorage branches on the magic isLua constant and skips the -error. ArrayList's added value on Lua is keeping element types static instead of relying -on typecasting. - -**[Source on GitHub](https://github.com/wurstscript/WurstStdlib2/blob/master/wurst/data/ArrayList.wurst)** - -## Classes - -### ArrayList - -```wurst -public class ArrayList -``` - -## Interfaces - -### ArrayListPredicate - -```wurst -public interface ArrayListPredicate -``` - -### ALItrClosure - -```wurst -public interface ALItrClosure -``` - -### ArrayListUpdater - -```wurst -public interface ArrayListUpdater -``` - -### MapClosure - -```wurst -public interface MapClosure -``` - -### FoldClosure - -```wurst -public interface FoldClosure -``` - -### Comparator - -```wurst -public interface Comparator -``` - -## Functions - -### asArrayList - -```wurst -public function asArrayList(vararg T ts) returns ArrayList -``` - -## Extension Functions - -### ArrayList.sort - -```wurst -public function ArrayList.sort() -``` - -### ArrayList.sort - -```wurst -public function ArrayList.sort() -``` - -### ArrayList.sort - -```wurst -public function ArrayList.sort() -``` - -### ArrayList.joinBy - -```wurst -public function ArrayList.joinBy(string separator) returns string -``` - -Joins elements from a string list into one string using a separator - -### ArrayList.join - -```wurst -public function ArrayList.join() returns string -``` - -Joins elements from a string list into one string - -### ArrayList.op_index - -```wurst -public function ArrayList.op_index(int index) returns T -``` - -### ArrayList.op_indexAssign - -```wurst -public function ArrayList.op_indexAssign(int index, T value) -``` diff --git a/_doc/stdlib/ref/index.md b/_doc/stdlib/ref/index.md index d93d857..35368f2 100644 --- a/_doc/stdlib/ref/index.md +++ b/_doc/stdlib/ref/index.md @@ -26,7 +26,6 @@ Auto-generated reference for every package in the [Wurst standard library](https ## Data Structures -- [ArrayList](/stdlib/ref/data/ArrayList.html): High-performance array-based list using static shared storage per type. - [BitSet](/stdlib/ref/data/BitSet.html) - [HashList](/stdlib/ref/data/HashList.html): HashLists are used if you require quick contains operations - [HashMap](/stdlib/ref/data/HashMap.html): Generic Table Wrapper