.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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 "2022-10-20" "perl v5.36.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
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::Utils
package.
See PDL::Ngrams::Utils 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
At the time of this module's writing, I was unable to figure out how to
use the (then undocumented) \s-1PDL::PP\s0 macro expansion mechanism.
As of 2022, \s-1PDL::PP\s0 offers support for user-defined macros, and
this module should be refactored to take advantage of that... but that
hasn't happened yet.
.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\-2022, 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).