Author:		Ashok P. Nadkarni <apnmbx-public@yahoo.com>
State:		Draft
Type:		Project
Vote:		Pending
Created:	14-Nov-2022
Tcl-Version:	9.1
Tcl-Branch:	tip-649
Keywords:	list

• Abstract
• Rationale
  • Efficiency of list manipulation
  • Efficiency of list access
• Specification
• Discussion
• Implementation
• Copyright

Abstract

The list implementation has functionality that is available at the script level but not in the C API. This TIP proposes to expose the same as a C API as well. The benefits include

• convenience for extension and application writers that need to manipulate lists at the C level by eliminating the need to implement the functionality themselves

• significantly better performance as the currently defined list related C API is implicitly built around the 8.6 list internal representation and does not allow callers to benefit from implementation of more efficient higher level operations available in Tcl 9.

• prevention of shimmering from the more efficient list representations made possible by TIP 636 (for example, arithmetic series).

Specification

The following functions will be added along with corresponding entries in the stubs table. (Names all subject to change)

int Tcl_ListObjRange(
    Tcl_Interp *interp,
    Tcl_Obj *srcListPtr,
    Tcl_Size first,
    Tcl_Size last,
    Tcl_Obj **newListPtr);
int Tcl_ListObjReverse(
    Tcl_Interp *interp,
    Tcl_Obj *srcListPtr,
    Tcl_Obj **newListPtr);
int Tcl_ListObjRepeat(
    Tcl_Interp *interp,
    Tcl_Obj *srcListPtr,
    Tcl_Size repeatCount,
    Tcl_Obj **newListPtr);
int Tcl_ListObjSort(
    Tcl_Interp *interp,
    Tcl_Obj *listPtr,
    TBD..,
    Tcl_Obj **newListPtr);

where

• interp is used for error messages and may be passed as NULL.

• srcListPtr points to the source list operand. This may be shared or unshared. In the latter case, it may be re-used to hold the result returned in newListPtr, but .

• newListPtr points to the location to store the result list. No assumption should be made about the internal type of the returned Tcl_Obj other than guarantee that it supports the public list C API.

Tcl_ListObjRange is the C equivalent of the lrange command and returns a list containing all elements in the source list at indices greater or equal to first and less than or equal to last. An empty list is returned in the case of first being greater than last.

Tcl_ListObjReverse returns a list containing all elements of the source list in reverse order.

Tcl_ListObjRepeat returns a list whose elements are the elements of the source list repeated repeatCount number of times. repeatCount must be a non-negative integer.

All functions return TCL_OK on success and TCL_ERROR on failure.

Implementation

TBD

Copyright

This document has been placed in the public domain.