Merge 'sybase' into 'trunk'
[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;
3f6cc7e4 39 my $new_parent_rs = $rs->search_rs; # we don't want to mess up the original, so clone it
5d1fc7dc 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
b6e85b48 42
152002c4 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).
b6e85b48 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;
b6e85b48 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;
6b051e14 53 $new->throw_exception("column must be supplied") unless $column;
2bb7b40b 54 return $new;
55}
56
658fa250 57=head2 as_query
58
59=over 4
60
61=item Arguments: none
62
4dc99a01 63=item Return Value: \[ $sql, @bind ]
658fa250 64
65=back
66
67Returns the SQL query and bind vars associated with the invocant.
68
03834f77 69This is generally used as the RHS for a subquery.
c7a9d102 70
71=cut
72
03834f77 73sub as_query { return shift->_resultset->as_query }
c7a9d102 74
2bb7b40b 75=head2 next
76
77=over 4
78
79=item Arguments: none
80
81=item Return Value: $value
82
83=back
84
eb98561c 85Returns the next value of the column in the resultset (or C<undef> if
86there is none).
2bb7b40b 87
eb98561c 88Much like L<DBIx::Class::ResultSet/next> but just returning the
89one value.
2bb7b40b 90
91=cut
92
93sub next {
94 my $self = shift;
66521001 95 my ($row) = $self->_resultset->cursor->next;
2bb7b40b 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
eb98561c 109Returns all values of the column in the resultset (or C<undef> if
110there are none).
2bb7b40b 111
eb98561c 112Much like L<DBIx::Class::ResultSet/all> but returns values rather
113than row objects.
2bb7b40b 114
115=cut
116
117sub all {
118 my $self = shift;
66521001 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
132Resets the underlying resultset's cursor, so you can iterate through the
133elements of the column again.
134
135Much like L<DBIx::Class::ResultSet/reset>.
136
137=cut
138
139sub 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
155Resets the underlying resultset and returns the next value of the column in the
156resultset (or C<undef> if there is none).
157
158Much like L<DBIx::Class::ResultSet/first> but just returning the one value.
159
160=cut
161
162sub first {
163 my $self = shift;
3484603a 164 my ($row) = $self->_resultset->cursor->reset->next;
66521001 165 return $row;
2bb7b40b 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
eb98561c 178 my $first_year = $year_col->min();
179
180Wrapper for ->func. Returns the lowest value of the column in the
181resultset (or C<undef> if there are none).
2bb7b40b 182
183=cut
184
185sub min {
6b051e14 186 return shift->func('MIN');
2bb7b40b 187}
188
4fa7bc22 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
201Wrapper for ->func_rs for function MIN().
202
203=cut
204
205sub min_rs { return shift->func_rs('MIN') }
206
2bb7b40b 207=head2 max
208
209=over 4
210
211=item Arguments: none
212
213=item Return Value: $highest_value
214
215=back
216
eb98561c 217 my $last_year = $year_col->max();
218
219Wrapper for ->func. Returns the highest value of the column in the
220resultset (or C<undef> if there are none).
2bb7b40b 221
222=cut
223
224sub max {
6b051e14 225 return shift->func('MAX');
2bb7b40b 226}
227
4fa7bc22 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
240Wrapper for ->func_rs for function MAX().
241
242=cut
243
244sub max_rs { return shift->func_rs('MAX') }
245
2bb7b40b 246=head2 sum
247
248=over 4
249
250=item Arguments: none
251
252=item Return Value: $sum_of_values
253
254=back
255
eb98561c 256 my $total = $prices_col->sum();
257
258Wrapper for ->func. Returns the sum of all the values in the column of
259the resultset. Use on varchar-like columns at your own risk.
2bb7b40b 260
261=cut
262
263sub sum {
6b051e14 264 return shift->func('SUM');
2bb7b40b 265}
266
4fa7bc22 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
279Wrapper for ->func_rs for function SUM().
280
281=cut
282
283sub sum_rs { return shift->func_rs('SUM') }
284
2bb7b40b 285=head2 func
286
287=over 4
288
289=item Arguments: $function
290
291=item Return Value: $function_return_value
292
293=back
294
e8419341 295 $rs = $schema->resultset("CD")->search({});
296 $length = $rs->get_column('title')->func('LENGTH');
2bb7b40b 297
eb98561c 298Runs a query using the function on the column and returns the
299value. Produces the following SQL:
300
301 SELECT LENGTH( title ) FROM cd me
2bb7b40b 302
303=cut
304
305sub func {
6b051e14 306 my ($self,$function) = @_;
4fa7bc22 307 my $cursor = $self->func_rs($function)->cursor;
5d62876f 308
309 if( wantarray ) {
310 return map { $_->[ 0 ] } $cursor->all;
311 }
312
313 return ( $cursor->next )[ 0 ];
2bb7b40b 314}
315
4fa7bc22 316=head2 func_rs
317
318=over 4
319
320=item Arguments: $function
321
322=item Return Value: $resultset
323
324=back
325
326Creates the resultset that C<func()> uses to run its query.
327
328=cut
329
330sub 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
5d1fc7dc 340=head2 throw_exception
341
342See L<DBIx::Class::Schema/throw_exception> for details.
343
344=cut
345
346sub 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
b6e85b48 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#
66521001 366sub _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
2bb7b40b 3771;
378
379=head1 AUTHORS
380
381Luke Saunders <luke.saunders@gmail.com>
382
eb98561c 383Jess Robinson
384
2bb7b40b 385=head1 LICENSE
386
387You may distribute this code under the same terms as Perl itself.
388
389=cut