TIP #127 Version 1.2: Add an -index Option to [lsearch]

This is not necessarily the current version of this TIP.

Abstract

Matching the lsort functionality a -index option should be added to the lsearch command to make searching lists in list easier. This TIP proposes such an added option.

Specification

Under this proposal the syntax of the lsearch is to be modified to accept an extra option:

    lsearch -index index 

The -index option should work exactly like the -index option in the lsort command.

If this option is specified, each of the elements of list must itself be a proper Tcl sublist. Instead of searching based on whole sublists, lsearch will extract the index'th element from each sublist and search based on the given element. The keyword end is allowed for the index to search on the last sublist element, and end-index searches on a sublist element offset from the end. For example,

    lsearch -integer -index 1 {{First 24} {Second 18} {Third 30}} 18

returns 1, and

    lsearch -index end-1 {{a 1 e i} {b 2 3 f g} {c 4 5 6 d h}} d

returns 2.

Rationale

Lists containing one level of sublists are a common technique to simulated complex data structures like matrices or records, or for results from database queries. The lsort command was enhanced with the -index option for this case, to handle sorting on sublist keys.

The lsearch command does not have this functionality yet, one has to use foreach and lindex to loop over the list one by one. This is slower, if the list was sorted with lsort and one could use lsearch -sorted.

Reference Implementation

A reference implementation exists, see: Tcl Patch 693836 on SourceForge. http://sf.net/tracker/?func=detail&atid=310894&aid=693836&group_id=10894

There are no patches and additions to the test suite yet, patches to the docs aren't provided either. Documentation could be copied from lsort with slight changes.

Copyright

This document has been placed in the public domain.

This is not necessarily the current version of this TIP.