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

```{index} single: at; PDL::Core function
```
```{index} single: PDL::Core::at; Perl function
```

# 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

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

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