Improve resultset_attributes docs
[dbsrgits/DBIx-Class-Historic.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;
38
39 my $object_ref = { _column => $column,
40 _parent_resultset => $rs };
41
42 my $new = bless $object_ref, $class;
43 $new->throw_exception("column must be supplied") unless ($column);
44 return $new;
45}
46
47=head2 next
48
49=over 4
50
51=item Arguments: none
52
53=item Return Value: $value
54
55=back
56
eb98561c 57Returns the next value of the column in the resultset (or C<undef> if
58there is none).
2bb7b40b 59
eb98561c 60Much like L<DBIx::Class::ResultSet/next> but just returning the
61one value.
2bb7b40b 62
63=cut
64
65sub next {
66 my $self = shift;
67
68 $self->{_resultset} = $self->{_parent_resultset}->search(undef, {select => [$self->{_column}], as => [$self->{_column}]}) unless ($self->{_resultset});
69 my ($row) = $self->{_resultset}->cursor->next;
70 return $row;
71}
72
73=head2 all
74
75=over 4
76
77=item Arguments: none
78
79=item Return Value: @values
80
81=back
82
eb98561c 83Returns all values of the column in the resultset (or C<undef> if
84there are none).
2bb7b40b 85
eb98561c 86Much like L<DBIx::Class::ResultSet/all> but returns values rather
87than row objects.
2bb7b40b 88
89=cut
90
91sub all {
92 my $self = shift;
93 return map {$_->[0]} $self->{_parent_resultset}->search(undef, {select => [$self->{_column}], as => [$self->{_column}]})->cursor->all;
94}
95
96=head2 min
97
98=over 4
99
100=item Arguments: none
101
102=item Return Value: $lowest_value
103
104=back
105
eb98561c 106 my $first_year = $year_col->min();
107
108Wrapper for ->func. Returns the lowest value of the column in the
109resultset (or C<undef> if there are none).
2bb7b40b 110
111=cut
112
113sub min {
114 my $self = shift;
115 return $self->func('MIN');
116}
117
118=head2 max
119
120=over 4
121
122=item Arguments: none
123
124=item Return Value: $highest_value
125
126=back
127
eb98561c 128 my $last_year = $year_col->max();
129
130Wrapper for ->func. Returns the highest value of the column in the
131resultset (or C<undef> if there are none).
2bb7b40b 132
133=cut
134
135sub max {
136 my $self = shift;
137 return $self->func('MAX');
138}
139
140=head2 sum
141
142=over 4
143
144=item Arguments: none
145
146=item Return Value: $sum_of_values
147
148=back
149
eb98561c 150 my $total = $prices_col->sum();
151
152Wrapper for ->func. Returns the sum of all the values in the column of
153the resultset. Use on varchar-like columns at your own risk.
2bb7b40b 154
155=cut
156
157sub sum {
158 my $self = shift;
159 return $self->func('SUM');
160}
161
162=head2 func
163
164=over 4
165
166=item Arguments: $function
167
168=item Return Value: $function_return_value
169
170=back
171
e8419341 172 $rs = $schema->resultset("CD")->search({});
173 $length = $rs->get_column('title')->func('LENGTH');
2bb7b40b 174
eb98561c 175Runs a query using the function on the column and returns the
176value. Produces the following SQL:
177
178 SELECT LENGTH( title ) FROM cd me
2bb7b40b 179
180=cut
181
182sub func {
183 my $self = shift;
184 my $function = shift;
185
186 my ($row) = $self->{_parent_resultset}->search(undef, {select => {$function => $self->{_column}}, as => [$self->{_column}]})->cursor->next;
187 return $row;
188}
189
1901;
191
192=head1 AUTHORS
193
194Luke Saunders <luke.saunders@gmail.com>
195
eb98561c 196Jess Robinson
197
2bb7b40b 198=head1 LICENSE
199
200You may distribute this code under the same terms as Perl itself.
201
202=cut