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 a resultset.
  20
  21 =cut
  22
  23 =head1 METHODS
  24
  25 =head2 new
  26
  27   my $obj = DBIx::Class::ResultSetColumn->new($rs, $column);
  28
  29 Creates a new resultset column object from the resultset and column passed as params
  30
  31 =cut
  32
  33 sub new {
  34   my ($class, $rs, $column) = @_;
  35   $class = ref $class if ref $class;
  36
  37   my $object_ref = { _column => $column,
  38                      _parent_resultset => $rs };
  39
  40   my $new = bless $object_ref, $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 (C<undef> is there is none).
  56
  57 Much like $rs->next but just returning the one value
  58
  59 =cut
  60
  61 sub next {
  62   my $self = shift;
  63
  64   $self->{_resultset} = $self->{_parent_resultset}->search(undef, {select => [$self->{_column}], as => [$self->{_column}]}) unless ($self->{_resultset});
  65   my ($row) = $self->{_resultset}->cursor->next;
  66   return $row;
  67 }
  68
  69 =head2 all
  70
  71 =over 4
  72
  73 =item Arguments: none
  74
  75 =item Return Value: @values
  76
  77 =back
  78
  79 Returns all values of the column in the resultset (C<undef> is there are none).
  80
  81 Much like $rs->all but returns values rather than row objects
  82
  83 =cut
  84
  85 sub all {
  86   my $self = shift;
  87   return map {$_->[0]} $self->{_parent_resultset}->search(undef, {select => [$self->{_column}], as => [$self->{_column}]})->cursor->all;
  88 }
  89
  90 =head2 min
  91
  92 =over 4
  93
  94 =item Arguments: none
  95
  96 =item Return Value: $lowest_value
  97
  98 =back
  99
 100 Wrapper for ->func. Returns the lowest value of the column in the resultset (C<undef> is there are none).
 101
 102 =cut
 103
 104 sub min {
 105   my $self = shift;
 106   return $self->func('MIN');
 107 }
 108
 109 =head2 max
 110
 111 =over 4
 112
 113 =item Arguments: none
 114
 115 =item Return Value: $highest_value
 116
 117 =back
 118
 119 Wrapper for ->func. Returns the highest value of the column in the resultset (C<undef> is there are none).
 120
 121 =cut
 122
 123 sub max {
 124   my $self = shift;
 125   return $self->func('MAX');
 126 }
 127
 128 =head2 sum
 129
 130 =over 4
 131
 132 =item Arguments: none
 133
 134 =item Return Value: $sum_of_values
 135
 136 =back
 137
 138 Wrapper for ->func. Returns the sum of all the values in the column of the resultset. Use on varchar-like columns at your own risk.
 139
 140 =cut
 141
 142 sub sum {
 143   my $self = shift;
 144   return $self->func('SUM');
 145 }
 146
 147 =head2 func
 148
 149 =over 4
 150
 151 =item Arguments: $function
 152
 153 =item Return Value: $function_return_value
 154
 155 =back
 156
 157 Runs a query using the function on the column and returns the value. For example
 158   $rs = $schema->resultset("CD")->search({});
 159   $length = $rs->get_column('title')->func('LENGTH');
 160
 161 Produces the following SQL
 162   SELECT LENGTH( title ) from cd me
 163
 164 =cut
 165
 166 sub func {
 167   my $self = shift;
 168   my $function = shift;
 169
 170   my ($row) = $self->{_parent_resultset}->search(undef, {select => {$function => $self->{_column}}, as => [$self->{_column}]})->cursor->next;
 171   return $row;
 172 }
 173
 174 1;
 175
 176 =head1 AUTHORS
 177
 178 Luke Saunders <luke.saunders@gmail.com>
 179
 180 =head1 LICENSE
 181
 182 You may distribute this code under the same terms as Perl itself.
 183
 184 =cut