Add an -index Option to [lsearch]Michael Schlenker$Revision: 1.13 $
Matching the lsort functionality a -index option should be added to the lsearch command to make searching lists in list easier. The lsort -index and the lsearch -index options should accept list style indices like lindex and lset do. This TIP proposes such added options.
Under this proposal the syntax of the lsearch is to be modified to accept two extra options.
The -index option:
The lsort -index option would get enhanced with multiple index support.
ICAgIGxzZWFyY2ggPy1pbmRleCBpbmRleD8g
The -index option should work similar to 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,
ICAgIGxzZWFyY2ggLWludGVnZXIgLWluZGV4IDEge3tGaXJzdCAyNH0ge1NlY29uZCAxOH0ge1RoaXJkIDMwfX0gMTg=
returns 1, and
ICAgIGxzZWFyY2ggLWluZGV4IGVuZC0xIHt7YSAxIGUgaX0ge2IgMiAzIGYgZ30ge2MgNCA1IDYgZCBofX0gZA==
returns 2.
The index given to lsearch -index and lsort -index may be either a single scalar index as in the current lsort implementation or the argument to -index may be a list of scalar indices (similar, but not exactly like the lset/lindex multiple indices). The -index option causes lsearch and lsort to extract the item for searching or sorting comparision from the list element by using in effect lindex $element $index.
For example:
ICAgIHNldCByZWNvcmQgew==ICAgICAgICB7ICAgICAgICAgIHtKYW1lcyBEZWFufSB7TXVzaWNpYW59IHtzb21lIG90aGVyIGRhdGF9ICAgICAgICB9ICAgICAgICB7ICAgICAgICAgIHtFbHZpcyBQcmVzbGV5fSB7TXVzaWNpYW59IHtzb21lIG1vcmUgZGF0YX0=ICAgICAgICB9ICAgICB9ICAgbHNlYXJjaCAtaW5kZXggezAgMH0gJHJlY29yZCAiRWx2aXMi
returns 1.
ICAgbHNvcnQgLWRpY3Rpb25hcnkgLWRlY3JlYXNpbmcgLWluZGV4IHswIDF9ICRyZWNvcmQ=
returns {{{Elvis Presley} {Musician} {some more data}} {{James Dean} {Musician} {some other data}}}.
Note: The following example is invalid, -index only takes a list as argument, unlike lset and lindex, that take either a list or multiple arguments, that get concatenated by the command.
IGxzZWFyY2ggLWluZGV4IDEgMSAkcmVjb3JkIFByZXNsZXk=
The -subindices option:
The -subindices option should be added only to the lsearch command as a convenience shortcut. It is only a valid option if the -index option is also used.
If -subindices is given, lsearch should return a list of indices that can be used directly by lindex or lset to manipulate the element used for searching, instead of the top level element of the list.
If -subindices and -inline are specified at the same time, the command returns the value instead of the index.
example:
IGxzZWFyY2ggLXN1YmluZGljZXMgLWluZGV4IHswIDB9ICRyZWNvcmQgRWx2aXM=
returns {1 0 0}.
If no -all option is specified, this is the same as doing:
IGNvbmNhdCBbbHNlYXJjaCAtaW5kZXggezAgMH0gJHJlY29yZCBFbHZpc10gW2xpc3QgMCAwXQ==
Lists containing one or more 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.
Multiple indices for the -index option to both lsearch and lsort should be added, to make the option more similar to lset and lindex style indices.
The -subindices option is a convenience option to make constructs like this example work well:
IGZvcmVhY2ggaXRlbSBbbHNlYXJjaCAtYWxsIC1zdWJpbmRpY2VzIC1pbmRleCB7MCAwfSAkcmVjb3JkIGJsYV0gew==ICAgICAgICAgbHNldCByZWNvcmQgJGl0ZW0gYmFyIH0=
Without the subindices option it could be written as:
IGZvcmVhY2ggaXRlbSBbbHNlYXJjaCAtYWxsIC1pbmRleCAkaWR4ICRyZWNvcmQgYmxhXSB7ICAgICAgICAgbHNldCByZWNvcmQgW2NvbmNhdCAkaWR4ICRpdGVtXSBiYXI=IH0=
A reference implementation exists, see the files attached to the Tcl Patch 693836 on SourceForge.
The reference implementation isn't honouring the -inline option if given in conjuction with -subindices, at the moment.
This document has been placed in the public domain.