Merge 'sybase' into 'trunk'
[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 use List::Util;
6
7 =head1 NAME
8
9   DBIx::Class::ResultSetColumn - helpful methods for messing
10   with a single column of the resultset
11
12 =head1 SYNOPSIS
13
14   $rs = $schema->resultset('CD')->search({ artist => 'Tool' });
15   $rs_column = $rs->get_column('year');
16   $max_year = $rs_column->max; #returns latest year
17
18 =head1 DESCRIPTION
19
20 A convenience class used to perform operations on a specific column of
21 a resultset.
22
23 =cut
24
25 =head1 METHODS
26
27 =head2 new
28
29   my $obj = DBIx::Class::ResultSetColumn->new($rs, $column);
30
31 Creates a new resultset column object from the resultset and column
32 passed as params. Used internally by L<DBIx::Class::ResultSet/get_column>.
33
34 =cut
35
36 sub new {
37   my ($class, $rs, $column) = @_;
38   $class = ref $class if ref $class;
39   my $new_parent_rs = $rs->search_rs; # we don't want to mess up the original, so clone it
40   my $attrs = $new_parent_rs->_resolved_attrs;
41   $new_parent_rs->{attrs}->{$_} = undef for qw(prefetch include_columns +select +as); # prefetch, include_columns, +select, +as cause additional columns to be fetched
42
43   # If $column can be found in the 'as' list of the parent resultset, use the
44   # corresponding element of its 'select' list (to keep any custom column
45   # definition set up with 'select' or '+select' attrs), otherwise use $column
46   # (to create a new column definition on-the-fly).
47   my $as_list = $attrs->{as} || [];
48   my $select_list = $attrs->{select} || [];
49   my $as_index = List::Util::first { ($as_list->[$_] || "") eq $column } 0..$#$as_list;
50   my $select = defined $as_index ? $select_list->[$as_index] : $column;
51
52   my $new = bless { _select => $select, _as => $column, _parent_resultset => $new_parent_rs }, $class;
53   $new->throw_exception("column must be supplied") unless $column;
54   return $new;
55 }
56
57 =head2 as_query
58
59 =over 4
60
61 =item Arguments: none
62
63 =item Return Value: \[ $sql, @bind ]
64
65 =back
66
67 Returns the SQL query and bind vars associated with the invocant.
68
69 This is generally used as the RHS for a subquery.
70
71 =cut
72
73 sub as_query { return shift->_resultset->as_query }
74
75 =head2 next
76
77 =over 4
78
79 =item Arguments: none
80
81 =item Return Value: $value
82
83 =back
84
85 Returns the next value of the column in the resultset (or C<undef> if
86 there is none).
87
88 Much like L<DBIx::Class::ResultSet/next> but just returning the 
89 one value.
90
91 =cut
92
93 sub next {
94   my $self = shift;
95   my ($row) = $self->_resultset->cursor->next;
96   return $row;
97 }
98
99 =head2 all
100
101 =over 4
102
103 =item Arguments: none
104
105 =item Return Value: @values
106
107 =back
108
109 Returns all values of the column in the resultset (or C<undef> if
110 there are none).
111
112 Much like L<DBIx::Class::ResultSet/all> but returns values rather
113 than row objects.
114
115 =cut
116
117 sub all {
118   my $self = shift;
119   return map { $_->[0] } $self->_resultset->cursor->all;
120 }
121
122 =head2 reset
123
124 =over 4
125
126 =item Arguments: none
127
128 =item Return Value: $self
129
130 =back
131
132 Resets the underlying resultset's cursor, so you can iterate through the
133 elements of the column again.
134
135 Much like L<DBIx::Class::ResultSet/reset>.
136
137 =cut
138
139 sub reset {
140   my $self = shift;
141   $self->_resultset->cursor->reset;
142   return $self;
143 }
144
145 =head2 first
146
147 =over 4
148
149 =item Arguments: none
150
151 =item Return Value: $value
152
153 =back
154
155 Resets the underlying resultset and returns the next value of the column in the
156 resultset (or C<undef> if there is none).
157
158 Much like L<DBIx::Class::ResultSet/first> but just returning the one value.
159
160 =cut
161
162 sub first {
163   my $self = shift;
164   my ($row) = $self->_resultset->cursor->reset->next;
165   return $row;
166 }
167
168 =head2 min
169
170 =over 4
171
172 =item Arguments: none
173
174 =item Return Value: $lowest_value
175
176 =back
177
178   my $first_year = $year_col->min();
179
180 Wrapper for ->func. Returns the lowest value of the column in the
181 resultset (or C<undef> if there are none).
182
183 =cut
184
185 sub min {
186   return shift->func('MIN');
187 }
188
189 =head2 min_rs
190
191 =over 4
192
193 =item Arguments: none
194
195 =item Return Value: $resultset
196
197 =back
198
199   my $rs = $year_col->min_rs();
200
201 Wrapper for ->func_rs for function MIN().
202
203 =cut
204
205 sub min_rs { return shift->func_rs('MIN') }
206
207 =head2 max
208
209 =over 4
210
211 =item Arguments: none
212
213 =item Return Value: $highest_value
214
215 =back
216
217   my $last_year = $year_col->max();
218
219 Wrapper for ->func. Returns the highest value of the column in the
220 resultset (or C<undef> if there are none).
221
222 =cut
223
224 sub max {
225   return shift->func('MAX');
226 }
227
228 =head2 max_rs
229
230 =over 4
231
232 =item Arguments: none
233
234 =item Return Value: $resultset
235
236 =back
237
238   my $rs = $year_col->max_rs();
239
240 Wrapper for ->func_rs for function MAX().
241
242 =cut
243
244 sub max_rs { return shift->func_rs('MAX') }
245
246 =head2 sum
247
248 =over 4
249
250 =item Arguments: none
251
252 =item Return Value: $sum_of_values
253
254 =back
255
256   my $total = $prices_col->sum();
257
258 Wrapper for ->func. Returns the sum of all the values in the column of
259 the resultset. Use on varchar-like columns at your own risk.
260
261 =cut
262
263 sub sum {
264   return shift->func('SUM');
265 }
266
267 =head2 sum_rs
268
269 =over 4
270
271 =item Arguments: none
272
273 =item Return Value: $resultset
274
275 =back
276
277   my $rs = $year_col->sum_rs();
278
279 Wrapper for ->func_rs for function SUM().
280
281 =cut
282
283 sub sum_rs { return shift->func_rs('SUM') }
284
285 =head2 func
286
287 =over 4
288
289 =item Arguments: $function
290
291 =item Return Value: $function_return_value
292
293 =back
294
295   $rs = $schema->resultset("CD")->search({});
296   $length = $rs->get_column('title')->func('LENGTH');
297
298 Runs a query using the function on the column and returns the
299 value. Produces the following SQL:
300
301   SELECT LENGTH( title ) FROM cd me
302
303 =cut
304
305 sub func {
306   my ($self,$function) = @_;
307   my $cursor = $self->func_rs($function)->cursor;
308   
309   if( wantarray ) {
310     return map { $_->[ 0 ] } $cursor->all;
311   }
312
313   return ( $cursor->next )[ 0 ];
314 }
315
316 =head2 func_rs
317
318 =over 4
319
320 =item Arguments: $function
321
322 =item Return Value: $resultset
323
324 =back
325
326 Creates the resultset that C<func()> uses to run its query.
327
328 =cut
329
330 sub func_rs {
331   my ($self,$function) = @_;
332   return $self->{_parent_resultset}->search(
333     undef, {
334       select => {$function => $self->{_select}},
335       as => [$self->{_as}],
336     },
337   );
338 }
339
340 =head2 throw_exception
341
342 See L<DBIx::Class::Schema/throw_exception> for details.
343   
344 =cut 
345     
346 sub throw_exception {
347   my $self=shift;
348   if (ref $self && $self->{_parent_resultset}) {
349     $self->{_parent_resultset}->throw_exception(@_)
350   } else {
351     croak(@_);
352   }
353 }
354
355 # _resultset
356 #
357 # Arguments: none
358 #
359 # Return Value: $resultset
360 #
361 #  $year_col->_resultset->next
362 #
363 # Returns the underlying resultset. Creates it from the parent resultset if
364 # necessary.
365
366 sub _resultset {
367   my $self = shift;
368
369   return $self->{_resultset} ||= $self->{_parent_resultset}->search(undef,
370     {
371       select => [$self->{_select}],
372       as => [$self->{_as}]
373     }
374   );
375 }
376
377 1;
378
379 =head1 AUTHORS
380
381 Luke Saunders <luke.saunders@gmail.com>
382
383 Jess Robinson
384
385 =head1 LICENSE
386
387 You may distribute this code under the same terms as Perl itself.
388
389 =cut