• NAME
• SYNOPSIS
• DESCRIPTION
• METHODS
• UTF-8 SUPPORT
• WARNINGS
• EXAMPLES
• AUTHOR

NAME

AZ::Splitter - Splitting and extracting data from file or from string, with loading into memory in parts

SYNOPSIS

  use AZ::Splitter;    # With flags importing into current namespace
  use AZ::Splitter (); # Access to flags from AZ:: namespace only

  $s = new AZ::Splitter(\*IN);
  $s = new AZ::Splitter(\*IN, $limitsize);
  $s = new AZ::Splitter(\*IN, $limitsize, $buffsize);
  $s = new AZ::Splitter(\*IN, $limitsize, $buffsize, s_2BUFF|s_UTFOK);
  $s = new AZ::Splitter(\$SCALAR, ...); # Same for scalar variables

  $s->read_to(\*OUT, $separator);
  $s->read_to(\*OUT, $separator, $maxsize);
  $s->read_to(\*OUT, $separator, $maxsize, s_APPEND|s_WEND|s_WCASE);
  $s->read_to(\*OUT, \@separators, ...) # Many separators
  $s->read_to(\$SCALAR, ...); # Same for scalar variables
  $s->read_to(undef, ...);    # Only rewind

  $s->read_some(\*OUT);
  $s->read_some(\*OUT, $maxsize);
  $s->read_some(\*OUT, $maxsize, s_APPEND);
  $s->read_some(\$SCALAR, ...); # Same for scalar variables
  $s->read_some(undef, ...);    # Only rewind

  $s->stat_rsize();
  $s->stat_wsize();
  $s->stat_match();
  $s->stat_error();

DESCRIPTION

This is object-oriented class for fast and simple splitting big files or strings with using little memory. As the same can be used for searching data in files, but the main fuction is parsing big volume data.

METHODS

new(STREAM_IN, [SIZE_LIMIT, BUFF_SIZE, FLAGS])

The constructor method instantiates a new AZ::Splitter object.

STREAM_IN - is reference to file stream, opened for read, or reference to string.

SIZE_LIMIT - limit size of input stream data in characters. If this argument not defined or equal to -1, then all input stream data will be avaible for read.

BUFF_SIZE - size of buffer in characters. If this argument not defined or equal to -1, then will be used default buffer size 32768 characters.

FLAGS - in this method avaible 2 modificators:

s_2BUFF - use second buffer. Can really speed up search in case insensitive mode.

s_UTFOK - disable utf8 data check in UTF-8 mode. Use this flag if you really sure, what your UTF-8 data is valid.

read_to(STREAM_OUT, SEPARATORS, [MAX_SIZE, FLAGS])

This method reads all data from input stream before first found separator, begining from current position. Returns true value if found separator or end of stream expected at first time. Else, or at reading error, will returns false value.

STREAM_OUT - is reference to file stream, opened for write, or reference to string. If other type of value (ex: undef), then data will be not stored.

SEPARATORS - is string-separator or reference to array with many separators.

MAX_SIZE - size in characters. Defines, how much maximum characters must be stored into STREAM_OUT. If this argument not defined or equal to -1, then this method will be trying to store all readed data.

FLAGS - in this method avaible 3 modificators:

s_APPEND - append data to STREAM_OUT if STREAM_OUT is reference to string.

s_WCASE - search in case insencitive mode.

s_WEND - at the end of input stream alltimes returns the false value.

read_some(STREAM_OUT, [MAX_SIZE, FLAGS])

This method method read fixed quantity of characters from input stream begining from current position. Returns true value, if any characters was readed or end of input stream not expected. Else, or at reading error, will returns false value.

STREAM_OUT - same as in read_to() method.

MAX_SIZE - limit size in characters, how many is necessary to read. If this argument not defined or equal to -1, then will be readed all avaible data from input stream.

FLAGS - only one modificator avaible:

s_APPEND - same as in read_to() method.

stat_wsize()

Returns quantity of characters, what was readed at last using of read_to() or read_some() methods. After using read_to() method this size not including size of found separator.

stat_rsize()

Returns quantity of characters, what was successfully stored at last using of read_to() or read_some() methods. This parameter can't be more then stat_wsize() parameter.

stat_match()

Returns found separator at last use of read_to() method or empty string.

stat_error()

Returns error status. In any reading errors methods read_to() and read_some() immediately stop any operations, returns false status and set up this paramerer to true value.

UTF-8 SUPPORT

Full supported when using perl version 5.8.0, or higher. Input stream, separators, and result reference(if this is file stream), must be in UTF-8 mode. If input stream will have malformed UTF-8 data, then reading from stream will be immediately stoped.

WARNINGS

Remember! This class using block reading and before destruct class-object, you should work with input stream only through this class methods.

In UTF-8 mode search without case sensitive is very slowly.. It becouse operation of changing case on UTF-8 data have slow speed.

Remember, at UTF-8 mode all sizes of this module containing characters, not bytes!

All flags exists in AZ:: namespace and you can not import them to your namespace if you don't want.

EXAMPLES

Reading configuration file:

  # Opening configuration file
  open(F, "<", "config.txt") or die $!;

  # Create new AZ::Splitter object
  # and associate with opened configuration file
  my $s = new AZ::Splitter(\*F);

  # Reading line per line in variable $line
  for (my $line; $s->read_to(\$line, "\r\n");)
  {
      # Do something with $line
  }

Find one of substrings in file without case sensetive:

  # Initialize array of strings
  my @strings=("word1", "word2", "phrase 1", "word3");

  # Open some file for reading
  open(F, "<", "file.txt") or die $!;

  # Create new AZ::Splitter object
  # and associate with opened file
  my $s = new AZ::Splitter(\*F);

  # Try to find, and print substring, when will found.
  my $result = $s->read_to(undef, \@strings, -1, s_WCASE|s_WEND)

  if ($result) {
      print "Found substring '".$s->stat_match()."'\n";
  }
  else {
      print "Nothing found..\n";
  }

AUTHOR

Andrian Zubko aka Ondr, <ondr@mail.ru>