File Coverage

blib/lib/Array/Diff.pm

Criterion	Covered	Total	%
statement	32	34	94.1
branch	8	10	80.0
condition	1	3	33.3
subroutine	7	7	100.0
pod	2	2	100.0
total	50	56	89.2

package Array::Diff;
$Array::Diff::VERSION = '0.09';
use strict;
use warnings;
use base qw/Class::Accessor::Fast/;

use Algorithm::Diff 1.19;
eval q{ use Algorithm::Diff::XS; };


__PACKAGE__->mk_accessors(qw/added deleted count diff_class/);

=head1 NAME

Array::Diff - Find the differences between two arrays

=head1 SYNOPSIS

    my @old = ( 'a', 'b', 'c' );
    my @new = ( 'b', 'c', 'd' );

    my $diff = Array::Diff->diff( \@old, \@new );

    $diff->count   # 2
    $diff->added   # [ 'd' ];
    $diff->deleted # [ 'a' ];

=head1 DESCRIPTION

This module compares two B arrays
and returns the added or deleted elements in two separate arrays.
It's a simple wrapper around L.

B: the arrays must be sorted before you call C.

And if you need more complex array tools, check L.

=head1 METHODS

=over 4

=item new ()

Create a new C object.

=cut

sub new {
    my $self = shift->SUPER::new(@_);

    $self->{diff_class} ||= $INC{'Algorithm/Diff/XS.pm'} ? 'Algorithm::Diff::XS' : 'Algorithm::Diff';

    $self;
}

=item diff ( OLD, NEW )

Compute the differences between two arrays.  The results are stored
in the C, C, and C properties that may be
examined using the corresponding methods.

This method may be invoked as an object method, in which case it will
recalculate the differences and repopulate the C, C, and
C properties, or as a static method, in which case it will
return a newly-created C object with the properties
set appropriately.

=cut

sub diff {
    my ( $self, $old, $new ) = @_;
    $self = $self->new unless ref $self;

    $self->added(   [] );
    $self->deleted( [] );
    $self->count( 0 );

    my $diff = $self->diff_class->new( $old, $new );
    while ( $diff->Next ) {
        next if $diff->Same;

        my @deleted = $diff->Items(1);
        my @added = $diff->Items(2);

        $self->{count} += @added + @deleted;
        push @{$self->{deleted}}, @deleted if @deleted;
        push @{$self->{added}}, @added if @added;
    }

    $self;
}

=item added ( [VALUES ] )

Get or set the elements present in the C array and absent in
the C one at the comparison performed by the last C
invocation.

=item deleted ( [VALUES] )

Get or set the elements present in the C array and absent in
the C one at the comparison performed by the last C
invocation.

=item count ( [VALUE] )

Get or set the total number of added or deleted elements at
the comparison performed by the last C invocation.
This count should be equal to the sum of the number of elements in
the C and C properties.

=back

=head1 SEE ALSO

L - performs the same function as this module,
but has options for controlling how it works.

L - similar functionality, but again with more options.

L - the underlying implementation of the diff algorithm.
If you've got L installed, that will be used.

L - find difference between two YAML documents.

L - find difference between two HTML documents.
This uses a more sane approach than L.

L - find difference between two XML documents.

L - find the differences between two Perl hashes.

L - find difference between two arbitrary data structures.

L - can find difference between two inputs, which can be
data structures or file names.

=head1 AUTHOR

Daisuke Murase

=head1 COPYRIGHT AND LICENSE

Copyright (c) 2009 by Daisuke Murase.

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

The full text of the license can be found in the
LICENSE file included with this module.

=cut

1;