Updated version and Changes for 0.06999_02
[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
19A convenience class used to perform operations on a specific column of a resultset.
20
21=cut
22
23=head1 METHODS
24
25=head2 new
26
27 my $obj = DBIx::Class::ResultSetColumn->new($rs, $column);
28
29Creates a new resultset column object from the resultset and column passed as params
30
31=cut
32
33sub new {
34 my ($class, $rs, $column) = @_;
35 $class = ref $class if ref $class;
36
37 my $object_ref = { _column => $column,
38 _parent_resultset => $rs };
39
40 my $new = bless $object_ref, $class;
41 $new->throw_exception("column must be supplied") unless ($column);
42 return $new;
43}
44
45=head2 next
46
47=over 4
48
49=item Arguments: none
50
51=item Return Value: $value
52
53=back
54
55Returns the next value of the column in the resultset (C<undef> is there is none).
56
57Much like $rs->next but just returning the one value
58
59=cut
60
61sub next {
62 my $self = shift;
63
64 $self->{_resultset} = $self->{_parent_resultset}->search(undef, {select => [$self->{_column}], as => [$self->{_column}]}) unless ($self->{_resultset});
65 my ($row) = $self->{_resultset}->cursor->next;
66 return $row;
67}
68
69=head2 all
70
71=over 4
72
73=item Arguments: none
74
75=item Return Value: @values
76
77=back
78
79Returns all values of the column in the resultset (C<undef> is there are none).
80
81Much like $rs->all but returns values rather than row objects
82
83=cut
84
85sub all {
86 my $self = shift;
87 return map {$_->[0]} $self->{_parent_resultset}->search(undef, {select => [$self->{_column}], as => [$self->{_column}]})->cursor->all;
88}
89
90=head2 min
91
92=over 4
93
94=item Arguments: none
95
96=item Return Value: $lowest_value
97
98=back
99
100Wrapper for ->func. Returns the lowest value of the column in the resultset (C<undef> is there are none).
101
102=cut
103
104sub min {
105 my $self = shift;
106 return $self->func('MIN');
107}
108
109=head2 max
110
111=over 4
112
113=item Arguments: none
114
115=item Return Value: $highest_value
116
117=back
118
119Wrapper for ->func. Returns the highest value of the column in the resultset (C<undef> is there are none).
120
121=cut
122
123sub max {
124 my $self = shift;
125 return $self->func('MAX');
126}
127
128=head2 sum
129
130=over 4
131
132=item Arguments: none
133
134=item Return Value: $sum_of_values
135
136=back
137
138Wrapper for ->func. Returns the sum of all the values in the column of the resultset. Use on varchar-like columns at your own risk.
139
140=cut
141
142sub sum {
143 my $self = shift;
144 return $self->func('SUM');
145}
146
147=head2 func
148
149=over 4
150
151=item Arguments: $function
152
153=item Return Value: $function_return_value
154
155=back
156
157Runs a query using the function on the column and returns the value. For example
e8419341 158 $rs = $schema->resultset("CD")->search({});
159 $length = $rs->get_column('title')->func('LENGTH');
2bb7b40b 160
161Produces the following SQL
162 SELECT LENGTH( title ) from cd me
163
164=cut
165
166sub func {
167 my $self = shift;
168 my $function = shift;
169
170 my ($row) = $self->{_parent_resultset}->search(undef, {select => {$function => $self->{_column}}, as => [$self->{_column}]})->cursor->next;
171 return $row;
172}
173
1741;
175
176=head1 AUTHORS
177
178Luke Saunders <luke.saunders@gmail.com>
179
180=head1 LICENSE
181
182You may distribute this code under the same terms as Perl itself.
183
184=cut