NAME

DBIx::Class::Numeric - helper methods for numeric columns

SYNOPSIS

 package MyApp::Schema::SomeTable;

 use base 'DBIx::Class';

 __PACKAGE__->load_components(qw/Numeric Core/); # Load the Numeric component
                                                                                                 # Don't forget to load it *before* Core!
 __PACKAGE__->add_columns(
     qw/primary_id some_string num_col1 num_col2 restricted bounded lower_bound upper_bound/
 );

 # Define 'simple' numeric cols, these will have some extra accessors & mutators
 #  created
 __PACKAGE__->numeric_columns(qw/num_col1 num_col2/);
 
 # Define min and max values for a column
 __PACKAGE__->numeric_columns(restricted => {min_value => 10, max_value => 30});
 
 # Define a column that's bound by the value of others
 __PACKAGE__->numeric_columns(bounded => {lower_bound_col => 'lower_bound', upper_bound_col => 'upper_bound'});

 # ... meanwhile, after reading a record from the DB

 $row->increase_num_col1(5); # Add 5 to num_col1

 $row->decrease_num_col2(9); # Subtract 9 from num_col2

 $row->adjust_num_col1(-5); # Subtract 5 from num_col1
                            # (can be positive or negative, as can increase/decrease...
                            #  adjust is just a clearer name...) 

 $row->increment_num_col1; # Increment num_col1

 $row->decrement_num_col2; # Decrement num_col2
 
 $row->restricted(40); # restricted col will be set to '30' since that's the max
 
 $row->lower_bound(5);
 $row->bounded(10);   # bounded will be set to '5', since its lower bound was set to 5

DESCRIPTION

A DBIx::Class component that adds some extra accessors / mutators to any numeric columns you define. Additionally, columns can have max and min values defined, or be bound to the values of other columns in the table.

METHODS

numeric_columns(@cols)

Call this method as you would add_columns(), and pass it a list of columns that are numeric. Note, you need to pass the column names to add_columns() *and* numeric_columns().

Any columns in this list will have extra accessors / mutators defined (see below).

If the item in the list after a column name is a hashref, the hashref will define the arguments for that numeric column. (If the next item's not a hashref, it's assumed to be the next column - you can mix and match columns with and without arguments in the same call to numeric_colums().

The valid keys in the argument hashref are:

min_value / max_value

These two keys define the minimum and/or maximum value of the column. If you attempt to set the column to a value outside this range, it will be set to that min or max value accordingly.

lower_bound_col / upper_bound_col

If either of these are set to the name of a column in the same table, the numeric column will be restricted in the same way as a min or max value, except the min/max value will be defined by the value of the column specified.

If the value of the lower or upper bound column changes, the bounded column won't be affected, until its value is set. Eg. if your bounded column is currently 5, and you set it's lower_bound_col to 8 the bounded col won't change, even though it's below the minimum value. If you were to (eg) increment the column, it would then be set to 8.

WARNING

Little (if any) validation is done on the list of cols passed to numeric_columns(). You could easily pass it non-existant column names, etc. (This may be improved in a later release).

In particular, no check is made to see if you are using incompatible combinations of min/max_value and lower/uppper_bound_col (e.g. both a min_value and a lower_bound_col). Doing this is unsupported, and may be prevented in the future (even thought it might 'kind of' work at the moment). You're free to use compatible combinations, though, eg. a min_value and an upper_bound_col.

increase_*, decrease_*, increment_*, decrement_*, adjust_*

These 5 methods are added to your schema class for each column you pass to numeric_cols(). E.g. if you have a numeric column called 'foo', you will automagically get methods called increment_foo(), decrement_foo(), etc. They are fairly self-explanatory, with the possible exception of 'adjust_*'. You can pass it either a positive or negative value to adjust the value of the column accordingly.

AUTHOR

Sam Crawley (Mutant) - mutant dot nz at gmail dot com

LICENSE

You may distribute this code under the same terms as Perl itself.