--- name: "PDL::VectorValued::Dev" section: "3pm" platform: "linux" package: "libpdl-vectorvalued-perl" version: "1.0.23-1+b1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/PDL::VectorValued::Dev" --- # PDL::VectorValued::Dev(3pm) development utilities for vector-valued PDLs ## NAME PDL::VectorValued::Dev - development utilities for vector-valued PDLs ## SYNOPSIS ``` use PDL; use PDL::VectorValued::Dev; ##--------------------------------------------------------------------- ## ... stuff happens ``` ## DESCRIPTION PDL::VectorValued::Dev provides some developer utilities for vector-valued PDLs. It produces code for processing with PDL::PP. ## PDL::PP Utilities ### vvpp\_def($funcName,%args) Wrapper for **pp\_def()** which calls **vvpp\_expand()** on 'Code' and 'BadCode' values in `%args`. ### $pp\_code = vvpp\_expand($vvpp\_code) Expand PDL::VectorValued macros in `$vvpp_code`. Currently known PDL::VectorValued macros include: ``` MACRO_NAME EXPANSION_SUBROUTINE ---------------------------------------------------------------------- $CMPVEC(...) vvpp_expand_cmpvec(...) $CMPVAL(...) vvpp_expand_cmpval(...) $LB(...) vvpp_expand_lb(...) ``` See the documentation of the individual expansion subroutines for details on calling conventions. You can add your own expansion macros by pushing an expansion manipulating the array ``` @PDL::VectorValued::Dev::MACROS ``` which is just a list of expansion subroutines which take a single argument (string for Code or BadCode) and should return the expanded string. ## Type Utilities ### vv\_indx\_sig() Returns a signature type for representing PDL indices. For PDL \>= v2.007 this should be `"PDL_Indx"`, otherwise it will be `"int"`. ### vv\_indx\_typedef() Returns a C typedef for the `"PDL_Indx"` type if running under PDL \<= v2.007, otherwise just a comment. You can call this from client PDL::PP modules as ``` pp_addhdr(PDL::VectorValued::Dev::vv_indx_typedef); ``` ## Macro Expansion Utilities ### vvpp\_pdlvar\_basename($pdlVarString) Gets basename of a PDL::PP variable by removing leading '$' and anything at or following the first open parenthesis: ``` $base = vvpp_pdlvar_basename('$a(n=>0)'); ##-- $base is now 'a' ``` ### vvpp\_cmpvec\_code($vec1,$vec2,$dimName,$retvar,%options) Returns PDL::PP code for lexicographically comparing two vectors `$vec1` and `$vec2` along the dimension named `$dim`, storing the comparison result in the C variable `$retvar`, similar to what: ``` $retvar = ($vec1 <=> $vec2); ``` "ought to" do. Parameters: - $vec1 - $vec2 PDL::PP string forms of vector PDLs to be compared. Need not be physical. - $dimName Name of the dimension along which vectors should be compared. - $retvar Name of a C variable to store the comparison result. - $options{cvar1} - $options{cvar2} If specified, temporary values for `$vec1` (rsp. `$vec2`) will be stored in the C variable `$options`{cvar1} (rsp. `$options{cvar2}`). If unspecified, a new locally scoped C variable `"_vvpp_cmpvec_val1"` (rsp. `"_vvpp_cmpvec_val2"`) will be declared and used. The PDL::PP code for **cmpvec()** looks something like this: ``` use PDL::VectorValued::Dev; pp_def('cmpvec', Pars => 'a(n); b(n); int [o]cmp()', Code => ( 'int cmpval;' .vvpp_cmpvec_code( '$a()', '$b()', 'n', 'cmpval' ) .$cmp() = cmpval' ); ); ``` ### vvpp\_cmpval\_code($val1,$val2) Returns PDL::PP expression code for lexicographically comparing two values `$val1` and `$val2`, storing the comparison result in the C variable `$retvar`, similar to what: ``` ($vec1 <=> $vec2); ``` "ought to" do. Parameters: - $val1 - $val2 PDL::PP string forms of values to be compared. Need not be physical. ### vvpp\_lb\_code($find,$vals, $imin,$imax, $retvar, %options) Returns PDL::PP code for binary lower-bound search for the value $**find()** in the sorted pdl `$val`s($imin:$imax-1). Parameters: - $find Value to search for or PDL::PP string form of such a value. - $vals PDL::PP string form of PDL to be searched. `$vals` should contain a placeholder `$_` representing the dimension to be searched. - $retvar Name of a C variable to store the result. On return, `$retvar` holds the maximum value for `$_` in `$vals($imin:$imax-1)` such that `"$vals($_=$retvar) <= $find"` and `"$vals($_=$j) < $find"` for all `$j` with `"$imin <= $j < $retvar"`, or `$imin` if no such value for `$retvar` exists, `"$imin <= $retvar < $imax"`. In other words, returns the least index `$_` of a match for `$find` in `$val`s($imin:$imax-1) whenever a match exists, otherwise the greatest index whose value in `$val`s($imin:$imax-1) is strictly less than `$find` if that exists, and `$imin` if all values in `$val`s($imin:$imax-1) are strictly greater than `$find`. - $options{lovar} - $options{hivar} - $options{midvar} - $options{cmpvar} If specified, temporary indices and comparison values will be stored in the C variables `$options`{lovar}, `$options`{hivar}, `$options`{midvar}, and `$options`{cmpvar}. If unspecified, new locally scoped C variables `"_vvpp_lb_loval"` etc. will be declared and used. - $options{ubmaxvar} If specified, should be a C variable to hold the index of the last inspected value for `$_` in `$val`s($imin:$imax-1) strictly greater than `$find`. ### Low-Level Functions Some additional low-level functions are provided in the PDL::Ngrams::Utils package. See PDL::Ngrams::Utils for details. ## KNOWN BUGS ### 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 **pp\_def()** rather than requiring **vvpp\_def()**. 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. ## ACKNOWLEDGEMENTS perl by Larry Wall. ## AUTHOR Bryan Jurish \ PDL by Karl Glazebrook, Tuomas J. Lukka, Christian Soeller, and others. ## COPYRIGHT Copyright (c) 2007-2022, Bryan Jurish. All rights reserved. This package is free software. You may redistribute it and/or modify it under the same terms as Perl itself. ## SEE ALSO [**perl**(1)](/perl/1.md), **PDL::PP**(3perl).