Type-Safe Bounds Checking

When to Use

• Working with array access or buffer operations
• Implementing cursor positioning logic (text editors, terminal emulators)
• Handling viewport rendering and scrolling
• Dealing with 0-based indices vs 1-based lengths
• Validating range boundaries
• Converting VT-100 ranges to Rust ranges
• Before creating commits with bounds-sensitive code
• When user asks about "bounds checking", "type safety", "off-by-one errors", etc.

The Problem

Raw

usize

// ❌ Bad - What is `x`? Index or length?
let x = 10_usize;
if x < length {  // Off-by-one error waiting to happen
    buffer[x]
}

// Is this an index (0-based) or a length (1-based)?
// The type system can't help us!

The Solution

Use type-safe wrappers from

tui/src/core/units/bounds_check/

// ✅ Good - Types make it clear
use r3bl_tui::{idx, len, ArrayBoundsCheck};

let index = idx(10);      // Clearly an index (0-based)
let length = len(100);    // Clearly a length (1-based)

if index.overflows(length) {
    // Safely caught! Can't accidentally compare incompatible types
}

Core Principles

Follow these principles when working with indices and lengths:

1. Use Index types (0-based) instead of

   usize

   • RowIndex

     ,

     ColIndex

     ,

     Index

   • Construct with

     row()

     ,

     col()

     ,

     idx()

2. Use Length types (1-based) instead of

   usize

   • RowHeight

     ,

     ColWidth

     ,

     Length

   • Construct with

     height()

     ,

     width()

     ,

     len()

3. Type-safe comparisons

   • Cannot compare

     RowIndex

     with

     ColWidth

     (compile error!)
   • Prevents category errors like "is row 5 < width 10?"

4. Use

   .is_zero()

   for zero checks
   • Instead of

     == 0

   • More idiomatic with newtype wrappers

5. Distinguish navigation from measurement

   • Navigation (

     index - offset → index

     ): Moving backward in position space
   • Measurement (

     index.distance_from(other) → length

     ): Calculating distance between positions
   • Use

     -

     for cursor movement, use

     distance_from()

     for calculating spans

Common Imports

use std::ops::Range;
use r3bl_tui::{
    // Traits
    ArrayBoundsCheck, CursorBoundsCheck, ViewportBoundsCheck,
    RangeBoundsExt, RangeConvertExt, IndexOps, LengthOps,

    // Status enums
    ArrayOverflowResult, CursorPositionBoundsStatus,
    RangeValidityStatus, RangeBoundsResult,

    // Type constructors
    col, row, width, height, idx, len,

    // Terminal delta types (relative cursor movement)
    TermRowDelta, TermColDelta, term_row_delta, term_col_delta,
};

Quick Pattern Reference

ArrayBoundsCheck

index.overflows(length)

buffer[index]

index < length

CursorBoundsCheck

length.check_cursor_position_bounds(pos)

index <= length

ViewportBoundsCheck

index.check_viewport_bounds(start, size)

RangeBoundsExt

range.check_range_is_valid_for_length(len)

RangeBoundsExt

range.check_index_is_within(index)

RangeConvertExt

inclusive_range.to_exclusive()

TermRowDelta

TermColDelta

TermRowDelta::new(n)

Option

Detailed Examples

Example 1: Array Bounds Checking

Use

ArrayBoundsCheck

use r3bl_tui::{idx, len, ArrayBoundsCheck, ArrayOverflowResult};

let buffer_length = len(100);
let index = idx(50);

match index.overflows(buffer_length) {
    ArrayOverflowResult::Within => {
        // Safe to access: buffer[50]
        let value = buffer[index.value()];
    }
    ArrayOverflowResult::Overflows => {
        // Out of bounds! Handle error
        eprintln!("Index {} overflows buffer length {}", index, buffer_length);
    }
}

Mathematical law:

• For valid access:

  0 <= index < length

• Or equivalently:

  index < length

  (since Index is always >= 0)

Example 2: Cursor Position Bounds

Use

CursorBoundsCheck

use r3bl_tui::{idx, len, CursorBoundsCheck, CursorPositionBoundsStatus};

let text_length = len(10);  // Text has 10 characters
let cursor = idx(10);        // Cursor at position 10 (after last char)

match text_length.check_cursor_position_bounds(cursor) {
    CursorPositionBoundsStatus::Within => {
        // Valid! Cursor CAN be at position 10 (after char 9)
        // User can insert text here
    }
    CursorPositionBoundsStatus::Overflows => {
        // Invalid cursor position
    }
}

Mathematical law:

• For valid cursor:

  0 <= position <= length

• Note: Cursor CAN be at

  length

  (after the last character)

Key difference from array access:

• Array access:

  index < length

  (strict inequality)
• Cursor position:

  index <= length

  (includes equality)

Example 3: Viewport Visibility Check

Use

ViewportBoundsCheck

use r3bl_tui::{idx, len, ViewportBoundsCheck};

let line_index = idx(150);      // Line 150 in document
let viewport_start = idx(100);  // Viewport starts at line 100
let viewport_size = len(50);    // Viewport shows 50 lines

if line_index.check_viewport_bounds(viewport_start, viewport_size) {
    // Line 150 is visible (100 <= 150 < 150)
    // Render this line
} else {
    // Line is off-screen, skip rendering
}

Mathematical law:

• Visible if:

  viewport_start <= index < viewport_start + viewport_size

Example 4: Range Validation

Use

RangeBoundsExt

use r3bl_tui::{len, RangeBoundsExt, RangeValidityStatus};

let buffer_length = len(100);
let range = 10..50;  // Want to process elements 10-49

match range.check_range_is_valid_for_length(buffer_length) {
    RangeValidityStatus::Valid => {
        // Range is valid for this buffer
        for i in range {
            process(buffer[i]);
        }
    }
    RangeValidityStatus::Invalid(reason) => {
        eprintln!("Invalid range: {}", reason);
    }
}

Example 5: Range Membership

Use

RangeBoundsExt

use r3bl_tui::{idx, RangeBoundsExt};

// VT-100 scroll region: lines 5-15
let scroll_region = 5..=15;  // Inclusive range
let cursor_row = idx(10);

if scroll_region.check_index_is_within(cursor_row) {
    // Cursor is within scroll region
    // Apply scroll behavior
} else {
    // Cursor outside scroll region
}

Example 6: Range Conversion

Use

RangeConvertExt

use r3bl_tui::RangeConvertExt;

// VT-100 uses inclusive ranges: 1..=10 means lines 1 through 10
let vt100_range = 1..=10;

// Rust iterators use exclusive ranges: 1..11
let rust_range = vt100_range.to_exclusive();

// Now can use in Rust iteration
for line in rust_range {
    process_line(line);
}

Example 7: Navigation vs Measurement

Use

-

distance_from()

use r3bl_tui::{row, height, RowIndex, RowHeight};

// Navigation: Move cursor backward by offset (returns RowIndex).
let cursor_pos = row(10);
let new_pos = cursor_pos - row(3);  // row(7) - moved 3 positions back
// Uses saturating subtraction: row(2) - row(5) = row(0), not overflow

// Measurement: Calculate distance between two positions (returns RowHeight).
let start = row(5);
let end = row(15);
let distance: RowHeight = end.distance_from(start);  // height(10) - 10 rows apart
// Panics if start > end (negative distance)

When to use which:

• Moving cursor up/down/left/right →

  -

  operator
• Calculating scroll amount, viewport span, selection size →

  distance_from()

Example 8: Terminal Cursor Movement (Make Illegal States Unrepresentable)

Use

TermRowDelta

TermColDelta

The CSI zero problem: ANSI cursor movement commands interpret parameter 0 as 1:

• CSI 0 A

  (

  CursorUp

  with n=0) moves cursor 1 row up, not 0

• CSI 0 C

  (

  CursorForward

  with n=0) moves cursor 1 column right, not 0

Solution:

TermRowDelta

TermColDelta

NonZeroU16

use r3bl_tui::{TermRowDelta, TermColDelta, CsiSequence};
use std::io::Write;

// Calculate cursor movement from position on 80-column terminal.
let position: u16 = 240;  // 240 chars from start
let term_width: u16 = 80;

// Fallible construction - must handle the None case.
// For position 240: rows = 3 (Some), cols = 0 (None).
if let Some(delta) = TermRowDelta::new(position / term_width) {
    // delta is guaranteed non-zero, safe to emit
    term.write_all(CsiSequence::CursorDown(delta).to_string().as_bytes())?;
}
if let Some(delta) = TermColDelta::new(position % term_width) {
    // This branch is NOT taken for position 240 (cols = 0)
    // Zero cannot be represented, so the bug is prevented at the type level!
    term.write_all(CsiSequence::CursorForward(delta).to_string().as_bytes())?;
}

Using the ONE constant for common case:

use r3bl_tui::{TermRowDelta, TermColDelta, CsiSequence};

// For the common case of moving exactly 1 row/column, use the ONE constant.
// This avoids the need for fallible construction or unwrap().
let up_one = CsiSequence::CursorUp(TermRowDelta::ONE);
let right_one = CsiSequence::CursorForward(TermColDelta::ONE);

Mathematical law:

• Zero deltas cannot exist - prevented at compile time by

  NonZeroU16

  wrapper

• new()

  returns

  None

  for zero,

  Some(delta)

  for non-zero

Key difference from absolute positioning:

• TermRow

  /

  TermCol

  : 1-based absolute coordinates (for

  CursorPosition

  )

• TermRowDelta

  /

  TermColDelta

  : Relative movement amounts (for

  CursorUp/Down/Forward/Backward

  )

Decision Trees

See the accompanying

decision-trees.md

Detailed Reference

For comprehensive documentation, decision trees, and more examples, see:

tui/src/core/units/bounds_check/mod.rs

This module contains:

• Complete API documentation
• Mathematical laws for each trait
• Visual decision trees
• Edge case handling
• Performance notes

Common Mistakes

❌ Mistake 1: Using raw usize

// Bad - ambiguous types
let index: usize = 10;
let length: usize = 100;
if index < length {  // Works, but no type safety
    // ...
}

Fix:

// Good - clear types
let index = idx(10);
let length = len(100);
if !index.overflows(length) {  // Type-safe!
    // ...
}

❌ Mistake 2: Array bounds used for cursor

// Bad - cursor can be at end!
let cursor = idx(10);
let text_length = len(10);
if cursor.overflows(text_length) {  // Wrong! Cursor at end is valid
    return Err("Invalid cursor");
}

Fix:

// Good - cursor bounds check
if text_length.check_cursor_position_bounds(cursor) == CursorPositionBoundsStatus::Overflows {
    return Err("Invalid cursor");
}

❌ Mistake 3: Comparing incompatible types

// Bad - this won't compile (good!)
let row = row(5);
let width = width(10);
if row < width {  // Compile error! Can't compare RowIndex with ColWidth
    // ...
}

This is actually GOOD - the type system prevents nonsensical comparisons!

❌ Mistake 4: Using

-

when you need distance

// Bad - using subtraction to calculate distance.
// This returns RowIndex, not RowHeight!
let current_row = row(5);
let target_row = row(15);
let rows_to_scroll = target_row - current_row;  // Returns row(10), a position!

Fix:

// Good - use distance_from() for measurement.
let rows_to_scroll: RowHeight = target_row.distance_from(current_row);  // height(10)

❌ Mistake 5: Emitting CSI zero for cursor movement

// Bad - CSI 0 C moves 1 column right, not 0!
// This won't even compile now - CursorForward requires TermColDelta, not u16!
let cols = position % term_width;  // Could be 0!
let seq = CsiSequence::CursorForward(cols);  // Compile error!

Fix:

// Good - use fallible delta construction (zero is unrepresentable)
if let Some(delta) = TermColDelta::new(position % term_width) {
    // delta is guaranteed non-zero
    term.write_all(CsiSequence::CursorForward(delta).to_string().as_bytes())?;
}
// No sequence emitted when cols = 0 (correct behavior - branch not taken)

Reporting Results

When applying bounds checking:

• ✅ All bounds checked with types → "Bounds safety verified with type-safe checks!"
• 🔧 Converted raw usize to Index/Length types → Report conversions made
• 📝 Added bounds checks → List where checks were added

Supporting Files in This Skill

This skill includes additional reference material:

• decision-trees.md

  - Visual decision trees and flowcharts for choosing the right bounds checking approach: main decision tree (which trait?), array vs cursor bounds comparison, index vs length visual diagrams, viewport visibility flowchart, range validation flowchart, comparison table, edge case reference, and quick reference card. Read this when:
  • Not sure which trait to use → Main decision tree
  • Array access vs cursor positioning confusion → Visual comparison diagrams
  • Viewport visibility logic → Viewport flowchart
  • Range validation → Range validation flowchart
  • Edge cases (empty arrays, cursor at end, zero-sized viewport) → Edge cases section
  • Quick lookup of which method for which scenario → Comparison table

Related Skills

• check-code-quality

  - Includes testing bounds-checking code

• write-documentation

  - For documenting bounds-checking logic

Related Commands

No dedicated command, but used throughout the codebase for safe index/length handling.

Additional Resources

• Main implementation:

  tui/src/core/units/bounds_check/mod.rs

• Type definitions:

  tui/src/core/units/

• Examples in tests:

  tui/src/core/units/bounds_check/tests/

• Terminal delta types:

  tui/src/core/coordinates/vt_100_ansi_coords/term_row_delta.rs

  and

  term_col_delta.rs