manpagez: man pages & more
man lsort(n)
Home | html | info | man
lsort(n)                     Tcl Built-In Commands                    lsort(n)



______________________________________________________________________________


NAME

       lsort - Sort the elements of a list


SYNOPSIS

       lsort ?options? list
______________________________________________________________________________


DESCRIPTION

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

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

       -dictionary
              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.

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

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

       -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.

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

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

       -indices
              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
              effect.

       -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".

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

       -unique
              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
              retained.


NOTES

       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.


EXAMPLES

       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}


SEE ALSO

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


KEYWORDS

       element, list, order, sort



Tcl                                   8.5                             lsort(n)

tcl 8.6.7 - Generated Thu Aug 10 13:47:54 CDT 2017
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.