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