Redo badly named constant folding arg introduced in 8d73fcd4
[dbsrgits/DBIx-Class-Historic.git] / lib / DBIx / Class / ResultSetColumn.pm
CommitLineData
2bb7b40b 1package DBIx::Class::ResultSetColumn;
1a58752c 2
2bb7b40b 3use strict;
4use warnings;
1a58752c 5
2bb7b40b 6use base 'DBIx::Class';
70c28808 7use DBIx::Class::Carp;
a9da9b6a 8use DBIx::Class::_Util 'fail_on_internal_wantarray';
64c50e81 9use namespace::clean;
94244987 10
11# not importing first() as it will clash with our own method
6298a324 12use List::Util ();
2bb7b40b 13
14=head1 NAME
15
16 DBIx::Class::ResultSetColumn - helpful methods for messing
17 with a single column of the resultset
18
19=head1 SYNOPSIS
20
21 $rs = $schema->resultset('CD')->search({ artist => 'Tool' });
22 $rs_column = $rs->get_column('year');
23 $max_year = $rs_column->max; #returns latest year
24
25=head1 DESCRIPTION
26
eb98561c 27A convenience class used to perform operations on a specific column of
28a resultset.
2bb7b40b 29
30=cut
31
32=head1 METHODS
33
34=head2 new
35
36 my $obj = DBIx::Class::ResultSetColumn->new($rs, $column);
37
eb98561c 38Creates a new resultset column object from the resultset and column
39passed as params. Used internally by L<DBIx::Class::ResultSet/get_column>.
2bb7b40b 40
41=cut
42
43sub new {
44 my ($class, $rs, $column) = @_;
45 $class = ref $class if ref $class;
7ae9706c 46
66e33361 47 $rs->throw_exception('column must be supplied') unless $column;
7ae9706c 48
d8dbe471 49 my $orig_attrs = $rs->_resolved_attrs;
9b8930f4 50 my $alias = $rs->current_source_alias;
2b3fc408 51 my $rsrc = $rs->result_source;
472d7df3 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 my $as_list = $orig_attrs->{as} || [];
58 my $select_list = $orig_attrs->{select} || [];
59 my $as_index = List::Util::first { ($as_list->[$_] || "") eq $column } 0..$#$as_list;
60 my $select = defined $as_index ? $select_list->[$as_index] : $column;
61
aca094b4 62 my $colmap;
2b3fc408 63 for ($rsrc->columns, $column) {
64 if ($_ =~ /^ \Q$alias\E \. ([^\.]+) $ /x) {
65 $colmap->{$_} = $1;
66 }
67 elsif ($_ !~ /\./) {
68 $colmap->{"$alias.$_"} = $_;
69 $colmap->{$_} = $_;
70 }
71 }
72
aca094b4 73 my $new_parent_rs;
472d7df3 74 # analyze the order_by, and see if it is done over a function/nonexistentcolumn
75 # if this is the case we will need to wrap a subquery since the result of RSC
76 # *must* be a single column select
472d7df3 77 if (
78 scalar grep
2b3fc408 79 { ! exists $colmap->{$_->[0]} }
80 ( $rsrc->schema->storage->_extract_order_criteria ($orig_attrs->{order_by} ) )
472d7df3 81 ) {
5716e003 82 # nuke the prefetch before collapsing to sql
aca094b4 83 my $subq_rs = $rs->search_rs;
37aafa2e 84 $subq_rs->{attrs}{join} = $subq_rs->_merge_joinpref_attr( $subq_rs->{attrs}{join}, delete $subq_rs->{attrs}{prefetch} );
9b8930f4 85 $new_parent_rs = $subq_rs->as_subselect_rs;
472d7df3 86 }
87
88 $new_parent_rs ||= $rs->search_rs;
66e33361 89 my $new_attrs = $new_parent_rs->{attrs} ||= {};
90
7ae9706c 91 # prefetch causes additional columns to be fetched, but we can not just make a new
92 # rs via the _resolved_attrs trick - we need to retain the separation between
bed3a173 93 # +select/+as and select/as. At the same time we want to preserve any joins that the
94 # prefetch would otherwise generate.
37aafa2e 95 $new_attrs->{join} = $rs->_merge_joinpref_attr( $new_attrs->{join}, delete $new_attrs->{prefetch} );
b6e85b48 96
d8dbe471 97 # {collapse} would mean a has_many join was injected, which in turn means
722c0140 98 # we need to group *IF WE CAN* (only if the column in question is unique)
f1693c0d 99 if (!$orig_attrs->{group_by} && $orig_attrs->{collapse}) {
d8dbe471 100
2b3fc408 101 if ($colmap->{$select} and $rsrc->_identifying_column_set([$colmap->{$select}])) {
102 $new_attrs->{group_by} = [ $select ];
1e4f9fb3 103 delete @{$new_attrs}{qw(distinct _grouped_by_distinct)}; # it is ignored when group_by is present
d8dbe471 104 }
2b3fc408 105 else {
722c0140 106 carp (
107 "Attempting to retrieve non-unique column '$column' on a resultset containing "
108 . 'one-to-many joins will return duplicate results.'
109 );
110 }
d8dbe471 111 }
112
722274d0 113 return bless {
114 _select => $select,
aca094b4 115 _as => $column,
722274d0 116 _parent_resultset => $new_parent_rs
117 }, $class;
2bb7b40b 118}
119
6dfbe2f8 120=head2 as_query
658fa250 121
122=over 4
123
428a645e 124=item Arguments: none
658fa250 125
00c12490 126=item Return Value: \[ $sql, L<@bind_values|DBIx::Class::ResultSet/DBIC BIND VALUES> ]
658fa250 127
128=back
129
130Returns the SQL query and bind vars associated with the invocant.
131
03834f77 132This is generally used as the RHS for a subquery.
c7a9d102 133
134=cut
135
0f6fc705 136sub as_query { return shift->_resultset->as_query(@_) }
c7a9d102 137
2bb7b40b 138=head2 next
139
140=over 4
141
142=item Arguments: none
143
144=item Return Value: $value
145
146=back
147
eb98561c 148Returns the next value of the column in the resultset (or C<undef> if
149there is none).
2bb7b40b 150
8273e845 151Much like L<DBIx::Class::ResultSet/next> but just returning the
eb98561c 152one value.
2bb7b40b 153
154=cut
155
156sub next {
157 my $self = shift;
b7c79955 158
159 # using cursor so we don't inflate anything
66521001 160 my ($row) = $self->_resultset->cursor->next;
b7c79955 161
2bb7b40b 162 return $row;
163}
164
165=head2 all
166
167=over 4
168
169=item Arguments: none
170
171=item Return Value: @values
172
173=back
174
eb98561c 175Returns all values of the column in the resultset (or C<undef> if
176there are none).
2bb7b40b 177
eb98561c 178Much like L<DBIx::Class::ResultSet/all> but returns values rather
fb13a49f 179than result objects.
2bb7b40b 180
181=cut
182
183sub all {
184 my $self = shift;
b7c79955 185
186 # using cursor so we don't inflate anything
66521001 187 return map { $_->[0] } $self->_resultset->cursor->all;
188}
189
190=head2 reset
191
192=over 4
193
194=item Arguments: none
195
196=item Return Value: $self
197
198=back
199
200Resets the underlying resultset's cursor, so you can iterate through the
201elements of the column again.
202
203Much like L<DBIx::Class::ResultSet/reset>.
204
205=cut
206
207sub reset {
208 my $self = shift;
209 $self->_resultset->cursor->reset;
b7c79955 210 return $self;
66521001 211}
212
213=head2 first
214
215=over 4
216
217=item Arguments: none
218
219=item Return Value: $value
220
221=back
222
223Resets the underlying resultset and returns the next value of the column in the
224resultset (or C<undef> if there is none).
225
226Much like L<DBIx::Class::ResultSet/first> but just returning the one value.
227
228=cut
229
230sub first {
231 my $self = shift;
b7c79955 232
233 # using cursor so we don't inflate anything
234 $self->_resultset->cursor->reset;
01dc6781 235 my ($row) = $self->_resultset->cursor->next;
b7c79955 236
66521001 237 return $row;
2bb7b40b 238}
239
4e55c3ae 240=head2 single
241
242=over 4
243
244=item Arguments: none
245
246=item Return Value: $value
247
248=back
249
250Much like L<DBIx::Class::ResultSet/single> fetches one and only one column
251value using the cursor directly. If additional rows are present a warning
252is issued before discarding the cursor.
253
254=cut
255
256sub single {
257 my $self = shift;
258
259 my $attrs = $self->_resultset->_resolved_attrs;
260 my ($row) = $self->_resultset->result_source->storage->select_single(
261 $attrs->{from}, $attrs->{select}, $attrs->{where}, $attrs
262 );
263
264 return $row;
265}
266
2bb7b40b 267=head2 min
268
269=over 4
270
271=item Arguments: none
272
273=item Return Value: $lowest_value
274
275=back
276
eb98561c 277 my $first_year = $year_col->min();
278
279Wrapper for ->func. Returns the lowest value of the column in the
280resultset (or C<undef> if there are none).
2bb7b40b 281
282=cut
283
284sub min {
6b051e14 285 return shift->func('MIN');
2bb7b40b 286}
287
4fa7bc22 288=head2 min_rs
289
290=over 4
291
292=item Arguments: none
293
fb13a49f 294=item Return Value: L<$resultset|DBIx::Class::ResultSet>
4fa7bc22 295
296=back
297
298 my $rs = $year_col->min_rs();
299
300Wrapper for ->func_rs for function MIN().
301
302=cut
303
304sub min_rs { return shift->func_rs('MIN') }
305
2bb7b40b 306=head2 max
307
308=over 4
309
310=item Arguments: none
311
312=item Return Value: $highest_value
313
314=back
315
eb98561c 316 my $last_year = $year_col->max();
317
318Wrapper for ->func. Returns the highest value of the column in the
319resultset (or C<undef> if there are none).
2bb7b40b 320
321=cut
322
323sub max {
6b051e14 324 return shift->func('MAX');
2bb7b40b 325}
326
4fa7bc22 327=head2 max_rs
328
329=over 4
330
331=item Arguments: none
332
fb13a49f 333=item Return Value: L<$resultset|DBIx::Class::ResultSet>
4fa7bc22 334
335=back
336
337 my $rs = $year_col->max_rs();
338
339Wrapper for ->func_rs for function MAX().
340
341=cut
342
343sub max_rs { return shift->func_rs('MAX') }
344
2bb7b40b 345=head2 sum
346
347=over 4
348
349=item Arguments: none
350
351=item Return Value: $sum_of_values
352
353=back
354
eb98561c 355 my $total = $prices_col->sum();
356
357Wrapper for ->func. Returns the sum of all the values in the column of
358the resultset. Use on varchar-like columns at your own risk.
2bb7b40b 359
360=cut
361
362sub sum {
6b051e14 363 return shift->func('SUM');
2bb7b40b 364}
365
4fa7bc22 366=head2 sum_rs
367
368=over 4
369
370=item Arguments: none
371
fb13a49f 372=item Return Value: L<$resultset|DBIx::Class::ResultSet>
4fa7bc22 373
374=back
375
376 my $rs = $year_col->sum_rs();
377
378Wrapper for ->func_rs for function SUM().
379
380=cut
381
382sub sum_rs { return shift->func_rs('SUM') }
383
2bb7b40b 384=head2 func
385
386=over 4
387
388=item Arguments: $function
389
390=item Return Value: $function_return_value
391
392=back
393
e8419341 394 $rs = $schema->resultset("CD")->search({});
395 $length = $rs->get_column('title')->func('LENGTH');
2bb7b40b 396
eb98561c 397Runs a query using the function on the column and returns the
398value. Produces the following SQL:
399
400 SELECT LENGTH( title ) FROM cd me
2bb7b40b 401
402=cut
403
404sub func {
6b051e14 405 my ($self,$function) = @_;
4fa7bc22 406 my $cursor = $self->func_rs($function)->cursor;
d4daee7b 407
5d62876f 408 if( wantarray ) {
e89c7968 409 DBIx::Class::_ENV_::ASSERT_NO_INTERNAL_WANTARRAY and my $sog = fail_on_internal_wantarray;
5d62876f 410 return map { $_->[ 0 ] } $cursor->all;
411 }
412
413 return ( $cursor->next )[ 0 ];
2bb7b40b 414}
415
4fa7bc22 416=head2 func_rs
417
418=over 4
419
420=item Arguments: $function
421
fb13a49f 422=item Return Value: L<$resultset|DBIx::Class::ResultSet>
4fa7bc22 423
424=back
425
426Creates the resultset that C<func()> uses to run its query.
427
428=cut
429
430sub func_rs {
431 my ($self,$function) = @_;
3214abc7 432
433 my $rs = $self->{_parent_resultset};
434 my $select = $self->{_select};
435
436 # wrap a grouped rs
437 if ($rs->_resolved_attrs->{group_by}) {
438 $select = $self->{_as};
439 $rs = $rs->as_subselect_rs;
440 }
441
442 $rs->search( undef, {
443 columns => { $self->{_as} => { $function => $select } }
444 } );
4fa7bc22 445}
446
5d1fc7dc 447=head2 throw_exception
448
449See L<DBIx::Class::Schema/throw_exception> for details.
d4daee7b 450
8273e845 451=cut
d4daee7b 452
5d1fc7dc 453sub throw_exception {
f9080e45 454 my $self = shift;
1a58752c 455
5d1fc7dc 456 if (ref $self && $self->{_parent_resultset}) {
1a58752c 457 $self->{_parent_resultset}->throw_exception(@_);
458 }
459 else {
460 DBIx::Class::Exception->throw(@_);
5d1fc7dc 461 }
462}
463
b6e85b48 464# _resultset
465#
466# Arguments: none
467#
468# Return Value: $resultset
469#
470# $year_col->_resultset->next
471#
472# Returns the underlying resultset. Creates it from the parent resultset if
473# necessary.
b7c79955 474#
66521001 475sub _resultset {
476 my $self = shift;
477
722274d0 478 return $self->{_resultset} ||= do {
479
480 my $select = $self->{_select};
481
482 if ($self->{_parent_resultset}{attrs}{distinct}) {
483 my $alias = $self->{_parent_resultset}->current_source_alias;
484 my $rsrc = $self->{_parent_resultset}->result_source;
485 my %cols = map { $_ => 1, "$alias.$_" => 1 } $rsrc->columns;
486
487 unless( $cols{$select} ) {
488 carp_unique(
489 'Use of distinct => 1 while selecting anything other than a column '
885c3dbd 490 . 'declared on the primary ResultSource is deprecated (you selected '
491 . "'$self->{_as}') - please supply an explicit group_by instead"
722274d0 492 );
493
494 # collapse the selector to a literal so that it survives the distinct parse
495 # if it turns out to be an aggregate - at least the user will get a proper exception
496 # instead of silent drop of the group_by altogether
ad1d374e 497 $select = \[ $rsrc->storage->sql_maker->_recurse_fields($select) ];
722274d0 498 }
66521001 499 }
722274d0 500
501 $self->{_parent_resultset}->search(undef, {
502 columns => { $self->{_as} => $select }
503 });
504 };
66521001 505}
506
a2bd3796 507=head1 FURTHER QUESTIONS?
2bb7b40b 508
a2bd3796 509Check the list of L<additional DBIC resources|DBIx::Class/GETTING HELP/SUPPORT>.
eb98561c 510
a2bd3796 511=head1 COPYRIGHT AND LICENSE
2bb7b40b 512
a2bd3796 513This module is free software L<copyright|DBIx::Class/COPYRIGHT AND LICENSE>
514by the L<DBIx::Class (DBIC) authors|DBIx::Class/AUTHORS>. You can
515redistribute it and/or modify it under the same terms as the
516L<DBIx::Class library|DBIx::Class/COPYRIGHT AND LICENSE>.
2bb7b40b 517
518=cut
a2bd3796 519
5201;
521