<!-- GENERATED by docs/sphinx/bin/02-reference from PDL/Core.rs. Do not edit. -->

```{index} single: PDL::Core; Perl module
```

# PDL::Core

```{pperl-module-badges} PDL::Core
```

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)

`$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)

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

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

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

```{toctree}
:hidden:
:maxdepth: 1

Core/at
Core/flowing
Core/set_sv_to_null_pdl
Core/howbig
```