List: List Insertion Cursor Shift Tool

Description

Shift cursor by insertedCount when it lies after insertionIndex or equals it with after affinity.

A splice replaces part of a list and changes later positions. Cursor affinity defines which side of inserted content a boundary follows when the splice covers it.

Shift cursor by insertedCount when it lies after insertionIndex or equals it with after affinity.

When to use this tool

Use List: List Insertion Cursor Shift when you need a splice length, gap-fill, or cursor-mapping calculation.

How to use the tool and how it works

Enter cursor, insertionIndex, insertedCount, length, affinity. Use the units and conventions below.
Run the tool. Correct any format, range, or cross-field input error before interpreting the output.
Read result. Expand result to inspect the returned fields.

Shift cursor by insertedCount when it lies after insertionIndex or equals it with after affinity. Otherwise retain it; return length plus insertedCount.^[1]

Input field	Meaning and units	Accepted input
cursor	Cursor	Required. Safe integer.
insertionIndex	Insertion Index	Required. Safe integer.
insertedCount	Inserted Count	Required. Safe integer.
length	Length, count, or code length under the stated domain and unit convention.	Required. Safe integer.
affinity	Affinity	Required. Text; one of "before", "after". Implementation limit: 8192 Unicode code points and 16384 UTF-16 code units.

Output field	Interpretation	Returned shape
result	Result	Required. Object.
result.cursor	Cursor	Calculated result member: number.
result.newLength	New Length	Calculated result member: number.

json

{
  "input": {
    "cursor": 2,
    "insertionIndex": 2,
    "insertedCount": 3,
    "length": 5,
    "affinity": "after"
  },
  "output": {
    "result": {
      "cursor": 5,
      "newLength": 8
    }
  }
}

Limitations and assumptions

Cursors are boundaries in [0, length]; affinity only affects equality and no content is inserted.
Outputs are nested inside result. Inputs must satisfy both the field types and the cross-field conditions above. Invalid input causes an error; a successful false flag or documented placeholder is a different result.
Numeric calculations use binary floating point unless exact decimal-integer arithmetic is explicitly stated. No hidden measurement tolerance or decimal rounding is added; nonfinite or out-of-contract results are rejected. Numeric signed-zero results are exported as zero.

Alternative or Complementary methods

Check the actual collection API's deletion clamping and cursor semantics before applying an edit.

References

Calculation and input contract: list/list-insertion-cursor-shift — tool.io

Similar or alternative tools

List: List Deletion Cursor Shift
Keep cursors at or before deletionStart, collapse those through deletionEnd to deletionStart, and shift later cursors left by the deleted length.
List Insert Block Cursor Boundary
Increase selected by blockLength when strictly beyond cursor, or at cursor when shiftAtBoundary is true.