Module Version: 0.26

NAME
SYNOPSIS
DESCRIPTION
- Usage
- Returncodes
EXAMPLES
BUGS
HISTORY
AUTHOR
THANKS
COPYRIGHT
SEE ALSO

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()
 - Must be declared

 - Utilizable in Discard_Duplicates()
 - Can be declared (if empty, it does not sort the array)

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 for now. ;)

HISTORY

- 2001-08-25 / 0.26

File permission fixed, now anybody can extract the archive, not only the user 'root'.

- 2001-08-23 / 0.25

Changed the Discard_Duplicates() function to discard duplicates and only sort the array if wished. You can set <sorting> to 'asending', 'desending' or let them empty to disable sorting.

Some misspelling corrected.

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