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

perl v5.38.2                                       2024-03-31                                           Dev(3pm)