Tie::Array(3perl)

💖 Tie::Array 💖 — the base class for tied arrays, bestie

okay so real talk: this is Tie::Array, a Perl Programmers Reference Guide situation, and it is literally the blueprint for every class that wants to pretend to be an array. no cap. if you've ever wanted your own object to go @somearray energy, this is the page. let's get into it 🫶

---

✨ SYNOPSIS ✨

here's the whole vibe, copy it exactly:

package Tie::NewArray;
use Tie::Array;
@ISA = ('Tie::Array');

# mandatory methods
sub TIEARRAY { ... }
sub FETCH { ... }
sub FETCHSIZE { ... }

sub STORE { ... }       # mandatory if elements writeable
sub STORESIZE { ... }   # mandatory if elements can be added/deleted
sub EXISTS { ... }      # mandatory if exists() expected to work
sub DELETE { ... }      # mandatory if delete() expected to work

# optional methods - for efficiency
sub CLEAR { ... }
sub PUSH { ... }
sub POP { ... }
sub SHIFT { ... }
sub UNSHIFT { ... }
sub SPLICE { ... }
sub EXTEND { ... }
sub DESTROY { ... }

package Tie::NewStdArray;
use Tie::Array;

@ISA = ('Tie::StdArray');

# all methods provided by default

package main;

$object = tie @somearray,'Tie::NewArray';
$object = tie @somearray,'Tie::StdArray';
$object = tie @somearray,'Tie::NewStdArray';

see how the optional ones are just sitting there like "call me if you need speed 💅" — that's the whole point. the mandatory ones you have to bring.

---

🌸 DESCRIPTION 🌸

so this module hands you methods for array-tying classes. if you wanna know the full list of functions you need in order to tie an array to a package, go read perltie — it's the syllabus, fr fr.

the basic Tie::Array package gives you:

• stub DESTROY and EXTEND methods that do absolutely nothing (iconic, honestly)
• stub DELETE and EXISTS methods that croak() if the delete() or exists() builtins ever get called on the tied array 😭 (they said no)
• implementations of PUSH, POP, SHIFT, UNSHIFT, SPLICE and CLEAR written in terms of the basic FETCH, STORE, FETCHSIZE, STORESIZE

meanwhile Tie::StdArray is the overachiever 👑 — it gives you efficient methods for tied arrays that are implemented as blessed references to an "inner" perl array. it inherits from Tie::Array, and it should make your tied arrays behave exactly like standard arrays, so you can selectively overload just the methods you care about. pick and choose, main character energy.

if you're a developer who wants to write your own tied arrays, the required methods are briefly defined below. for the full detailed description plus example code, go check out the perltie section. that's where the lore lives.

---

🦋 THE METHODS 🦋

TIEARRAY classname, LIST

this is the class method, and it gets invoked by the command tie @array, classname. it associates an array instance with the class you specified. LIST is the place for any extra arguments you need (think along the lines of AnyDBM_File and its compatriots) to complete the association.

the method should return an object of a class that provides the methods below. that's the deal. 🤝

STORE this, index, value

store the datum value into index for the tied array associated with the object this. if this makes the array larger, then the class's mapping of undef should be returned for the new positions. don't skip that part bestie.

FETCH this, index

retrieve the datum in index for the tied array associated with the object this. simple. fetch. slay.

FETCHSIZE this

returns the total number of items in the tied array associated with the object this. (equivalent to scalar(@array), same energy ⭐)

STORESIZE this, count

sets the total number of items in the tied array associated with the object this to be count.

two lil rules:

• if this makes the array larger, the class's mapping of undef should be returned for the new positions
• if the array becomes smaller, entries beyond count should be deleted

EXTEND this, count

this is an informative call — it's telling you the array is likely to grow to have count entries. you can use it to optimize allocation. this method need do nothing. literally nothing. it's just a heads-up text. 📱

EXISTS this, key

verify that the element at index key exists in the tied array this.

heads up: the Tie::Array implementation is a stub that simply croaks. so like, don't be surprised.

DELETE this, key

delete the element at index key from the tied array this.

same warning again, bestie: the Tie::Array implementation is a stub that simply croaks.

CLEAR this

clear (remove, delete, ...) all values from the tied array associated with the object this. wipe it. gone. ghosted. 💀

DESTROY this

normal object destructor method. nothing wild, just the standard goodbye.

PUSH this, LIST

append elements of LIST to the array.

POP this

remove the last element of the array and return it.

SHIFT this

remove the first element of the array (shifting all the other elements down) and return it.

UNSHIFT this, LIST

insert LIST elements at the beginning of the array, moving existing elements up to make room. making space, being considerate 🥰

SPLICE this, offset, length, LIST

perform the equivalent of splice on the array.

the deets:

• offset is optional and defaults to zero. negative values count back from the end of the array
• length is optional and defaults to the rest of the array
• LIST may be empty

returns a list of the original length elements at offset. 📋

---

⚠️ CAVEATS ⚠️

there is no support at present for tied @ISA. not a vibe, but it's the truth.

there's a potential conflict between the magic entries needed to notice setting of @ISA, and those needed to implement 'tie'. so like, be aware. 🙈

---

👑 AUTHOR 👑

Nick Ing-Simmons <nik@tiuk.ti.com>

shoutout to the legend. periodt. 💜

---

🌈 okay that's the whole page! this was perl v5.44.0, dated 2026-10-17 — that's the version and the date from the footer, mwah, love that for us. go tie some arrays, bestie, you got this 💅🎀✨