NAME

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

VERSION

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

SYNOPSIS

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

DESCRIPTION

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.

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=>[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_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',
	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.

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