at#

$pdl->at(@pos) – return a single element of an ndarray as a Perl scalar.

@pos is a coordinate list whose length matches the number of dimensions of $pdl. Indices may be negative (counted from the far end, so -1 is the last element along that axis). Missing trailing indices default to 0; extra trailing indices past $pdl->ndims are ignored.

Before the lookup, the PDL is made physical-or-affine (pdl_make_physvaffine), and if any upstream transform has been invalidated (PDL_ANYCHANGED) a full pdl_make_physical is run so the data we read is current. The returned SV has the same Perl-level numeric type as the underlying PDL cell (IV for integer types, NV for floats); complex-typed PDLs yield a PDL::Complex::Overloads object upstream – the connector currently returns the real part via pdl_anyval_to_f64.

Signature#

$z = at($pdl, @pos);       # function form
$z = $pdl->at(@pos);       # method form

Broadcasting#

at does not broadcast. It is a scalar-valued accessor: supply exactly one coordinate tuple.

Bad values#

If $pdl has the BADFLAG set and the fetched cell is the bad sentinel, at returns the string "BAD" (matches upstream at_bad_c and test 170-bad.t #54). If BADFLAG is clear the raw numeric value is returned regardless of content.

Examples#

use PDL;
my $x = sequence(3, 4);     # 3x4, values 0..11
print $x->at(1, 2);         # 7
print $x->at(-1, -1);       # 11 (last element via negative indexing)

## BAD value propagation

my $b = pdl([1, 2, 3]);
$b->badflag(1);
$b->inplace->setbadat(1);
print $b->at(1);            # "BAD"

Errors#

Croaks with "Position out of range" when:

  • $pdl is a null PDL (NOMYDIMS, e.g. fresh from PDL->null);

  • $pdl has zero elements (e.g. pdl([]));

  • any supplied index, after negative-index resolution, falls outside [0, dim_size) for its axis.

Also croaks via croak_c_pdl_error if the engine’s pdl_make_physvaffine / pdl_make_physical reports an error.

Upstream#

Mirrors PDL::at in lib/PDL/Core.pm, which delegates to the XS routine at_bad_c defined in Core.xs:at_c. Our flat-index computation is done connector-side via pdl_indices_to_flat rather than going back through pdl_at for each call.