Merge 'trunk' into 'DBIx-Class-current'
[dbsrgits/DBIx-Class.git] / lib / DBIx / Class / ResultSetColumn.pm
CommitLineData
2bb7b40b 1package DBIx::Class::ResultSetColumn;
2use strict;
3use warnings;
4use base 'DBIx::Class';
5
6=head1 NAME
7
8 DBIx::Class::ResultSetColumn - helpful methods for messing
9 with a single column of the resultset
10
11=head1 SYNOPSIS
12
13 $rs = $schema->resultset('CD')->search({ artist => 'Tool' });
14 $rs_column = $rs->get_column('year');
15 $max_year = $rs_column->max; #returns latest year
16
17=head1 DESCRIPTION
18
eb98561c 19A convenience class used to perform operations on a specific column of
20a resultset.
2bb7b40b 21
22=cut
23
24=head1 METHODS
25
26=head2 new
27
28 my $obj = DBIx::Class::ResultSetColumn->new($rs, $column);
29
eb98561c 30Creates a new resultset column object from the resultset and column
31passed as params. Used internally by L<DBIx::Class::ResultSet/get_column>.
2bb7b40b 32
33=cut
34
35sub new {
36 my ($class, $rs, $column) = @_;
37 $class = ref $class if ref $class;
6b051e14 38 my $new = bless { _column => $column, _parent_resultset => $rs }, $class;
39 $new->throw_exception("column must be supplied") unless $column;
2bb7b40b 40 return $new;
41}
42
43=head2 next
44
45=over 4
46
47=item Arguments: none
48
49=item Return Value: $value
50
51=back
52
eb98561c 53Returns the next value of the column in the resultset (or C<undef> if
54there is none).
2bb7b40b 55
eb98561c 56Much like L<DBIx::Class::ResultSet/next> but just returning the
57one value.
2bb7b40b 58
59=cut
60
61sub next {
62 my $self = shift;
2bb7b40b 63 $self->{_resultset} = $self->{_parent_resultset}->search(undef, {select => [$self->{_column}], as => [$self->{_column}]}) unless ($self->{_resultset});
64 my ($row) = $self->{_resultset}->cursor->next;
65 return $row;
66}
67
68=head2 all
69
70=over 4
71
72=item Arguments: none
73
74=item Return Value: @values
75
76=back
77
eb98561c 78Returns all values of the column in the resultset (or C<undef> if
79there are none).
2bb7b40b 80
eb98561c 81Much like L<DBIx::Class::ResultSet/all> but returns values rather
82than row objects.
2bb7b40b 83
84=cut
85
86sub all {
87 my $self = shift;
88 return map {$_->[0]} $self->{_parent_resultset}->search(undef, {select => [$self->{_column}], as => [$self->{_column}]})->cursor->all;
89}
90
91=head2 min
92
93=over 4
94
95=item Arguments: none
96
97=item Return Value: $lowest_value
98
99=back
100
eb98561c 101 my $first_year = $year_col->min();
102
103Wrapper for ->func. Returns the lowest value of the column in the
104resultset (or C<undef> if there are none).
2bb7b40b 105
106=cut
107
108sub min {
6b051e14 109 return shift->func('MIN');
2bb7b40b 110}
111
112=head2 max
113
114=over 4
115
116=item Arguments: none
117
118=item Return Value: $highest_value
119
120=back
121
eb98561c 122 my $last_year = $year_col->max();
123
124Wrapper for ->func. Returns the highest value of the column in the
125resultset (or C<undef> if there are none).
2bb7b40b 126
127=cut
128
129sub max {
6b051e14 130 return shift->func('MAX');
2bb7b40b 131}
132
133=head2 sum
134
135=over 4
136
137=item Arguments: none
138
139=item Return Value: $sum_of_values
140
141=back
142
eb98561c 143 my $total = $prices_col->sum();
144
145Wrapper for ->func. Returns the sum of all the values in the column of
146the resultset. Use on varchar-like columns at your own risk.
2bb7b40b 147
148=cut
149
150sub sum {
6b051e14 151 return shift->func('SUM');
2bb7b40b 152}
153
154=head2 func
155
156=over 4
157
158=item Arguments: $function
159
160=item Return Value: $function_return_value
161
162=back
163
e8419341 164 $rs = $schema->resultset("CD")->search({});
165 $length = $rs->get_column('title')->func('LENGTH');
2bb7b40b 166
eb98561c 167Runs a query using the function on the column and returns the
168value. Produces the following SQL:
169
170 SELECT LENGTH( title ) FROM cd me
2bb7b40b 171
172=cut
173
174sub func {
6b051e14 175 my ($self,$function) = @_;
2bb7b40b 176 my ($row) = $self->{_parent_resultset}->search(undef, {select => {$function => $self->{_column}}, as => [$self->{_column}]})->cursor->next;
177 return $row;
178}
179
1801;
181
182=head1 AUTHORS
183
184Luke Saunders <luke.saunders@gmail.com>
185
eb98561c 186Jess Robinson
187
2bb7b40b 188=head1 LICENSE
189
190You may distribute this code under the same terms as Perl itself.
191
192=cut