Added NumberConstrainToIncrement

src/Functions.test.ts

@@ -23,7 +23,7 @@ import {
 	JSONParse,
 	JSONStringToObject,
 	LeastNumber,
-	LeastNumberNull,
+	LeastNumberNull, NumberConstrainToIncrement,
 	ObjectToJSONString,
 	OmitFalsey,
 	OmitProperty,
@@ -445,4 +445,18 @@ describe('DistributeEvenly function', () => {
 		expect(EqualNumber('Test', 1.13)).toEqual(false)
 		expect(EqualNumber('Test', 'Test 2')).toEqual(false)
 	})
+
+	test('Constrain Number to Increment', () => {
+		expect(NumberConstrainToIncrement('1', 0.25)).toEqual(1)
+		expect(NumberConstrainToIncrement('1.26', 0.25)).toEqual(1.25)
+		expect(NumberConstrainToIncrement('1.24', 0.25)).toEqual(1.25)
+		expect(NumberConstrainToIncrement('1.94', 0.25)).toEqual(2)
+		expect(NumberConstrainToIncrement('1.84', 0.25)).toEqual(1.75)
+		expect(NumberConstrainToIncrement('0.12', 0.25)).toEqual(0)
+		expect(NumberConstrainToIncrement('0.13', 0.25)).toEqual(0.25)
+		expect(NumberConstrainToIncrement(10.13, 0.25)).toEqual(10.25)
+		expect(NumberConstrainToIncrement('1.24', 0)).toEqual(1)
+		expect(NumberConstrainToIncrement('1.24', 1)).toEqual(1)
+		expect(NumberConstrainToIncrement('1.24', 2)).toEqual(2)
+	})
 })

src/Functions.ts

@@ -66,6 +66,34 @@ export function IsNumber(value: any): boolean {
 	return val !== null && !isNaN(val)
 }
 
+/**
+ * Constrain a number based on an increment value and round to a given number of decimal places.
+ *
+ * @param {number} num - The input number to be constrained.
+ * @param {number} increment - The value by which the input number should be constrained.
+ * @param {number} [round=2] - The number of decimal places to round the constrained number to. Defaults to 2.
+ * @returns {number | null} - The constrained number or null.
+ */
+export function NumberConstrainToIncrementNull(num: any, increment: number, round = 2) {
+	return CleanNumberNull(num) === null
+		? null
+		: increment == 0
+		? CleanNumber(num, 0)
+		: CleanNumber(Math.round(CleanNumber(num) / CleanNumber(increment)) * CleanNumber(increment), round)
+}
+
+/**
+ * Constrain a number based on an increment value and round to a given number of decimal places.
+ *
+ * @param {number} num - The input number to be constrained.
+ * @param {number} increment - The value by which the input number should be constrained.
+ * @param {number} [round=2] - The number of decimal places to round the constrained number to. Defaults to 2.
+ * @returns {number} - The constrained number.
+ */
+export function NumberConstrainToIncrement(num: any, increment: number, round = 2) {
+	return NumberConstrainToIncrementNull(num, increment, round) ?? 0
+}
+
 /**
  * Cleans a number with a symbol like '$', ',' or '%'.
  *
@@ -924,7 +952,10 @@ export function OmitUndefined<T extends object>(obj: T): Partial<T> {
  * @param {...any} keys - The keys of the properties to be picked.
  * @returns {Object} - A new object containing only the specified properties.
  */
-export function PickProperty<T extends Record<any, any>, K extends Extract<keyof T, any>>(obj: T, ...keys: K[]): Pick<T, K> {
+export function PickProperty<T extends Record<any, any>, K extends Extract<keyof T, any>>(
+	obj: T,
+	...keys: K[]
+): Pick<T, K> {
 	let ret: any = {}
 
 	for (let key of keys) {