.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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::Helper::ResultSet::Shortcut 3pm"
.TH DBIx::Class::Helper::ResultSet::Shortcut 3pm "2022-12-06" "perl v5.36.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::Helper::ResultSet::Shortcut \- Shortcuts to common searches (\->order_by, etc)
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& package MyApp::Schema::ResultSet::Foo;
\&
\& _\|_PACKAGE_\|_\->load_components(qw{Helper::ResultSet::Shortcut});
\&
\& ...
\&
\& 1;
.Ve
.PP
And then elsewhere:
.PP
.Vb 12
\& # let\*(Aqs say you grab a resultset from somewhere else
\& my $foo_rs = get_common_rs()
\& # but I\*(Aqd like it sorted!
\&   \->order_by({ \-desc => \*(Aqpower_level\*(Aq })
\& # and without those other dumb columns
\&   \->columns([qw/cromulence_ratio has_jimmies_rustled/])
\& # but get rid of those duplicates
\&   \->distinct
\& # and put those straight into hashrefs, please
\&   \->hri
\& # but only give me the first 3
\&   \->rows(3);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This helper provides convenience methods for resultset modifications.
.PP
See \*(L"\s-1NOTE\*(R"\s0 in DBIx::Class::Helper::ResultSet for a nice way to apply it to your
entire schema.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
This component is actually a number of other components put together.  It will
get more components added to it over time.  If you are worried about all the
extra methods you won't use or something, using the individual shortcuts is
a simple solution.  All the documentation will remain here, but the individual
components are:
.IP "\(bu" 2
DBIx::Class::Helper::ResultSet::Shortcut::HRI
.IP "\(bu" 2
DBIx::Class::Helper::ResultSet::Shortcut::OrderBy
.IP "\(bu" 2
DBIx::Class::Helper::ResultSet::Shortcut::OrderByMagic
.Sp
(adds the \*(L"magic string\*(R" functionality to
\&\f(CW\*(C`DBIx::Class::Helper::ResultSet::Shortcut::OrderBy\*(C'\fR))
.IP "\(bu" 2
DBIx::Class::Helper::ResultSet::Shortcut::GroupBy
.IP "\(bu" 2
DBIx::Class::Helper::ResultSet::Shortcut::Distinct
.IP "\(bu" 2
DBIx::Class::Helper::ResultSet::Shortcut::Rows
.IP "\(bu" 2
DBIx::Class::Helper::ResultSet::Shortcut::Limit
.Sp
(inherits from \f(CW\*(C`DBIx::Class::Helper::ResultSet::Shortcut::Rows\*(C'\fR)
.IP "\(bu" 2
DBIx::Class::Helper::ResultSet::Shortcut::HasRows
.Sp
(inherits from \f(CW\*(C`DBIx::Class::Helper::ResultSet::Shortcut::Rows\*(C'\fR)
.IP "\(bu" 2
DBIx::Class::Helper::ResultSet::Shortcut::Columns
.IP "\(bu" 2
DBIx::Class::Helper::ResultSet::Shortcut::AddColumns
.IP "\(bu" 2
DBIx::Class::Helper::ResultSet::Shortcut::Page
.IP "\(bu" 2
DBIx::Class::Helper::ResultSet::Shortcut::LimitedPage
.Sp
(inherits from \f(CW\*(C`DBIx::Class::Helper::ResultSet::Shortcut::Page\*(C'\fR and
DBIx::Class::Helper::ResultSet::Shortcut::Rows)
.IP "\(bu" 2
DBIx::Class::Helper::ResultSet::Shortcut::ResultsExist
.SH "METHODS"
.IX Header "METHODS"
.SS "distinct"
.IX Subsection "distinct"
.Vb 1
\& $foo_rs\->distinct
\&
\& # equivalent to...
\& $foo_rs\->search(undef, { distinct => 1 });
.Ve
.SS "group_by"
.IX Subsection "group_by"
.Vb 1
\& $foo_rs\->group_by([ qw/ some column names /])
\&
\& # equivalent to...
\& $foo_rs\->search(undef, { group_by => [ qw/ some column names /] });
.Ve
.SS "order_by"
.IX Subsection "order_by"
.Vb 1
\& $foo_rs\->order_by({ \-desc => \*(Aqcol1\*(Aq });
\&
\& # equivalent to...
\& $foo_rs\->search(undef, { order_by => { \-desc => \*(Aqcol1\*(Aq } });
.Ve
.PP
You can also specify the order as a \*(L"magic string\*(R", e.g.:
.PP
.Vb 4
\& $foo_rs\->order_by(\*(Aq!col1\*(Aq)       # \->order_by({ \-desc => \*(Aqcol1\*(Aq })
\& $foo_rs\->order_by(\*(Aqcol1,col2\*(Aq)   # \->order_by([qw(col1 col2)])
\& $foo_rs\->order_by(\*(Aqcol1,!col2\*(Aq)  # \->order_by([{ \-asc => \*(Aqcol1\*(Aq }, { \-desc => \*(Aqcol2\*(Aq }])
\& $foo_rs\->order_by(qw(col1 col2)) # \->order_by([qw(col1 col2)])
.Ve
.PP
Can mix it all up as well:
.PP
.Vb 1
\& $foo_rs\->order_by(qw(col1 col2 col3), \*(Aqcol4,!col5\*(Aq)
.Ve
.SS "hri"
.IX Subsection "hri"
.Vb 1
\& $foo_rs\->hri;
\&
\& # equivalent to...
\& $foo_rs\->search(undef, {
\&    result_class => \*(AqDBIx::Class::ResultClass::HashRefInflator\*(Aq
\& });
.Ve
.SS "rows"
.IX Subsection "rows"
.Vb 1
\& $foo_rs\->rows(10);
\&
\& # equivalent to...
\& $foo_rs\->search(undef, { rows => 10 })
.Ve
.SS "limit"
.IX Subsection "limit"
This is an alias for \f(CW\*(C`rows\*(C'\fR.
.PP
.Vb 1
\&  $foo_rs\->limit(10);
\&
\&  # equivalent to...
\&  $foo_rs\->rows(10);
.Ve
.SS "has_rows"
.IX Subsection "has_rows"
A lighter way to check the resultset contains any data rather than
calling \f(CW\*(C`$rs\->count\*(C'\fR.
.SS "page"
.IX Subsection "page"
.Vb 1
\& $foo_rs\->page(2);
\&
\& # equivalent to...
\& $foo_rs\->search(undef, { page => 2 })
.Ve
.SS "limited_page"
.IX Subsection "limited_page"
.Vb 1
\& $foo_rs\->limited_page(2, 3);
\&
\& # equivalent to...
\& $foo_rs\->search(undef, { page => 2, rows => 3 })
.Ve
.SS "columns"
.IX Subsection "columns"
.Vb 1
\& $foo_rs\->columns([qw/ some column names /]);
\&
\& # equivalent to...
\& $foo_rs\->search(undef, { columns => [qw/ some column names /] });
.Ve
.SS "add_columns"
.IX Subsection "add_columns"
.Vb 1
\& $foo_rs\->add_columns([qw/ some column names /]);
\&
\& # equivalent to...
\& $foo_rs\->search(undef, { \*(Aq+columns\*(Aq => [qw/ some column names /] });
.Ve
.SS "remove_columns"
.IX Subsection "remove_columns"
.Vb 1
\& $foo_rs\->remove_columns([qw/ some column names /]);
\&
\& # equivalent to...
\& $foo_rs\->search(undef, { remove_columns => [qw/ some column names /] });
.Ve
.SS "prefetch"
.IX Subsection "prefetch"
.Vb 1
\& $foo_rs\->prefetch(\*(Aqbar\*(Aq);
\&
\& # equivalent to...
\& $foo_rs\->search(undef, { prefetch => \*(Aqbar\*(Aq });
.Ve
.SS "results_exist($cond?)"
.IX Subsection "results_exist($cond?)"
.Vb 1
\& my $results_exist = $schema\->resultset(\*(AqBar\*(Aq)\->search({...})\->results_exist;
\&
\& # there is no easily expressable equivalent, so this is not exactly a
\& # shortcut. Nevertheless kept in this class for historical reasons
.Ve
.PP
Uses \f(CW\*(C`EXISTS\*(C'\fR \s-1SQL\s0 function to check if the query would return anything.
Usually much less resource intensive the more common \f(CW\*(C`foo() if $rs\->count\*(C'\fR
idiom.
.PP
The optional \f(CW$cond\fR argument can be used like in \f(CW\*(C`search()\*(C'\fR.
.SS "results_exist_as_query($cond?)"
.IX Subsection "results_exist_as_query($cond?)"
.Vb 6
\& ...\->search(
\&    {},
\&    { \*(Aq+columns\*(Aq => {
\&       subquery_has_members => $some_correlated_rs\->results_exist_as_query
\&    }},
\& );
\&
\& # there is no easily expressable equivalent, so this is not exactly a
\& # shortcut. Nevertheless kept in this class for historical reasons
.Ve
.PP
The query generator behind \*(L"results_exist\*(R". Can be used standalone in
complex queries returning a boolean result within a larger query context.
.SS "null(@columns || \e@columns)"
.IX Subsection "null(@columns || @columns)"
.Vb 2
\& $rs\->null(\*(Aqstatus\*(Aq);
\& $rs\->null([\*(Aqstatus\*(Aq, \*(Aqtitle\*(Aq]);
.Ve
.SS "not_null(@columns || \e@columns)"
.IX Subsection "not_null(@columns || @columns)"
.Vb 2
\& $rs\->not_null(\*(Aqstatus\*(Aq);
\& $rs\->not_null([\*(Aqstatus\*(Aq, \*(Aqtitle\*(Aq]);
.Ve
.ie n .SS "like($column || \e@columns, $cond)"
.el .SS "like($column || \e@columns, \f(CW$cond\fP)"
.IX Subsection "like($column || @columns, $cond)"
.Vb 2
\& $rs\->like(\*(Aqlyrics\*(Aq, \*(Aq%zebra%\*(Aq);
\& $rs\->like([\*(Aqlyrics\*(Aq, \*(Aqtitle\*(Aq], \*(Aq%zebra%\*(Aq);
.Ve
.ie n .SS "not_like($column || \e@columns, $cond)"
.el .SS "not_like($column || \e@columns, \f(CW$cond\fP)"
.IX Subsection "not_like($column || @columns, $cond)"
.Vb 2
\& $rs\->not_like(\*(Aqlyrics\*(Aq, \*(Aq%zebra%\*(Aq);
\& $rs\->not_like([\*(Aqlyrics\*(Aq, \*(Aqtitle\*(Aq], \*(Aq%zebra%\*(Aq);
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Arthur Axel \*(L"fREW\*(R" Schmidt <frioux+cpan@gmail.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2020 by Arthur Axel \*(L"fREW\*(R" Schmidt.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.