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

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

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

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

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

This is a Tie object to map a SUBSET of the records in a Tie::FieldVals data file into an array. It is a sub-class of Tie::FieldVals. 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.

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

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();

$sel->sort_records( sort_by=>[qw(Author Series SeriesOrder Title Date)], sort_numeric=>{ SeriesOrder=>1 }, sort_title=>{ Title=>1 }, sort_lastword=>{ Author=>1 }, sort_reversed=>{ Date=>1 });

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

The other arguments are for indications of changes to the type of sorting done on the given fields.

sort_numeric

The given field(s) should be sorted as numbers. Note that for multi-valued fields, this compares only the first value in the set.

sort_title

The given field(s) should be treated as titles: any leading "The " or "A " will be ignored.

sort_lastword

The given field(s) will be sorted with their last word first (such as for surnames).

sort_reversed

The given field(s) will be sorted in reverse order.

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

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

    tie @SEL_RECS, 'Tie::FieldVals::Select',
	datafile=>$datafile, selection=>{$key=>$value},
	match_any=>$val_any;

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

Other options are the same as for TIEARRAY in Tie::FieldVals.

Get a row from the array.

    $val = $array[$ind];

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

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.

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.

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

    exists $array[$ind];

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

    delete $array[$ind];

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

    @array = ();

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

    untie @array;

Untie the array.

For developer reference only.

Set debugging on.

For debugging: say who called this

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

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

Please report any bugs or feature requests to the author.

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

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.