.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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" ''
.    ds C`
.    ds C'
'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 >0, 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Dev 3pm"
.TH Dev 3pm "2020-11-19" "perl v5.32.0" "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"
PDL::VectorValued::Dev \- development utilities for vector\-valued PDLs
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& use PDL;
\& use PDL::VectorValued::Dev;
\&
\& ##\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\& ## ... stuff happens
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
PDL::VectorValued::Dev provides some developer utilities for
vector-valued PDLs.  It produces code for processing with \s-1PDL::PP.\s0
.SH "PDL::PP Utilities"
.IX Header "PDL::PP Utilities"
.SS "vvpp_def($funcName,%args)"
.IX Subsection "vvpp_def($funcName,%args)"
Wrapper for \fBpp_def()\fR which calls \fBvvpp_expand()\fR on 'Code' and 'BadCode'
values in \f(CW%args\fR.
.ie n .SS "$pp_code = vvpp_expand($vvpp_code)"
.el .SS "\f(CW$pp_code\fP = vvpp_expand($vvpp_code)"
.IX Subsection "$pp_code = vvpp_expand($vvpp_code)"
Expand PDL::VectorValued macros in \f(CW$vvpp_code\fR.
Currently known PDL::VectorValued macros include:
.PP
.Vb 5
\&  MACRO_NAME            EXPANSION_SUBROUTINE
\&  \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&  $CMPVEC(...)          vvpp_expand_cmpvec(...)
\&  $CMPVAL(...)          vvpp_expand_cmpval(...)
\&  $LB(...)              vvpp_expand_lb(...)
.Ve
.PP
See the documentation of the individual expansion subroutines
for details on calling conventions.
.PP
You can add your own expansion macros by pushing an expansion
manipulating the array
.PP
.Vb 1
\& @PDL::VectorValued::Dev::MACROS
.Ve
.PP
which is just a list of expansion subroutines which take a single
argument (string for Code or BadCode) and should return the expanded
string.
.SH "Type Utilities"
.IX Header "Type Utilities"
.SS "\fBvv_indx_sig()\fP"
.IX Subsection "vv_indx_sig()"
Returns a signature type for representing \s-1PDL\s0 indices.
For \s-1PDL\s0 >= v2.007 this should be \f(CW\*(C`PDL_Indx\*(C'\fR, otherwise it will be \f(CW\*(C`int\*(C'\fR.
.SS "\fBvv_indx_typedef()\fP"
.IX Subsection "vv_indx_typedef()"
Returns a C typedef for the \f(CW\*(C`PDL_Indx\*(C'\fR type if running under
\&\s-1PDL\s0 <= v2.007, otherwise just a comment.  You can call this
from client \s-1PDL::PP\s0 modules as
.PP
.Vb 1
\& pp_addhdr(PDL::VectorValued::Dev::vv_indx_typedef);
.Ve
.SH "Macro Expansion Utilities"
.IX Header "Macro Expansion Utilities"
.SS "vvpp_pdlvar_basename($pdlVarString)"
.IX Subsection "vvpp_pdlvar_basename($pdlVarString)"
Gets basename of a \s-1PDL::PP\s0 variable by removing leading '$'
and anything at or following the first open parenthesis:
.PP
.Vb 1
\& $base = vvpp_pdlvar_basename(\*(Aq$a(n=>0)\*(Aq); ##\-\- $base is now \*(Aqa\*(Aq
.Ve
.SS "vvpp_cmpvec_code($vec1,$vec2,$dimName,$retvar,%options)"
.IX Subsection "vvpp_cmpvec_code($vec1,$vec2,$dimName,$retvar,%options)"
Returns \s-1PDL::PP\s0 code for lexicographically comparing two vectors
\&\f(CW$vec1\fR and \f(CW$vec2\fR along the dimension named \f(CW$dim\fR, storing the
comparison result in the C variable \f(CW$retvar\fR,
similar to what:
.PP
.Vb 1
\& $retvar = ($vec1 <=> $vec2);
.Ve
.PP
\&\*(L"ought to\*(R" do.
.PP
Parameters:
.ie n .IP "$vec1" 4
.el .IP "\f(CW$vec1\fR" 4
.IX Item "$vec1"
.PD 0
.ie n .IP "$vec2" 4
.el .IP "\f(CW$vec2\fR" 4
.IX Item "$vec2"
.PD
\&\s-1PDL::PP\s0 string forms of vector PDLs to be compared.
Need not be physical.
.ie n .IP "$dimName" 4
.el .IP "\f(CW$dimName\fR" 4
.IX Item "$dimName"
Name of the dimension along which vectors should be compared.
.ie n .IP "$retvar" 4
.el .IP "\f(CW$retvar\fR" 4
.IX Item "$retvar"
Name of a C variable to store the comparison result.
.ie n .IP "$options{cvar1}" 4
.el .IP "\f(CW$options\fR{cvar1}" 4
.IX Item "$options{cvar1}"
.PD 0
.ie n .IP "$options{cvar2}" 4
.el .IP "\f(CW$options\fR{cvar2}" 4
.IX Item "$options{cvar2}"
.PD
If specified, temporary values for \f(CW$vec1\fR (rsp. \f(CW$vec2\fR)
will be stored in the C variable \f(CW$options\fR{cvar1} (rsp. \f(CW$options{cvar2}\fR).
If unspecified, a new locally scoped C variable
\&\f(CW\*(C`_vvpp_cmpvec_val1\*(C'\fR (rsp. \f(CW\*(C`_vvpp_cmpvec_val2\*(C'\fR) will be declared and used.
.PP
The \s-1PDL::PP\s0 code for \fBcmpvec()\fR looks something like this:
.PP
.Vb 9
\& use PDL::VectorValued::Dev;
\& pp_def(\*(Aqcmpvec\*(Aq,
\&        Pars => \*(Aqa(n); b(n); int [o]cmp()\*(Aq,
\&        Code => (
\&                 \*(Aqint cmpval;\*(Aq
\&                 .vvpp_cmpvec_code( \*(Aq$a()\*(Aq, \*(Aq$b()\*(Aq, \*(Aqn\*(Aq, \*(Aqcmpval\*(Aq )
\&                 .$cmp() = cmpval\*(Aq
\&                );
\&        );
.Ve
.SS "vvpp_cmpval_code($val1,$val2)"
.IX Subsection "vvpp_cmpval_code($val1,$val2)"
Returns \s-1PDL::PP\s0 expression code for lexicographically comparing two values
\&\f(CW$val1\fR and \f(CW$val2\fR, storing the
comparison result in the C variable \f(CW$retvar\fR,
similar to what:
.PP
.Vb 1
\& ($vec1 <=> $vec2);
.Ve
.PP
\&\*(L"ought to\*(R" do.
.PP
Parameters:
.ie n .IP "$val1" 4
.el .IP "\f(CW$val1\fR" 4
.IX Item "$val1"
.PD 0
.ie n .IP "$val2" 4
.el .IP "\f(CW$val2\fR" 4
.IX Item "$val2"
.PD
\&\s-1PDL::PP\s0 string forms of values to be compared.
Need not be physical.
.ie n .SS "vvpp_lb_code($find,$vals, $imin,$imax, $retvar, %options)"
.el .SS "vvpp_lb_code($find,$vals, \f(CW$imin\fP,$imax, \f(CW$retvar\fP, \f(CW%options\fP)"
.IX Subsection "vvpp_lb_code($find,$vals, $imin,$imax, $retvar, %options)"
Returns \s-1PDL::PP\s0 code for binary lower-bound search for the value $\fBfind()\fR in the sorted pdl \f(CW$val\fRs($imin:$imax\-1).
Parameters:
.ie n .IP "$find" 4
.el .IP "\f(CW$find\fR" 4
.IX Item "$find"
Value to search for or \s-1PDL::PP\s0 string form of such a value.
.ie n .IP "$vals" 4
.el .IP "\f(CW$vals\fR" 4
.IX Item "$vals"
\&\s-1PDL::PP\s0 string form of \s-1PDL\s0 to be searched. \f(CW$vals\fR should contain a placeholder \f(CW$_\fR
representing the dimension to be searched.
.ie n .IP "$retvar" 4
.el .IP "\f(CW$retvar\fR" 4
.IX Item "$retvar"
Name of a C variable to store the result.
On return, \f(CW$retvar\fR holds the maximum value for \f(CW$_\fR in \f(CW\*(C`$vals($imin:$imax\-1)\*(C'\fR such that
\&\f(CW\*(C`$vals($_=$retvar) <= $find\*(C'\fR and \f(CW\*(C`$vals($_=$j) < $find\*(C'\fR for all
\&\f(CW$j\fR with \f(CW\*(C`$imin <= $j < $retvar\*(C'\fR, or \f(CW$imin\fR if no such value for \f(CW$retvar\fR exists,
\&\f(CW\*(C`$imin <= $retvar < $imax\*(C'\fR.
In other words,
returns the least index \f(CW$_\fR of a match for \f(CW$find\fR in \f(CW$val\fRs($imin:$imax\-1) whenever a match exists,
otherwise the greatest index whose value in \f(CW$val\fRs($imin:$imax\-1) is strictly less than \f(CW$find\fR if that exists,
and \f(CW$imin\fR if all values in \f(CW$val\fRs($imin:$imax\-1) are strictly greater than \f(CW$find\fR.
.ie n .IP "$options{lovar}" 4
.el .IP "\f(CW$options\fR{lovar}" 4
.IX Item "$options{lovar}"
.PD 0
.ie n .IP "$options{hivar}" 4
.el .IP "\f(CW$options\fR{hivar}" 4
.IX Item "$options{hivar}"
.ie n .IP "$options{midvar}" 4
.el .IP "\f(CW$options\fR{midvar}" 4
.IX Item "$options{midvar}"
.ie n .IP "$options{cmpvar}" 4
.el .IP "\f(CW$options\fR{cmpvar}" 4
.IX Item "$options{cmpvar}"
.PD
If specified, temporary indices and comparison values will be stored in
in the C variables \f(CW$options\fR{lovar}, \f(CW$options\fR{hivar}, \f(CW$options\fR{midvar}, and \f(CW$options\fR{cmpvar}.
If unspecified, new locally scoped C variables
\&\f(CW\*(C`_vvpp_lb_loval\*(C'\fR etc. will be declared and used.
.ie n .IP "$options{ubmaxvar}" 4
.el .IP "\f(CW$options\fR{ubmaxvar}" 4
.IX Item "$options{ubmaxvar}"
If specified, should be a C variable to hold the index of the last inspected value for \f(CW$_\fR
in \f(CW$val\fRs($imin:$imax\-1) strictly greater than \f(CW$find\fR.
.SS "Low-Level Functions"
.IX Subsection "Low-Level Functions"
Some additional low-level functions are provided in the
PDL::Ngrams::ngutils
package.
See PDL::Ngrams::ngutils for details.
.SH "KNOWN BUGS"
.IX Header "KNOWN BUGS"
.SS "Why not \s-1PDL::PP\s0 macros?"
.IX Subsection "Why not PDL::PP macros?"
All of these functions would be more intuitive if implemented directly
as \s-1PDL::PP\s0 macros, and thus expanded directly by \fBpp_def()\fR rather
than requiring \fBvvpp_def()\fR.
.PP
Unfortunately, I don't currently have the time to figure out how to
use the (undocumented) \s-1PDL::PP\s0 macro expansion mechanism.
Feel free to add real macro support.
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
perl by Larry Wall.
.SH "AUTHOR"
.IX Header "AUTHOR"
Bryan Jurish <moocow@cpan.org>
.PP
\&\s-1PDL\s0 by Karl Glazebrook, Tuomas J. Lukka, Christian Soeller, and others.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2007\-2015, Bryan Jurish.  All rights reserved.
.PP
This package is free software.  You may redistribute it
and/or modify it under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBperl\fR\|(1), \s-1\fBPDL::PP\s0\fR\|(3perl).