Applied patch from kados regarding use of a DateTime::Format class to validate
[dbsrgits/DBIx-Class-Historic.git] / lib / DBIx / Class / ResultSetColumn.pm
CommitLineData
2bb7b40b 1package DBIx::Class::ResultSetColumn;
2use strict;
3use warnings;
4use base 'DBIx::Class';
66521001 5use List::Util;
2bb7b40b 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
eb98561c 20A convenience class used to perform operations on a specific column of
21a resultset.
2bb7b40b 22
23=cut
24
25=head1 METHODS
26
27=head2 new
28
29 my $obj = DBIx::Class::ResultSetColumn->new($rs, $column);
30
eb98561c 31Creates a new resultset column object from the resultset and column
32passed as params. Used internally by L<DBIx::Class::ResultSet/get_column>.
2bb7b40b 33
34=cut
35
36sub new {
37 my ($class, $rs, $column) = @_;
38 $class = ref $class if ref $class;
7ae9706c 39
40 $rs->throw_exception("column must be supplied") unless $column;
41
d8dbe471 42 my $orig_attrs = $rs->_resolved_attrs;
43 my $new_parent_rs = $rs->search_rs;
7ae9706c 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
bed3a173 47 # +select/+as and select/as. At the same time we want to preserve any joins that the
48 # prefetch would otherwise generate.
d8dbe471 49
50 my $new_attrs = $new_parent_rs->{attrs} ||= {};
51 $new_attrs->{join} = $rs->_merge_attr( delete $new_attrs->{join}, delete $new_attrs->{prefetch} );
b6e85b48 52
152002c4 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).
7ae9706c 57
d8dbe471 58 my $as_list = $orig_attrs->{as} || [];
59 my $select_list = $orig_attrs->{select} || [];
b6e85b48 60 my $as_index = List::Util::first { ($as_list->[$_] || "") eq $column } 0..$#$as_list;
b6e85b48 61 my $select = defined $as_index ? $select_list->[$as_index] : $column;
62
d8dbe471 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
b6e85b48 84 my $new = bless { _select => $select, _as => $column, _parent_resultset => $new_parent_rs }, $class;
2bb7b40b 85 return $new;
86}
87
70bb942d 88=head2 as_query (EXPERIMENTAL)
658fa250 89
90=over 4
91
428a645e 92=item Arguments: none
658fa250 93
4dc99a01 94=item Return Value: \[ $sql, @bind ]
658fa250 95
96=back
97
98Returns the SQL query and bind vars associated with the invocant.
99
03834f77 100This is generally used as the RHS for a subquery.
c7a9d102 101
6a9530d1 102B<NOTE>: This feature is still experimental.
103
c7a9d102 104=cut
105
0f6fc705 106sub as_query { return shift->_resultset->as_query(@_) }
c7a9d102 107
2bb7b40b 108=head2 next
109
110=over 4
111
112=item Arguments: none
113
114=item Return Value: $value
115
116=back
117
eb98561c 118Returns the next value of the column in the resultset (or C<undef> if
119there is none).
2bb7b40b 120
eb98561c 121Much like L<DBIx::Class::ResultSet/next> but just returning the
122one value.
2bb7b40b 123
124=cut
125
126sub next {
127 my $self = shift;
66521001 128 my ($row) = $self->_resultset->cursor->next;
2bb7b40b 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
eb98561c 142Returns all values of the column in the resultset (or C<undef> if
143there are none).
2bb7b40b 144
eb98561c 145Much like L<DBIx::Class::ResultSet/all> but returns values rather
146than row objects.
2bb7b40b 147
148=cut
149
150sub all {
151 my $self = shift;
66521001 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
165Resets the underlying resultset's cursor, so you can iterate through the
166elements of the column again.
167
168Much like L<DBIx::Class::ResultSet/reset>.
169
170=cut
171
172sub 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
188Resets the underlying resultset and returns the next value of the column in the
189resultset (or C<undef> if there is none).
190
191Much like L<DBIx::Class::ResultSet/first> but just returning the one value.
192
193=cut
194
195sub first {
196 my $self = shift;
3484603a 197 my ($row) = $self->_resultset->cursor->reset->next;
66521001 198 return $row;
2bb7b40b 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
eb98561c 211 my $first_year = $year_col->min();
212
213Wrapper for ->func. Returns the lowest value of the column in the
214resultset (or C<undef> if there are none).
2bb7b40b 215
216=cut
217
218sub min {
6b051e14 219 return shift->func('MIN');
2bb7b40b 220}
221
4fa7bc22 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
234Wrapper for ->func_rs for function MIN().
235
236=cut
237
238sub min_rs { return shift->func_rs('MIN') }
239
2bb7b40b 240=head2 max
241
242=over 4
243
244=item Arguments: none
245
246=item Return Value: $highest_value
247
248=back
249
eb98561c 250 my $last_year = $year_col->max();
251
252Wrapper for ->func. Returns the highest value of the column in the
253resultset (or C<undef> if there are none).
2bb7b40b 254
255=cut
256
257sub max {
6b051e14 258 return shift->func('MAX');
2bb7b40b 259}
260
4fa7bc22 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
273Wrapper for ->func_rs for function MAX().
274
275=cut
276
277sub max_rs { return shift->func_rs('MAX') }
278
2bb7b40b 279=head2 sum
280
281=over 4
282
283=item Arguments: none
284
285=item Return Value: $sum_of_values
286
287=back
288
eb98561c 289 my $total = $prices_col->sum();
290
291Wrapper for ->func. Returns the sum of all the values in the column of
292the resultset. Use on varchar-like columns at your own risk.
2bb7b40b 293
294=cut
295
296sub sum {
6b051e14 297 return shift->func('SUM');
2bb7b40b 298}
299
4fa7bc22 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
312Wrapper for ->func_rs for function SUM().
313
314=cut
315
316sub sum_rs { return shift->func_rs('SUM') }
317
2bb7b40b 318=head2 func
319
320=over 4
321
322=item Arguments: $function
323
324=item Return Value: $function_return_value
325
326=back
327
e8419341 328 $rs = $schema->resultset("CD")->search({});
329 $length = $rs->get_column('title')->func('LENGTH');
2bb7b40b 330
eb98561c 331Runs a query using the function on the column and returns the
332value. Produces the following SQL:
333
334 SELECT LENGTH( title ) FROM cd me
2bb7b40b 335
336=cut
337
338sub func {
6b051e14 339 my ($self,$function) = @_;
4fa7bc22 340 my $cursor = $self->func_rs($function)->cursor;
5d62876f 341
342 if( wantarray ) {
343 return map { $_->[ 0 ] } $cursor->all;
344 }
345
346 return ( $cursor->next )[ 0 ];
2bb7b40b 347}
348
4fa7bc22 349=head2 func_rs
350
351=over 4
352
353=item Arguments: $function
354
355=item Return Value: $resultset
356
357=back
358
359Creates the resultset that C<func()> uses to run its query.
360
361=cut
362
363sub 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
5d1fc7dc 373=head2 throw_exception
374
375See L<DBIx::Class::Schema/throw_exception> for details.
376
377=cut
378
379sub 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
b6e85b48 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#
66521001 399sub _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
2bb7b40b 4101;
411
412=head1 AUTHORS
413
414Luke Saunders <luke.saunders@gmail.com>
415
eb98561c 416Jess Robinson
417
2bb7b40b 418=head1 LICENSE
419
420You may distribute this code under the same terms as Perl itself.
421
422=cut