[dbsrgits/DBIx-Class.git] / lib / DBIx / Class / ResultSetColumn.pm

package DBIx::Class::ResultSetColumn;
use strict;
use warnings;
use base 'DBIx::Class';
use List::Util;

=head1 NAME

  DBIx::Class::ResultSetColumn - helpful methods for messing
  with a single column of the resultset

=head1 SYNOPSIS

  $rs = $schema->resultset('CD')->search({ artist => 'Tool' });
  $rs_column = $rs->get_column('year');
  $max_year = $rs_column->max; #returns latest year

=head1 DESCRIPTION

A convenience class used to perform operations on a specific column of
a resultset.

=cut

=head1 METHODS

=head2 new

  my $obj = DBIx::Class::ResultSetColumn->new($rs, $column);

Creates a new resultset column object from the resultset and column
passed as params. Used internally by L<DBIx::Class::ResultSet/get_column>.

=cut

sub new {
  my ($class, $rs, $column) = @_;
  $class = ref $class if ref $class;

  $rs->throw_exception("column must be supplied") unless $column;

  my $orig_attrs = $rs->_resolved_attrs;
  my $new_parent_rs = $rs->search_rs;

  # prefetch causes additional columns to be fetched, but we can not just make a new
  # rs via the _resolved_attrs trick - we need to retain the separation between
  # +select/+as and select/as. At the same time we want to preserve any joins that the
  # prefetch would otherwise generate.

  my $new_attrs = $new_parent_rs->{attrs} ||= {};
  $new_attrs->{join} = $rs->_merge_attr( delete $new_attrs->{join}, delete $new_attrs->{prefetch} );

  # If $column can be found in the 'as' list of the parent resultset, use the
  # corresponding element of its 'select' list (to keep any custom column
  # definition set up with 'select' or '+select' attrs), otherwise use $column
  # (to create a new column definition on-the-fly).

  my $as_list = $orig_attrs->{as} || [];
  my $select_list = $orig_attrs->{select} || [];
  my $as_index = List::Util::first { ($as_list->[$_] || "") eq $column } 0..$#$as_list;
  my $select = defined $as_index ? $select_list->[$as_index] : $column;

  # {collapse} would mean a has_many join was injected, which in turn means
  # we need to group IF WE CAN (only if the column in question is unique)
  if (!$new_attrs->{group_by} && keys %{$orig_attrs->{collapse}}) {

    # scan for a constraint that would contain our column only - that'd be proof
    # enough it is unique
    my $constraints = { $rs->result_source->unique_constraints };
    for my $constraint_columns ( values %$constraints ) {

      next unless @$constraint_columns == 1;

      my $col = $constraint_columns->[0];
      my $fqcol = join ('.', $new_attrs->{alias}, $col);

      if ($col eq $select or $fqcol eq $select) {
        $new_attrs->{group_by} = [ $select ];
        last;
      }
    }
  }

  my $new = bless { _select => $select, _as => $column, _parent_resultset => $new_parent_rs }, $class;
  return $new;
}

=head2 as_query (EXPERIMENTAL)

=over 4

=item Arguments: none

=item Return Value: \[ $sql, @bind ]

=back

Returns the SQL query and bind vars associated with the invocant.

This is generally used as the RHS for a subquery.

B<NOTE>: This feature is still experimental.

=cut

sub as_query { return shift->_resultset->as_query(@_) }

=head2 next

=over 4

=item Arguments: none

=item Return Value: $value

=back

Returns the next value of the column in the resultset (or C<undef> if
there is none).

Much like L<DBIx::Class::ResultSet/next> but just returning the 
one value.

=cut

sub next {
  my $self = shift;

  # using cursor so we don't inflate anything
  my ($row) = $self->_resultset->cursor->next;

  return $row;
}

=head2 all

=over 4

=item Arguments: none

=item Return Value: @values

=back

Returns all values of the column in the resultset (or C<undef> if
there are none).

Much like L<DBIx::Class::ResultSet/all> but returns values rather
than row objects.

=cut

sub all {
  my $self = shift;

  # using cursor so we don't inflate anything
  return map { $_->[0] } $self->_resultset->cursor->all;
}

=head2 reset

=over 4

=item Arguments: none

=item Return Value: $self

=back

Resets the underlying resultset's cursor, so you can iterate through the
elements of the column again.

Much like L<DBIx::Class::ResultSet/reset>.

=cut

sub reset {
  my $self = shift;
  $self->_resultset->cursor->reset;
  return $self;
}

=head2 first

=over 4

=item Arguments: none

=item Return Value: $value

=back

Resets the underlying resultset and returns the next value of the column in the
resultset (or C<undef> if there is none).

Much like L<DBIx::Class::ResultSet/first> but just returning the one value.

=cut

sub first {
  my $self = shift;

  # using cursor so we don't inflate anything
  $self->_resultset->cursor->reset;
  my ($row) = $self->_resultset->cursor->next;

  return $row;
}

=head2 single

=over 4

=item Arguments: none

=item Return Value: $value

=back

Much like L<DBIx::Class::ResultSet/single> fetches one and only one column
value using the cursor directly. If additional rows are present a warning
is issued before discarding the cursor.

=cut

sub single {
  my $self = shift;

  my $attrs = $self->_resultset->_resolved_attrs;
  my ($row) = $self->_resultset->result_source->storage->select_single(
    $attrs->{from}, $attrs->{select}, $attrs->{where}, $attrs
  );

  return $row;
}

=head2 min

=over 4

=item Arguments: none

=item Return Value: $lowest_value

=back

  my $first_year = $year_col->min();

Wrapper for ->func. Returns the lowest value of the column in the
resultset (or C<undef> if there are none).

=cut

sub min {
  return shift->func('MIN');
}

=head2 min_rs

=over 4

=item Arguments: none

=item Return Value: $resultset

=back

  my $rs = $year_col->min_rs();

Wrapper for ->func_rs for function MIN().

=cut

sub min_rs { return shift->func_rs('MIN') }

=head2 max

=over 4

=item Arguments: none

=item Return Value: $highest_value

=back

  my $last_year = $year_col->max();

Wrapper for ->func. Returns the highest value of the column in the
resultset (or C<undef> if there are none).

=cut

sub max {
  return shift->func('MAX');
}

=head2 max_rs

=over 4

=item Arguments: none

=item Return Value: $resultset

=back

  my $rs = $year_col->max_rs();

Wrapper for ->func_rs for function MAX().

=cut

sub max_rs { return shift->func_rs('MAX') }

=head2 sum

=over 4

=item Arguments: none

=item Return Value: $sum_of_values

=back

  my $total = $prices_col->sum();

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.

=cut

sub sum {
  return shift->func('SUM');
}

=head2 sum_rs

=over 4

=item Arguments: none

=item Return Value: $resultset

=back

  my $rs = $year_col->sum_rs();

Wrapper for ->func_rs for function SUM().

=cut

sub sum_rs { return shift->func_rs('SUM') }

=head2 func

=over 4

=item Arguments: $function

=item Return Value: $function_return_value

=back

  $rs = $schema->resultset("CD")->search({});
  $length = $rs->get_column('title')->func('LENGTH');

Runs a query using the function on the column and returns the
value. Produces the following SQL:

  SELECT LENGTH( title ) FROM cd me

=cut

sub func {
  my ($self,$function) = @_;
  my $cursor = $self->func_rs($function)->cursor;

  if( wantarray ) {
    return map { $_->[ 0 ] } $cursor->all;
  }

  return ( $cursor->next )[ 0 ];
}

=head2 func_rs

=over 4

=item Arguments: $function

=item Return Value: $resultset

=back

Creates the resultset that C<func()> uses to run its query.

=cut

sub func_rs {
  my ($self,$function) = @_;
  return $self->{_parent_resultset}->search(
    undef, {
      select => {$function => $self->{_select}},
      as => [$self->{_as}],
    },
  );
}

=head2 throw_exception

See L<DBIx::Class::Schema/throw_exception> for details.

=cut 

sub throw_exception {
  my $self=shift;
  if (ref $self && $self->{_parent_resultset}) {
    $self->{_parent_resultset}->throw_exception(@_)
  } else {
    croak(@_);
  }
}

# _resultset
#
# Arguments: none
#
# Return Value: $resultset
#
#  $year_col->_resultset->next
#
# Returns the underlying resultset. Creates it from the parent resultset if
# necessary.
#
sub _resultset {
  my $self = shift;

  return $self->{_resultset} ||= $self->{_parent_resultset}->search(undef,
    {
      select => [$self->{_select}],
      as => [$self->{_as}]
    }
  );
}

1;

=head1 AUTHORS

Luke Saunders <luke.saunders@gmail.com>

Jess Robinson

=head1 LICENSE

You may distribute this code under the same terms as Perl itself.

=cut
Commit	Line	Data
2bb7b40b	1	package DBIx::Class::ResultSetColumn;
	2	use strict;
	3	use warnings;
	4	use base 'DBIx::Class';
66521001	5	use List::Util;
2bb7b40b	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
eb98561c	20	A convenience class used to perform operations on a specific column of
eb98561c	21	a resultset.
2bb7b40b	22
	23	=cut
	24
	25	=head1 METHODS
	26
	27	=head2 new
	28
	29	my $obj = DBIx::Class::ResultSetColumn->new($rs, $column);
	30
eb98561c	31	Creates a new resultset column object from the resultset and column
eb98561c	32	passed as params. Used internally by L<DBIx::Class::ResultSet/get_column>.
2bb7b40b	33
	34	=cut
	35
	36	sub new {
	37	my ($class, $rs, $column) = @_;
	38	$class = ref $class if ref $class;
7ae9706c	39
	40	$rs->throw_exception("column must be supplied") unless $column;
	41
d8dbe471	42	my $orig_attrs = $rs->_resolved_attrs;
d8dbe471	43	my $new_parent_rs = $rs->search_rs;
7ae9706c	44
	45	# prefetch causes additional columns to be fetched, but we can not just make a new
	46	# rs via the _resolved_attrs trick - we need to retain the separation between
bed3a173	47	# +select/+as and select/as. At the same time we want to preserve any joins that the
bed3a173	48	# prefetch would otherwise generate.
d8dbe471	49
	50	my $new_attrs = $new_parent_rs->{attrs} \|\|= {};
	51	$new_attrs->{join} = $rs->_merge_attr( delete $new_attrs->{join}, delete $new_attrs->{prefetch} );
b6e85b48	52
152002c4	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).
7ae9706c	57
d8dbe471	58	my $as_list = $orig_attrs->{as} \|\| [];
d8dbe471	59	my $select_list = $orig_attrs->{select} \|\| [];
b6e85b48	60	my $as_index = List::Util::first { ($as_list->[$_] \|\| "") eq $column } 0..$#$as_list;
b6e85b48	61	my $select = defined $as_index ? $select_list->[$as_index] : $column;
b6e85b48	62
d8dbe471	63	# {collapse} would mean a has_many join was injected, which in turn means
	64	# we need to group IF WE CAN (only if the column in question is unique)
	65	if (!$new_attrs->{group_by} && keys %{$orig_attrs->{collapse}}) {
	66
	67	# scan for a constraint that would contain our column only - that'd be proof
	68	# enough it is unique
	69	my $constraints = { $rs->result_source->unique_constraints };
	70	for my $constraint_columns ( values %$constraints ) {
	71
	72	next unless @$constraint_columns == 1;
	73
	74	my $col = $constraint_columns->[0];
	75	my $fqcol = join ('.', $new_attrs->{alias}, $col);
	76
	77	if ($col eq $select or $fqcol eq $select) {
	78	$new_attrs->{group_by} = [ $select ];
	79	last;
	80	}
	81	}
	82	}
	83
b6e85b48	84	my $new = bless { _select => $select, _as => $column, _parent_resultset => $new_parent_rs }, $class;
2bb7b40b	85	return $new;
	86	}
	87
70bb942d	88	=head2 as_query (EXPERIMENTAL)
658fa250	89
	90	=over 4
	91
428a645e	92	=item Arguments: none
658fa250	93
4dc99a01	94	=item Return Value: \[ $sql, @bind ]
658fa250	95
	96	=back
	97
	98	Returns the SQL query and bind vars associated with the invocant.
	99
03834f77	100	This is generally used as the RHS for a subquery.
c7a9d102	101
6a9530d1	102	B<NOTE>: This feature is still experimental.
6a9530d1	103
c7a9d102	104	=cut
c7a9d102	105
0f6fc705	106	sub as_query { return shift->_resultset->as_query(@_) }
c7a9d102	107
2bb7b40b	108	=head2 next
	109
	110	=over 4
	111
	112	=item Arguments: none
	113
	114	=item Return Value: $value
	115
	116	=back
	117
eb98561c	118	Returns the next value of the column in the resultset (or C<undef> if
eb98561c	119	there is none).
2bb7b40b	120
eb98561c	121	Much like L<DBIx::Class::ResultSet/next> but just returning the
eb98561c	122	one value.
2bb7b40b	123
	124	=cut
	125
	126	sub next {
	127	my $self = shift;
b7c79955	128
b7c79955	129	# using cursor so we don't inflate anything
66521001	130	my ($row) = $self->_resultset->cursor->next;
b7c79955	131
2bb7b40b	132	return $row;
	133	}
	134
	135	=head2 all
	136
	137	=over 4
	138
	139	=item Arguments: none
	140
	141	=item Return Value: @values
	142
	143	=back
	144
eb98561c	145	Returns all values of the column in the resultset (or C<undef> if
eb98561c	146	there are none).
2bb7b40b	147
eb98561c	148	Much like L<DBIx::Class::ResultSet/all> but returns values rather
eb98561c	149	than row objects.
2bb7b40b	150
	151	=cut
	152
	153	sub all {
	154	my $self = shift;
b7c79955	155
b7c79955	156	# using cursor so we don't inflate anything
66521001	157	return map { $_->[0] } $self->_resultset->cursor->all;
	158	}
	159
	160	=head2 reset
	161
	162	=over 4
	163
	164	=item Arguments: none
	165
	166	=item Return Value: $self
	167
	168	=back
	169
	170	Resets the underlying resultset's cursor, so you can iterate through the
	171	elements of the column again.
	172
	173	Much like L<DBIx::Class::ResultSet/reset>.
	174
	175	=cut
	176
	177	sub reset {
	178	my $self = shift;
	179	$self->_resultset->cursor->reset;
b7c79955	180	return $self;
66521001	181	}
	182
	183	=head2 first
	184
	185	=over 4
	186
	187	=item Arguments: none
	188
	189	=item Return Value: $value
	190
	191	=back
	192
	193	Resets the underlying resultset and returns the next value of the column in the
	194	resultset (or C<undef> if there is none).
	195
	196	Much like L<DBIx::Class::ResultSet/first> but just returning the one value.
	197
	198	=cut
	199
	200	sub first {
	201	my $self = shift;
b7c79955	202
	203	# using cursor so we don't inflate anything
	204	$self->_resultset->cursor->reset;
01dc6781	205	my ($row) = $self->_resultset->cursor->next;
b7c79955	206
66521001	207	return $row;
2bb7b40b	208	}
2bb7b40b	209
4e55c3ae	210	=head2 single
	211
	212	=over 4
	213
	214	=item Arguments: none
	215
	216	=item Return Value: $value
	217
	218	=back
	219
	220	Much like L<DBIx::Class::ResultSet/single> fetches one and only one column
	221	value using the cursor directly. If additional rows are present a warning
	222	is issued before discarding the cursor.
	223
	224	=cut
	225
	226	sub single {
	227	my $self = shift;
	228
	229	my $attrs = $self->_resultset->_resolved_attrs;
	230	my ($row) = $self->_resultset->result_source->storage->select_single(
	231	$attrs->{from}, $attrs->{select}, $attrs->{where}, $attrs
	232	);
	233
	234	return $row;
	235	}
	236
2bb7b40b	237	=head2 min
	238
	239	=over 4
	240
	241	=item Arguments: none
	242
	243	=item Return Value: $lowest_value
	244
	245	=back
	246
eb98561c	247	my $first_year = $year_col->min();
	248
	249	Wrapper for ->func. Returns the lowest value of the column in the
	250	resultset (or C<undef> if there are none).
2bb7b40b	251
	252	=cut
	253
	254	sub min {
6b051e14	255	return shift->func('MIN');
2bb7b40b	256	}
2bb7b40b	257
4fa7bc22	258	=head2 min_rs
	259
	260	=over 4
	261
	262	=item Arguments: none
	263
	264	=item Return Value: $resultset
	265
	266	=back
	267
	268	my $rs = $year_col->min_rs();
	269
	270	Wrapper for ->func_rs for function MIN().
	271
	272	=cut
	273
	274	sub min_rs { return shift->func_rs('MIN') }
	275
2bb7b40b	276	=head2 max
	277
	278	=over 4
	279
	280	=item Arguments: none
	281
	282	=item Return Value: $highest_value
	283
	284	=back
	285
eb98561c	286	my $last_year = $year_col->max();
	287
	288	Wrapper for ->func. Returns the highest value of the column in the
	289	resultset (or C<undef> if there are none).
2bb7b40b	290
	291	=cut
	292
	293	sub max {
6b051e14	294	return shift->func('MAX');
2bb7b40b	295	}
2bb7b40b	296
4fa7bc22	297	=head2 max_rs
	298
	299	=over 4
	300
	301	=item Arguments: none
	302
	303	=item Return Value: $resultset
	304
	305	=back
	306
	307	my $rs = $year_col->max_rs();
	308
	309	Wrapper for ->func_rs for function MAX().
	310
	311	=cut
	312
	313	sub max_rs { return shift->func_rs('MAX') }
	314
2bb7b40b	315	=head2 sum
	316
	317	=over 4
	318
	319	=item Arguments: none
	320
	321	=item Return Value: $sum_of_values
	322
	323	=back
	324
eb98561c	325	my $total = $prices_col->sum();
	326
	327	Wrapper for ->func. Returns the sum of all the values in the column of
	328	the resultset. Use on varchar-like columns at your own risk.
2bb7b40b	329
	330	=cut
	331
	332	sub sum {
6b051e14	333	return shift->func('SUM');
2bb7b40b	334	}
2bb7b40b	335
4fa7bc22	336	=head2 sum_rs
	337
	338	=over 4
	339
	340	=item Arguments: none
	341
	342	=item Return Value: $resultset
	343
	344	=back
	345
	346	my $rs = $year_col->sum_rs();
	347
	348	Wrapper for ->func_rs for function SUM().
	349
	350	=cut
	351
	352	sub sum_rs { return shift->func_rs('SUM') }
	353
2bb7b40b	354	=head2 func
	355
	356	=over 4
	357
	358	=item Arguments: $function
	359
	360	=item Return Value: $function_return_value
	361
	362	=back
	363
e8419341	364	$rs = $schema->resultset("CD")->search({});
e8419341	365	$length = $rs->get_column('title')->func('LENGTH');
2bb7b40b	366
eb98561c	367	Runs a query using the function on the column and returns the
	368	value. Produces the following SQL:
	369
	370	SELECT LENGTH( title ) FROM cd me
2bb7b40b	371
	372	=cut
	373
	374	sub func {
6b051e14	375	my ($self,$function) = @_;
4fa7bc22	376	my $cursor = $self->func_rs($function)->cursor;
d4daee7b	377
5d62876f	378	if( wantarray ) {
	379	return map { $_->[ 0 ] } $cursor->all;
	380	}
	381
	382	return ( $cursor->next )[ 0 ];
2bb7b40b	383	}
2bb7b40b	384
4fa7bc22	385	=head2 func_rs
	386
	387	=over 4
	388
	389	=item Arguments: $function
	390
	391	=item Return Value: $resultset
	392
	393	=back
	394
	395	Creates the resultset that C<func()> uses to run its query.
	396
	397	=cut
	398
	399	sub func_rs {
	400	my ($self,$function) = @_;
	401	return $self->{_parent_resultset}->search(
	402	undef, {
	403	select => {$function => $self->{_select}},
	404	as => [$self->{_as}],
	405	},
	406	);
	407	}
	408
5d1fc7dc	409	=head2 throw_exception
	410
	411	See L<DBIx::Class::Schema/throw_exception> for details.
d4daee7b	412
5d1fc7dc	413	=cut
d4daee7b	414
5d1fc7dc	415	sub throw_exception {
	416	my $self=shift;
	417	if (ref $self && $self->{_parent_resultset}) {
	418	$self->{_parent_resultset}->throw_exception(@_)
	419	} else {
	420	croak(@_);
	421	}
	422	}
	423
b6e85b48	424	# _resultset
	425	#
	426	# Arguments: none
	427	#
	428	# Return Value: $resultset
	429	#
	430	# $year_col->_resultset->next
	431	#
	432	# Returns the underlying resultset. Creates it from the parent resultset if
	433	# necessary.
b7c79955	434	#
66521001	435	sub _resultset {
	436	my $self = shift;
	437
	438	return $self->{_resultset} \|\|= $self->{_parent_resultset}->search(undef,
	439	{
	440	select => [$self->{_select}],
	441	as => [$self->{_as}]
	442	}
	443	);
	444	}
	445
2bb7b40b	446	1;
	447
	448	=head1 AUTHORS
	449
	450	Luke Saunders <luke.saunders@gmail.com>
	451
eb98561c	452	Jess Robinson
eb98561c	453
2bb7b40b	454	=head1 LICENSE
	455
	456	You may distribute this code under the same terms as Perl itself.
	457
	458	=cut