@oleksii-pavlov/ranges
Version:
The Ranges utils
185 lines (123 loc) • 4.86 kB
Markdown
# Range Utility Library
A utility library for handling and manipulating numerical ranges in JavaScript/TypeScript.
## Installation
Install the package via npm:
```bash
npm install @oleksii-pavlov/ranges
```
## Usage
Import the `Range` class in your code:
```typescript
import { Range } from '@oleksii-pavlov/ranges';
```
## API Reference
### Range Class
#### Constructor
```typescript
constructor(rangeValues: RangeValues)
```
Initializes a `Range` instance with the specified `rangeValues`.
#### Methods
##### `getValues()`
```typescript
getValues(): RangeValues
```
Returns the `RangeValues` object containing the `min` and `max` values of the range.
##### `within(value: number)`
```typescript
within(value: number): number
```
Constrains a given value within the range. If the value is less than the range's `min`, it returns `min`. If the value is greater than the range's `max`, it returns `max`. Otherwise, it returns the value itself.
##### `isGreaterThanMinAndLessThanMax(value: number)`
```typescript
isGreaterThanMinAndLessThanMax(value: number): boolean
```
Checks if the value is within the range `(min, max)` (exclusive).
##### `isGreaterThanMinOrEqualAndLessThanMax(value: number)`
```typescript
isGreaterThanMinOrEqualAndLessThanMax(value: number): boolean
```
Checks if the value is within the range `[min, max)` (inclusive of `min` and exclusive of `max`).
##### `isGreaterThanMinAndLessThanMaxOrEqual(value: number)`
```typescript
isGreaterThanMinAndLessThanMaxOrEqual(value: number): boolean
```
Checks if the value is within the range `(min, max]` (exclusive of `min` and inclusive of `max`).
##### `isGreaterThanMinOrEqualAndLessThanMaxOrEqual(value: number)`
```typescript
isGreaterThanMinOrEqualAndLessThanMaxOrEqual(value: number): boolean
```
Checks if the value is within the range `[min, max]` (inclusive).
##### `getIntersection(rangeValues: RangeValues)`
```typescript
getIntersection(rangeValues: RangeValues): Range | null
```
Returns the intersection of the current range with another range defined by `rangeValues`. If there is no intersection, it returns `null`.
##### `isInRangeOf(rangeValues: RangeValues)`
```typescript
isInRangeOf(rangeValues: RangeValues): boolean
```
Checks if the current range is entirely within another range defined by `rangeValues`.
##### `containsRange(rangeValues: RangeValues)`
```typescript
containsRange(rangeValues: RangeValues): boolean
```
Checks if the current range entirely contains another range defined by `rangeValues`.
### mapValueToRange Function
```typescript
export function mapValueToRange(value: number): RangeValues
```
Maps a single value to a `RangeValues` object where both `min` and `max` are equal to the given value.
### RangeValues Interface
```typescript
export interface RangeValues {
min: number;
max: number;
}
```
Represents a range with a minimum (`min`) and a maximum (`max`) value.
## Examples
### Constraining a Value Within a Range
```typescript
const range = new Range({ min: 1, max: 10 });
console.log(range.within(0)); // Output: 1
console.log(range.within(5)); // Output: 5
console.log(range.within(15)); // Output: 10
```
### Checking if a Value is Within a Specific Range
```typescript
const range = new Range({ min: 1, max: 10 });
console.log(range.isGreaterThanMinAndLessThanMax(5)); // Output: true
console.log(range.isGreaterThanMinOrEqualAndLessThanMax(1)); // Output: true
console.log(range.isGreaterThanMinAndLessThanMaxOrEqual(10)); // Output: true
console.log(range.isGreaterThanMinOrEqualAndLessThanMaxOrEqual(5)); // Output: true
```
### Finding the Intersection of Two Ranges
```typescript
const range1 = new Range({ min: 1, max: 10 });
const range2 = new Range({ min: 5, max: 15 });
const intersection = range1.getIntersection(range2.getValues());
console.log(intersection?.getValues()); // Output: { min: 5, max: 10 }
```
### Checking if a Range is Within Another Range
```typescript
const range1 = new Range({ min: 1, max: 10 });
const range2 = new Range({ min: 0, max: 20 });
console.log(range1.isInRangeOf(range2.getValues())); // Output: true
```
### Checking if a Range Contains Another Range
```typescript
const range1 = new Range({ min: 1, max: 10 });
const range2 = new Range({ min: 2, max: 8 });
console.log(range1.containsRange(range2.getValues())); // Output: true
```
### Checking if a Range Contains Value
```typescript
const range = new Range({ min: 1, max: 10 });
console.log(range.containsValue(3)); // Output: true
```
### Mapping a Single Value to a Range
```typescript
const rangeValues = mapValueToRange(5);
console.log(rangeValues); // Output: { min: 5, max: 5 }
```