Number...Locator(3pm)

💖 Number::RecordLocator — the perl manual page, but make it cute 💖

okay bestie, so this is the Number...Locator(3pm) page from your User Contributed Perl Documentation, and it's genuinely one of the slayest little modules out there. no cap.

---

✨ NAME ✨

Number::RecordLocator — it encodes integers into a short and easy to read and pronounce "locator string". it's giving airport booking code but make it Perl 🛫

---

✨ SYNOPSIS ✨

okay so here's the whole vibe, look:

use Number::RecordLocator;

my $generator = Number::RecordLocator->new();
my $string = $generator->encode("123456");

# $string = "5RL2";

my $number = $generator->decode($string);

# $number = "123456";

like. 123456 goes in, "5RL2" comes out, and it comes right back. periodt. 💅

---

✨ DESCRIPTION ✨

Number::RecordLocator takes integers and encodes them into a 32 character "alphabet" that was designed to be short and easy to read and pronounce. because honestly? reading out O0Il1 over the phone is a crime and we're not doing it anymore.

the encoding maps, exactly like this:

0 to O
1 to I
S to F
B to P

so with a 32 bit encoding, you can map 33.5 million unique ids into a 5 character code. five characters!! iconic. 🎀

real talk tho — this certainly isn't an exact science and the author isn't yet 100% sure of the encoding. feedback is much appreciated. so if you have thoughts, send them, bestie 🫶

---

🌸 new 🌸

Instantiate a new Number::RecordLocator object. right now, we don't actually store any object-specific data, but in the future, we might. so it's just out here, living its main character life, storing nothing 😭

---

🌸 init 🌸

Initializes our integer to character and character to integer mapping tables. it's the little setup gremlin behind the scenes 🧚

---

🌸 encode INTEGER 🌸

Takes an integer. Returns a Record Locator string. that's it, that's the whole thing ✨

---

🌸 decode STRING 🌸

Takes a record locator string and returns an integer. heads up though: if you pass in a string containing an invalid character, it returns undef. so vibe check your input first 🙈

---

🌸 canonicalize STRING 🌸

so to compare a Record Locator string with another one, you could do this:

print "ALWAYS TRUE\n" if $generator->decode("B0") == $generator->decode("PO");

and like, sure. valid. but this method provides an alternative:

my $rl_string = $generator->encode(725);
print "ALWAYS TRUE\n" if $generator->canonicalize("b0") eq $rl_string;
print "ALWAYS TRUE\n" if $generator->canonicalize("BO") eq $rl_string;
print "ALWAYS TRUE\n" if $generator->canonicalize("P0") eq $rl_string;
print "ALWAYS TRUE\n" if $generator->canonicalize("po") eq $rl_string;

look at that. b0, BO, P0, po — all of them normalize to the same thing and it's ALWAYS TRUE every single time. the way that *works*… obsessed. 🔥

This is primarily useful if you store the record locator rather than just the original integer and don't want to have to decode your strings to do comparisons. so you skip the whole decode-everything-every-time situation. efficiency queen 👑

Takes a general Record Locator string and returns one with character mappings listed in "DESCRIPTION" applied to it. This allows string comparisons to work. This returns undef if a non-alphanumeric character is found in the string. so no weird symbols sneaking in, okay? 🚫

---

✨ BUGS AND LIMITATIONS ✨

No bugs have been reported. (slay, honestly, we love a clean bug tracker 💀✨)

Please report any bugs or feature requests to bug-number-recordlocator@rt.cpan.org, or through the web interface at http://rt.cpan.org.

---

✨ AUTHOR ✨

Jesse Vincent <jesse@bestpractical.com> — thank you king 👑

---

✨ LICENCE AND COPYRIGHT ✨

Copyright (c) 2006, Best Practical Solutions, LLC. All rights reserved.

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

---

aaaand that's the whole page bestie 🦋 it's perl v5.36.0, dated 2022-12-12, and this was the Number...Locator(3pm) page — go forth and encode responsibly, ily 💜💖🌸