---
name: "toFixedString"
mode: "api"
versionRequirements:
  - { name: "@ray-js/panel-sdk", version: "1.0.0" }
title: "number"
---

## toFixedString

> [VERSION] @ray-js/panel-sdk >= 1.0.0

### Description

Convert a number to a string of the specified length; pad with leading zeros if shorter, truncate from the right if longer

### Parameters

`Params`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `num` | `number` | Yes | Number to convert |
| `count` | `number` | Yes | The fixed length of the target string |

### Return Value

None


### Examples

#### Basic usage

```ts
import { utils } from '@ray-js/panel-sdk';

const { toFixedString } = utils;

toFixedString(111, 5);  // '00111'
toFixedString(-42, 4);  // '-0042'
toFixedString(123456, 3); // '456'
```

---
name: "toFilledString"
mode: "api"
versionRequirements:
  - { name: "@ray-js/panel-sdk", version: "1.0.0" }
title: "number"
---
## toFilledString

> [VERSION] @ray-js/panel-sdk >= 1.0.0

### Description

Convert a number to a string with a specified minimum length; pad with leading zeros if shorter, keep as is if longer

### Parameters

`Params`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `num` | `number` | Yes | Number to convert |
| `count` | `number` | Yes | The minimum length of the target string |

### Return Value

None


### Examples

#### Basic usage

```ts
import { utils } from '@ray-js/panel-sdk';

const { toFilledString } = utils;

toFilledString(111, 5);      // '00111'
toFilledString(-1111111, 5); // '-1111111'
toFilledString(42, 4);       // '0042'
```

---
name: "bytesToHexString"
mode: "api"
versionRequirements:
  - { name: "@ray-js/panel-sdk", version: "1.0.0" }
title: "number"
---
## bytesToHexString

> [VERSION] @ray-js/panel-sdk >= 1.0.0

### Description

Convert a byte array to a hex string

### Parameters

`Params`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `bytes` | `number[]` | Yes | Byte array; each element is an integer from 0 to 255 |

### Return Value

None


### Examples

#### Basic usage

```ts
import { utils } from '@ray-js/panel-sdk';

const { bytesToHexString } = utils;

bytesToHexString([1, 2]);   // '0102'
bytesToHexString([23, 2]);  // '1702'
bytesToHexString([255, 0]); // 'ff00'
```

---
name: "numToByteNumbers"
mode: "api"
versionRequirements:
  - { name: "@ray-js/panel-sdk", version: "1.0.0" }
title: "number"
---
## numToByteNumbers

> [VERSION] @ray-js/panel-sdk >= 1.0.0

> 💡 Applicable to non-negative integers. The result uses big-endian order; for example, 256 converts to [1, 0].

### Description

Convert a decimal integer to a big-endian byte array

### Parameters

`Params`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `num` | `number` | Yes | The decimal integer to convert |
| `bytes` | `number` | No | Minimum byte count (default 2); if the result is shorter than this length, pad zeros on the high-order side |

### Return Value

Type: `number[]`

The corresponding byte array, high-order first; if the value exceeds the width specified by bytes, it will not be truncated

### Examples

#### Basic usage

```ts
import { utils } from '@ray-js/panel-sdk';

const { numToByteNumbers } = utils;

numToByteNumbers(111);      // [0, 111]
numToByteNumbers(1040001);  // [15, 222, 129]
numToByteNumbers(256, 2);   // [1, 0]
```

---
name: "intToHighLow"
mode: "api"
versionRequirements:
  - { name: "@ray-js/panel-sdk", version: "1.0.0" }
title: "number"
---
## intToHighLow

> [VERSION] @ray-js/panel-sdk >= 1.0.0

### Description

Split an integer into an array of high and low bytes

### Parameters

`Params`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `num` | `number` | Yes | Integer to split |

### Return Value

Type: `[number, number]`

A tuple containing [high 8 bits, low 8 bits]

### Examples

#### Basic usage

```ts
import { utils } from '@ray-js/panel-sdk';

const { intToHighLow } = utils;

intToHighLow(2838); // [11, 22]
intToHighLow(5643); // [22, 11]
intToHighLow(256);  // [1, 0]
```

---
name: "inMaxMin"
mode: "api"
versionRequirements:
  - { name: "@ray-js/panel-sdk", version: "1.0.0" }
title: "number"
---
## inMaxMin

> [VERSION] @ray-js/panel-sdk >= 1.0.0

### Description

Clamp a value between a minimum and a maximum

### Parameters

`Params`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `min` | `number` | Yes | Minimum allowed value |
| `max` | `number` | Yes | Maximum allowed value |
| `value` | `number` | Yes | Value to clamp |

### Return Value

None


### Examples

#### Basic usage

```ts
import { utils } from '@ray-js/panel-sdk';

const { inMaxMin } = utils;

inMaxMin(1, 233, 2838); // 233 (exceeds max, returns max)
inMaxMin(2, 0, 1);      // 1 (out of range, but note parameter order min < max)
inMaxMin(0, 100, 50);   // 50 (within range, return as is)
```

---
name: "scaleNumber"
mode: "api"
versionRequirements:
  - { name: "@ray-js/panel-sdk", version: "1.0.0" }
title: "number"
---
## scaleNumber

> [VERSION] @ray-js/panel-sdk >= 1.0.0

### Description

Scale a number by the specified precision and return a string

### Parameters

`Params`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `scale` | `number` | Yes | Scale precision: divide by 10^scale and keep scale decimal places |
| `value` | `number` | Yes | Value to scale |

### Return Value

None


### Examples

#### Basic usage

```ts
import { utils } from '@ray-js/panel-sdk';

const { scaleNumber } = utils;

scaleNumber(2, 10245); // '102.45'
scaleNumber(1, 1024);  // '102.4'
scaleNumber(0, 42);    // '42'
```

---
name: "range"
mode: "api"
versionRequirements:
  - { name: "@ray-js/panel-sdk", version: "1.0.0" }
title: "number"
---
## range

> [VERSION] @ray-js/panel-sdk >= 1.0.0

### Description

Generate an array of numbers within a specified range

### Parameters

`Params`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `start` | `number` | Yes | Start value |
| `end` | `number` | Yes | End value |
| `step` | `number` | No | Step value, defaults to 1 |

### Return Value

Type: `number[]`

Array from start to end, with step as the increment

### Examples

#### Basic usage

```ts
import { utils } from '@ray-js/panel-sdk';

const { range } = utils;

range(0, 3);      // [0, 1, 2]
range(1, 10, 3);  // [1, 4, 7]
range(0, -3, -1); // [0, -1, -2]
```

---
name: "calcPosition"
mode: "api"
versionRequirements:
  - { name: "@ray-js/panel-sdk", version: "1.0.0" }
title: "number"
---
## calcPosition

> [VERSION] @ray-js/panel-sdk >= 1.0.0

### Description

Linearly map a value from one range to another

### Parameters

`Params`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | `number` | Yes | Original value |
| `min` | `number` | Yes | Minimum of the original range |
| `max` | `number` | Yes | Maximum of the original range |
| `newMin` | `number` | Yes | Minimum of the target range |
| `newMax` | `number` | Yes | Maximum of the target range |

### Return Value

None


### Examples

#### Basic usage

```ts
import { utils } from '@ray-js/panel-sdk';

const { calcPosition } = utils;

calcPosition(50, 0, 100, -100, 0);   // -50
calcPosition(255, 0, 255, 0, 100);   // 100
calcPosition(127.5, 0, 255, 0, 100); // 50
```

---
name: "calcPercent"
mode: "api"
versionRequirements:
  - { name: "@ray-js/panel-sdk", version: "1.0.0" }
title: "number"
---
## calcPercent

> [VERSION] @ray-js/panel-sdk >= 1.0.0

### Description

Compute the percentage of a value within a specified range

### Parameters

`Params`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `min` | `number` | Yes | Range minimum |
| `max` | `number` | Yes | Range maximum |
| `value` | `number` | Yes | The value to compute, which will be clamped to [min, max] |
| `offset` | `number` | No | Percentage start offset (0–1), defaults to 0 |

### Return Value

None


### Examples

#### Basic usage

```ts
import { utils } from '@ray-js/panel-sdk';

const { calcPercent } = utils;

calcPercent(0, 100, 50);       // 0.5
calcPercent(25, 255, 25);      // 0
calcPercent(25, 255, 25, 0.1); // 0.1 (with offset)
```

---
name: "getBitValue"
mode: "api"
versionRequirements:
  - { name: "@ray-js/panel-sdk", version: "1.0.0" }
title: "number"
---
## getBitValue

> [VERSION] @ray-js/panel-sdk >= 1.0.0

### Description

Get the bit value at the specified position in a number's binary representation

### Parameters

`Params`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `num` | `number` | Yes | Input number |
| `idx` | `number` | Yes | Bit index (starting from the least significant bit; 0 is the LSB) |

### Return Value

None


### Examples

#### Basic usage

```ts
import { utils } from '@ray-js/panel-sdk';

const { getBitValue } = utils;

// 17 = 10001(2)
getBitValue(17, 0); // 1
getBitValue(17, 1); // 0
getBitValue(17, 4); // 1
```

---
name: "changeBitValue"
mode: "api"
versionRequirements:
  - { name: "@ray-js/panel-sdk", version: "1.0.0" }
title: "number"
---
## changeBitValue

> [VERSION] @ray-js/panel-sdk >= 1.0.0

### Description

Flip the bit at the specified position in a number's binary representation (0 becomes 1, 1 becomes 0)

### Parameters

`Params`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `num` | `number` | Yes | Input number |
| `idx` | `number` | Yes | Bit index (starting from the least significant bit; 0 is the LSB) |

### Return Value

None


### Examples

#### Basic usage

```ts
import { utils } from '@ray-js/panel-sdk';

const { changeBitValue } = utils;

// 17 = 10001(2)
changeBitValue(17, 0); // 16 (10000)
changeBitValue(17, 1); // 19 (10011)
changeBitValue(17, 4); // 1  (00001)
```

---
name: "setBitValueWithOne"
mode: "api"
versionRequirements:
  - { name: "@ray-js/panel-sdk", version: "1.0.0" }
title: "number"
---
## setBitValueWithOne

> [VERSION] @ray-js/panel-sdk >= 1.0.0

### Description

Set the bit at the specified position to 1 in a number's binary representation

### Parameters

`Params`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `num` | `number` | Yes | Input number |
| `idx` | `number` | Yes | Bit index (starting from the least significant bit; 0 is the LSB) |

### Return Value

None


### Examples

#### Basic usage

```ts
import { utils } from '@ray-js/panel-sdk';

const { setBitValueWithOne } = utils;

// 17 = 10001(2)
setBitValueWithOne(17, 0); // 17 (10001), already 1
setBitValueWithOne(17, 1); // 19 (10011)
setBitValueWithOne(17, 5); // 49 (110001)
```

---
name: "setBitValueWithZero"
mode: "api"
versionRequirements:
  - { name: "@ray-js/panel-sdk", version: "1.0.0" }
title: "number"
---
## setBitValueWithZero

> [VERSION] @ray-js/panel-sdk >= 1.0.0

### Description

Set the bit at the specified position to 0 in a number's binary representation

### Parameters

`Params`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `num` | `number` | Yes | Input number |
| `idx` | `number` | Yes | Bit index (starting from the least significant bit; 0 is the LSB) |

### Return Value

None


### Examples

#### Basic usage

```ts
import { utils } from '@ray-js/panel-sdk';

const { setBitValueWithZero } = utils;

// 17 = 10001(2)
setBitValueWithZero(17, 0); // 16 (10000)
setBitValueWithZero(17, 1); // 17 (10001), already 0
setBitValueWithZero(17, 4); // 1  (00001)
```

---
name: "numToHexString"
mode: "api"
versionRequirements:
  - { name: "@ray-js/panel-sdk", version: "1.0.0" }
title: "number"
---
## numToHexString

> [VERSION] @ray-js/panel-sdk >= 1.0.0

### Description

Convert a decimal number to a hex string with the specified minimum length

### Parameters

`Params`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `num` | `number` | Yes | Decimal number to convert |
| `padding` | `number` | No | Minimum hex string length; defaults to 2, pad with leading zeros if shorter |

### Return Value

None


### Examples

#### Basic usage

```ts
import { utils } from '@ray-js/panel-sdk';

const { numToHexString } = utils;

numToHexString(111);    // '6f'
numToHexString(15);     // '0f'
numToHexString(255, 4); // '00ff'
```

---
name: "highLowToInt"
mode: "api"
versionRequirements:
  - { name: "@ray-js/panel-sdk", version: "1.0.0" }
title: "number"
---
## highLowToInt

> [VERSION] @ray-js/panel-sdk >= 1.0.0

### Description

Combine high and low bytes into an integer

### Parameters

`Params`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `high` | `number` | Yes | High 8-bit byte value |
| `low` | `number` | Yes | Low 8-bit byte value |

### Return Value

None


### Examples

#### Basic usage

```ts
import { utils } from '@ray-js/panel-sdk';

const { highLowToInt } = utils;

highLowToInt(11, 22); // 2838
highLowToInt(22, 11); // 5643
highLowToInt(1, 0);   // 256
```

---
name: "add"
mode: "api"
versionRequirements:
  - { name: "@ray-js/panel-sdk", version: "1.0.0" }
title: "number"
---
## add

> [VERSION] @ray-js/panel-sdk >= 1.0.0

> 💡 Multiply by 10 to the power of n first to use integer arithmetic, then divide back to avoid JavaScript floating-point precision loss.

### Description

Accurately add two numbers to avoid floating-point precision issues

### Parameters

`Params`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `number1` | `number` | Yes | First addend |
| `number2` | `number` | Yes | Second addend |

### Return Value

None


### Examples

#### Basic usage

```ts
import { utils } from '@ray-js/panel-sdk';

const { add } = utils;

add(0.1, 0.2);   // 0.3 (instead of 0.30000000000000004)
add(1.005, 0.01); // 1.015
```

---
name: "subtract"
mode: "api"
versionRequirements:
  - { name: "@ray-js/panel-sdk", version: "1.0.0" }
title: "number"
---
## subtract

> [VERSION] @ray-js/panel-sdk >= 1.0.0

> 💡 Multiply by 10 to the power of n first to use integer arithmetic, then divide back to avoid JavaScript floating-point precision loss.

### Description

Accurately subtract two numbers to avoid floating-point precision issues

### Parameters

`Params`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `number1` | `number` | Yes | Minuend |
| `number2` | `number` | Yes | Subtrahend |

### Return Value

None


### Examples

#### Basic usage

```ts
import { utils } from '@ray-js/panel-sdk';

const { subtract } = utils;

subtract(0.3, 0.1);   // 0.2 (instead of 0.19999999999999998)
subtract(1.005, 0.01); // 0.995
```