Author:		Ashok P. Nadkarni <[email protected]>
State:		Final
Type:		Project
Vote:		Done
Created:	6-Aug-2022
Tcl-Version:	8.7
Tcl-Branch:	tip-631
Keywords:	list
Vote-Summary:	Accepted 6/0/0
Votes-For:	BG, KW, KK, MC, SL, FV
Votes-Against:	none
Votes-Present:	none

Abstract

Add a command to efficiently delete and insert multiple elements in list values stored in variables.

Rationale

Tcl provides commands lappend, lpop and lset to efficiently operate on unshared list values stored in variables. The efficiency of these commands is a result of its operating on variables containing unshared values which can then be modified in place, generally without needing reallocation or copying as extra trailing free space is present in the list internal representation.

There is however no equivalent for the lreplace command which operates on list values and subsumes several different insert/delete/replace functions. The TIP 625 implementation also allows for leading free space and subranges in the internal representation. This opens the door for more efficient operation in several situations and hence the motivation for this TIP.

Specification

The ledit command has the following syntax:

ledit listVar first last ?element element ...?

The command fetches the list value in variable listVar and replaces the elements in the range given by indices first to last (inclusive) with the element arguments. The resulting value is then stored back in the listVar variable. The indices follow the standard Tcl index format supporting simple index arithmetic and indices relative to the end using the end keyword.

Some special cases are:

If either first or last is negative, it is considered to refer to the position before the first element of the list.
If either first or last is greater than the length of the list, it indicates the position just after the last element of the list.
If last is less than first, no elements are deleted and the element arguments are inserted in front of the element at first.
If no element arguments are specified, the command only deletes elements.
An error is raised if the value in listVar does not exist (as in lset) or cannot be interpreted as a list.

Discussion

The command subsumes "lprepend" (lappend analogue for front insertions) or "linject" (linsert analogue for variables) though they would be a little more intuitive to use.

Name conflicts

As a data point, this name is not found in the entire magicsplat distribution with source for over a hundred packages and extensions.

Concerns were voiced on the chat that ledit is easily confused with subst. The name lupdate was suggested though one might argue that can be confused with update.

The author has no particular objection to choosing a different name.

Copyright