view release on metacpan or  search on metacpan

lib/DBIx/Class/ResultSet.pm  view on Meta::CPAN

=back

  my @cds    = $cd_rs->search({ year => 2001 }); # "... WHERE year = 2001"
  my $new_rs = $cd_rs->search({ year => 2005 });

  my $new_rs = $cd_rs->search([ { year => 2005 }, { year => 2004 } ]);
                 # year = 2005 OR year = 2004

In list context, C<< ->all() >> is called implicitly on the resultset, thus
returning a list of L<result|DBIx::Class::Manual::ResultClass> objects instead.
To avoid that, use L</search_rs>.

If you need to pass in additional attributes but no additional condition,
call it as C<search(undef, \%attrs)>.

  # "SELECT name, artistid FROM $artist_table"
  my @all_artists = $schema->resultset('Artist')->search(undef, {
    columns => [qw/name artistid/],
  });

For a list of attributes that can be passed to C<search>, see
L</ATTRIBUTES>. For more examples of using this function, see
L<Searching|DBIx::Class::Manual::Cookbook/SEARCHING>. For a complete
documentation for the first argument, see
L<SQL::Abstract::Classic/"WHERE CLAUSES"> and its extension
L<DBIx::Class::SQLMaker>.

For more help on using joins with search, see L<DBIx::Class::Manual::Joining>.

=head3 CAVEAT

Note that L</search> does not process/deflate any of the values passed in the
L<SQL::Abstract::Classic>-compatible search condition structure. This is unlike
other condition-bound methods L</new_result>, L</create> and L</find>. The user
must ensure manually that any value passed to this method will stringify to
something the RDBMS knows how to deal with. A notable example is the handling
of L<DateTime> objects, for more info see:
L<DBIx::Class::Manual::Cookbook/Formatting DateTime objects in queries>.

=cut

sub search {
  my $self = shift;
  my $rs = $self->search_rs( @_ );

  if (wantarray) {
    DBIx::Class::_ENV_::ASSERT_NO_INTERNAL_WANTARRAY and my $sog = fail_on_internal_wantarray;
    return $rs->all;
  }
  elsif (defined wantarray) {
    return $rs;
  }
  else {
    # we can be called by a relationship helper, which in
    # turn may be called in void context due to some braindead
    # overload or whatever else the user decided to be clever
    # at this particular day. Thus limit the exception to
    # external code calls only
    $self->throw_exception ('->search is *not* a mutator, calling it in void context makes no sense')
      if (caller)[0] !~ /^\QDBIx::Class::/;

    return ();
  }
}

=head2 search_rs

=over 4

=item Arguments: L<$cond|DBIx::Class::SQLMaker>, L<\%attrs?|/ATTRIBUTES>

=item Return Value: L<$resultset|/search>

=back

This method does the same exact thing as search() except it will
always return a resultset, even in list context.

=cut

sub search_rs {
  my $self = shift;

  my $rsrc = $self->result_source;
  my ($call_cond, $call_attrs);

  # Special-case handling for (undef, undef) or (undef)
  # Note that (foo => undef) is valid deprecated syntax
  @_ = () if not scalar grep { defined $_ } @_;

  # just a cond
  if (@_ == 1) {
    $call_cond = shift;
  }
  # fish out attrs in the ($condref, $attr) case
  elsif (@_ == 2 and ( ! defined $_[0] or (ref $_[0]) ne '') ) {
    ($call_cond, $call_attrs) = @_;
  }
  elsif (@_ % 2) {
    $self->throw_exception('Odd number of arguments to search')
  }
  # legacy search
  elsif (@_) {
    carp_unique 'search( %condition ) is deprecated, use search( \%condition ) instead'
      unless $rsrc->result_class->isa('DBIx::Class::CDBICompat');

    for my $i (0 .. $#_) {
      next if $i % 2;
      $self->throw_exception ('All keys in condition key/value pairs must be plain scalars')
        if (! defined $_[$i] or ref $_[$i] ne '');
    }

    $call_cond = { @_ };
  }

  # see if we can keep the cache (no $rs changes)
  my $cache;
  my %safe = (alias => 1, cache => 1);
  if ( ! grep { !$safe{$_} } keys %$call_attrs and (
    ! defined $call_cond