Applied patch from kados regarding use of a DateTime::Format class to validate
[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
40   $rs->throw_exception("column must be supplied") unless $column;
41
42   my $orig_attrs = $rs->_resolved_attrs;
43   my $new_parent_rs = $rs->search_rs;
44
45   # prefetch causes additional columns to be fetched, but we can not just make a new
46   # rs via the _resolved_attrs trick - we need to retain the separation between
47   # +select/+as and select/as. At the same time we want to preserve any joins that the
48   # prefetch would otherwise generate.
49
50   my $new_attrs = $new_parent_rs->{attrs} ||= {};
51   $new_attrs->{join} = $rs->_merge_attr( delete $new_attrs->{join}, delete $new_attrs->{prefetch} );
52
53   # If $column can be found in the 'as' list of the parent resultset, use the
54   # corresponding element of its 'select' list (to keep any custom column
55   # definition set up with 'select' or '+select' attrs), otherwise use $column
56   # (to create a new column definition on-the-fly).
57
58   my $as_list = $orig_attrs->{as} || [];
59   my $select_list = $orig_attrs->{select} || [];
60   my $as_index = List::Util::first { ($as_list->[$_] || "") eq $column } 0..$#$as_list;
61   my $select = defined $as_index ? $select_list->[$as_index] : $column;
62
63   # {collapse} would mean a has_many join was injected, which in turn means
64   # we need to group IF WE CAN (only if the column in question is unique)
65   if (!$new_attrs->{group_by} && keys %{$orig_attrs->{collapse}}) {
66
67     # scan for a constraint that would contain our column only - that'd be proof
68     # enough it is unique
69     my $constraints = { $rs->result_source->unique_constraints };
70     for my $constraint_columns ( values %$constraints ) {
71
72       next unless @$constraint_columns == 1;
73
74       my $col = $constraint_columns->[0];
75       my $fqcol = join ('.', $new_attrs->{alias}, $col);
76
77       if ($col eq $select or $fqcol eq $select) {
78         $new_attrs->{group_by} = [ $select ];
79         last;
80       }
81     }
82   }
83
84   my $new = bless { _select => $select, _as => $column, _parent_resultset => $new_parent_rs }, $class;
85   return $new;
86 }
87
88 =head2 as_query (EXPERIMENTAL)
89
90 =over 4
91
92 =item Arguments: none
93
94 =item Return Value: \[ $sql, @bind ]
95
96 =back
97
98 Returns the SQL query and bind vars associated with the invocant.
99
100 This is generally used as the RHS for a subquery.
101
102 B<NOTE>: This feature is still experimental.
103
104 =cut
105
106 sub as_query { return shift->_resultset->as_query(@_) }
107
108 =head2 next
109
110 =over 4
111
112 =item Arguments: none
113
114 =item Return Value: $value
115
116 =back
117
118 Returns the next value of the column in the resultset (or C<undef> if
119 there is none).
120
121 Much like L<DBIx::Class::ResultSet/next> but just returning the 
122 one value.
123
124 =cut
125
126 sub next {
127   my $self = shift;
128   my ($row) = $self->_resultset->cursor->next;
129   return $row;
130 }
131
132 =head2 all
133
134 =over 4
135
136 =item Arguments: none
137
138 =item Return Value: @values
139
140 =back
141
142 Returns all values of the column in the resultset (or C<undef> if
143 there are none).
144
145 Much like L<DBIx::Class::ResultSet/all> but returns values rather
146 than row objects.
147
148 =cut
149
150 sub all {
151   my $self = shift;
152   return map { $_->[0] } $self->_resultset->cursor->all;
153 }
154
155 =head2 reset
156
157 =over 4
158
159 =item Arguments: none
160
161 =item Return Value: $self
162
163 =back
164
165 Resets the underlying resultset's cursor, so you can iterate through the
166 elements of the column again.
167
168 Much like L<DBIx::Class::ResultSet/reset>.
169
170 =cut
171
172 sub reset {
173   my $self = shift;
174   $self->_resultset->cursor->reset;
175   return $self;
176 }
177
178 =head2 first
179
180 =over 4
181
182 =item Arguments: none
183
184 =item Return Value: $value
185
186 =back
187
188 Resets the underlying resultset and returns the next value of the column in the
189 resultset (or C<undef> if there is none).
190
191 Much like L<DBIx::Class::ResultSet/first> but just returning the one value.
192
193 =cut
194
195 sub first {
196   my $self = shift;
197   my ($row) = $self->_resultset->cursor->reset->next;
198   return $row;
199 }
200
201 =head2 min
202
203 =over 4
204
205 =item Arguments: none
206
207 =item Return Value: $lowest_value
208
209 =back
210
211   my $first_year = $year_col->min();
212
213 Wrapper for ->func. Returns the lowest value of the column in the
214 resultset (or C<undef> if there are none).
215
216 =cut
217
218 sub min {
219   return shift->func('MIN');
220 }
221
222 =head2 min_rs
223
224 =over 4
225
226 =item Arguments: none
227
228 =item Return Value: $resultset
229
230 =back
231
232   my $rs = $year_col->min_rs();
233
234 Wrapper for ->func_rs for function MIN().
235
236 =cut
237
238 sub min_rs { return shift->func_rs('MIN') }
239
240 =head2 max
241
242 =over 4
243
244 =item Arguments: none
245
246 =item Return Value: $highest_value
247
248 =back
249
250   my $last_year = $year_col->max();
251
252 Wrapper for ->func. Returns the highest value of the column in the
253 resultset (or C<undef> if there are none).
254
255 =cut
256
257 sub max {
258   return shift->func('MAX');
259 }
260
261 =head2 max_rs
262
263 =over 4
264
265 =item Arguments: none
266
267 =item Return Value: $resultset
268
269 =back
270
271   my $rs = $year_col->max_rs();
272
273 Wrapper for ->func_rs for function MAX().
274
275 =cut
276
277 sub max_rs { return shift->func_rs('MAX') }
278
279 =head2 sum
280
281 =over 4
282
283 =item Arguments: none
284
285 =item Return Value: $sum_of_values
286
287 =back
288
289   my $total = $prices_col->sum();
290
291 Wrapper for ->func. Returns the sum of all the values in the column of
292 the resultset. Use on varchar-like columns at your own risk.
293
294 =cut
295
296 sub sum {
297   return shift->func('SUM');
298 }
299
300 =head2 sum_rs
301
302 =over 4
303
304 =item Arguments: none
305
306 =item Return Value: $resultset
307
308 =back
309
310   my $rs = $year_col->sum_rs();
311
312 Wrapper for ->func_rs for function SUM().
313
314 =cut
315
316 sub sum_rs { return shift->func_rs('SUM') }
317
318 =head2 func
319
320 =over 4
321
322 =item Arguments: $function
323
324 =item Return Value: $function_return_value
325
326 =back
327
328   $rs = $schema->resultset("CD")->search({});
329   $length = $rs->get_column('title')->func('LENGTH');
330
331 Runs a query using the function on the column and returns the
332 value. Produces the following SQL:
333
334   SELECT LENGTH( title ) FROM cd me
335
336 =cut
337
338 sub func {
339   my ($self,$function) = @_;
340   my $cursor = $self->func_rs($function)->cursor;
341   
342   if( wantarray ) {
343     return map { $_->[ 0 ] } $cursor->all;
344   }
345
346   return ( $cursor->next )[ 0 ];
347 }
348
349 =head2 func_rs
350
351 =over 4
352
353 =item Arguments: $function
354
355 =item Return Value: $resultset
356
357 =back
358
359 Creates the resultset that C<func()> uses to run its query.
360
361 =cut
362
363 sub func_rs {
364   my ($self,$function) = @_;
365   return $self->{_parent_resultset}->search(
366     undef, {
367       select => {$function => $self->{_select}},
368       as => [$self->{_as}],
369     },
370   );
371 }
372
373 =head2 throw_exception
374
375 See L<DBIx::Class::Schema/throw_exception> for details.
376   
377 =cut 
378     
379 sub throw_exception {
380   my $self=shift;
381   if (ref $self && $self->{_parent_resultset}) {
382     $self->{_parent_resultset}->throw_exception(@_)
383   } else {
384     croak(@_);
385   }
386 }
387
388 # _resultset
389 #
390 # Arguments: none
391 #
392 # Return Value: $resultset
393 #
394 #  $year_col->_resultset->next
395 #
396 # Returns the underlying resultset. Creates it from the parent resultset if
397 # necessary.
398
399 sub _resultset {
400   my $self = shift;
401
402   return $self->{_resultset} ||= $self->{_parent_resultset}->search(undef,
403     {
404       select => [$self->{_select}],
405       as => [$self->{_as}]
406     }
407   );
408 }
409
410 1;
411
412 =head1 AUTHORS
413
414 Luke Saunders <luke.saunders@gmail.com>
415
416 Jess Robinson
417
418 =head1 LICENSE
419
420 You may distribute this code under the same terms as Perl itself.
421
422 =cut