.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "DBIx::Class::FilterColumn 3pm"
.TH DBIx::Class::FilterColumn 3pm "2022-05-21" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
DBIx::Class::FilterColumn \- Automatically convert column data
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
In your Schema or \s-1DB\s0 class add \*(L"FilterColumn\*(R" to the top of the component list.
.PP
.Vb 1
\&  _\|_PACKAGE_\|_\->load_components(qw( FilterColumn ... ));
.Ve
.PP
Set up filters for the columns you want to convert.
.PP
.Vb 4
\& _\|_PACKAGE_\|_\->filter_column( money => {
\&     filter_to_storage => \*(Aqto_pennies\*(Aq,
\&     filter_from_storage => \*(Aqfrom_pennies\*(Aq,
\& });
\&
\& sub to_pennies   { $_[1] * 100 }
\&
\& sub from_pennies { $_[1] / 100 }
\&
\& 1;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This component is meant to be a more powerful, but less DWIM-y,
DBIx::Class::InflateColumn.  One of the major issues with said component is
that it \fBonly\fR works with references.  Generally speaking anything that can
be done with DBIx::Class::InflateColumn can be done with this component.
.SH "METHODS"
.IX Header "METHODS"
.SS "filter_column"
.IX Subsection "filter_column"
.Vb 4
\& _\|_PACKAGE_\|_\->filter_column( colname => {
\&     filter_from_storage => \*(Aqmethod\*(Aq|\e&coderef,
\&     filter_to_storage   => \*(Aqmethod\*(Aq|\e&coderef,
\& })
.Ve
.PP
This is the method that you need to call to set up a filtered column. It takes
exactly two arguments; the first being the column name the second being a hash
reference with \f(CW\*(C`filter_from_storage\*(C'\fR and \f(CW\*(C`filter_to_storage\*(C'\fR set to either
a method name or a code reference. In either case the filter is invoked as:
.PP
.Vb 1
\&  $result\->$filter_specification ($value_to_filter)
.Ve
.PP
with \f(CW$filter_specification\fR being chosen depending on whether the
\&\f(CW$value_to_filter\fR is being retrieved from or written to permanent
storage.
.PP
If a specific directional filter is not specified, the original value will be
passed to/from storage unfiltered.
.SS "get_filtered_column"
.IX Subsection "get_filtered_column"
.Vb 1
\& $obj\->get_filtered_column(\*(Aqcolname\*(Aq)
.Ve
.PP
Returns the filtered value of the column
.SS "set_filtered_column"
.IX Subsection "set_filtered_column"
.Vb 1
\& $obj\->set_filtered_column(colname => \*(Aqnew_value\*(Aq)
.Ve
.PP
Sets the filtered value of the column
.SH "EXAMPLE OF USE"
.IX Header "EXAMPLE OF USE"
Some databases have restrictions on values that can be passed to
boolean columns, and problems can be caused by passing value that
perl considers to be false (such as \f(CW\*(C`undef\*(C'\fR).
.PP
One solution to this is to ensure that the boolean values are set
to something that the database can handle \- such as numeric zero
and one, using code like this:\-
.PP
.Vb 5
\&    _\|_PACKAGE_\|_\->filter_column(
\&        my_boolean_column => {
\&            filter_to_storage   => sub { $_[1] ? 1 : 0 },
\&        }
\&    );
.Ve
.PP
In this case the \f(CW\*(C`filter_from_storage\*(C'\fR is not required, as just
passing the database value through to perl does the right thing.
.SH "FURTHER QUESTIONS?"
.IX Header "FURTHER QUESTIONS?"
Check the list of additional \s-1DBIC\s0 resources.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This module is free software copyright
by the DBIx::Class (\s-1DBIC\s0) authors. You can
redistribute it and/or modify it under the same terms as the
DBIx::Class library.