NAME

Text::NumericList - Perl extension for converting strings into arrays of positive integers and vice-versa.

SYNOPSIS

  use Text::NumericList;
  my $list = Text::NumericList->new;

Converting arrays into strings

  $list->set_array(1,2,3,5,6,7);
  my $string = $list->get_string;   # Returns '1-3,5-7'

  $list->set_output_separator(';');
  $string = $list->get_string;      # Returns '1-3;5-7'

  $list->set_range_symbol('..');
  $string = $list->get_string;      # Returns '1..3;5..7'

Converting strings into arrays

  $list->set_string('1-3,5-7');
  my @array = $list->get_array;     # Returns (1,2,3,5,6,7)

  $list->set_range_regexp('.+');    # Set range regular expression to
                                    # a single or multiple periods
  $list->set_string('1..3,5...7');
  @array = $list->get_array;        # Returns (1,2,3,5,6,7) 

Additional methods

  my $mask = new Text::NumericList;
  $mask->set_string('1-10,20-25');
  $list->set_mask($mask);           # Set the list mask

Mask limits the numeric list to certain values, so that get_string() and get_array() methods return intersection of the current list and the mask:

  $list->set_string('15-30');
  @array    = $list->get_array;     # Returns (20,21,22,23,24,25)
  $string   = $list->get_string;    # Returns '20-25'

The following shortcuts work if the mask is set.

  $list->set_string('18,odd');
  @array    = $list->get_array;     # Returns (15,17-19,21,23,25,27,29)

  $list->set_string('21,even');
  @array    = $list->get_array;     # Returns (16,18,20-22,24,26,28,30)

  $list->set_string('all');
  $string   = $list->get_string;    # Returns '15-30'

DESCRIPTION

This class is useful for applications where a user is required to enter large arrays of integers. This class parses user-provided text strings and converts them into arrays of integers. This class also converts arrays of integers into a text string replacing sequential integers with a range (e.g. "1-5").

METHODS

new()

Creates a new Text::NumericList object.

set_array(@)

Sets the 'array' attribute. Converts array into string and sets the 'string' attribute as well.

 Conversion algorithm:

 * In each array element, remove all non-digit characters.
 * Remove non-unique elements.
 * Sort the array.
 * Set the 'array' attribute.
 * Apply the mask to the array.
 * Replace 3 and more sequential elements with a range string (e.g.
   '1-5') using range_symbol attribute.
 * Join elements and with the output_separator string.
 * Set the 'string' attribute.

set_string($)

Converts the string into an array. Sets the 'array' and 'string' attributes to the resulting array using set_array(). Every effort is made to make sense of user input. Unrecognizeable characters are removed from the string. Some illegal combinations of other symbols are removed or replaced. Reverse ranges (such as 8-5) are ignored. If the mask is set, set_string() method recognizes the following keywords: 'all', 'odd', and 'even'.

 Examples (assuming that mask is set to '1-10'):

 ===================================================
 Input string   Resulting array     Resulting string        
 ---------------------------------------------------
 '3,2,1,3,5-7'  1,2,3,5,6,7         '1-3,5-7'
 '2,oDD'        1,2,3,5,7,9         '1-3,5,7,9'
 'eVen,5'       2,4,5,6,8,10        '2,4-6,8,10'
 '5,-4-,7'      4,5,7               '4,5,7'
 '7-9-12'       7,8,9,10            '7-10'
 '1 -&% 4s7'    1,2,3,4,7           '1-4,7'
 ===================================================

get_array()

Returns the array attribute.

get_string()

Returns the string attribute.

set_range_regexp($)

Argument: a string. Sets range regular expression. Default is '\-'.

set_range_symbol($)

Argument: a string. Set the combination of characters to present ranges in the output string. Default is '-'.

set_output_separator($)

Argument: a string. Sets the string to separate elements in the output string. Default is ','.

set_input_separator($)

Argument: a string. Sets the string which is considered an element separator in the input string. Default is ','. In general, elements in the input string can be separated by any non-digit character which does not match range regular expression. Input separator is used only to avoid character combinations like '5-,' in the input strings.

set_mask($Text_NumericList)

Argument: another Text::NumericList object. When the mask is set, the values of the 'array' attribute are limited to those specified in the mask object. All other values in the input string or input array are ignored.

BUGS

Methods set_mask(), set_input_separator(), set_output_separator(), set_range_regexp(), and set_range_symbol() are supposed to be used prior to set_array() or set_string(). The output may not look as expected if you use these methods after set_array() or set_string(), although some effort has been made to make the output look reasonable.

AUTHOR

Arkady Grudzinsky, <grudziar@linuxhightech.com>

SEE ALSO

perl.