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 comparsion 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 comparsion 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 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::ngutils package. See PDL::Ngrams::ngutils 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().

Unfortunately, I don't currently have the time to figure out how to use the (undocumented) PDL::PP macro expansion mechanism. Feel free to add real macro support.

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-2015, 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).

cpanm PDL::VectorValued

perl -MCPAN -e shell
install PDL::VectorValued