NAME

Tie::FieldVals::Select - an array tie for a subset of Tie::FieldVals data

VERSION

This describes version 0.20 of Tie::FieldVals::Select.

SYNOPSIS

    use Tie::FieldVals;
    use Tie::FieldVals::Row;
    use Tie::FieldVals::Select;

    my @records;
    tie @records, 'Tie::FieldVals', datafile=>$datafile;

    my @sel_recs;
    my $sel_obj = tie @sel_recs, 'Tie::FieldVals::Select',
	all_data=>\@records, selection=>{$key=>$value...};

    # sort the records
    $sel_obj->sort_records(sort_by=>@sort_order);
    

DESCRIPTION

This is a Tie object to map a SUBSET of the records in a Tie::FieldVals data file into an array. This is useful as a separate object because one can do things to it without affecting the underlying file, unlike with a Tie::FieldVals object. One can re-select the data, sort the data, or take a temporary "slice" of the data.

This depends on the Tie::FieldVals and Tie::FieldVals::Row modules.

OBJECT METHODS

make_selection

Select the records (again). Resets the selection and re-makes it with the new selection criteria.

    $arr_obj->make_selection(selection=>{$key=>$value},
		    match_any=>$val2);

    $arr_obj->make_selection(selection=>$value);

set_sel_slice

Set this selection to a sub-set of itself. In other words, keep the original selection, but perform all operations on a slice of it. Assumes the array is sorted, and that the selection is related to the sort order (for example, that key1=>value1 where key1 is the first key of the sort order).

    $arr_obj->set_sel_slice(selection=>{$key=>$value},
		    match_any=>$val2);
		    start_at_zero=>0);

clear_sel_slice

Restore this selection to the full selection (if it has been previously "sliced"). If it hasn't been previously sliced, then calling this makes no difference.

$arr_obj->clear_sel_slice();

sort_records

$sel->sort_records( sort_by=>\@sort_fields, sort_numeric=>\%sort_numeric, sort_reversed=>\%sort_reversed)

Take the current selected records array and sort it by field names. The @sort_fields array contains an array of field names for this data. Yes, that's right, you can sort on multiple fields.

You can alter the sort type for a field by giving a sort_numeric hash to indicate that a sort is numeric:

    %sort_numeric = (
	SeriesOrder => 1
    );

You can alter the sort direction for a field by giving a sort_reversed hash to indicate that the sort order is reversed:

    %sort_reversed = (
	Date => 1
    );

get_column

Get the data from a column. my @col = $obj->get_column(field_name=>$field_name, unique=>1);

If unique is true, then duplicate values will be eliminated.

This can be useful in operating on subsets of the selection, for example if one has sorted on a field, then one gets the column data for that field, with "unique" to true, then calls "set_sel_slice" with each unique value...

TIE-ARRAY METHODS

TIEARRAY

Create a new instance of the object as tied to an array.

    tie @sel_recs, 'Tie::FieldVals::Select',
	all_data=>\@records, selection=>{$key=>$value},
	match_any=>$val_any;

The all_data option is a reference to a Tie::FieldVals array, and selection and match_any options are the selection criteria used to define this sub-set; they have the same format as those used in "match" in Tie::FieldVals::Row and "match_any" in Tie::FieldVals::Row methods.

FETCH

Get a row from the array.

$val = $array[$ind];

Returns a reference to a Tie::FieldVals::Row hash, or undef.

STORE

Set a value in the array.

$array[$ind] = $val;

If $ind is bigger than the array, then do nothing. (If you want to add a new row to the data file, do it directly with the Tie::FieldVals array.) The $val is expected to be a Tie::FieldVals::Row hash. This does replace the given the data in the data file.

FETCHSIZE

Get the apparent size of the array. This gives the size of the current slice, not the size of the underlying array. Of course if we are not in "slice" mode, the two values will be the same.

STORESIZE

Set the apparent size of the array. This actually sets the size of the current slice of the array, not the underlying array.

EXISTS

exists $array[$ind];

Note that if the array is in "slice" mode, this will only say whether the row exists in the slice.

DELETE

delete $array[$ind];

Delete the value at $ind -- deletes from the selection. Does not delete from the data file.

CLEAR

@array = ();

Clear the array -- clears the selection. Does not affect the data file.

UNTIE

untie @array;

Untie the array.

PRIVATE METHODS

For developer reference only.

debug

Set debugging on.

whowasi

For debugging: say who called this

REQUIRES

Test::More
Carp
Data::Dumper
Tie::Array
Fcntl
Tie::FieldVals
Tie::FieldVals::Row

SEE ALSO

perl(1). Tie::FieldVals Tie::FieldVals::Row

BUGS

Please report any bugs or feature requests to the author.

AUTHOR

Kathryn Andersen (RUBYKAT)
perlkat AT katspace dot com
http://www.katspace.com

COPYRIGHT AND LICENCE

Copyright (c) 2004 by Kathryn Andersen

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.