> For the complete documentation index, see [llms.txt](https://testbox.ortusbooks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://testbox.ortusbooks.com/digging-deeper/expectations/range-expectations.md).

# Range Expectations

Matchers for BoxLang Range objects

BoxLang has a native `Range` type covering containment, ordering, bounds, stepping and clamping. TestBox 7.1 adds matchers that assert against ranges directly instead of picking them apart into endpoints first.

{% hint style="info" %}
These matchers require BoxLang. On CFML engines they are guarded and report unsupported behavior cleanly rather than erroring.
{% endhint %}

## Creating Ranges

Ranges are built with the `..` operator and stepped with `.step( n )`. There is no `rangeNew()` built-in.

```java
var base    = 1..10
var stepped = ( 0..100 ).step( 5 )
var chars   = "a".."z"
var dates   = createDate( 2024, 1, 1 )..createDate( 2024, 1, 31 )

var openEnd   = 1..     // half bounded
var openStart = ..10    // half bounded
var open      = ..      // unbounded
```

## Containment

### `toBeRange()`

```java
expect( 1..10 ).toBeRange()
```

### `toContainValue()`

Asserts a value falls inside the range.

```java
expect( 1..10 ).toContainValue( 5 )
expect( "a".."z" ).toContainValue( "m" )
expect( dates ).toContainValue( "2024-01-15" )
```

### `toContainRange()`

Asserts an entire range fits inside another.

```java
expect( 1..10 ).toContainRange( 3..7 )
```

### `toBeInRange()`

The inverse reading of `toContainValue()`, with the value as the subject. Use whichever makes the sentence read better.

```java
expect( 8 ).toBeInRange( 1..10 )
```

### `toBeBeforeRange()` / `toBeAfterRange()`

```java
expect( 0 ).toBeBeforeRange( 1..10 )
expect( 11 ).toBeAfterRange( 1..10 )
```

## Shape And Direction

### `toBeBounded()`, `toBeUnbounded()`, `toBeHalfBounded()`

```java
expect( 1..10 ).toBeBounded()
expect( .. ).toBeUnbounded()
expect( 1.. ).toBeHalfBounded()
```

### `toBeIterable()`

A range is iterable when it can actually be walked, which an unbounded range cannot.

```java
expect( 1..10 ).toBeIterable()
```

### `toBeAscending()` / `toBeDescending()`

```java
expect( 1..10 ).toBeAscending()
expect( 10..1 ).toBeDescending()
expect( "a".."z" ).toBeAscending()
```

## Step And Clamp

### `toHaveStep()`

```java
expect( ( 0..100 ).step( 5 ) ).toHaveStep( 5 )
```

### `toClampTo()`

Asserts what the range clamps a given value to. Takes the input value and the expected clamped result.

```java
expect( 1..10 ).toClampTo( 15, 10 );   // 15 clamps down to 10
expect( 1..10 ).toClampTo( -3, 1 );    // -3 clamps up to 1
```

## Native Equivalents

These matchers sit on top of the native Range API, so the following are equivalent to the assertions above:

```java
base.contains( 5 )
base.contains( 3..7 )
stepped.getStep()          // 5
base.clamp( 15 )           // 10
```

## A Real Example

```java
describe( "Pagination window", function(){

    it( "clamps a requested page into the available range", function(){
        var pages = 1..totalPages

        expect( pages ).toBeRange()
        expect( pages ).toBeBounded()
        expect( pages ).toBeAscending()

        expect( pages ).toContainValue( currentPage )
        expect( pages ).toClampTo( 9999, totalPages )
    } )

} )
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://testbox.ortusbooks.com/digging-deeper/expectations/range-expectations.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.