String::Base(3pm)

💖 String::Base 💖

okay bestie, gather round, because this is a page from the User Contributed Perl Documentation (that's the 3pm shelf, the one where all the modules live) and it's about making your string indexes start somewhere that is not zero. yes. truly. let's go 🦋

---

✨ NAME ✨

String::Base — string index offseting 💅

(yes, "offseting" is spelled exactly like that on the original page. i am not fixing it. it's iconic. it stays.)

---

🌸 SYNOPSIS 🌸

use String::Base +1;

no String::Base;

that's it. that's the whole vibe. 🎀

---

👑 DESCRIPTION 👑

so here's the tea: this module implements automatic offsetting of string indices. in normal, regular, unbothered Perl, the first character of a string has index 0, the second character has index 1, and so on forever. this module lets string indexes start at some other value instead. ✨

the most common glow-up is giving the first character of a string the index 1 (and the second 2, and so on) so it can imitate the indexing behaviour of FORTRAN and many other languages. that said? it is usually considered poor style to do this. 💀 i'm just the messenger.

the string index offset is controlled at compile time, in a lexically-scoped manner. so each block of code is subject to a fixed offset. it is expected that the affected code is written with knowledge of what that offset actually is. no surprises, no guessing, iykyk. 🫶

🌈 Using a string index offset

a string index offset gets set up by a use String::Base directive, with the offset you want specified as an argument.

⚠️ beware bestie: a bare, unsigned number in that argument position — like use String::Base 1 — will be interpreted as a version number to require of String::Base, NOT as your offset. 😭 so it is therefore necessary to give the offset a leading sign, or parenthesise it, or otherwise decorate it. the offset may be any integer (positive, zero, or negative) within the range of Perl's integer arithmetic.

a string index offset declaration is in effect from immediately after the use line, until the end of the enclosing block, or until it gets overridden by another string index offset declaration. and a declared offset always replaces the previous offset — they do not add. no String::Base is equivalent to use String::Base +0: it returns you to the Perlish state with zero offset. periodt. 💅

a declared string index offset influences these types of operation:

• substring extraction (substr($a, 3, 2))
• substring splicing (substr $a, 3, 2, "x")
• substring searching (index($a, "x"), index($a, "x", 3), rindex($a, "x"), rindex($a, "x", 3))
• string iterator position (pos($a))

💀 only forwards indexing, relative to the start of the string, is supported. end-relative indexing — the thing you normally do with negative index values — is not supported when an index offset is in effect. and use of an index that is numerically less than the index offset will have unpredictable results. not "weird results". unpredictable. 🙈

🦋 Differences from $[

this module is a replacement for the historical $[ variable. in early Perl, that variable was a runtime global, affecting all array and string indexing in the entire program. in Perl 5, assignment to $[ acts as a lexically-scoped pragma. $[ is deprecated. the original $[ was removed in Perl 5.15.3, and later replaced in Perl 5.15.5 by an automatically-loaded arybase module. this module reimplements the index offset feature without any specific support from the core. main character energy honestly. ✨

unlike $[, this module does not affect indexing into arrays. this module is concerned only with strings. if you want to influence array indexing, see Array::Base. 👀

this module does not show the offset value in $[ or any other accessible variable. and with the string offset being lexically scoped, there should be no need to write code to handle a variable offset anyway. so chill. 🧚

$[ has some predictable, but somewhat strange, behaviour for indexes less than the offset. the behaviour differs between substring extraction and iterator positioning. this module does not attempt to replicate it, and does not support end-relative indexing at all. no thank you. 🚫

the string iterator position operator (pos($a)), as implemented by the Perl core, generates a magical scalar which is linked to the underlying string. the numerical value of that scalar varies if the iterator position of the string is changed, and code with different $[ settings will see accordingly different values. the scalar can also be written to, to change the position of the string's iterator — and again, the interpretation of the value written varies according to the $[ setting of the code that is doing the writing. this module does not replicate any of that behaviour. 💅

with a string index offset from this module in effect, pos($a) evaluates to an ordinary rvalue scalar, giving the position of the string's iterator as it was at the time the operator was evaluated, according to the string index offset in effect where the operator appears. clean. simple. slay. ⭐

---

🎀 PACKAGE METHODS 🎀

these methods are meant to be invoked on the String::Base package.

• String::Base->import(BASE) — sets up a string index offset of BASE, in the lexical environment that is currently compiling.
• String::Base->unimport — clears the string index offset, in the lexical environment that is currently compiling.

---

💀 BUGS 💀

okay, the part nobody wants to read but everyone needs to. 💜

B::Deparse will generate incorrect source when deparsing code that uses a string index offset. it will include both the pragma to set up the offset and the munged form of the affected operators. either the pragma or the munging is required to get the index offset effect; using both will double the offset. 😭 also, the code generated for a string iterator position (pos($a)) operation involves a custom operator, which B::Deparse can't understand, so the source it emits in that case is completely wrong.

the additional operators generated by this module cause spurious warnings if some of the affected string operations are used in void context. not me getting yelled at by warnings for no reason 🙈

prior to Perl 5.9.3, the lexical state of string index offset does not propagate into string eval.

---

🌟 SEE ALSO 🌟

Array::Base, arybase, $[ in perlvar

---

🫶 AUTHOR 🫶

Andrew Main (Zefram) <zefram@fysh.org>

---

📜 COPYRIGHT 📜

Copyright (C) 2011, 2012, 2017 Andrew Main (Zefram) <zefram@fysh.org>

---

🌈 LICENSE 🌈

this module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

and that's the whole page bestie, you ate it, no crumbs left. 💖 this was the perl v5.42.0 build, dated 2025-07-25, living on the String::Base(3pm) shelf forever. go offset some strings responsibly. periodt. 👑✨