@rbxts/abbreviate 3.0.4 → 3.0.5

package/README.md

@@ -1,98 +1,56 @@
-# @rbxts/abbreviate
-
-[![NPM](https://nodei.co/npm/@rbxts/abbreviate.png)](https://npmjs.org/package/@rbxts/abbreviate)
-
-## Installation:
-```npm i @rbxts/abbreviate```
-
-## Example Usage
-```typescript
-import Abbreviator from "@rbxts/abbreviate";
-
-const abbreviator = new Abbreviator();
-abbreviator.setSetting('suffixTable', ['k', 'm', 'b']);
-abbreviator.setSetting('decimalPlaces', 2);
-
-print(abbreviator.stringToNumber('500')) // 500
-print(abbreviator.stringToNumber('5k')) // 5000
-print(abbreviator.stringToNumber('5m')) // 5000000
-print(abbreviator.stringToNumber('1.23456m')) // 1234560
-
-print(abbreviator.numberToString(999)) // 999
-print(abbreviator.numberToString(1000)) // 1.00k
-print(abbreviator.numberToString(1000000)) // 1.00m
-print(abbreviator.numberToString(1234567)) // 1.23m
-```
-
-## Settings
-The possible settings you can set are the following:
-| Setting Name | Setting Value Type | Setting Description | Setting Default | Setting Example
-|---|---|---|---|---|
-| suffixTable | Array\<string\> | Sets the suffix table to be used when using `numberToString` | [here](https://github.com/OverHash/Roblox-TS-Libraries/blob/master/abbreviate/init.lua#L1-L52) 	| <pre lang="ts">["k", "m", "b"] |
-| decimalPlaces | number | Sets the amount of decimal places a number may have when using `numberToString` | 2 | 4 |
-| stripTrailingZeroes | boolean | Removes any extra zeroes after a decimal place that are dangling after `numberToString` calls. E.g. `"52506.004"` => `"5.2506k"` | false | `true`
-
-## Why make `Abbreviator` a class?
-You may want multiple abbreviators throughout your game with different settings, i.e. one module may want only 2 d.p. while another may want 0 d.p
-To solve this, abbreviate requires you to construct a new abbreviator.
-The settings of this abbreviator is independent of other abbreviators.
-
-## Changelog
-
-### 3.0.3
-- Fixed `stripTrailingZeroes` incorrectly showing as `removeDanglingZeroes` in `README.md`
-
-### 3.0.2
-- Added setting default and setting example for `stripTrailingZeroes`
-
-### 3.0.1
-- Fixed `README.md` example being outdated
-- Added `Scyfren` to contributors
-
-### 3.0.0
-- Changed the method to create an abbreviator from `createAbbreviator()` to `abbreviator.new()` (`new Abbreviator()` in TypeScript)
-- Added option `stripTrailingZeroes`
-- Fixed some bugs regarding settings changes
-- Slight speed improvements
-
-### 2.7.3
-- Updated `README.md` to use `createAbbreviator()`
-
-### 2.7.2
-- Refactored internal code to use less memory
-
-### 2.7.1
-- Fixed a case where numbers under 1000 would have their decimal places stripped (e.g. `1.05` would become `1`, `0.5` would become `0`)
-- Added unit tests
-- Made function calls safer (it now validates the type of the data you pass)
-
-### 2.7.0
-- Changed the method used in `numberToString` to be similar to [Zombie Strike's](https://github.com/Kampfkarren/zombie-strike/blob/master/src/shared/ReplicatedStorage/Core/EnglishNumbers.lua) for more accurate rounding.
-
-### 2.6.3
-- Fixed numbers under 1000 not being added to the return result in `numbersToSortedString`.
-
-### 2.6.2
-- Removed prints in `numbersToSortedString`.
-
-### 2.6.1
-- Updated README.md.
-
-### 2.6.0
-- Created `numbersToSortedString`.
-
-### 2.5.0
-- Fixed a bug with `commify` function erroring.
-
-### 2.4.0
-- Added `commify(num: number): string` to convert a string into a comma separated value.
-
-### 2.3.4
-- Fixed `stringToNumber` returning `void` instead of `number`.
-### 2.3.3
-- Fixed numbers under 1000 not being decimal placed correctly when numberToString is called.
-
-## Credits
-[Kampfkarren](http://github.com/Kampfkarren/) - `numberToString` method
-[Corecii](https://github.com/Corecii) - Help with `numbersToSortedString`
-[Scyfren](https://github.com/Scyfren) - Help with `stripTrailingZeroes`
+# @rbxts/abbreviate
+
+[![NPM](https://nodei.co/npm/@rbxts/abbreviate.png)](https://npmjs.org/package/@rbxts/abbreviate)
+
+## Installation:
+
+`npm i @rbxts/abbreviate`
+
+## Example Usage
+
+```typescript
+import Abbreviator from "@rbxts/abbreviate";
+
+const abbreviator = new Abbreviator();
+abbreviator.setSetting("suffixTable", ["k", "m", "b"]);
+abbreviator.setSetting("decimalPlaces", 2);
+
+print(abbreviator.stringToNumber("500")); // 500
+print(abbreviator.stringToNumber("5k")); // 5000
+print(abbreviator.stringToNumber("5m")); // 5000000
+print(abbreviator.stringToNumber("1.23456m")); // 1234560
+
+print(abbreviator.numberToString(999)); // 999
+print(abbreviator.numberToString(1000)); // 1.00k
+print(abbreviator.numberToString(1000000)); // 1.00m
+print(abbreviator.numberToString(1234567)); // 1.23m
+```
+
+## Settings
+
+The possible settings you can set are the following:
+| Setting Name | Setting Value Type | Setting Description | Setting Default | Setting Example
+|---|---|---|---|---|
+| suffixTable | Array\<string\> | Sets the suffix table to be used when using `numberToString` | [here](https://github.com/OverHash/Roblox-TS-Libraries/blob/master/abbreviate/init.lua#L1-L52) | <pre lang="ts">["k", "m", "b"] |
+| decimalPlaces | number | Sets the amount of decimal places a number may have when using `numberToString` | 2 | 4 |
+| stripTrailingZeroes | boolean | Removes any extra zeroes after a decimal place that are dangling after `numberToString` calls. E.g. `"52506.004"` => `"5.2506k"` | false | `true`
+
+## Why make `Abbreviator` a class?
+
+You may want multiple abbreviators throughout your game with different settings, i.e. one module may want only 2 d.p. while another may want 0 d.p
+To solve this, abbreviate requires you to construct a new abbreviator.
+The settings of this abbreviator is independent of other abbreviators.
+
+## Changelog
+
+See [CHANGELOG.md](https://github.com/OverHash/Roblox-TS-Libraries/blob/master/abbreviate/CHANGELOG.md)
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/OverHash/Roblox-TS-Libraries/blob/master/abbreviate/CONTRIBUTING.md)
+
+## Credits
+
+- [Kampfkarren](http://github.com/Kampfkarren/) - `numberToString` method
+- [Corecii](https://github.com/Corecii) - Help with `numbersToSortedString`
+- [Scyfren](https://github.com/Scyfren) - Help with `stripTrailingZeroes`

package/package.json

@@ -1,39 +1,39 @@
-{
-  "name": "@rbxts/abbreviate",
-  "version": "3.0.4",
-  "description": "A lightweight number abbreviator",
-  "main": "src/init.lua",
-  "types": "src/index.d.ts",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/OverHash/Roblox-TS-Libraries/tree/master/abbreviate"
-  },
-  "keywords": [
-    "abbreviate",
-    "roblox",
-    "roblox-ts",
-    "roblox-typescript",
-    "number"
-  ],
-  "author": "OverHash",
-  "license": "mpl-2.0",
-  "bugs": {
-    "url": "https://github.com/OverHash/Roblox-TS-Libraries/issues"
-  },
-  "homepage": "https://github.com/OverHash/Roblox-TS-Libraries/blob/master/abbreviate/README.md",
-  "publishConfig": {
-    "access": "public"
-  },
-  "files": [
-    "src/init.lua",
-    "src/index.d.ts",
-    "src/commify.lua",
-    "src/numbersToSortedString.lua",
-    "src/numberToString.lua",
-    "src/setSetting.lua",
-    "src/stringToNumber.lua"
-  ]
-}
+{
+  "name": "@rbxts/abbreviate",
+  "version": "3.0.5",
+  "description": "A lightweight number abbreviator",
+  "main": "src/init.lua",
+  "types": "src/index.d.ts",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/OverHash/Roblox-TS-Libraries/tree/master/abbreviate"
+  },
+  "keywords": [
+    "abbreviate",
+    "roblox",
+    "roblox-ts",
+    "roblox-typescript",
+    "number"
+  ],
+  "author": "OverHash",
+  "license": "mpl-2.0",
+  "bugs": {
+    "url": "https://github.com/OverHash/Roblox-TS-Libraries/issues"
+  },
+  "homepage": "https://github.com/OverHash/Roblox-TS-Libraries/blob/master/abbreviate/README.md",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src/init.luau",
+    "src/index.d.ts",
+    "src/commify.luau",
+    "src/numbersToSortedString.luau",
+    "src/numberToString.luau",
+    "src/setSetting.luau",
+    "src/stringToNumber.luau"
+  ]
+}

package/src/index.d.ts

@@ -13,7 +13,7 @@ declare class Abbreviator {
 	 * @example
 	 * 10 => "10"
 	 * 10.1234 => "10.1234"
-	 * 1000 => "1,400"
+	 * 1400 => "1,400"
 	 * 123456789 => "123,456,789"
 	 * 1234567890 => "1,234,567,890"
 	 * @param number The number to comma separate
@@ -21,14 +21,31 @@ declare class Abbreviator {
 	commify(number: number): string;
 
 	/**
-	 * Converts a number of full length into a string with a suffix as defined in the prefix table
+	 * Converts a number into an abbreviated string using the configured suffix table.
+	 *
+	 * Defaulting to `roundDown = true` avoids overstating balances in UI (e.g. 1.499k won't display as 1.50k),
+	 * which helps prevent players thinking they can afford a purchase when they cannot.
+	 *
 	 * @param number The number to convert into a abbreviated string
-	 * @param roundDown If the abbreviation should round up or down. @default down.
+	 * @param roundDown If the abbreviation should round up or down. @default true.
+	 * @example
+	 * ```ts
+	 * const abbreviator = new Abbreviator();
+	 *
+	 * abbreviator.numberToString(1000); // "1.00k"
+	 *
+	 * abbreviator.numberToString(1005); // "1.00k" // default will round down
+	 * abbreviator.numberToString(1005, false); // "1.01k"
+	 *
+	 * abbreviator.numberToString(999995, false); // "1.00M"
+	 * ```
 	 */
 	numberToString(number: number, roundDown?: boolean): string;
 
 	/**
-	 * Converts an array of numbers into sorted strings with a suffix as defined in the prefix table
+	 * Converts an array of numbers into sorted strings with a suffix as defined in the prefix table.
+	 * 
+	 * This is often useful when using default Roblox leaderboards, as they otherwise won't sort correctly.
 	 * @param numbers The numbers to abbreviate and sort correctly
 	 * @example
 	 * ```ts

package/src/{init.lua → init.luau}

@@ -1,54 +1,54 @@
 local DEFAULT_SUFFIX_TABLE = {
-	'k',
-	'M',
-	'B',
-	'T',
-	'Qd',
-	'Qn',
-	'Sx',
-	'Sp',
-	'O',
-	'N',
-	'De',
-	'Ud',
-	'DD',
-	'tdD',
-	'QnD',
-	'SxD',
-	'SpD',
-	'OcD',
-	'NvD',
-	'VgN',
-	'UvG',
-	'DvG',
-	'TvG',
-	'QtV',
-	'QnV',
-	'SeV',
-	'SpG',
-	'OvG',
-	'NvG',
-	'TgN',
-	'UtG',
-	'DtG',
-	'TsTg',
-	'QtTg',
-	'QnTg',
-	'SsTg',
-	'SpTg',
-	'OcTg',
-	'NoTg',
-	'QdDr',
-	'UnAg',
-	'DuAg',
-	'TeAg',
-	'QdAg',
-	'QnAG',
-	'SxAg',
-	'SpAg',
-	'OcAg',
-	'NvAg',
-	'CT'
+	"k",
+	"M",
+	"B",
+	"T",
+	"Qd",
+	"Qn",
+	"Sx",
+	"Sp",
+	"O",
+	"N",
+	"De",
+	"Ud",
+	"DD",
+	"tdD",
+	"QnD",
+	"SxD",
+	"SpD",
+	"OcD",
+	"NvD",
+	"VgN",
+	"UvG",
+	"DvG",
+	"TvG",
+	"QtV",
+	"QnV",
+	"SeV",
+	"SpG",
+	"OvG",
+	"NvG",
+	"TgN",
+	"UtG",
+	"DtG",
+	"TsTg",
+	"QtTg",
+	"QnTg",
+	"SsTg",
+	"SpTg",
+	"OcTg",
+	"NoTg",
+	"QdDr",
+	"UnAg",
+	"DuAg",
+	"TeAg",
+	"QdAg",
+	"QnAG",
+	"SxAg",
+	"SpAg",
+	"OcAg",
+	"NvAg",
+	"CT",
 }
 
 local setSetting = require(script.setSetting).setSetting
@@ -70,5 +70,5 @@ return {
 			stringToNumber = stringToNumber,
 			commify = commify,
 		}
-	end
+	end,
 }

package/src/{numberToString.lua → numberToString.luau}

@@ -21,7 +21,7 @@ end
 
 local function numberToString(self, number, roundDown)
 	if type(number) ~= "number" then
-		error('numberToString invalid parameter #1, expected number, got "nil"', 2)
+		error(`numberToString invalid parameter #1, expected number, got "${type(number)}"`, 2)
 	end
 
 	if roundDown == nil then
@@ -30,11 +30,15 @@ local function numberToString(self, number, roundDown)
 
 	if number < 1000 and number > -1000 then
 		-- special case: we must manually abbreviate numbers between -1000 and 1000
-		if not self._stripTrailingZeroes then
-			return ("%." .. self._decimalPlaces .. "f"):format(number)
+		local rounded = round(number, self._decimalPlaces, roundDown)
+		if math.abs(rounded) < 1000 then
+			if not self._stripTrailingZeroes then
+				return ("%." .. self._decimalPlaces .. "f"):format(rounded)
+			else
+				return tostring(rounded)
+			end
 		else
-			number = round(number, self._decimalPlaces, roundDown)
-			return tostring(number)
+			number = rounded
 		end
 	end
 
@@ -48,9 +52,9 @@ local function numberToString(self, number, roundDown)
 		if size <= number then
 			number = round(number / size, self._decimalPlaces, roundDown)
 
-			if number == 1000 and index < #self._suffixTable[index] then
+			if number == 1000 and index < #self._suffixTable then
 				number = 1
-				unit = self._suffixTable[index][index + 1]
+				unit = self._suffixTable[index + 1]
 			end
 
 			if not self._stripTrailingZeroes then