Merge 'bulk_create' into 'DBIx-Class-current'
[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   my $new = bless { _column => $column, _parent_resultset => $rs }, $class;
39   $new->throw_exception("column must be supplied") unless $column;
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
53 Returns the next value of the column in the resultset (or C<undef> if
54 there is none).
55
56 Much like L<DBIx::Class::ResultSet/next> but just returning the 
57 one value.
58
59 =cut
60
61 sub next {
62   my $self = shift;
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
78 Returns all values of the column in the resultset (or C<undef> if
79 there are none).
80
81 Much like L<DBIx::Class::ResultSet/all> but returns values rather
82 than row objects.
83
84 =cut
85
86 sub 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
101   my $first_year = $year_col->min();
102
103 Wrapper for ->func. Returns the lowest value of the column in the
104 resultset (or C<undef> if there are none).
105
106 =cut
107
108 sub min {
109   return shift->func('MIN');
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
122   my $last_year = $year_col->max();
123
124 Wrapper for ->func. Returns the highest value of the column in the
125 resultset (or C<undef> if there are none).
126
127 =cut
128
129 sub max {
130   return shift->func('MAX');
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
143   my $total = $prices_col->sum();
144
145 Wrapper for ->func. Returns the sum of all the values in the column of
146 the resultset. Use on varchar-like columns at your own risk.
147
148 =cut
149
150 sub sum {
151   return shift->func('SUM');
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
164   $rs = $schema->resultset("CD")->search({});
165   $length = $rs->get_column('title')->func('LENGTH');
166
167 Runs a query using the function on the column and returns the
168 value. Produces the following SQL:
169
170   SELECT LENGTH( title ) FROM cd me
171
172 =cut
173
174 sub func {
175   my ($self,$function) = @_;
176   my ($row) = $self->{_parent_resultset}->search(undef, {select => {$function => $self->{_column}}, as => [$self->{_column}]})->cursor->next;
177   return $row;
178 }
179
180 1;
181
182 =head1 AUTHORS
183
184 Luke Saunders <luke.saunders@gmail.com>
185
186 Jess Robinson
187
188 =head1 LICENSE
189
190 You may distribute this code under the same terms as Perl itself.
191
192 =cut