oracular (3) PDL::VectorValued::Dev.3pm.gz
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
$vals($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 $vals($imin:$imax-1)
whenever a match exists, otherwise the greatest index whose value in $vals($imin:$imax-1) is strictly
less than $find if that exists, and $imin if all values in $vals($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
$vals($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 <moocow@cpan.org> 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), PDL::PP(3perl).