lsort(n) Tcl Built-In Commands lsort(n)

NAME
       lsort - Sort the elements of a list

SYNOPSIS
       llssoorrtt ?options? list



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

       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
       accepted):

       -aasscciiii              Use  string comparison with Unicode code-point col-
                           lation order (the name is for  backward-compatabil-
                           ity reasons.)  This is the default.

       -ddiiccttiioonnaarryy         Use  dictionary-style comparison.  This is the same
                           as -aasscciiii except (a) case is ignored  except  as  a
                           tie-breaker and (b) if two strings contain embedded
                           numbers, the numbers compare as integers, not char-
                           acters.   For  example, in -ddiiccttiioonnaarryy mode, bbiiggBBooyy
                           sorts between bbiiggbbaanngg and bbiiggbbooyy,  and  xx1100yy  sorts
                           between xx99yy and xx1111yy.

       -iinntteeggeerr            Convert  list  elements to integers and use integer
                           comparison.

       -rreeaall               Convert list elements to floating-point values  and
                           use floating comparison.

       -ccoommmmaanndd command    Use  command  as  a comparison command.  To compare
                           two elements, evaluate a Tcl script  consisting  of
                           command  with  the  two  elements appended as addi-
                           tional 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.

       -iinnccrreeaassiinngg         Sort the list  in  increasing  order  (``smallest''
                           items first).  This is the default.

       -ddeeccrreeaassiinngg         Sort  the  list  in  decreasing  order (``largest''
                           items first).

       -iinnddeexx index        If this option is specified, each of  the  elements
                           of  list  must  itself  be  a  proper  Tcl sublist.
                           Instead of sorting based on whole  sublists,  llssoorrtt
                           will extract the index'th element from each sublist
                           and sort based on the given element.   The  keyword
                           eenndd  is  allowed  for the index to sort on the last
                           sublist element, and eenndd-index sorts on  a  sublist |
                           element offset from the end.  For example,
                                  lsort -integer -index 1 {{First 24} {Second 18} {Third 30}}
                           returns {{SSeeccoonndd 1188}} {{FFiirrsstt 2244}} {{TThhiirrdd 3300}}, and      |
                                  lsort -index end-1 {{a 1 e i} {b 2 3 f g} {c 4 5 6 d h}}|
                           returns  {{cc 44 55 66 dd hh}} {{aa 11 ee ii}} {{bb 22 33 ff gg}}.  This
                           option is much more efficient than  using  -ccoommmmaanndd
                           to achieve the same effect.

       -uunniiqquuee             If this option is specified, then only the last set
                           of duplicate elements found in  the  list  will  be
                           retained.  Note that duplicates are determined rel-
                           ative to the comparison used in the sort.  Thus  if
                           -index  0 is used, {{11 aa}} and {{11 bb}} would be consid-
                           ered duplicates and only the second element, {{11 bb}},
                           would be retained.


NNOOTTEESS
       The  options to llssoorrtt 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 llssoorrtt command is reentrant, meaning it is safe to use  as  part  of
       the implementation of a command used in the -ccoommmmaanndd option.


EEXXAAMMPPLLEESS
       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}


       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}


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


KKEEYYWWOORRDDSS
       element, list, order, sort



Tcl                                   8.3                             lsort(n)