.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Statistics::Basic::ComputedVector 3pm"
.TH Statistics::Basic::ComputedVector 3pm "2012-01-23" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Statistics::Basic::ComputedVector \- a class for computing filtered vectors
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Invoke it this way:
.PP
.Vb 5
\&    my $vector   = vector(1,2,3);
\&    my $computed = computed($vector)\->set_filter(sub{
\&        # NOTE: only interested in even numbers:
\&        grep { !($_ % 2) } @_
\&    });
\&
\&    # nearly the same, opposite order:
\&
\&    my $computed = computed(1,2,3)\->set_filter(sub {map{$_+1}@_});
\&    my $vector   = $computed\->query_vector;
.Ve
.SH "METHODS"
.IX Header "METHODS"
.IP "\fB\f(BInew()\fB\fR" 4
.IX Item "new()"
The constructor takes a single array ref or a single
Statistics::Basic::ComputedVector as its argument.  It returns a
Statistics::Basic::ComputedVector object.
.Sp
If passed arguments other than Statistics::Basic::Vector objects, the
constructor will built an appropriate vector object \*(-- which can be queried with
\&\*(L"\fIquery_vector()\fR\*(R"
.Sp
Note: normally you'd use the \fIcomputed()\fR
constructor, rather than building these by hand using \f(CW\*(C`new()\*(C'\fR.
.IP "\fB\f(BIcopy()\fB\fR" 4
.IX Item "copy()"
Creates a new computed vector object referring to the same source vector and
using the same filter as this one.
.Sp
.Vb 2
\&    my $v1 = vector(1,2,3);
\&    my $c1 = computed($v1); $c1\->set_filter(my $s = sub {});
\&
\&    my $copy1 = computed($v1); $copy1\->set_filter($s);
\&    my $copy2 = $c1\->copy; # just like $c2, but in one step
.Ve
.Sp
To instead create a filtered version of a filtered vector, choose this form:
.Sp
.Vb 3
\&    my $v1 = vector(1,2,3);
\&    my $c1 = computed($v1); $c1\->set_filter(sub {});
\&    my $c2 = computed($c1); $c2\->set_filter(sub {});
.Ve
.IP "\fB\f(BIinsert()\fB\fR" 4
.IX Item "insert()"
Insert new values into the input vector.  If the vector was already full (see
\&\*(L"\fIset_size()\fR\*(R"), this will also shift oldest elements from the input vector to
compensate.
.Sp
.Vb 1
\&    $computed\->insert( 4, 3 ); # insert a 3 and a 4
.Ve
.Sp
Note that continuing from the \*(L"\s-1SYNOPSIS\s0\*(R" example, this would certainly insert
a 4 and a 3 into the input vector, but the 3 wouldn't be returned from a
\&\*(L"\fIquery()\fR\*(R" because it is odd.
.Sp
This function returns the object itself, for chaining purposes.
.IP "\fB\f(BIappend()\fB\fR \fB\f(BIginsert()\fB\fR" 4
.IX Item "append() ginsert()"
Insert new values into the input vector.  If the vector was already full (see
\&\*(L"\fIset_size()\fR\*(R"), these functions will grow the size of the input vector to
accommodate the new values, rather than shifting things.
.Sp
.Vb 1
\&    $computed\->append( 4, 3 ); # append a 3 and a 4
.Ve
.Sp
Note that continuing from the \*(L"\s-1SYNOPSIS\s0\*(R" example, this would certainly insert
a 4 and a 3 into the input vector, but the 3 wouldn't be returned from a
\&\*(L"\fIquery()\fR\*(R" because it is odd.
.Sp
This function returns the object itself, for chaining purposes.
.IP "\fB\f(BIquery()\fB\fR" 4
.IX Item "query()"
\&\f(CW\*(C`query()\*(C'\fR returns the contents of the computed vector (after filtering) either
as a list or as an arrayref.
.Sp
.Vb 2
\&    my @copy_of_contents      = $computed\->query;
\&    my $reference_to_contents = $computed\->query;
.Ve
.Sp
Note that changing the \f(CW$reference_to_contents\fR will not usefully affect the
contents of the vector itself, but it will adversely affect any computations
based on the vector.  If you need to change the contents of a vector in a
special way, use another Statistics::Basic::ComputedVector object instead.
.Sp
Keeping \f(CW$reference_to_contents\fR available long term should work acceptably
(since it refers to the vector contents itself).
.IP "\fB\f(BIquery_vector()\fB\fR" 4
.IX Item "query_vector()"
Return the input Statistics::Basic::Vector object.
.IP "\fB\f(BIquery_filled()\fB\fR" 4
.IX Item "query_filled()"
This returns true when the input vector is full (see
\&\*(L"\fIquery_filled()\fR\*(R" in Statistics::Basic::Vector).  This is of questionable
usefulness on computed vectors, but is provided for completeness (and internal
package consistency).
.IP "\fB\f(BIquery_size()\fB\fR" 4
.IX Item "query_size()"
Return the current size of the computed vector.
.IP "\fB\f(BIset_filter()\fB\fR" 4
.IX Item "set_filter()"
Set the filtering for the computed vector.  This function takes a single coderef
argument \*(-- all other arguments will be ignored.  The elements of the input
vector are passed to your filter coderef in \f(CW@_\fR and your ref should return the
calculated elements of the computed vector as a list.
.Sp
.Vb 3
\&    my $vec = vector(1,2,3);
\&    my $pow = computed($vec);
\&       $pow\->set_filter(sub { return map { $_ ** 2 } @_ })
.Ve
.Sp
If you need to call more than one filter function, concatenate them together
using map or an anonymous sub.
.Sp
.Vb 1
\&    $pow\->set_filter(sub { return f1(f2(f3(f4(@_)))) });
.Ve
.Sp
This function returns the object itself, for chaining purposes.
.IP "\fB\f(BIset_size()\fB\fR" 4
.IX Item "set_size()"
Set the size of the input vector (not the computed vector, that would make
little sense).
.Sp
This function returns the object itself, for chaining purposes.
.IP "\fB\f(BIset_vector()\fB\fR" 4
.IX Item "set_vector()"
Set the contents of the input vector (not the computed one).
.Sp
This function returns the object itself, for chaining purposes.
.SH "OVERLOADS"
.IX Header "OVERLOADS"
This object is overloaded.  It tries to return an appropriate string for the
vector and raises errors in numeric context.
.PP
In boolean context, this object is always true (even when empty).
.SH "AUTHOR"
.IX Header "AUTHOR"
Paul Miller \f(CW\*(C`<jettero@cpan.org>\*(C'\fR
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2012 Paul Miller \*(-- Licensed under the \s-1LGPL\s0
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIperl\fR\|(1), Statistics::Basic, Statistics::Basic::Vector