FFI::C::Array(3pm)

💖 FFI::C::Array — the vibe ✨

okay bestie, listen up. this is FFI::C::Array, version 0.15, and it's the whole "array instance for FFI" situation. it lives in the User Contributed Perl Documentation section of your man pages, and it's about to become your new hyperfixation. no cap. 🫶

---

🌸 NAME 🌸

FFI::C::Array — Array instance for FFI. that's it. that's the whole name. iconic. 👑

---

⭐ VERSION ⭐

version 0.15 💅

---

🦋 SYNOPSIS 🦋

okay so here's the whole flow, verbatim, don't skip a line because it all matters:

use FFI::C::ArrayDef;
use FFI::C::StructDef;

my $point_def = FFI::C::StructDef->new(
  name  => 'point_t',
  class => 'Point',
  members => [
    x => 'double',
    y => 'double',
  ],
);

my $rect_def = FFI::C::ArrayDef->new(
  name    => 'rectangle_t',
  class   => 'Rectangle',
  members => [
    $point_def, 2,
  ]
);

# create a rectangle using the def's create method
my $square = $rect_def->create([
  { x => 1.0, y => 1.0 },
  { x => 2.0, y => 2.0 },
]);

printf "[[%d %d][%d %d]]\n",
  $square->[0]->x, $square->[0]->y,
  $square->[1]->x, $square->[1]->y;   # [[1 1][2 2]]

# move square by 1 on the x axis
$square->[$_]->x( $square->[$_]->x + 1 ) for 0..1;

printf "[[%d %d][%d %d]]\n",
  $square->[0]->x, $square->[0]->y,
  $square->[1]->x, $square->[1]->y;   # [[2 1][3 2]]

# Create a rectangle using the generated class
my $rect = Rectangle->new;
$rect->[0]->x(1.0);
$rect->[0]->y(1.0);
$rect->[1]->x(2.0);
$rect->[1]->y(3.0);

look at that. look at how clean it is. we are thriving. 🌈

---

💅 DESCRIPTION 💅

so this class represents an instance of a C array. literally what it says on the tin, bestie.

how do you even get one of these? two ways, and both are valid:

• you can create it using new on the generated class — but only if that class was specified for the FFI::C::ArrayDef 👀
• or you use the create method on FFI::C::ArrayDef

and then, here's the fun part: you can grab each element of the array with the get method (it's down below, don't worry), OR you can just treat the object like an array reference, because ✨ magical Perl ties ✨. that's the good stuff. the way Perl just does that? obsessed. 😭

---

🎀 CONSTRUCTOR 🎀

new

FFI::C::ArrayDef->new( class => 'User::Array::Class', ... );
my $instance = User::Array::Class->new;
my $instance = User::Array::Class->new($count);

creates a shiny new instance of the array. ✨

now here's the tea about $count:

• if you pass $count, that's what gets used as the element count — it overrides the count that the def defined
• if the def didn't specify a count, then you MUST provide a count. like, mandatory. non-negotiable. the code will simply not be doing that for you. 🫠

---

✨ METHODS ✨

get

my $element = $instance->get($index);
my $element = $instance->[$index];

gets the element sitting at the given $index. two syntaxes, same energy, pick your fave. 💖

count

my $count = $instance->count;

returns the number of elements in the array — if known. note that "if known" bestie, because sometimes it is simply not known and that's just how it is. 🙈

tie

my $arrayref = $instance->tie;

returns a Perl array reference that's tied to the C array. this is the plumbing behind the magic. 🧚

---

👑 SEE ALSO 👑

your reading list, your syllabus, your curated little ecosystem:

• FFI::C
• FFI::C::Array
• FFI::C::ArrayDef
• FFI::C::Def
• FFI::C::File
• FFI::C::PosixFile
• FFI::C::Struct
• FFI::C::StructDef
• FFI::C::Union
• FFI::C::UnionDef
• FFI::C::Util
• FFI::Platypus::Record

go read them all. i'll wait. 💜

---

🌸 AUTHOR 🌸

Graham Ollis <plicease@cpan.org> — thank you for your service, king. 🫶

---

💜 COPYRIGHT AND LICENSE 💜

This software is copyright (c) 2020-2022 by Graham Ollis.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

bestie if you got all the way here you are officially a C-array-in-Perl main character. periodt. 💅

and that's a wrap on the perl v5.36.0 build from 2023-02-06 — go forth and slay some FFI. 🦋✨