@kaelyx/ts-kit / number / clamp

Function: clamp()

clamp(input, options): number | undefined

Defined in: number/clamp/clamp.ts:31

Clamps a number within the specified minimum and maximum bounds.

An input of NaN or undefined, or a bound of NaN, is an invalid value. By default an invalid value gives NaN. Set strict to true to use strictBehaviour instead.

Parameters

input

number

The number to be clamped.

options

ClampOptions

The options containing the minimum and maximum bounds.

Returns

number | undefined

The clamped number within the specified bounds. Returns NaN for an invalid value when strict is false. Can return undefined for an invalid value when strict is true.

Throws

If min is greater than max.

Example

clamp(5, { min: 1, max: 10 }) // 5
clamp(-3, { min: 1, max: 10 }) // 1
clamp(15, { min: 1, max: 10 }) // 10
clamp(NaN, { min: 1, max: 10 }) // NaN
clamp(NaN, { min: 1, max: 10, strict: true }) // undefined
clamp(NaN, { min: 1, max: 10, strict: true, strictBehaviour: ClampUndefinedBehaviour.CLAMP_TO_LOWEST }) // 1
clamp(5, { min: 10, max: 1 }) // throws RangeError

Types

ClampUndefinedBehaviour type

ClampUndefinedBehaviour = ValueOf<typeof ClampUndefinedBehaviour>

Defined in: number/clamp/clamp.types.ts:10

Represents what clamp returns for an invalid value when strict is true.

---

ClampOptions interface

Defined in: number/clamp/clamp.types.ts:23

Represents the options for clamping a number within specified bounds.

Properties

max

max: number

Defined in: number/clamp/clamp.types.ts:28

The maximum value allowed. Must not be less than min.

Default

Number.MAX_VALUE

---

min

min: number

Defined in: number/clamp/clamp.types.ts:25

The minimum value allowed. Must not be greater than max.

Default

-Number.MAX_VALUE

---

strict?

optional strict?: boolean

Defined in: number/clamp/clamp.types.ts:34

Whether to use strictBehaviour for an invalid value. When false, an invalid value gives NaN.

Default

false

---

strictBehaviour?

optional strictBehaviour?: "return-undefined" | "clamp-to-lowest" | "clamp-to-highest"

Defined in: number/clamp/clamp.types.ts:40

What to return for an invalid value when strict is true. Has no effect when strict is false.

Default

ClampUndefinedBehaviour.RETURN_UNDEFINED