Add automatic naming of unique constraints
[dbsrgits/DBIx-Class.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 a resultset.
20
21 =cut
22
23 =head1 METHODS
24
25 =head2 new
26
27   my $obj = DBIx::Class::ResultSetColumn->new($rs, $column);
28
29 Creates a new resultset column object from the resultset and column passed as params
30
31 =cut
32
33 sub 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
55 Returns the next value of the column in the resultset (C<undef> is there is none).
56
57 Much like $rs->next but just returning the one value
58
59 =cut
60
61 sub 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
79 Returns all values of the column in the resultset (C<undef> is there are none).
80
81 Much like $rs->all but returns values rather than row objects
82
83 =cut
84
85 sub 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
100 Wrapper for ->func. Returns the lowest value of the column in the resultset (C<undef> is there are none).
101
102 =cut
103
104 sub 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
119 Wrapper for ->func. Returns the highest value of the column in the resultset (C<undef> is there are none).
120
121 =cut
122
123 sub 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
138 Wrapper 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
142 sub 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
157 Runs a query using the function on the column and returns the value. For example 
158   $rs = $schema->resultset("CD")->search({});
159   $length = $rs->get_column('title')->func('LENGTH');
160
161 Produces the following SQL
162   SELECT LENGTH( title ) from cd me
163
164 =cut
165
166 sub 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
174 1;
175
176 =head1 AUTHORS
177
178 Luke Saunders <luke.saunders@gmail.com>
179
180 =head1 LICENSE
181
182 You may distribute this code under the same terms as Perl itself.
183
184 =cut