remove_columns now deletes columns from _columns fixing has_columns false positives
[dbsrgits/DBIx-Class-Historic.git] / lib / DBIx / Class / ResultSetColumn.pm
1 package DBIx::Class::ResultSetColumn;
2 use strict;
3 use warnings;
4 use 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
19 A convenience class used to perform operations on a specific column of
20 a resultset.
21
22 =cut
23
24 =head1 METHODS
25
26 =head2 new
27
28   my $obj = DBIx::Class::ResultSetColumn->new($rs, $column);
29
30 Creates a new resultset column object from the resultset and column
31 passed as params. Used internally by L<DBIx::Class::ResultSet/get_column>.
32
33 =cut
34
35 sub 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
57 Returns the next value of the column in the resultset (or C<undef> if
58 there is none).
59
60 Much like L<DBIx::Class::ResultSet/next> but just returning the 
61 one value.
62
63 =cut
64
65 sub 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
83 Returns all values of the column in the resultset (or C<undef> if
84 there are none).
85
86 Much like L<DBIx::Class::ResultSet/all> but returns values rather
87 than row objects.
88
89 =cut
90
91 sub 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
106   my $first_year = $year_col->min();
107
108 Wrapper for ->func. Returns the lowest value of the column in the
109 resultset (or C<undef> if there are none).
110
111 =cut
112
113 sub 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
128   my $last_year = $year_col->max();
129
130 Wrapper for ->func. Returns the highest value of the column in the
131 resultset (or C<undef> if there are none).
132
133 =cut
134
135 sub 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
150   my $total = $prices_col->sum();
151
152 Wrapper for ->func. Returns the sum of all the values in the column of
153 the resultset. Use on varchar-like columns at your own risk.
154
155 =cut
156
157 sub 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
172   $rs = $schema->resultset("CD")->search({});
173   $length = $rs->get_column('title')->func('LENGTH');
174
175 Runs a query using the function on the column and returns the
176 value. Produces the following SQL:
177
178   SELECT LENGTH( title ) FROM cd me
179
180 =cut
181
182 sub 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
190 1;
191
192 =head1 AUTHORS
193
194 Luke Saunders <luke.saunders@gmail.com>
195
196 Jess Robinson
197
198 =head1 LICENSE
199
200 You may distribute this code under the same terms as Perl itself.
201
202 =cut