lib/DBIx/Class/ResultSetColumn.pm

   1 package DBIx::Class::ResultSetColumn;
   2 use strict;
   3 use warnings;
   4 use base 'DBIx::Class';
   5
   6 =head1 NAME
   7
   8   DBIx::Class::ResultSetColumn - helpful methods for messing
   9   with a single column of the resultset
  10
  11 =head1 SYNOPSIS
  12
  13   $rs = $schema->resultset('CD')->search({ artist => 'Tool' });
  14   $rs_column = $rs->get_column('year');
  15   $max_year = $rs_column->max; #returns latest year
  16
  17 =head1 DESCRIPTION
  18
  19 A convenience class used to perform operations on a specific column of
  20 a resultset.
  21
  22 =cut
  23
  24 =head1 METHODS
  25
  26 =head2 new
  27
  28   my $obj = DBIx::Class::ResultSetColumn->new($rs, $column);
  29
  30 Creates a new resultset column object from the resultset and column
  31 passed as params. Used internally by L<DBIx::Class::ResultSet/get_column>.
  32
  33 =cut
  34
  35 sub new {
  36   my ($class, $rs, $column) = @_;
  37   $class = ref $class if ref $class;
  38   my $new = bless { _column => $column, _parent_resultset => $rs }, $class;
  39   $new->throw_exception("column must be supplied") unless $column;
  40   return $new;
  41 }
  42
  43 =head2 next
  44
  45 =over 4
  46
  47 =item Arguments: none
  48
  49 =item Return Value: $value
  50
  51 =back
  52
  53 Returns the next value of the column in the resultset (or C<undef> if
  54 there is none).
  55
  56 Much like L<DBIx::Class::ResultSet/next> but just returning the
  57 one value.
  58
  59 =cut
  60
  61 sub next {
  62   my $self = shift;
  63   $self->{_resultset} = $self->{_parent_resultset}->search(undef, {select => [$self->{_column}], as => [$self->{_column}]}) unless ($self->{_resultset});
  64   my ($row) = $self->{_resultset}->cursor->next;
  65   return $row;
  66 }
  67
  68 =head2 all
  69
  70 =over 4
  71
  72 =item Arguments: none
  73
  74 =item Return Value: @values
  75
  76 =back
  77
  78 Returns all values of the column in the resultset (or C<undef> if
  79 there are none).
  80
  81 Much like L<DBIx::Class::ResultSet/all> but returns values rather
  82 than row objects.
  83
  84 =cut
  85
  86 sub all {
  87   my $self = shift;
  88   return map {$_->[0]} $self->{_parent_resultset}->search(undef, {select => [$self->{_column}], as => [$self->{_column}]})->cursor->all;
  89 }
  90
  91 =head2 min
  92
  93 =over 4
  94
  95 =item Arguments: none
  96
  97 =item Return Value: $lowest_value
  98
  99 =back
 100
 101   my $first_year = $year_col->min();
 102
 103 Wrapper for ->func. Returns the lowest value of the column in the
 104 resultset (or C<undef> if there are none).
 105
 106 =cut
 107
 108 sub min {
 109   return shift->func('MIN');
 110 }
 111
 112 =head2 max
 113
 114 =over 4
 115
 116 =item Arguments: none
 117
 118 =item Return Value: $highest_value
 119
 120 =back
 121
 122   my $last_year = $year_col->max();
 123
 124 Wrapper for ->func. Returns the highest value of the column in the
 125 resultset (or C<undef> if there are none).
 126
 127 =cut
 128
 129 sub max {
 130   return shift->func('MAX');
 131 }
 132
 133 =head2 sum
 134
 135 =over 4
 136
 137 =item Arguments: none
 138
 139 =item Return Value: $sum_of_values
 140
 141 =back
 142
 143   my $total = $prices_col->sum();
 144
 145 Wrapper for ->func. Returns the sum of all the values in the column of
 146 the resultset. Use on varchar-like columns at your own risk.
 147
 148 =cut
 149
 150 sub sum {
 151   return shift->func('SUM');
 152 }
 153
 154 =head2 func
 155
 156 =over 4
 157
 158 =item Arguments: $function
 159
 160 =item Return Value: $function_return_value
 161
 162 =back
 163
 164   $rs = $schema->resultset("CD")->search({});
 165   $length = $rs->get_column('title')->func('LENGTH');
 166
 167 Runs a query using the function on the column and returns the
 168 value. Produces the following SQL:
 169
 170   SELECT LENGTH( title ) FROM cd me
 171
 172 =cut
 173
 174 sub func {
 175   my ($self,$function) = @_;
 176   my ($row) = $self->{_parent_resultset}->search(undef, {select => {$function => $self->{_column}}, as => [$self->{_column}]})->cursor->next;
 177   return $row;
 178 }
 179
 180 1;
 181
 182 =head1 AUTHORS
 183
 184 Luke Saunders <luke.saunders@gmail.com>
 185
 186 Jess Robinson
 187
 188 =head1 LICENSE
 189
 190 You may distribute this code under the same terms as Perl itself.
 191
 192 =cut