Dev(3pm)

📦
version 1.0.23 · 6 versions
, in ubuntu stonking

💖 Dev(3pm) 💖

okay bestie, welcome to Dev from the 3pm manual section — the user-contributed Perl docs corner. this one's called PDL::VectorValued::Dev and it's giving ✨developer utilities✨. buckle up, we're going in 🫶

✨ NAME ✨

PDL::VectorValued::Dev — development utilities for vector-valued PDLs 🦋

✨ SYNOPSIS ✨

use PDL;
use PDL::VectorValued::Dev;

##---------------------------------------------------------------------
## ... stuff happens

✨ DESCRIPTION ✨

PDL::VectorValued::Dev hooks you up with some developer utilities for vector-valued PDLs. the whole vibe? it produces code for processing with PDL::PP. that's the assignment, and it ate 💅

🌈 PDL::PP Utilities

🎀 vvpp_def($funcName,%args)

it's a wrapper for pp_def() — but make it cute. it calls vvpp_expand() on the 'Code' and 'BadCode' values inside %args. periodt.

🎀 $pp_code = vvpp_expand($vvpp_code)

expands PDL::VectorValued macros inside $vvpp_code. the currently known PDL::VectorValued macros are, and I'm quoting exactly:

MACRO_NAME            EXPANSION_SUBROUTINE
----------------------------------------------------------------------
$CMPVEC(...)          vvpp_expand_cmpvec(...)
$CMPVAL(...)          vvpp_expand_cmpval(...)
$LB(...)              vvpp_expand_lb(...)

peep the docs for each individual expansion subroutine for the deets on calling conventions, iykyk.

and bestie — you can add your own expansion macros! just push an expansion onto the array

@PDL::VectorValued::Dev::MACROS

it's literally just a list of expansion subroutines. each one takes a single argument (a string for Code or BadCode) and should return the expanded string. no cap 🔥

🌈 Type Utilities

🎀 vv_indx_sig()

returns a signature type for representing PDL indices. for PDL >= v2.007 this should be "PDL_Indx", otherwise it'll be "int". simple as that 💜

🎀 vv_indx_typedef()

returns a C typedef for the "PDL_Indx" type if you're running under PDL <= v2.007, otherwise it's just a comment. you can call this from client PDL::PP modules like:

pp_addhdr(PDL::VectorValued::Dev::vv_indx_typedef);

🌈 Macro Expansion Utilities

🎀 vvpp_pdlvar_basename($pdlVarString)

gets the basename of a PDL::PP variable by removing the leading '$' and anything at or following the first open parenthesis:

$base = vvpp_pdlvar_basename('$a(n=>0)'); ##-- $base is now 'a'

slay 🍓

🎀 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. 💀 (yes the quotes are doing a lot of work there, that's the original energy, we respect it)

Parameters:

  • $vec1
  • $vec2

PDL::PP string forms of the vector PDLs to be compared. they 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 in.

  • $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 the values to be compared. need not be physical. 🦋

🎀 vvpp_lb_code($find,$vals, $imin,$imax, $retvar, %options)

returns PDL::PP code for a binary lower-bound search for the value $find() in the sorted pdl $vals($imin:$imax-1). 🔍

Parameters:

  • $find

value to search for, or the PDL::PP string form of such a value.

  • $vals

PDL::PP string form of the 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 (and this is the icon itself): it 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. that's the whole bit. 👑

  • $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. go peek, bestie 📚

💀 KNOWN BUGS 💀

🎀 Why not PDL::PP macros?

okay so — all of these functions would be way more intuitive if they were implemented directly as PDL::PP macros, and thus expanded directly by pp_def() rather than requiring vvpp_def(). objectively the better design, no notes.

buuut at the time of this module's writing, the author 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. 💀 the "should" is doing a lot of hopeful heavy lifting and we love that for it.

ngl this is the most relatable bug note in the entire CPAN. "I could fix it, it should be fixed, it is not fixed." iconic behavior fr fr 🙈

🌸 ACKNOWLEDGEMENTS 🌸

perl by Larry Wall. 🫶

👑 AUTHOR 👑

Bryan Jurish <moocow@cpan.org>

PDL by Karl Glazebrook, Tuomas J. Lukka, Christian Soeller, and others. legends only 💜

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 🦋

and that's a wrap bestie!! 🎉 this whole page came straight out of perl v5.42.3, dated 2026-08-21, and it's filed under Dev(3pm) in your friendly neighborhood user-contributed Perl documentation. go write some macros. or don't. either way, you understood it, and that's the main character moment. bye babe 💅✨🌈

📦 where this page comes from