refactor - NSS - metaoperators, illion, exponentials, normalization

Added .pause for pausing the progress bar animations as if halted.

Author: blueshank-gh

docs/platforms/garrysmod/libraries/nss.md

@@ -8,26 +8,31 @@ Big-integer helper built on 32-bit words for arbitrary-size numeric storage, con
 Static constructors and coercion helpers exposed directly on the `nss` class.
 
 - `#!ts nss.fromNumber(num: number): nss.object`\
-Builds an NSS value from a Lua number.
+Builds an NSS value from a Lua number.\
+Throws if `num` is `NaN`, `+inf`, or `-inf`.
 
 - `#!ts nss.fromBinary(str: string): nss.object`\
 Builds an NSS value from a binary string.\
-Non-binary characters are ignored.
+An optional `0b`/`0B` prefix is stripped. Throws on non-binary characters.
 
 - `#!ts nss.fromString(str: string): nss.object`\
 Builds an NSS value from a decimal string.\
-Non-digit characters are ignored.
+An optional leading sign (`+`/`-`) is accepted. Throws on non-digit characters.
 
 - `#!ts nss.fromHex(hex: string): nss.object`\
 Builds an NSS value from a hexadecimal string.\
-Non-hex characters are ignored.
+An optional `0x`/`0X` prefix is stripped. Throws on non-hex characters.
 
 - `#!ts nss.fromTable(words: number[]): nss.object`\
 Builds an NSS value from its raw 32-bit word array.
 
 - `#!ts nss.fromAny(value: any): nss.object`\
 Coerces supported input into an NSS value.\
-Accepts existing `nss` objects, numbers, and strings.
+Accepts existing `nss` objects, numbers, strings (decimal, `0x…` hex, `0b…` binary), and raw word tables.
+
+- `#!ts nss.getIllionName(index: number): string`\
+Returns the short-scale illion name for the given group index (e.g. `1` → `"million"`, `2` → `"billion"`).\
+Supports arbitrarily large indices using Conway–Wechsler notation.
 
 ## Object
 Instances are created through the static helpers above or the underlying class constructor.
@@ -50,6 +55,10 @@ Removes and returns the raw word at an index.
 - `#!ts nss:resize(size: number)`\
 Truncates or zero-pads the internal word array to the requested size.
 
+- `#!ts nss:size(absolute?: boolean): number`\
+Returns the number of stored 32-bit words.\
+When `absolute` is `true`, returns the total addressable bit count minus one (`words * 32 - 1`).
+
 - `#!ts nss:clone(): nss.object`\
 Returns a copy of the current value.
 
@@ -59,32 +68,78 @@ Removes leading zero words while preserving a single zero word for empty values.
 - `#!ts nss:isZero(): boolean`\
 Returns whether the value is numerically zero.
 
+- `#!ts nss:isNegative(): boolean`\
+Returns whether the value is negative (non-zero and sign is `-1`).
+
+- `#!ts nss:isOdd(): boolean`\
+Returns whether the value is odd.
+
+- `#!ts nss:isEven(): boolean`\
+Returns whether the value is even.
+
+- `#!ts nss:applySign(sign: number): self`\
+Sets the sign to `-1` if `sign == -1`, otherwise `1`, then normalizes.
+
+- `#!ts nss:abs(): nss.object`\
+Returns a copy of the value with a positive sign.
+
+- `#!ts nss:negate(): nss.object`\
+Returns a copy of the value with the sign flipped.\
+Zero always remains positive.
+
 - `#!ts nss:bitlen(): number`\
 Returns the effective bit length of the value.
 
+- `#!ts nss:compareAbs(other: any): -1 | 0 | 1`\
+Compares the absolute magnitudes of this value and another coerced value.\
+Returns `-1`, `0`, or `1`.
+
 - `#!ts nss:compare(other: any): -1 | 0 | 1`\
-Compares this value against another coerced value.
+Compares this signed value against another coerced value.\
+Returns `-1`, `0`, or `1`.
 
-- `#!ts nss:divmodSmall(divisor: number): [nss.object, number]`\
-Divides by a small Lua number and returns quotient plus remainder.
+- `#!ts nss:isWithin(limit: any): boolean`\
+Returns `true` if this value is less than or equal to `limit`.\
+Alias: `fitsWithin`.
+
+- `#!ts nss:exceeds(limit: any): boolean`\
+Returns `true` if this value is greater than `limit`.\
+Alias: `exceedsLimit`.
+
+- `#!ts nss:bound(limit: any, fallback?: any): nss.object | nil, boolean`\
+Returns `(clone, true)` if this value is within `limit`.\
+Returns `(fallback, false)` if it exceeds `limit` and a fallback is given, otherwise `(nil, false)`.\
+Alias: `limit`.
+
+- `#!ts nss:divmodSmall(divisor: number): nss.object, number`\
+Divides by a small Lua number and returns the quotient and the integer remainder.
 
 - `#!ts nss:toNumber(): number`\
 Converts the value back into a Lua number.\
 Large values can exceed normal number precision.
 
-- `#!ts nss:toString(group?: number): string`\
-Returns a decimal string representation.\
-When `group` is provided, spaces are inserted every `group` characters.
+- `#!ts nss:toString(): string`\
+Returns a decimal string representation.
 
-- `#!ts nss:toBinary(group?: number): string`\
-Returns a binary string representation.\
-When `group` is provided, spaces are inserted every `group` characters.
+- `#!ts nss:toBinary(): string`\
+Returns a binary string representation.
 
 - `#!ts nss:toHex(): string`\
 Returns an uppercase hexadecimal string representation.
 
 - `#!ts nss:toTable(): number[]`\
-Returns a copy of the internal word array.
+Returns a copy of the internal word array.\
+Negative values include a `sign = -1` field.
+
+- `#!ts nss:toScientific(decimals?: number): string`\
+Returns a scientific-notation string (e.g. `"1.23e6"`).\
+`decimals` defaults to `3`. Trailing fractional zeros are stripped.\
+Alias: `toExponential`.
+
+- `#!ts nss:toNamed(decimals?: number): string`\
+Returns a short-scale named string (e.g. `"1.2 million"`).\
+`decimals` defaults to `1`. Values below one thousand are returned as plain decimal.\
+Alias: `toShortScale`.
 
 ## Bitwise
 All operands are coerced with `nss.fromAny(...)` and return new NSS objects.
@@ -121,11 +176,22 @@ Multiplies two values using 32-bit word multiplication.
 
 - `#!ts nss:div(other: any): nss.object`\
 Returns the integer quotient of division.\
-Division by zero yields `0`.
+Throws on divide by zero.
+
+- `#!ts nss:divmod(other: any): nss.object, nss.object`\
+Returns the integer quotient and signed remainder as two values.\
+Throws on divide by zero.
+
+- `#!ts nss:divmodAbs(other: any): nss.object, nss.object`\
+Returns the quotient and remainder of the absolute magnitudes as two values.\
+Throws on divide by zero.
+
+- `#!ts nss:mod(other: any): nss.object`\
+Returns the signed remainder of division.
 
 - `#!ts nss:pow(other: any): nss.object`\
-Raises the value to an exponent.\
-The exponent is converted through `toNumber()`, so very large exponents are not practical.
+Raises the value to an exponent using binary exponentiation.\
+Throws if the exponent is negative.
 
 - `#!ts nss:factorial(limit?: number): nss.object`\
 Returns `n!`.\

docs/stylesheets/extra.css

@@ -141,3 +141,13 @@
     background-position: 4rem 0;
   }
 }
+
+.paused .progress-bar {
+  animation: progress-paused 2s ease-in-out infinite;
+  background-color: #ff1744;
+}
+
+@keyframes progress-paused {
+  0%, 100% { background-color: #ff1744; }
+  50%       { background-color: #4a0010; }
+}