# PDL::Core

📦 stdpdl

Option B architecture: every PDL SV stores a `*mut c_pdl` in PERL_MAGIC_ext. All functions operate directly on c_pdl pointers via core_vtable — no rust_pdl. ## Functions ### Other Functions #### `pdl_new` `new($class?, @data)` #### `null` `null()` — create a null (typeless, dimensionless) PDL placeholder. #### `zeroes` `zeroes($class?, TYPE?, @dims)` — create a zero-filled PDL. #### `ones` `ones($class?, TYPE?, @dims)` — create a PDL filled with 1. #### `destroy` No-op destructor; magic vtable svt_free handles pdl_destroy. #### `get_dataref` `get_dataref($pdl)` — return a SCALAR ref to a byte buffer aliasing the pdl’s data. Mirrors `PDL::Core::get_dataref` from `Core.xs:1141-1156`. #### `upd_data` `upd_data($pdl, $keep_datasv=0)` — Perl wrote into the dataref; propagate back. Mirrors `PDL::Core::upd_data` from `Core.xs:1158-1182`. #### `update_data_from` `update_data_from($pdl, $sv)` — overwrite pdl buffer from an SV of bytes. Mirrors `PDL::Core::update_data_from` from `Core.xs:1184-1197`. #### `shape` `shape($pdl)` — return the ndarray’s dim-vector as a 1-D PDL of indx. #### `ndims` `ndims($pdl)` — return the number of dimensions. Also aliased as getndims(). Mirrors `Core.xs`:getndims — calls pdl_make_physdims first. #### `nelem` `nelem($pdl)` — return the total number of elements. Upstream `Core.xs`:nelem does make_physvaffine (not just physdims) for reasons unclear — we mirror exactly. #### [`at`](Core/at.md) `$pdl->at(@pos)` – return a single element of an ndarray as a Perl scalar. #### `set` `set($pdl, @indices, $value)` — set the element at the given indices. #### `list` `list($pdl)` — return all elements as a flat Perl list. Upstream `Core.xs`:list calls pdl_make_physvaffine before iterating. #### `unpdl` `unpdl($pdl)` — return nested arrayrefs matching the dim structure. e.g. pdl([[1,2],[3,4]])->unpdl returns [[1,2],[3,4]]. Mirrors `Core.xs`:unpdl — calls pdl_make_physvaffine first. #### `type` `type($pdl)` — return the PDL datatype as a string. `type($pdl)` — returns a `PDL::Type` blessed arrayref [`$enum`] Mirrors upstream: returns `PDL::Type` object that stringifies to lowercase name. #### `convert` `convert($pdl, $typecode)` — convert to a different datatype. #### `inplace` `inplace($pdl)` — set the inplace flag. Croaks if called as a class method (PDL->inplace) instead of on an object. #### `is_inplace` `is_inplace($pdl)` — check whether the inplace flag is set. #### `badflag` `badflag($pdl, $flag?)` — get or set the bad-value flag. #### `string` `string($pdl)` — return the PDL’s string representation. #### `barf` `barf(@msg)` — croak with the given error message. #### `copy` `copy($pdl)` — return a deep copy via pdl_hard_copy. #### `sclr` `sclr($pdl)` — return the first element as a plain Perl scalar. #### [`flowing`](Core/flowing.md) `flowing($pdl)` — no-op stub, returns self. `flowing($pdl)` — enable forward-flow dataflow on this pdl. Sets `PDL_DATAFLOW_F` on the state flags. Upstream `Core.pm` semantics: trans created from this pdl retain their link so parent changes cascade to children. #### `squeeze` `squeeze($pdl)` — remove size-1 dimensions. #### `info` `info($pdl)` — return a diagnostic string. #### `sever` `sever($pdl)` — break dataflow (no-op for physical pdls), return self. #### `cat` `cat($class?, @pdls)` — concatenate PDLs along a new trailing dimension. #### `dog` `dog($pdl)` — split along last dimension into a list of sub-PDLs. #### `empty` `empty($class?, TYPE?)` — create an empty PDL with dimension [0]. #### `dim` `dim($pdl, $n)` — return the size of dimension `$n`. #### `dimincs` `dimincs($pdl)` — return the list of stride increments. #### `isnull` `isnull($pdl)` — return 1 if the PDL is a null placeholder. #### `isempty` `isempty($pdl)` — return 1 if the PDL has zero elements. #### `is_readonly` `is_readonly($pdl)` — return whether the PDL is marked read-only. #### `set_readonly_on` `readonly($pdl)` — SET the read-only flag and return self. Upstream PDL: `$pdl->readonly` always sets the flag (no args needed). Distinct from is_readonly() which only reads the flag. #### `set_readonly` `set_readonly($pdl, $flag)` — set or clear the read-only flag. #### `make_physical` `make_physical($pdl)` — no-op for physical pdls, return self. #### `check_badflag` `nbad($pdl)` — count of bad values. Uses effective_badvalue_f64 to mirror upstream’s `has_badvalue ? pdl->badvalue : PDL.bvals[dtype]` lookup (`pdlcore.c:631` BADTRANS macro). `check_badflag($pdl)` — clear the badflag if no bad values are present. Mirrors `PDL::check_badflag` (`Bad.pm:262-266`). Returns the final badflag. #### `ngood` `ngood($pdl)` — count of good (non-bad) values. #### `nbadover_core` `nbadover($pdl)` — per-row bad-value count (reduces along first dimension). #### `ngoodover_core` `ngoodover($pdl)` — per-row good-value count. #### `set_badvalue` `set_badvalue($pdl, $val)` — set the bad-value sentinel. #### `get_badvalue` `get_badvalue($pdl)` — return the current bad-value sentinel. #### `set_datatype` `set_datatype($pdl, $typecode)` — set the ndarray’s datatype. Mirrors `Core.xs:997-1001` → `pdlapi.c:1022` `pdl_set_datatype`. For a NOMYDIMS (fresh-from-null) pdl, just assigns the datatype; otherwise converts the existing data. Used by `PDL::IO::Storable`’s thaw path. #### `set_donttouchdata` `set_donttouchdata($pdl, $size=-1)` — mark data as externally owned. Mirrors `Core.xs:481-489`. Sets `PDL_DONTTOUCHDATA`|`PDL_ALLOCATED` and optionally overrides nbytes. Used by set_data_by_file_map so that pdl_destroy won’t free() the mmap’d region. #### `setdims` `setdims($pdl, \@dims)` — set the ndarray’s dimensions in-place. Mirrors `Core.xs:1300-1305` → pdl_setdims(). The `dims` argument is an arrayref of integers. #### [`set_sv_to_null_pdl`](Core/set_sv_to_null_pdl.md) `set_sv_to_null_pdl($sv)` — connect an existing SV to a freshly-allocated empty pdl. Mirrors `Core.xs:1073-1082` → `pdlcore.c:34` pdl_SetSV_PDL. #### [`howbig`](Core/howbig.md) `howbig($typecode)` — size in bytes of a PDL type, by integer type code. #### `get_datatype` `get_datatype($pdl)` — return the datatype as integer type code. #### `orig_badvalue` orig_badvalue — class method on `PDL::Type`. Returns hardcoded `pdl.h` default. Call form: `byte->orig_badvalue` returns u8::MAX as IV/NV. #### `badvalue` badvalue — dual dispatch mirror of `PDL::badvalue` (`Bad.pm:177-194`). PDL instance: `$pdl`->`badvalue([$new])` → get/set per-PDL (\*pdl).badvalue PDL::Type: byte->`badvalue([$new])` → get/set global per-type table #### `approx` `approx($a, $b, $tol?)` — element-wise approximate equality. Returns a PDL of 0/1 (default tolerance 1e-6). #### `inf` `inf()` — return positive infinity as a 0-d Double PDL. #### `nan` `nan()` — return NaN as a 0-d Double PDL. #### `r2c` `r2C($pdl)` — convert real to complex (stub: croak). #### `i2c` `i2C($pdl)` — convert imaginary to complex (stub: croak). #### `broadcast` `broadcast($pdl, $dim?)` — return a broadcasted view. Broadcasting happens automatically in PDL binary operations, so this is a no-op that returns self. Mirrors `PDL::Core::broadcast`. #### `nbytes` `nbytes($pdl)` — return the number of bytes in the pdl’s data buffer. #### `unbroadcast` `unbroadcast($pdl, $n?)` — remove up to `$n` trailing size-1 dimensions. With no `$n` argument, removes all trailing size-1 dims. Returns a new PDL with the reduced dimensionality. #### `sethdr` `sethdr($pdl, $hashref)` — attach a header hashref to the PDL. #### `gethdr` `gethdr($pdl)` — retrieve the header hashref from the PDL. #### `hdr` `hdr($pdl, $hashref?)` — get or set header (combined accessor). #### `hdrcpy` `hdrcpy($pdl, $flag?)` — get/set whether header is copied on operations. Stores the flag as a package variable in `%PDL::_hdrcpy` keyed by SV address. #### `fhdr` `fhdr($pdl)` — «force header» = get header, creating an empty one if none exists. #### `new_or_inplace` `new_or_inplace($pdl)` — if inplace flag is set, return the pdl itself (clearing the inplace flag); otherwise return a hard copy. Mirrors `PDL::Core::new_or_inplace`. #### `dup` `dup($pdl, $dim, $n)` — duplicate along dimension `$dim`, `$n` times. Output dim[`$dim`] = input dim[`$dim`] \* `$n`. Data is repeated. #### `dupn` `dupN($pdl, @counts)` — duplicate along each dimension by the corresponding count. #### `datasv_refcount` `datasv_refcount($pdl)` — return SvREFCNT of the pdl’s datasv slot. #### `allocated` `allocated($pdl)` — return 1 iff `PDL_ALLOCATED` is set on state flags.