File-BetweenTree version 1.02
=============================

NAME

File::BetweenTree.pm - binary search of variable length.


SYNOPSIS

        use File::BetweenTree;

        # Object interface
        $bt = File::BetweenTree->new("log_file") or
                        die "Can't open file: $!";

        # .. Gets between a and b
        $result_array_ref = $bt->search($a, $b);

        # .. or only a
        $result_array_ref = $bt->search($a);

        # .. process monitor
        print $bt->mon;


DESCRIPTION

        This module tracks the data instantly from "Sorted file of variable length" 
        with a binary search. It is simple to use,
        memory efficient and search instantly from the files of 100 million.

        You can choose to search in ascending or descending order.Further Can set 
        the offset and the number of results.
        you can set the input record separator string on a per file basis.


OBJECT INTERFACE
 
        These are the methods in C<File::BetweenTree>' object interface:

new($file, [ $rec_sep ]);

        C<new> takes as arguments a filename, an optional record separator.
        set the default record separator according to this OS.


search

        C<search> is able to find all of the intermediate element "two elements".

                search(
                $a, $b, [mode], [limit], [offset], [order_by], [col_sep], [col_num]
                );

        look for the data between <$a> and <$b>.
        <$a>, the maximum and minimum values are <$b>.
        It can be the same value <$b> a <$a>.

        The return value is an array reference. If you can not find a match, 
        it returns a NULL data. Nearby value is returned to the second. Become 
        undef if the minimum value of the one front does not exist.

                @{$result_array_ref}[0] => NULL
                @{$result_array_ref}[1] => ..Minimum value near

        C<mode> is optional; the default is '0'
        Search target set number or a text string. Settings are required to 
        appropriate an accurate result.

        [mode]
        0 : number string search dedicated
        1 : text string search dedicated.

        C<limit> is optional; the default is '1000'

        [limit]
        You can use C<limit> to restrict the scope of the C<search>.

        C<offset> is optional; the default is '0'

        [offset]
        This specifies the offset of the first row to return

        C<order_by> is optional; the default is 'ASC'
        Select a search in ascending or descending order

        [order_by]
        ASC  : ascending
        DESC : descending

        C<col_sep> is optional; the default is ','
        You can specify a separator to divide the line.

        [col_sep]
        example: value_0:value_1:value_2 => ":"

        C<col_num> is optional; the default is '0'
        Order of the sequence obtained by dividing the line.

        [col_num]
        example: value_0,value_1,value2 => Value_1 and is "1"


For example:

        foo.txt
        -------
        0:apple
        1:apple
        2:apple
        3:blackberry
        4:blackberry
        5:lemon
        6:lemon
        7:lemon
        8:orange
        9:orange
        0:pine

        my $result_array_ref = $bt->search(
           'lemon', # mininum data
           'orang', # maximum data
           1,       # mode is text string
           10,      # result 10 limit
           0,       # offset 0
           'ASC',   # order_by: ascending
           ':',     # separator to divide the line
           1,       # data of the second from the left
           );
        print "result = " . join("\n", @{$result_array_ref});

        result = 5:lemon 6:lemon 7:lemon 8:orange 9:orange


mon

        You can monitor the state of the processing

        print $bt->mon;

        Process:
        -----------------------
        file_read:1 roughly_start_addr:420200 search_length:2285

        <=|<- 37415913 18707956
        <=|<- 18707957 9353978
        <=|<- 9353979 4676989
        <=|<- 4676990 2338494
        <=|<- 2338496 1169247
        <=|<- 1169249 584623
        <=|<- 584626 292311
        =>|-> 292315 146155 | min
        <=|<- 438470 73077
        =>|-> 365393 36538 | min
        =>|-> 401931 18269 | min
        =>|-> 420200 9134 | min
        <=|<- 429334 4567
        <=|<- 424767 2283
        <=|   421342 1141 | max

        Interpretation above

        <- : $a Move to low  addr the current pointer.
        -> : $a Move to high addr the current pointer.
        <= : $b Move to low  addr the current pointer.
        => : $b Move to high addr the current pointer.

        Number of first : current pointer addr.
        Number of second: Amount of movement of the pointer.

        | min : Addr with a minimum value determined for the time being.
        | max : Addr with a maximum value determined for the time being.

        please try to run the "example/test_large_lows.cgi"

AUTHOR

        Mitsuru Yasuda, dsyrtm@gmail.com

        http://simql.com/


COPYRIGHT & LICENSE

        Copyright (C) 2013 by Mitsuru Yasuda &

        This library is free software; you can redistribute it and/or modify
        it under the same terms as Perl itself, either Perl version 5.14.2 or,
        at your option, any later version of Perl 5 you may have available.