libdbix-searchbuilder-perl 1.67-1 / usr / share / perl5 / DBIx / SearchBuilder / Union.pm

package DBIx::SearchBuilder::Union;
use strict;
use warnings;

# WARNING --- This is still development code.  It is experimental.

our $VERSION = '0';

# This could inherit from DBIx::SearchBuilder, but there are _a lot_
# of things in DBIx::SearchBuilder that we don't want, like Limit and
# stuff.  It probably makes sense to (eventually) split out
# DBIx::SearchBuilder::Collection to contain all the iterator logic.
# This could inherit from that.

=head1 NAME

DBIx::SearchBuilder::Union - Deal with multiple SearchBuilder result sets as one

=head1 SYNOPSIS

  use DBIx::SearchBuilder::Union;
  my $U = new DBIx::SearchBuilder::Union;
  $U->add( $tickets1 );
  $U->add( $tickets2 );

  $U->GotoFirstItem;
  while (my $z = $U->Next) {
    printf "%5d %30.30s\n", $z->Id, $z->Subject;
  }

=head1 WARNING

This module is still experimental.

=head1 DESCRIPTION

Implements a subset of the DBIx::SearchBuilder collection methods, but
enough to do iteration over a bunch of results.  Useful for displaying
the results of two unrelated searches (for the same kind of objects)
in a single list.

=head1 METHODS

=head2 new

Create a new DBIx::SearchBuilder::Union object.  No arguments.

=cut

sub new {
  bless {
		 data => [],
		 curp => 0,				# current offset in data
		 item => 0,				# number of indiv items from First
		 count => undef,
		}, shift;
}

=head2 add $sb

Add a searchbuilder result (collection) to the Union object.

It must be the same type as the first object added.

=cut

sub add {
    my $self   = shift;
	my $newobj = shift;

	unless ( @{$self->{data}} == 0
			 || ref($newobj) eq ref($self->{data}[0]) ) {
	  die "All elements of a DBIx::SearchBuilder::Union must be of the same type.  Looking for a " . ref($self->{data}[0]) .".";
	}

	$self->{count} = undef;
    push @{$self->{data}}, $newobj;
}

=head2 First

Return the very first element of the Union (which is the first element
of the first Collection).  Also reset the current pointer to that
element.

=cut

sub First {
    my $self = shift;

	die "No elements in DBIx::SearchBuilder::Union"
	  unless @{$self->{data}};

    $self->{curp} = 0;
	$self->{item} = 0;
    $self->{data}[0]->First;
}

=head2 Next

Return the next element in the Union.

=cut

sub Next {
    my $self=shift;

    my $goto_first = 0;
    while ( my $cur = $self->{'data'}[ $self->{'curp'} ] ) {
        $cur->GotoFirstItem if $goto_first;

        my $res = $cur->Next;
        if ( $res ) {
            $self->{'item'}++;
            return $res;
        }

        $goto_first = 1;
        $self->{'curp'}++;
    }
    return undef;
}

=head2 Last

Returns the last item

=cut

sub Last {
  die "Last doesn't work right now";
  my $self = shift;
  $self->GotoItem( ( $self->Count ) - 1 );
  return ( $self->Next );
}

=head2 Count

Returns the total number of elements in the Union'ed Collection

=cut

sub Count {
  my $self = shift;
  my $sum = 0;

  # cache the results
  return $self->{count} if defined $self->{count};

  $sum += $_->Count for (@{$self->{data}});

  $self->{count} = $sum;

  return $sum;
}


=head2 GotoFirstItem

Starts the recordset counter over from the first item. the next time
you call Next, you'll get the first item returned by the database, as
if you'd just started iterating through the result set.

=cut

sub GotoFirstItem {
  my $self = shift;
  $self->GotoItem(0);
}

sub GotoItem {
  my $self = shift;
  my $item = shift;

  die "We currently only support going to the First item"
	unless $item == 0;

  $self->{curp} = 0;
  $self->{item} = 0;
  $self->{data}[0]->GotoItem(0);

  return $item;
}

=head2 IsLast

Returns true if the current row is the last record in the set.

=cut

sub IsLast {
    my $self = shift;

	$self->{item} == $self->Count ? 1 : undef;
}

=head2 ItemsArrayRef

Return a refernece to an array containing all objects found by this search.

Will destroy any positional state.

=cut

sub ItemsArrayRef {
    my $self = shift;

    return [] unless $self->Count;

	$self->GotoFirstItem();
	my @ret;
	while( my $r = $self->Next ) {
	  push @ret, $r;
	}

	return \@ret;
}

=head1 AUTHOR

Copyright (c) 2004 Robert Spier

All rights reserved.

This library is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.

=head1 SEE ALSO

DBIx::SearchBuilder

=cut

1;

__END__