r3bl-open-core: Skill for Claude Code

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 values are ambiguous and error-prone:

// ❌ 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/coordinates/bounds_check/:

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

let index = vp_idx(10);      // Clearly an index (0-based)
let length = vp_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

   • VPRow, VPCol, VPIndex
   • Construct with row(), col(), vp_idx()

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

   • VPHeight, VPWidth, VPLength
   • Construct with height(), width(), vp_len()

3. Type-safe comparisons

   • Cannot compare VPRow with VPWidth (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