Geo::Hash::XS(3pm)

✨ NAME ✨

Geo::Hash::XS — it's Geo::Hash but in XS, babes. That's the whole vibe. 💅

---

🌸 SYNOPSIS 🌸

my $gh = Geo::Hash::XS->new();
my $hash = $gh->encode( $lat, $lon );  # default precision = 32
my $hash = $gh->encode( $lat, $lon, $precision );
my ($lat, $lon) = $gh->decode( $hash );

---

🦋 DESCRIPTION 🦋

Okay so bestie, Geo::Hash::XS encodes AND decodes geohash strings, and it does it fast. Like, unhinged fast. ✨

💀 Real talk though: this module is currently alpha quality right now — especially the adjacent() and negihbors() methods, which the author literally just kind of copied the logic for from elsewhere. So pls pls pls submit tests and patches! 🥺🙏

---

👑 METHODS 👑

💖 $gh = Geo::Hash::XS->new()

Makes you a brand new object. Main character energy from the jump. ✨

🎀 $hash = $gh->encode($lat, $lon[, $precision])

Encodes the $lat and $lon you hand it into a geohash. If you don't pass $precision, it automatically adjusts the precision based on the $lat and $lon values you gave it. So smart. So thoughtful. 🧚

If you do not want Geo::Hash::XS to spend time doing that calculation, just explicitly say the $precision yourself. Periodt. 💅

🦋 ($lat, $lon) = $gh->decode( $hash )

Decodes $hash back into $lat and $lon. Round trip, slay. 🌈

🌸 ($lat_range, $lon_range) = $gh->decode_to_interval( $hash )

Same idea as decode() but with a glow-up: decode_to_interval() decodes $hash into $lat_range and $lon_range. Each range is a reference to two element arrays, and those arrays hold the upper and lower bounds. 🫶

💜 $adjacent_hash = $gh->adjacent($hash, $where)

Gives you back the adjacent geohash. $where is the direction, so if you want the block to the right of $hash, you say:

use Geo::Hash::XS qw(ADJ_RIGHT);

my $gh = Geo::Hash::XS->new();
my $adjacent = $gh->adjacent( $hash, ADJ_RIGHT );

⭐ @list_of_geohashes = $gh->neighbors($hash, $around, $offset)

Returns the list of neighbors — that's the blocks surrounding $hash. A whole lil squad. 😭💖

🌈 $precision = $gh->precision($lat, $lon)

Returns the apparent required precision needed to describe that latitude and longitude. It literally tells you what it needs. Communication queen. 👑

---

🎀 CONSTANTS 🎀

✨ ADJ_LEFT, ADJ_RIGHT, ADJ_TOP, ADJ_BOTTOM

These are what you use to specify the direction in adjacent(). Pick your direction, bestie. 🧭

---

🔥 PERFORMANCE 🔥

Here's the output from running benchmark/encode.pl — prepare to be gagged:

Geo::Hash: 0.02
Geo::Hash::XS: 0.00014

precision = auto...
         Rate  perl    xs
perl  18332/s    --  -98%
xs   964744/s 5163%    --

precision = 5...
           Rate  perl    xs
perl   16500/s    --  -98%
xs   1011557/s 6030%    --

precision = 10...
          Rate   perl     xs
perl   8650/s     --   -99%
xs   980236/s 11232%     --

precision = 20...
          Rate   perl     xs
perl   4736/s     --   -99%
xs   858875/s 18035%     --

precision = 30...
          Rate   perl     xs
perl   3050/s     --  -100%
xs   712136/s 23252%     --

So yeah — obviously, the benefit of doing this calculation in XS becomes larger with higher precision. But generaly, bestie, you don't need precision > 10. Save yourself the drama. 💅

---

📜 LICENSE 📜

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

See http://www.perl.com/perl/misc/Artistic.html

---

💌 AUTHOR 💌

Copyright (c) 2010 Daisuke Maki <daisuke@endworks.jp>

---

And that's the whole page, bestie — brought to you by perl v5.42.3 (dated 2026-08-20), the Geo::Hash::XS(3pm) manual. Go forth and hash responsibly. 🫶✨💖