Go to main content

man pages section 1: User Commands

Exit Print View

Updated: Thursday, June 13, 2019

lsort (1t)


lsort - Sort the elements of a list


lsort ?options? list


lsort(1t)                    Tcl Built-In Commands                   lsort(1t)


       lsort - Sort the elements of a list

       lsort ?options? list

       This command sorts the elements of list, returning a new list in sorted
       order.  The implementation of the lsort  command  uses  the  merge-sort
       algorithm  which is a stable sort that has O(n log n) performance char-

       By default ASCII sorting is used with the result returned in increasing
       order.   However,  any of the following options may be specified before
       list  to  control  the  sorting  process  (unique   abbreviations   are

       -ascii Use  string  comparison  with Unicode code-point collation order
              (the name is for backward-compatibility reasons.)  This  is  the

              Use  dictionary-style  comparison.   This  is the same as -ascii
              except (a) case is ignored except as a tie-breaker  and  (b)  if
              two  strings  contain  embedded  numbers, the numbers compare as
              integers, not characters.  For  example,  in  -dictionary  mode,
              bigBoy  sorts between bigbang and bigboy, and x10y sorts between
              x9y and x11y. Overrides the -nocase option.

              Convert list elements to integers and use integer comparison.

       -real  Convert list elements to floating-point values and use  floating

       -command command
              Use  command  as a comparison command.  To compare two elements,
              evaluate a Tcl script consisting of command with  the  two  ele-
              ments  appended  as  additional  arguments.   The  script should
              return an integer less than, equal to, or greater than  zero  if
              the  first  element  is to be considered less than, equal to, or
              greater than the second, respectively.

              Sort the list in increasing order ("smallest"items first).  This
              is the default.

              Sort the list in decreasing order ("largest"items first).

              Return  a  list  of indices into list in sorted order instead of
              the values themselves.

       -index indexList
              If this option is specified, each of the elements of  list  must
              itself  be  a  proper  Tcl  sublist  (unless  -stride  is used).
              Instead of sorting based on whole sublists, lsort  will  extract
              the  indexList'th  element  from each sublist (as if the overall
              element and the indexList were passed to lindex) and sort  based
              on the given element.  For example,

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

              returns {Second 18} {First 24} {Third 30},

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

              returns {c 4 5 6 d h} {a 1 e i} {b 2 3 f g}, and

                     lsort -index {0 1} {
                         {{b i g} 12345}
                         {{d e m o} 34512}
                         {{c o d e} 54321}

              returns  {{d  e  m  o}  34512} {{b i g} 12345} {{c o d e} 54321}
              (because e sorts before i which sorts before o.)  This option is
              much  more  efficient  than  using  -command to achieve the same

       -stride strideLength
              If this option is specified, the list is treated  as  consisting
              of  groups of strideLength elements and the groups are sorted by
              either their first element or, if the -index option is used,  by
              the element within each group given by the first index passed to
              -index (which is then ignored by -index). Elements always remain
              in the same position within their group.

              The  list  length  must  be an integer multiple of strideLength,
              which in turn must be at least 2.

              For example,

                     lsort -stride 2 {carrot 10 apple 50 banana 25}

              returns "apple 50 banana 25 carrot 10", and

                     lsort -stride 2 -index 1 -integer {carrot 10 apple 50 banana 25}

              returns "carrot 10 banana 25 apple 50".

              Causes comparisons to be handled in a  case-insensitive  manner.
              Has  no  effect  if  combined with the -dictionary, -integer, or
              -real options.

              If this option is specified, then only the last set of duplicate
              elements  found  in the list will be retained.  Note that dupli-
              cates are determined relative to  the  comparison  used  in  the
              sort.   Thus  if -index 0 is used, {1 a} and {1 b} would be con-
              sidered duplicates and only the second element, {1 b}, would  be

       See attributes(7) for descriptions of the following attributes:

       |Availability   | runtime/tcl-8    |
       |Stability      | Uncommitted      |
       The  options to lsort only control what sort of comparison is used, and
       do not necessarily constrain what the values themselves  actually  are.
       This  distinction  is  only  noticeable  when the list to be sorted has
       fewer than two elements.

       The lsort command is reentrant, meaning it is safe to use  as  part  of
       the implementation of a command used in the -command option.

       Sorting a list using ASCII sorting:

              % lsort {a10 B2 b1 a1 a2}
              B2 a1 a10 a2 b1

       Sorting a list using Dictionary sorting:

              % lsort -dictionary {a10 B2 b1 a1 a2}
              a1 a2 a10 b1 B2

       Sorting lists of integers:

              % lsort -integer {5 3 1 2 11 4}
              1 2 3 4 5 11
              % lsort -integer {1 2 0x5 7 0 4 -1}
              -1 0 1 2 4 0x5 7

       Sorting lists of floating-point numbers:

              % lsort -real {5 3 1 2 11 4}
              1 2 3 4 5 11
              % lsort -real {.5 0.07e1 0.4 6e-1}
              0.4 .5 6e-1 0.07e1

       Sorting using indices:

              % # Note the space character before the c
              % lsort {{a 5} { c 3} {b 4} {e 1} {d 2}}
              { c 3} {a 5} {b 4} {d 2} {e 1}
              % lsort -index 0 {{a 5} { c 3} {b 4} {e 1} {d 2}}
              {a 5} {b 4} { c 3} {d 2} {e 1}
              % lsort -index 1 {{a 5} { c 3} {b 4} {e 1} {d 2}}
              {e 1} {d 2} { c 3} {b 4} {a 5}

       Sorting a dictionary:                                                   |

              % set d [dict create c d a b h i f g c e]                        |
              c e a b h i f g                                                  |
              % lsort -stride 2 $d                                             |
              a b c e f g h i                                                  |

       Sorting using striding and multiple indices:                            |

              % # Note the first index value is relative to the group          |
              % lsort -stride 3 -index {0 1} \                                 |
                   {{Bob Smith} 25 Audi {Jane Doe} 40 Ford}                    |
              {{Jane Doe} 40 Ford {Bob Smith} 25 Audi}                         |

       Stripping duplicate values using sorting:

              % lsort -unique {a b c a b c a b c}
              a b c

       More complex sorting using a comparison function:

              % proc compare {a b} {
                  set a0 [lindex $a 0]
                  set b0 [lindex $b 0]
                  if {$a0 < $b0} {
                      return -1
                  } elseif {$a0 > $b0} {
                      return 1
                  return [string compare [lindex $a 1] [lindex $b 1]]
              % lsort -command compare \
                      {{3 apple} {0x2 carrot} {1 dingo} {2 banana}}
              {1 dingo} {2 banana} {0x2 carrot} {3 apple}

       list(n),  lappend(n),  lindex(n),  linsert(n),  llength(n), lsearch(n),
       lset(n), lrange(n), lreplace(n)

       element, list, order, sort

       This    software    was    built    from    source     available     at
       https://github.com/oracle/solaris-userland.    The  original  community
       source was downloaded from  http://prdownloads.sourceforge.net/tcl/tcl-

       Further information about this software can be found on the open source
       community website at https://www.tcl.tk/.

Tcl                                   8.5                            lsort(1t)