1) changed all 4 space indentation to 2 space style indents for replication code...
[dbsrgits/DBIx-Class-Historic.git] / 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 $cursor = $self->{_parent_resultset}->search(undef, {select => {$function => $self->{_column}}, as => [$self->{_column}]})->cursor;
179   
180   if( wantarray ) {
181     return map { $_->[ 0 ] } $cursor->all;
182   }
183
184   return ( $cursor->next )[ 0 ];
185 }
186
187 1;
188
189 =head1 AUTHORS
190
191 Luke Saunders <luke.saunders@gmail.com>
192
193 Jess Robinson
194
195 =head1 LICENSE
196
197 You may distribute this code under the same terms as Perl itself.
198
199 =cut