.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 2024-03-07 "perl v5.38.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
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 PDL::PP.
.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 PDL indices.
For PDL >= 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
PDL <= v2.007, otherwise just a comment.  You can call this
from client PDL::PP 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 PDL::PP 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 PDL::PP 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
"ought to" 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
PDL::PP 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 PDL::PP 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 PDL::PP 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
"ought to" 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
PDL::PP 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 PDL::PP 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 PDL::PP string form of such a value.
.ie n .IP $vals 4
.el .IP \f(CW$vals\fR 4
.IX Item "$vals"
PDL::PP string form of PDL 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$vals($imin:$imax\-1)\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 PDL::PP macros?"
.IX Subsection "Why not PDL::PP macros?"
All of these functions would be more intuitive if implemented directly
as PDL::PP 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) PDL::PP macro expansion mechanism.
As of 2022, PDL::PP 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
PDL 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), \fBPDL::PP\fR\|(3perl).