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


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

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

=head1 WARNING

This module is still experimental.


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.


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.


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


sub First {
    my $self = shift;

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

    $self->{curp} = 0;
	$self->{item} = 0;

=head2 Next

Return the next element in the Union.


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 ) {
            return $res;

        $goto_first = 1;
    return undef;

=head2 Last

Returns the last item


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


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.


sub GotoFirstItem {
  my $self = shift;

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;

  return $item;

=head2 IsLast

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


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.


sub ItemsArrayRef {
    my $self = shift;

    return [] unless $self->Count;

	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