<!-- GENERATED by docs/sphinx/bin/20-reference (p5) from Peta/FFI/Cairo/Path.rs. Do not edit. -->


# Peta::FFI::Cairo::Path

<div class="pperl-badges"><span class="pperl-badge pperl-tier-std" title="Minimum feature tier: std. Available in all builds from \`--features native-std\` upward.">📦 std</span></div>

`Cairo::Path` package plug-in - the tied-array live view onto `cairo_path_t*`.

`Cairo::Path` is not a plain blessed pointer like the other cairo objects:
it is a **tied ARRAY of tied HASHes of tied ARRAYs** presenting a live view
onto a C `cairo_path_t*`. This file is a 1:1 mirror of upstream
`CairoPath.xs`; read that alongside this for the semantics. The four
Perl-visible packages map to the XS’s four MODULE blocks:

- `Cairo::Path`        (tied ARRAY)  - one element per path command.
- `Cairo::Path::Data`  (tied HASH)   - keys «type» / «points» for a command.
- `Cairo::Path::Points`(tied ARRAY)  - the points of one command.
- `Cairo::Path::Point` (tied 2-ARRAY)- the (x, y) of one point.

## Magic representation (mirrors `create_tie` / `cairo_perl_mg_get`)

`create_tie` (XS lines 41-69) attaches TWO magics to the referent AV/HV:

1. `PERL_MAGIC_tied` (“P”, obj = the blessed RV) so Perl routes element
   access through this package’s FETCH/STORE/… methods.
2. `PERL_MAGIC_ext`  (“~”, mg_ptr = the C object pointer, namlen = 0),
   with `mg->mg_private = MY_MAGIC_SIG (0xCAFE)` marking it as ours.

The C pointer carried in the ext slot IS the element/point offset: the
top-level tie carries `cairo_path_t*`; each `Cairo::Path::Data` /
`::Points` tie carries the `cairo_path_data_t*` pointing at that command’s
header; each `Cairo::Path::Point` tie carries the `cairo_path_data_t*`
pointing at that specific point union. There is no separate index stored -
the pointer already threads the location, exactly as the XS does (e.g.
`newSVCairoPathPoint(&data[index + 1])`, XS line 427/444).

Recovery mirrors `cairo_perl_mg_get` (XS lines 29-37): given the invocant
blessed RV `sv`, walk `SvRV(sv)`”s magic chain for a `PERL_MAGIC_ext` slot
whose `mg_private == 0xCAFE`, and read `mg_ptr`.

## VERSION SCOPE

Path is stable cairo API; there is no version gating and no post-1.109
superset here.

## Functions

### Other Functions

#### `path_destroy`

`$path->DESTROY` -> cairo_path_destroy (XS:283-295). Recover the pointer through the ext-magic slot (via `mg_get`, matching `SvCairoPath`); if present, destroy it. The 5.6.x mg_ptr-unset branch is not mirrored (pperl targets 5.42+, XS lines 289-293 are guarded out).

#### `path_fetchsize`

`Cairo::Path::FETCHSIZE` (XS:297-305): number of path commands. Walk data[] stepping by `header.length`, counting each command.

#### `path_fetch`

`Cairo::Path::FETCH` (XS:307-320): the i-th command as a tied `Cairo::Path::Data`. Walk by header.length, counting to `index`; return the tie carrying that command’s `cairo_path_data_t*`, else undef.

#### `data_fetch`

`Cairo::Path::Data::FETCH` (XS:337-351): key «type» -> nickname; «points» -> a tied `Cairo::Path::Points`; anything else croaks.

#### `data_store`

`Cairo::Path::Data::STORE` (XS:353-367): only «points» is writable. Rewrite this command’s coordinates from the arrayref value (keeping the existing header.type), and return a fresh tied Points view (matching the XS RETVAL).

#### `data_exists`

`Cairo::Path::Data::EXISTS` (XS:369-379): true for «type»/»points» only.

#### `data_firstkey`

`Cairo::Path::Data::FIRSTKEY` (XS:381-385): always «type».

#### `data_nextkey`

`Cairo::Path::Data::NEXTKEY` (XS:387-395): «type» -> «points», else undef.

#### `points_fetchsize`

`Cairo::Path::Points::FETCHSIZE` (XS:412-419): n_points for this command.

#### `points_fetch`

`Cairo::Path::Points::FETCH` (XS:421-432): the i-th point of this command as a tied `Cairo::Path::Point` carrying `&data[index + 1]`, else undef.

#### `points_store`

`Cairo::Path::Points::STORE` (XS:434-454): write x/y of the i-th point back into the C buffer from the [x,y] arrayref value; return a tied Point view.

#### `point_fetchsize`

`Cairo::Path::Point::FETCHSIZE` (XS:471-475): always 2.

#### `point_fetch`

`Cairo::Path::Point::FETCH` (XS:477-494): index 0 -> x, 1 -> y, read straight from the C buffer’s point union; else undef.

#### `point_store`

`Cairo::Path::Point::STORE` (XS:496-513): the LIVE write-back. index 0 sets point.x, 1 sets point.y - straight into the C buffer - and returns the new value as an NV (matching `newSVnv(data->point.x = value)`).