lib/DBIx/Class/ResultSetColumn.pm

   1 package DBIx::Class::ResultSetColumn;
   2 use strict;
   3 use warnings;
   4 use base 'DBIx::Class';
   5 use List::Util;
   6
   7 =head1 NAME
   8
   9   DBIx::Class::ResultSetColumn - helpful methods for messing
  10   with a single column of the resultset
  11
  12 =head1 SYNOPSIS
  13
  14   $rs = $schema->resultset('CD')->search({ artist => 'Tool' });
  15   $rs_column = $rs->get_column('year');
  16   $max_year = $rs_column->max; #returns latest year
  17
  18 =head1 DESCRIPTION
  19
  20 A convenience class used to perform operations on a specific column of
  21 a resultset.
  22
  23 =cut
  24
  25 =head1 METHODS
  26
  27 =head2 new
  28
  29   my $obj = DBIx::Class::ResultSetColumn->new($rs, $column);
  30
  31 Creates a new resultset column object from the resultset and column
  32 passed as params. Used internally by L<DBIx::Class::ResultSet/get_column>.
  33
  34 =cut
  35
  36 sub new {
  37   my ($class, $rs, $column) = @_;
  38   $class = ref $class if ref $class;
  39
  40   $rs->throw_exception("column must be supplied") unless $column;
  41
  42   my $new_parent_rs = $rs->search_rs; # we don't want to mess up the original, so clone it
  43
  44   # prefetch causes additional columns to be fetched, but we can not just make a new
  45   # rs via the _resolved_attrs trick - we need to retain the separation between
  46   # +select/+as and select/as
  47   for my $attr (qw/prefetch collapse/) {
  48     for (qw/attrs _attrs/) {
  49       delete $new_parent_rs->{$_}{$attr} if ref $new_parent_rs->{$_};
  50     }
  51   }
  52
  53   # If $column can be found in the 'as' list of the parent resultset, use the
  54   # corresponding element of its 'select' list (to keep any custom column
  55   # definition set up with 'select' or '+select' attrs), otherwise use $column
  56   # (to create a new column definition on-the-fly).
  57   my $attrs = $new_parent_rs->_resolved_attrs;
  58
  59   my $as_list = $attrs->{as} || [];
  60   my $select_list = $attrs->{select} || [];
  61   my $as_index = List::Util::first { ($as_list->[$_] || "") eq $column } 0..$#$as_list;
  62   my $select = defined $as_index ? $select_list->[$as_index] : $column;
  63
  64   my $new = bless { _select => $select, _as => $column, _parent_resultset => $new_parent_rs }, $class;
  65   return $new;
  66 }
  67
  68 =head2 as_query (EXPERIMENTAL)
  69
  70 =over 4
  71
  72 =item Arguments: none
  73
  74 =item Return Value: \[ $sql, @bind ]
  75
  76 =back
  77
  78 Returns the SQL query and bind vars associated with the invocant.
  79
  80 This is generally used as the RHS for a subquery.
  81
  82 B<NOTE>: This feature is still experimental.
  83
  84 =cut
  85
  86 sub as_query { return shift->_resultset->as_query(@_) }
  87
  88 =head2 next
  89
  90 =over 4
  91
  92 =item Arguments: none
  93
  94 =item Return Value: $value
  95
  96 =back
  97
  98 Returns the next value of the column in the resultset (or C<undef> if
  99 there is none).
 100
 101 Much like L<DBIx::Class::ResultSet/next> but just returning the
 102 one value.
 103
 104 =cut
 105
 106 sub next {
 107   my $self = shift;
 108   my ($row) = $self->_resultset->cursor->next;
 109   return $row;
 110 }
 111
 112 =head2 all
 113
 114 =over 4
 115
 116 =item Arguments: none
 117
 118 =item Return Value: @values
 119
 120 =back
 121
 122 Returns all values of the column in the resultset (or C<undef> if
 123 there are none).
 124
 125 Much like L<DBIx::Class::ResultSet/all> but returns values rather
 126 than row objects.
 127
 128 =cut
 129
 130 sub all {
 131   my $self = shift;
 132   return map { $_->[0] } $self->_resultset->cursor->all;
 133 }
 134
 135 =head2 reset
 136
 137 =over 4
 138
 139 =item Arguments: none
 140
 141 =item Return Value: $self
 142
 143 =back
 144
 145 Resets the underlying resultset's cursor, so you can iterate through the
 146 elements of the column again.
 147
 148 Much like L<DBIx::Class::ResultSet/reset>.
 149
 150 =cut
 151
 152 sub reset {
 153   my $self = shift;
 154   $self->_resultset->cursor->reset;
 155   return $self;
 156 }
 157
 158 =head2 first
 159
 160 =over 4
 161
 162 =item Arguments: none
 163
 164 =item Return Value: $value
 165
 166 =back
 167
 168 Resets the underlying resultset and returns the next value of the column in the
 169 resultset (or C<undef> if there is none).
 170
 171 Much like L<DBIx::Class::ResultSet/first> but just returning the one value.
 172
 173 =cut
 174
 175 sub first {
 176   my $self = shift;
 177   my ($row) = $self->_resultset->cursor->reset->next;
 178   return $row;
 179 }
 180
 181 =head2 min
 182
 183 =over 4
 184
 185 =item Arguments: none
 186
 187 =item Return Value: $lowest_value
 188
 189 =back
 190
 191   my $first_year = $year_col->min();
 192
 193 Wrapper for ->func. Returns the lowest value of the column in the
 194 resultset (or C<undef> if there are none).
 195
 196 =cut
 197
 198 sub min {
 199   return shift->func('MIN');
 200 }
 201
 202 =head2 min_rs
 203
 204 =over 4
 205
 206 =item Arguments: none
 207
 208 =item Return Value: $resultset
 209
 210 =back
 211
 212   my $rs = $year_col->min_rs();
 213
 214 Wrapper for ->func_rs for function MIN().
 215
 216 =cut
 217
 218 sub min_rs { return shift->func_rs('MIN') }
 219
 220 =head2 max
 221
 222 =over 4
 223
 224 =item Arguments: none
 225
 226 =item Return Value: $highest_value
 227
 228 =back
 229
 230   my $last_year = $year_col->max();
 231
 232 Wrapper for ->func. Returns the highest value of the column in the
 233 resultset (or C<undef> if there are none).
 234
 235 =cut
 236
 237 sub max {
 238   return shift->func('MAX');
 239 }
 240
 241 =head2 max_rs
 242
 243 =over 4
 244
 245 =item Arguments: none
 246
 247 =item Return Value: $resultset
 248
 249 =back
 250
 251   my $rs = $year_col->max_rs();
 252
 253 Wrapper for ->func_rs for function MAX().
 254
 255 =cut
 256
 257 sub max_rs { return shift->func_rs('MAX') }
 258
 259 =head2 sum
 260
 261 =over 4
 262
 263 =item Arguments: none
 264
 265 =item Return Value: $sum_of_values
 266
 267 =back
 268
 269   my $total = $prices_col->sum();
 270
 271 Wrapper for ->func. Returns the sum of all the values in the column of
 272 the resultset. Use on varchar-like columns at your own risk.
 273
 274 =cut
 275
 276 sub sum {
 277   return shift->func('SUM');
 278 }
 279
 280 =head2 sum_rs
 281
 282 =over 4
 283
 284 =item Arguments: none
 285
 286 =item Return Value: $resultset
 287
 288 =back
 289
 290   my $rs = $year_col->sum_rs();
 291
 292 Wrapper for ->func_rs for function SUM().
 293
 294 =cut
 295
 296 sub sum_rs { return shift->func_rs('SUM') }
 297
 298 =head2 func
 299
 300 =over 4
 301
 302 =item Arguments: $function
 303
 304 =item Return Value: $function_return_value
 305
 306 =back
 307
 308   $rs = $schema->resultset("CD")->search({});
 309   $length = $rs->get_column('title')->func('LENGTH');
 310
 311 Runs a query using the function on the column and returns the
 312 value. Produces the following SQL:
 313
 314   SELECT LENGTH( title ) FROM cd me
 315
 316 =cut
 317
 318 sub func {
 319   my ($self,$function) = @_;
 320   my $cursor = $self->func_rs($function)->cursor;
 321
 322   if( wantarray ) {
 323     return map { $_->[ 0 ] } $cursor->all;
 324   }
 325
 326   return ( $cursor->next )[ 0 ];
 327 }
 328
 329 =head2 func_rs
 330
 331 =over 4
 332
 333 =item Arguments: $function
 334
 335 =item Return Value: $resultset
 336
 337 =back
 338
 339 Creates the resultset that C<func()> uses to run its query.
 340
 341 =cut
 342
 343 sub func_rs {
 344   my ($self,$function) = @_;
 345   return $self->{_parent_resultset}->search(
 346     undef, {
 347       select => {$function => $self->{_select}},
 348       as => [$self->{_as}],
 349     },
 350   );
 351 }
 352
 353 =head2 throw_exception
 354
 355 See L<DBIx::Class::Schema/throw_exception> for details.
 356
 357 =cut
 358
 359 sub throw_exception {
 360   my $self=shift;
 361   if (ref $self && $self->{_parent_resultset}) {
 362     $self->{_parent_resultset}->throw_exception(@_)
 363   } else {
 364     croak(@_);
 365   }
 366 }
 367
 368 # _resultset
 369 #
 370 # Arguments: none
 371 #
 372 # Return Value: $resultset
 373 #
 374 #  $year_col->_resultset->next
 375 #
 376 # Returns the underlying resultset. Creates it from the parent resultset if
 377 # necessary.
 378 #
 379 sub _resultset {
 380   my $self = shift;
 381
 382   return $self->{_resultset} ||= $self->{_parent_resultset}->search(undef,
 383     {
 384       select => [$self->{_select}],
 385       as => [$self->{_as}]
 386     }
 387   );
 388 }
 389
 390 1;
 391
 392 =head1 AUTHORS
 393
 394 Luke Saunders <luke.saunders@gmail.com>
 395
 396 Jess Robinson
 397
 398 =head1 LICENSE
 399
 400 You may distribute this code under the same terms as Perl itself.
 401
 402 =cut