NAME
    Sort::Array - This extended sorting algorithm allows you to

    a) sort an array by ANY field number, not only the first. b) find
    duplicates in your data-set and sort them out.

    The function is case-sensitive. Future versions might come without this
    limitation.

SYNOPSIS
      use Sort::Array qw(
          Sort_Table
          Discard_Duplicates
      );
      @data = Sort_Table(
          cols      => '4',
          field     => '4',
          sorting   => 'descending',
          structure => 'csv',
          separator => '\*',
          data      => \@data,
      );
      @languages = Discard_Duplicates(
          sorting      => 'ascending',
          empty_fields => 'delete',
          data         => \@languages,
      );

DESCRIPTION
    Sort_Table() is capable of sorting table-form arrays by a particular
    value.

    Discard_Duplicates() discards doubles from an array and returns the
    sorted array.

  Usage

      @data = Sort_Table(
          cols      => '4',
          field     => '4',
          sorting   => 'descending',
          structure => 'csv',
          separator => '\*',
          data      => \@data,
      );

      @languages = Discard_Duplicates(
          sorting      => 'ascending',
          empty_fields => 'delete',
          data         => \@languages,
      );

    cols
      How many columns in a line. Integer beginning at
      1 (not 0) (for better readability).
      e.g.: '4' = Four fields at one line. ($array[0..3])
      --- Utilizable only in Sort_Table()
      --- Must be declared

    field
      Which column should be used for sorting. Integer
      beginning at 1 (not 0).
      e.g.: '4' = Sorting the fourth field. ($array[3])
      --- Utilizable only in Sort_Table()
      --- Must be declared

    sorting
      In which order should be sorted.
      e.g.: 'ascending' or 'descending'
      --- Utilizable in Sort_Table() and Discard_Duplicates()
      --- Must be declared

    empty_fields
      Should empty fields removed
      e.g.: 'delete' or not specified
      --- Utilizable only in Discard_Duplicates()
      --- Can be declared

    structure
      Structure of that Array.
      e.g.: 'csv' or 'single'
      --- Utilizable only in Sort_Table()
      --- Must be declared

    separator
      Which separator should be used? Only needed when
      structure => 'csv' is set. If left empty default
      is ";".
      For ?+*{} as a separator you must mask it since
      it is a RegEx.
      e.g.: \? or \* ...
      --- Utilizable only in Sort_Table()
      --- Must be declared when using 'csv' or ';'
          will be used.

    data
      Reference to the array that should be sorted.
      --- Utilizable in Sort_Table() and Discard_Duplicates()
      --- Must be declared

    If everything went right, Sort_Table() returns an array containing your
    sorted Array. The structure from the imput-array is kept although it's
    sorted. ;)

  Returncodes

    If an error occurs, than will be returned an undefinied Array and set
    $Sort::Array::error with one of the following code. Normally
    $Sort::Array::error is 0.

    The following codes are returned, if an error occurs:

    '100'
      <cols> is empty or not set or contains wrong content.

    '101'
      <field> is emtpy or not set or contains wrong content.

    '102'
      <sorting> is empty or contains not 'ascending' or 'descending'.

    '103'
      <structure> is empty or contains not 'csv' or 'single'.

    '104'
      <data> is empty (your reference array).

EXAMPLES
    Here are some short samples. These should help you getting used to
    Sort::Array

  Sorting CSV-Lines in an array

      my @data = (
         '00003*layout-3*19990803*0.30',
         '00002*layout-2*19990802*0.20',
         '00004*layout-4*19990804*0.40',
         '00001*layout-1*19990801*0.10',
         '00005*layout-5*19990805*0.50',
         '00007*layout-7*19990807*0.70',
         '00006*layout-6*19990806*0.60',
      );

      @data = Sort_Table(
          cols      => '4',
          field     => '4',
          sorting   => 'descending',
          structure => 'csv',
          separator => '\*',
          data      => \@data,
      );

      Returns an array (with CSV-Lines):

      00007*layout-7*19990807*0.70
      00006*layout-6*19990806*0.60
      00005*layout-5*19990805*0.50
      00004*layout-4*19990804*0.40
      00003*layout-3*19990803*0.30
      00002*layout-2*19990802*0.20
      00001*layout-1*19990801*0.10

  Sorting single-fields in an array

      my @data = (
         '00003', 'layout-3', '19990803', '0.30',
         '00002', 'layout-2', '19990802', '0.20',
         '00004', 'layout-4', '19990804', '0.40',
         '00001', 'layout-1', '19990801', '0.10',
         '00005', 'layout-5', '19990805', '0.50',
         '00007', 'layout-7', '19990807', '0.70',
         '00006', 'layout-6', '19990806', '0.60',
      );

      @data = Sort_Table(
          cols      => '4',
          field     => '4',
          sorting   => 'descending',
          structure => 'single',
          data      => \@data,
      );

      Returns an array (with single fields)

      00007 layout-7 19990807 0.70
      00006 layout-6 19990806 0.60
      00005 layout-5 19990805 0.50
      00004 layout-4 19990804 0.40
      00003 layout-3 19990803 0.30
      00002 layout-2 19990802 0.20
      00001 layout-1 19990801 0.10

  Discard duplicates in an array:

      my @languages = (
          '',
          'German',
          'Dutch',
          'English',
          'Spanish',
          '',
          'German',
          'Spanish',
          'English',
          'Dutch',
      );

      @languages = Discard_Duplicates(
          sorting      => 'ascending',
          empty_fields => 'delete',
          data         => \@languages,
      );

      Returns an array (with single fields):

      Dutch
      English
      German
      Spanish

BUGS
    No Bugs known fo now. ;)

HISTORY
    - 2001-08-17 / 0.24
    Error codes are no longer returned in an array (that array that contains
    the sorted Data). $Sort::Array::error is used with the code instead.

    - 2001-07-28 / 0.23
    First beta-release, non-public

AUTHOR
    Michael Diekmann, <michael.diekmann@undef.de>

THANKS
    Rainer Luedtke, <sirbedivere@freshfish.de>

COPYRIGHT
    Copyright (c) 2001 Michael Diekmann <michael.diekmann@undef.de>. All
    rights reserved. This program is free software; you can redistribute it
    and/or modify it under the same terms as Perl itself.

SEE ALSO
    perl(1).

