docs(stdlib): regenerate API reference

_doc/stdlib/ref/_handles/Integer.md

@@ -10,6 +10,10 @@ generated: true
 toc: sections
 ---
 
+Returns this int to the power of the argument int.
+	A negative exponent yields 1, since the true result is not an integer.
+	Overflow wraps silently.
+
 **[Source on GitHub](https://github.com/wurstscript/WurstStdlib2/blob/master/wurst/_handles/primitives/Integer.wurst)**
 
 ## Extension Functions
@@ -62,14 +66,21 @@ public function int.toString() returns string
 
 Returns the string representation of this int
 
+### int.toStringOrdinal
+
+```wurst
+public function int.toStringOrdinal() returns string
+```
+
+Returns this int with its English ordinal suffix, e.g. 1 -> "1st", 2 -> "2nd", 3 -> "3rd", 4 -> "4th".
+	Handles the 11/12/13 exceptions correctly.
+
 ### int.pow
 
 ```wurst
 public function int.pow(int x) returns int
 ```
 
-Returns this int to the power of the argument int
-
 ### int.lerp
 
 ```wurst

_doc/stdlib/ref/_handles/Real.md

@@ -24,7 +24,7 @@ The arctangent function with two arguments.
 public function real.abs() returns real
 ```
 
-Returns the abolsute value of the given real.
+Returns the absolute value of the given real.
 This means, negative values will be return positive.
 
 ### real.squared

_doc/stdlib/ref/_handles/Rect.md

@@ -140,6 +140,33 @@ public function rect.remove()
 public function rect.copy() returns rect
 ```
 
+### rect.toRegion
+
+```wurst
+public function rect.toRegion() returns region
+```
+
+Converts this rect to a region.
+	WARNING: Creates a new region; caller owns it and must call .destr() to avoid a handle leak.
+
+### rect.fromCenter
+
+```wurst
+public function rect.fromCenter(real sizeX, real sizeY) returns rect
+```
+
+Creates a rect centered at this rect's center with the given full width and height.
+	Example: A rect at (100,100) with sizeX=20, sizeY=30 spans from (90,85) to (110,115).
+
+### rect.fromCenterWithOffset
+
+```wurst
+public function rect.fromCenterWithOffset(real sizeX, real sizeY, vec2 offset) returns rect
+```
+
+Creates a rect centered at this rect's center plus offset, with the given full width and height.
+	Example: A rect at (100,100) with offset (10,0), sizeX=20, sizeY=30 spans from (100,85) to (120,115).
+
 ### rect.setRectFromLoc
 
 ```wurst

_doc/stdlib/ref/_handles/String.md

@@ -61,7 +61,15 @@ public class StringLines
 public function stringCompare(string s1, string s2) returns int
 ```
 
-Returns an integer result based on a lexicographic string comparison of strings s1 and s2.
+Returns a negative number if s1 sorts before s2, a positive number if it
+sorts after, and 0 only if the two strings are equal.
+
+Alphanumerics keep their long standing order: digits, then lowercase, then
+uppercase, so "Hello" sorts after "hello". Every other printable ascii
+character sorts after all alphanumerics, ordered by ascii code point among
+themselves. Bytes outside printable ascii - control characters and the
+individual bytes of multibyte characters - sort last, tie-broken by string
+hash so the result stays consistent.
 
 ## Extension Functions
 
@@ -230,23 +238,23 @@ True when string contains only lowercase letters
 public function string.trim() returns string
 ```
 
-Returns the given string with whitespaces removed from both ends
+Returns the given string with whitespace (" ", \n, \t, \r) removed from both ends
 
 ### string.ltrim
 
 ```wurst
 public function string.ltrim() returns string
 ```
 
-Returns the given string with whitespaces removed from the left end
+Returns the given string with whitespace (" ", \n, \t, \r) removed from the left end
 
 ### string.rtrim
 
 ```wurst
 public function string.rtrim() returns string
 ```
 
-Returns the given string with whitespaces removed from the right end
+Returns the given string with whitespace (" ", \n, \t, \r) removed from the right end
 
 ### string.ltrim
 

_doc/stdlib/ref/_handles/Unit.md

@@ -1386,6 +1386,16 @@ public function unit.disableAbility(int abilId, boolean flag, boolean hideUI)
 public function unit.disableAttack(boolean flag, boolean hideUI)
 ```
 
+### unit.disableAttackEx
+
+```wurst
+public function unit.disableAttackEx(int index, bool flag)
+```
+
+Enables/disables a single weapon by index (0 = the unit's first/regular attack).
+	Unlike disableAttack this toggles the weapon field directly, so it can disable one
+	weapon on a multi-weapon unit without hiding the attack command.
+
 ### unit.disableWorkQueue
 
 ```wurst

_doc/stdlib/ref/closures/ClosureForGroups.md

@@ -13,9 +13,9 @@ toc: sections
 curated: /stdlib/closure_for_groups
 ---
 
-Executes the given closure for every unit in this group,
-	removing the units from the group as processed.
-	Return true to continue iteration, false to stop.
+Executes the given closure for every unit of the given type.
+	Stops invoking the closure after *count* units. The underlying enumeration
+	cannot be aborted, so it still visits every match.
 
 **[Source on GitHub](https://github.com/wurstscript/WurstStdlib2/blob/master/wurst/closures/ClosureForGroups.wurst)**
 
@@ -72,9 +72,6 @@ Executes the given closure for every unit of the given type.
 public function forUnitsOfTypeCounted(string unitname, int count, ForGroupCallback c)
 ```
 
-Executes the given closure for every unit of the given player.
-	Cancels itself after *count* iterations
-
 ### forUnitsOfPlayer
 
 ```wurst
@@ -106,7 +103,8 @@ public function forUnitsInRectCounted(rect r, int count, ForGroupCallback c)
 ```
 
 Executes the given closure for every unit in the given rect.
-	Cancels itself after *count* iterations
+	Stops invoking the closure after *count* units. The underlying enumeration
+	cannot be aborted, so it still visits every unit in the rect.
 
 ### forUnitsInRange
 
@@ -131,8 +129,9 @@ Executes the given closure for every unit in range of the given position
 public function forUnitsInRangeCounted(vec2 pos, real radius, int count, ForGroupCallback c)
 ```
 
-Executes the given closure for every unit in range of the given position
-	Cancels itself after *count* iterations
+Executes the given closure for every unit in range of the given position.
+	Stops invoking the closure after *count* units. The underlying enumeration
+	cannot be aborted, so it still visits every unit in range.
 
 ### forUnitsSelected
 
@@ -212,7 +211,7 @@ public function forDestructablesInRange(vec2 pos, real range, ForGroupCallbackD
 ```
 
 Executes the given closure for all destructables in a rect
-	that incompasses the circle with the range radius at the given position.
+	that encompasses the circle with the range radius at the given position.
 
 ### forDestructablesInRange
 
@@ -221,7 +220,7 @@ public function forDestructablesInRange(vec2 pos, real range, boolexpr filter, F
 ```
 
 Executes the given closure for all destructables in a rect
-	that incompasses the circle with the range radius at the given position.
+	that encompasses the circle with the range radius at the given position.
 
 ### forDestructablesInRect
 
@@ -245,7 +244,7 @@ Executes the given closure for all destructables in the given rect
 public function forNearestDestructable(vec2 pos, real range, ForGroupCallbackD c)
 ```
 
-Executes the given closure for the closes destructable in the given rect.
+Executes the given closure for the closest destructable in the given range.
 	If there is no destructable in range, the closure will be run with "null"
 
 ## Extension Functions
@@ -274,6 +273,10 @@ Executes the given closure for every unit in this group,
 public function group.forEachFromUntil(ForGroupCallbackUntil cb)
 ```
 
+Executes the given closure for every unit in this group,
+	removing the units from the group as processed.
+	Return true to continue iteration, false to stop.
+
 ### group.forEachInUntil
 
 ```wurst

_doc/stdlib/ref/closures/ClosureTimers.md

@@ -49,6 +49,10 @@ public abstract class CallbackPeriodic
 **Members:**
 
 - `abstract function call(thistype cb)`
+- `disable()`
+  Pauses this periodic callback without destroying it. Safe to call when already disabled.
+- `enable()`
+  Resumes a previously disabled periodic callback. Safe to call when already enabled.
 
 ### CallbackCounted
 
@@ -61,9 +65,14 @@ public abstract class CallbackCounted
 - `abstract function call(thistype cb)`
 - `isLast() returns boolean`
 - `getCount() returns int`
+  The number of this call, counting down: maxCount on the first call and
+  		1 on the last. Returns maxCount before the first call.
 - `progress() returns real`
-  Returns a value between 0 and 1.
+  Progress through the run as a value between 0 and 1.
+  		Returns 0 if the callback was started with a call count of 0.
 - `stop()`
+  Stops the callback. The remaining calls are skipped and the object is
+  		destroyed on the next tick, not immediately.
 - `callAndCount()`
 
 ## Interfaces

_doc/stdlib/ref/data/ArrayList.md

@@ -197,3 +197,23 @@ public function ArrayList<string>.join() returns string
 ```
 
 Joins elements from a string list into one string
+
+## Constants
+
+### intComparator
+
+```wurst
+public constant Comparator<int> intComparator = (i1, i2) -> i1 < i2 ? -1 : (i1 > i2 ? 1 : 0)
+```
+
+### realComparator
+
+```wurst
+public constant Comparator<real> realComparator = (r1, r2) -> r1 < r2 ? -1 : (r1 > r2 ? 1 : 0)
+```
+
+### stringComparator
+
+```wurst
+public constant Comparator<string> stringComparator = (s1, s2) -> stringCompare(s1, s2)
+```

_doc/stdlib/ref/data/HashList.md

@@ -57,7 +57,8 @@ public class HashList<T>
 - `isEmpty() returns bool`
   Return whether the list is empty
 - `get(int index) returns T`
-  Get the element at the given index from this list
+  Get the element at the given index from this list.
+  		Indices outside [0, size) are not validated and yield the null/zero value.
 - `has(T elem) returns bool`
   Return whether the element exists in the list
 - `hasAt(int index) returns bool`
@@ -71,7 +72,9 @@ public class HashList<T>
 - `staticItr() returns HLIterator<T>`
   get the static iterator for this list
 - `removeIf(RemovePredicate<T> predicate)`
-  Removes the element if the predicates returns true
+  Removes the element if the predicates returns true.
+  		Single pass compaction - removing through the iterator instead would
+  		shift the tail once per removal, making this O(n^2).
 - `getRandomElement() returns T`
 
 ### HLIterator

_doc/stdlib/ref/data/HashMap.md

@@ -64,7 +64,9 @@ Iterable generic Table Wrapper
 - `override function flush()`
   Remove all data from this map
 - `override function getAndRemove(K key) returns V`
-  Retrieves the value saved under the given key and removes it
+  Retrieves the value saved under the given key and removes it.
+  		super.getAndRemove dispatches back into this class's remove(), which
+  		already drops the key, so no second keys.remove() is needed here.
 - `iterator() returns HLIterator<K>`
   Returns an iterator that iterates over the map's keys
 - `hasKey(K key) returns bool`

_doc/stdlib/ref/data/LinkedList.md

@@ -48,17 +48,19 @@ public class LinkedList<T>
   		It does not add/remove elements internally, only the internal pointers of the list nodes are re-pointed.
   		The other list will be empty, but not destroyed.
 - `get(int index) returns T`
-  Returns the element at the specified index
+  Returns the element at the specified index.
+  		Errors if the index is outside [0, size).
 - `indexOf(T t) returns int`
   Returns the index of the specified element or -1 is it doesn't exist
 - `set(int index, T elem)`
-  Sets the element at the specified index
+  Sets the element at the specified index.
+  		Errors if the index is outside [0, size).
 - `push(T elem)`
   Adds an element to the end of the list (top of stack, beginning of queue)
 - `getFirst() returns T`
-  Returns the first element in the list
+  Returns the first element in the list, or null if it is empty
 - `getLast() returns T`
-  Returns the last element in the list
+  Returns the last element in the list, or null if it is empty
 - `dequeue() returns T`
   Returns and removes the first added Element (FIFO)
 - `pop() returns T`
@@ -101,24 +103,29 @@ public class LinkedList<T>
 - `updateAll(LinkedListUpdater<T> f)`
   Updates all elements
 - `shuffle()`
-  Performs a Fisher–Yates shuffle on this list
+  Performs a Fisher-Yates shuffle on this list.
+  		Permutes the elements in place - no nodes are destroyed or reallocated.
 - `getRandomElement() returns T`
-  Returns a random element from this list or null, if empty
+  Returns a random element from this list, or null if it is empty
 - `addAt(T elem, int index)`
-  Adds the given element directly behind the element at the given index
+  Inserts the given element at the given index, shifting the element that
+  		was there (and everything after it) one position to the right.
+  		An index equal to the list's size appends to the end.
 - `sortWith(Comparator<T> comparator)`
   Sorts the list according the the comparator using merge sort
 - `map<Q>(MapClosure<T, Q> itr) returns LinkedList<Q>`
   Returns the list obtained by applying the given closure to each element of the original list
 - `filter(LinkedListPredicate<T> predicate) returns LinkedList<T>`
-  Returns a new list of the elements that satisfy the predicate
+  Returns a new list of the elements that satisfy the predicate.
+  		Builds the result directly instead of copying and pruning, so only the
+  		matching elements are ever allocated.
 - `foldl<Q>(Q startValue, FoldClosure<T, Q> predicate) returns Q`
   'Folds' this list into a single value of type Q
   		Example int-list sum: `list.foldl<int>(0, (i, q) -> q + i)`
 - `find(LinkedListPredicate<T> predicate) returns T`
   Returns the first element that satisfies the predicate, or null if none present
 - `toString() returns string`
-  Prints the content of the list
+  Prints the content of the list. Only meaningful for int-like element types.
 - `clear()`
   Removes all elements from the list
 

_doc/stdlib/ref/data/LinkedListModule.md

@@ -28,7 +28,9 @@ public module LinkedListModule
 - `construct()`
 - `static function getFirst() returns thistype`
 - `getNext() returns thistype`
+  The next instance, wrapping around to the first one at the end of the list
 - `getPrev() returns thistype`
+  The previous instance, wrapping around to the last one at the start of the list
 - `remove()`
 - `static function iterator() returns Iterator`
   An iterator which iterates over all instances of this class