Description
Lookup one exact zero-based logical position with owning run and within-run offset; out-of-range positions reject.
Run-length records represent repeated observations without expanding them. Each record pairs a literal string value with a positive exact integer length; neighboring equal values can be valid but noncompact. Expanded offsets count observations rather than run records, and half-open ranges include their start while excluding their end.
Lookup one exact zero-based logical position with owning run and within-run offset; out-of-range positions reject.
When to use this tool
Use this tool to lookup one exact zero-based logical position with owning run and within-run offset; out-of-range positions reject.
How to use the tool and how it works
- Enter runsJson, index using the definitions below. Serialize JSON text fields in the decoded shape shown below.
- Run the operation. Resolve input-format errors before interpreting an output.
- Read result.value, result.runIndex, result.offset, using the stated boundary, ordering, sign and absence conventions.
Require 0≤index<expanded total. Locate its cumulative half-open run interval, then return that run’s value, original runIndex and index−runStart as decimal-text offset within the run.1
| Input field | Meaning and units | Accepted input |
|---|---|---|
| runsJson | JSON array of {value,length} records: literal string value and positive exact decimal-string length. | Text, at most 8,192 UTF-16 code units; narrower grammar/range rules also apply. |
| index | Zero-based expanded observation index as exact decimal text, strictly below total. | Text, at most 8,192 UTF-16 code units; narrower grammar/range rules also apply. |
These decoded structures show the examples inside JSON text fields. Supply their serialized JSON strings as input.
{
"runsJson": [
{
"value": "a",
"length": "3"
},
{
"value": "a",
"length": "2"
},
{
"value": "b",
"length": "4"
}
]
}| Output field | Interpretation |
|---|---|
| result | Object containing the fields below. |
| result.value | Literal value at the requested expanded index. |
| result.runIndex | Original zero-based containing/first-matching run index, or null when absent. |
| result.offset | Exact expanded or within-run offset as decimal text, or null when a requested value is absent. |
{
"input": {
"runsJson": "[{\"value\": \"a\", \"length\": \"3\"}, {\"value\": \"a\", \"length\": \"2\"}, {\"value\": \"b\", \"length\": \"4\"}]",
"index": "5"
},
"output": {
"result": {
"value": "b",
"runIndex": 2,
"offset": "0"
}
}
}Limitations and assumptions
- An index equal to total is out of range; exact arithmetic avoids loss for long expanded sequences.
- Run records contain string value and positive length as exact decimal integer text. Lengths and offset inputs support up to 256 decimal digits before operation-specific checks; results use decimal text and do not expand the repeated observations.
- Every declared outer field is required and unknown outer fields are rejected. Strings and JSON text have size limits, lists are bounded to 128 entries, and JSON nesting/node counts are bounded. Tighter operation-specific bounds stated above take precedence.
- Ordinary numeric outputs must be finite and within safe-integer magnitude. Exact large lengths/counts use decimal strings. Original record indexes and code-unit positions are zero-based; span ends are exclusive unless stated otherwise.
Alternative or Complementary methods
Use compaction for a canonical adjacent-run layout and boundary-aware operations when provenance matters. Retain exact decimal lengths rather than converting long totals to floating-point numbers.
References
Similar or alternative tools
- Run Length Record Adjacent Compaction
Run lengths are positive exact integer decimal strings with literal string values, never expanded; compact adjacent exactly equal values by summing exact lengths, not global deduplication.
- Run Length Record Aligned Pair Spans
Run lengths are positive exact integer decimal strings with literal string values, never expanded; align two equal-total encoded sequences at every source boundary, with paired values and exact logical spans.