# TIP 57: Move TclX's [lassign] into the Tcl Core
	Author:         Donal K. Fellows <fellowsd@cs.man.ac.uk>
	Author:         Agnar Renolen <agnar.renolen@emap.no>
	Author:         Don Porter <dgp@users.sf.net>
	State:          Final
	Type:           Project
	Vote:           Done
	Created:        30-Aug-2001
	Post-History:   
	Tcl-Version:    8.5
	Obsoletes:      170
-----

# Abstract

This TIP proposes to move the _lassign_ command from the TclX
extension into the Tcl core to make multiple assignment a much easier
process for people.

# Rationale

In many cases, a command needs to return more than one return value to
the caller.  For example, suppose that the statement:

	 set coords [LocateFeature $featureID]

would set the variable "coords" to a list containing two elements "x"
and "y".  Assume that you need to set the "x" and "y" components
directly, you can do this today using the following statement:

	 foreach {x y} [LocateFeature $featureID] {}

Now, this is not what the _foreach_ command was designed for, and it
is not obvious at first glance from the source code what the statement
does.  Although it is quite useful for the purpose described in this
TIP, It would be more logical if the developer could write the
following:

	 set {x y} [LocateFeature $featureID]

or

	 mset {x y} [LocateFeature $featureID]

However, there is already a command in TclX for doing this kind of
operation: [lassign].  Given that many people already know TclX,
importing the command from there makes a great deal of sense.  It also
has the nice feature of returning those list items that were not
assigned, making it easy to strip a few words off the front of a list.
That sort of operation is useful when performing tasks like
command-line option parsing.

# Proposal

Define a new command in Tcl called [lassign] with the following syntax
\(_$val_ indicates an argument that the caller would supply\):

	 lassign $listValue $varName ?$varName ...?

The command interprets its first argument as a list value and all
subsequent arguments as variable names.  The first item in the list
value \(i.e. at index 0\) will be assigned to the first variable named,
the second item in the list value will be assigned to the second
variable named \(if present\), etc.  When there are more variables than
list items, the remaining variables will be assigned the empty string.
The result of the command is a sublist of the input list-value that
contains only items that were not assigned to a variable; if all
values were assigned, the result is an empty list.

This is exactly the specification of the behaviour of the
correspondingly-named command in TclX.

# Notes

It should be possible to efficiently compile [lassign] in many cases,
which would make a tremendous difference in execution speed over not
only the TclX version of [lassign], but also over the [foreach]
"idiom", especially when assigning to variables that are not simple
local variables \(the case which [foreach] compilation is optimized
for.\)  For this reason, I'm not committing to implementing [lassign]
using the TclX code.

This TIP was substantially different in the past.  Please view the CVS
history for details.

# Copyright

This document is placed in the public domain.

