package Audio::TagLib::ByteVector;

use 5.008003;
use strict;
use warnings;

our $VERSION = '1.1';

use Audio::TagLib;

sub _to_array {

    # This has a shortingcoming
    # index out of bound will not croak
    my $this   = shift;
    my $vector = $this->data();
    return [] if $vector eq q{};
    return [ map { substr $vector, $_, 1 } ( 0 .. length($vector) - 1 ) ];
}

use overload
    q(@{}) => \&_to_array,
    q(==)  => \&_equal,
    q(eq)  => \&_equal,
    q(!=)  => sub { not shift->_equal(@_); },
    q(ne)  => \&_notEqual,
    q(<)   => \&_lessThan,
    q(lt)  => \&_lessThan,
    q(>)   => \&_greatThan,
    q(gt)  => \&_greatThan,
    q(+)   => \&_add,
    q("")  => sub { shift->_memoAddress(); };

1;
__END__

=pod

=begin stopwords

Dongxu

=end stopwords

=head1 NAME

Audio::TagLib::ByteVector - A byte vector

=head1 SYNOPSIS

  use Audio::TagLib::ByteVector;
  
  my $i = Audio::TagLib::ByteVector->new();
  $i->setData("blah blah blah");
  print $i->data(), "\n"; # got "blah blah blah"

=head1 DESCRIPTION

This class provides a byte vector with some methods that are useful
for tagging purposes.  Many of the search functions are tailored to
what is useful for finding tag related paterns in a data array. 

=over

=item I<new()>

Constructs an empty byte vector.

=item I<new(UV $size, PV $value = 0)>

Construct a vector of size $size with all values set to $value by
default. 

=item I<new(L<ByteVector|Audio::TagLib::ByteVector> $v)>

Contructs a byte vector that is a copy of $v.

=item I<new(PV $data)>

Contructs a byte vector that contains $data if length($data) is 1.

Constructs a byte vector that copies $data up to the first null  byte.
The behavior is undefined if $data is not null terminated. This is
particularly useful for constructing byte arrays from string
constants. 

=item I<new(PV $data, IV $length)>

Constructs a byte vector that copies $data for up to $length bytes.

=item I<DESTROY()>

Destroys this ByteVector instance.

=item I<void setData(PV $data, UV $length)>

Sets the data for the byte array using the first $length bytes of
$data. 
Note: Use without updating size
should be used with caution since this effects the behavior of other
methods such as at & clear & resize

=item I<void setData(PV $data)>

Sets the data for the byte array copies $data up to the first null
byte.  The behavior is undefined if \a data is not null terminated. 
Note: Use without updating size
should be used with caution since this effects the behavior of other
methods such as at & clear & resize

=item I<PV data()>

Returns a copy to the internal data structure.

=item I<L<ByteVector|Audio::TagLib::ByteVector> mid(UV $index, UV $length =
0xffffffff)> 

Returns a byte vector made up of the bytes starting at $index and for
$length bytes. If $length is not specified it will return the bytes
from $index  to the end of the vector.

=item I<PV at(UV $index)>

Returns a char at the specific $index. If the index is out of bounds,
it will return a null byte. 

=item I<IV find(L<ByteVector|Audio::TagLib::ByteVector> $pattern, UV $offset
= 0, IV $byteAlign = 1)>

Searches the ByteVector for $pattern starting at $offset  and returns
the offset. Returns -1 if the pattern was not found.  If $byteAlign is
specified the pattern will only be matched if it starts on a
byteDivisible by $byteAlign.

=item I<IV rfind(L<ByteVector|Audio::TagLib::ByteVector> $pattern, UV $offset
= 0, IV $byteAlign = 1)>

Searches the ByteVector for $pattern starting from either the end of
 the vector or $offset and returns the offset.  Returns -1 if the
 pattern was not found.  If $byteAlign is specified the pattern will
 only be matched if it starts on a byteDivisible by $byteAlign.

=item I<BOOL containsAt(L<ByteVector|Audio::TagLib::ByteVector> $pattern, UV
$offset, UV $patternOffset = 0, UV $patternLength = Oxffffffff)>

Checks to see if the vector contains the $pattern starting at position
$offset. Optionally, if you only want to search for part of the
pattern you can specify an offset within the pattern to start from.
Also, you can specify to only check for the first $patternLength bytes
of $pattern with the $patternLength argument.

=item I<BOOL startsWith(L<ByteVector|Audio::TagLib::ByteVector> $pattern)>

Returns true if the vector starts with $pattern.

=item I<BOOL endsWith(L<ByteVector|Audio::TagLib::ByteVector> $pattern)>

Returns true if the vector ends with $pattern.

=item I<IV endsWithPartialMatch(L<ByteVector|Audio::TagLib::ByteVector>
$pattern)> 

Checks for a partial match of $pattern at the end of the vector. It
returns the offset of the partial match within the vector, or -1 if
the pattern is not found.  This method is particularly useful when
searching for patterns that start in one vector and end in another.
When combined with startsWith() it can be used to find a pattern that
overlaps two buffers. 

note This will not match the complete pattern at the end of the
 string; use endsWith() for that.

=item I<void append(L<ByteVector|Audio::TagLib::ByteVector> $v)>

 Appends $v to the end of the ByteVector.

=item I<void clear()>

Clears the data.

=item I<UV size()>

Returns the size of the array.

=item I<L<ByteVector|Audio::TagLib::ByteVector> resize(UV $size, PV padding =
0)>

Resize the vector to $size. If the vector is currently less than
$size, pad the remaining spaces with $padding. Returns a reference to
the resized vector.

=item I<L<Iterator|Audio::TagLib::ByteVector::Iterator> begin()>

Returns an Iterator that points to the front of the vector.

=item I<L<Iterator|Audio::TagLib::ByteVector::Iterator> end()>

Returns an Iterator that points to the back of the vector.

=item I<BOOL isNull()>

Returns true if the vector is null.

note A vector may be empty without being null.

see I<isEmpty()>

=item I<BOOL isEmpty()>

Returns true if the ByteVector is empty.

see I<size()>
see I<isNull()>

=item I<UV checksum()>

Returns a CRC checksum of the byte vector's data.

=item I<UV toUInt(BOOL $mostSignificantByteFirst = true)>

Converts the first 4 bytes of the vector to an unsigned integer.

If $mostSignificantByteFirst is true this will operate left to right
evaluating the integer.  For example if $mostSignificantByteFirst is
true then $00 $00 $00 $01 == 0x00000001 == 1, if false, $01 00 00 00
== 0x01000000 == 1.

see I<fromUInt()>

=item I<IV toShort(BOOL $mostSignificantByteFirst = true)>

Converts the first 2 bytes of the vector to a short.

If $mostSignificantByteFirst is true this will operate left to right
  evaluating the integer.  For example if $mostSignificantByteFirst is
  true then $00 $01 == 0x0001 == 1, if false, $01 00 == 0x01000000 ==
  1. 

see I<fromShort()>

=item I<IV toLongLong(BOOL $mostSignificantByteFirst = true)>

Converts the first 8 bytes of the vector to a (signed) long long. 

If $mostSignificantByteFirst is true this will operate left to right
  evaluating the integer.  For example if $mostSignificantByteFirst is
  true then $00 00 00 00 00 00 00 01 == 0x0000000000000001 == 1, if
  false, $01 00 00 00 00 00 00 00 == 0x0100000000000000 == 1.

see I<fromUInt()>

=item I<L<ByteVector|Audio::TagLib::ByteVector> fromUInt(UV $value, BOOL
$mostSignificantByteFirst = true)> [static]

Creates a 4 byte ByteVector based on $value. If
$mostSignificantByteFirst is true, then this will operate left to
right in building the ByteVector.  For example if
$mostSignificantByteFirst is  true then $00 00 00 01 == 0x00000001 ==
1, if false, $01 00 00 00 == 0x01000000 == 1.

see I<toUInt()>

=item I<L<ByteVector|Audio::TagLib::ByteVector> fromShort(IV $value, BOOL
$bool mostSignificantByteFirst = true)> [static]

Creates a 2 byte ByteVector based on $value. If
  $mostSignificantByteFirst is true, then this will operate left to
  right in building the ByteVector.  For example if
  $mostSignificantByteFirst is true then $00 01 == 0x0001 == 1, if
  false, $01 00 == 0x0100 == 1. 

see I<toShort()>

=item I<L<ByteVector|Audio::TagLib::ByteVector> fromLongLong(IV $value, BOOL
$mostSignificantByteFirst = true)> [static]

Creates a 8 byte ByteVector based on $value. If
$mostSignificantByteFirst is true, then this will operate left to
right in building the ByteVector.  For example if
$mostSignificantByteFirst is true then $00 00 00 01 ==
0x0000000000000001 == 1, if false, $01 00 00 00 00 00 00 00 ==
0x0100000000000000 == 1. 

see I<toLongLong()>

=item I<L<ByteVector|Audio::TagLib::ByteVector> fromCString(PV $s, UV $length
= 0xffffffff)> [static]

Returns a ByteVector based on the CString $s.

=item I<void setItem(IV $index, PV $c)>

Sets the char at $index to $c.

=item I<copy(L<ByteVector|Audio::TagLib::ByteVector> $v)>

Inplements operator=. 

=item I<L<ByteVector|Audio::TagLib::ByteVector> null()> [static]

Returns the static object Audio::TagLib::ByteVector::null.

=back

=head2 OVERLOADED OPERATORS

B<@{} == eq != ne < lt > gt + "">

=head2 EXPORT

None by default.



=head1 SEE ALSO

L<Audio::TagLib|Audio::TagLib>

=head1 AUTHOR

Dongxu Ma, E<lt>dongxu@cpan.orgE<gt>

=head1 MAINTAINER

Geoffrey Leach GLEACH@cpan.org

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2005-2010 by Dongxu Ma

Copyright (C) 2011 - 2013 Geoffrey Leach


This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.7 or,
at your option, any later version of Perl 5 you may have available.


=cut