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_parent_rs = $rs->search_rs; # we don't want to mess up the original, so clone it
  39   $new_parent_rs->{attrs}->{prefetch} = undef; # prefetch causes additional columns to be fetched
  40   my $new = bless { _column => $column, _parent_resultset => $new_parent_rs }, $class;
  41   $new->throw_exception("column must be supplied") unless $column;
  42   return $new;
  43 }
  44
  45 =head2 next
  46
  47 =over 4
  48
  49 =item Arguments: none
  50
  51 =item Return Value: $value
  52
  53 =back
  54
  55 Returns the next value of the column in the resultset (or C<undef> if
  56 there is none).
  57
  58 Much like L<DBIx::Class::ResultSet/next> but just returning the
  59 one value.
  60
  61 =cut
  62
  63 sub next {
  64   my $self = shift;
  65   $self->{_resultset} = $self->{_parent_resultset}->search(undef, {select => [$self->{_column}], as => [$self->{_column}]}) unless ($self->{_resultset});
  66   my ($row) = $self->{_resultset}->cursor->next;
  67   return $row;
  68 }
  69
  70 =head2 all
  71
  72 =over 4
  73
  74 =item Arguments: none
  75
  76 =item Return Value: @values
  77
  78 =back
  79
  80 Returns all values of the column in the resultset (or C<undef> if
  81 there are none).
  82
  83 Much like L<DBIx::Class::ResultSet/all> but returns values rather
  84 than row objects.
  85
  86 =cut
  87
  88 sub all {
  89   my $self = shift;
  90   return map {$_->[0]} $self->{_parent_resultset}->search(undef, {select => [$self->{_column}], as => [$self->{_column}]})->cursor->all;
  91 }
  92
  93 =head2 min
  94
  95 =over 4
  96
  97 =item Arguments: none
  98
  99 =item Return Value: $lowest_value
 100
 101 =back
 102
 103   my $first_year = $year_col->min();
 104
 105 Wrapper for ->func. Returns the lowest value of the column in the
 106 resultset (or C<undef> if there are none).
 107
 108 =cut
 109
 110 sub min {
 111   return shift->func('MIN');
 112 }
 113
 114 =head2 max
 115
 116 =over 4
 117
 118 =item Arguments: none
 119
 120 =item Return Value: $highest_value
 121
 122 =back
 123
 124   my $last_year = $year_col->max();
 125
 126 Wrapper for ->func. Returns the highest value of the column in the
 127 resultset (or C<undef> if there are none).
 128
 129 =cut
 130
 131 sub max {
 132   return shift->func('MAX');
 133 }
 134
 135 =head2 sum
 136
 137 =over 4
 138
 139 =item Arguments: none
 140
 141 =item Return Value: $sum_of_values
 142
 143 =back
 144
 145   my $total = $prices_col->sum();
 146
 147 Wrapper for ->func. Returns the sum of all the values in the column of
 148 the resultset. Use on varchar-like columns at your own risk.
 149
 150 =cut
 151
 152 sub sum {
 153   return shift->func('SUM');
 154 }
 155
 156 =head2 func
 157
 158 =over 4
 159
 160 =item Arguments: $function
 161
 162 =item Return Value: $function_return_value
 163
 164 =back
 165
 166   $rs = $schema->resultset("CD")->search({});
 167   $length = $rs->get_column('title')->func('LENGTH');
 168
 169 Runs a query using the function on the column and returns the
 170 value. Produces the following SQL:
 171
 172   SELECT LENGTH( title ) FROM cd me
 173
 174 =cut
 175
 176 sub func {
 177   my ($self,$function) = @_;
 178   my ($row) = $self->{_parent_resultset}->search(undef, {select => {$function => $self->{_column}}, as => [$self->{_column}]})->cursor->next;
 179   return $row;
 180 }
 181
 182 1;
 183
 184 =head1 AUTHORS
 185
 186 Luke Saunders <luke.saunders@gmail.com>
 187
 188 Jess Robinson
 189
 190 =head1 LICENSE
 191
 192 You may distribute this code under the same terms as Perl itself.
 193
 194 =cut