.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Geo::Hash::XS 3pm" .TH Geo::Hash::XS 3pm "2022-10-20" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Geo::Hash::XS \- Geo::Hash in XS .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 4 \& 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 ); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Geo::Hash::XS encodes and decodes geohash strings, fast. .PP Currently this module is alpha quality (especially the \f(CW\*(C`adjacent()\*(C'\fR and \f(CW\*(C`negihbors()\*(C'\fR methods, which I just kind of copied the logic from elsewhere). Please submit tests and patches! .SH "METHODS" .IX Header "METHODS" .ie n .SS "$gh = Geo::Hash::XS\->\fBnew()\fP" .el .SS "\f(CW$gh\fP = Geo::Hash::XS\->\fBnew()\fP" .IX Subsection "$gh = Geo::Hash::XS->new()" .ie n .SS "$hash = $gh\->encode($lat, $lon[, $precision])" .el .SS "\f(CW$hash\fP = \f(CW$gh\fP\->encode($lat, \f(CW$lon\fP[, \f(CW$precision\fP])" .IX Subsection "$hash = $gh->encode($lat, $lon[, $precision])" Encodes the given \f(CW$lat\fR and \f(CW$lon\fR to a geohash. If \f(CW$precision\fR is not given, automatically adjusts the precision according the the given \f(CW$lat\fR and \f(CW$lon\fR values. .PP If you do not want Geo::Hash::XS to spend time calculating this, explicitly specify \f(CW$precision\fR. .ie n .SS "($lat, $lon) = $gh\->decode( $hash )" .el .SS "($lat, \f(CW$lon\fP) = \f(CW$gh\fP\->decode( \f(CW$hash\fP )" .IX Subsection "($lat, $lon) = $gh->decode( $hash )" Decodes \f(CW$hash\fR to \f(CW$lat\fR and \f(CW$lon\fR .ie n .SS "($lat_range, $lon_range) = $gh\->decode_to_interval( $hash )" .el .SS "($lat_range, \f(CW$lon_range\fP) = \f(CW$gh\fP\->decode_to_interval( \f(CW$hash\fP )" .IX Subsection "($lat_range, $lon_range) = $gh->decode_to_interval( $hash )" Like \f(CW\*(C`decode()\*(C'\fR but \f(CW\*(C`decode_to_interval()\*(C'\fR decodes \f(CW$hash\fR to \f(CW$lat_range\fR and \f(CW$lon_range\fR. Each range is a reference to two element arrays which contains the upper and lower bounds. .ie n .SS "$adjacent_hash = $gh\->adjacent($hash, $where)" .el .SS "\f(CW$adjacent_hash\fP = \f(CW$gh\fP\->adjacent($hash, \f(CW$where\fP)" .IX Subsection "$adjacent_hash = $gh->adjacent($hash, $where)" Returns the adjacent geohash. \f(CW$where\fR denotes the direction, so if you want the block to the right of \f(CW$hash\fR, you say: .PP .Vb 1 \& use Geo::Hash::XS qw(ADJ_RIGHT); \& \& my $gh = Geo::Hash::XS\->new(); \& my $adjacent = $gh\->adjacent( $hash, ADJ_RIGHT ); .Ve .ie n .SS "@list_of_geohashes = $gh\->neighbors($hash, $around, $offset)" .el .SS "\f(CW@list_of_geohashes\fP = \f(CW$gh\fP\->neighbors($hash, \f(CW$around\fP, \f(CW$offset\fP)" .IX Subsection "@list_of_geohashes = $gh->neighbors($hash, $around, $offset)" Returns the list of neighbors (the blocks surrounding \f(CW$hash\fR) .ie n .SS "$precision = $gh\->precision($lat, $lon)" .el .SS "\f(CW$precision\fP = \f(CW$gh\fP\->precision($lat, \f(CW$lon\fP)" .IX Subsection "$precision = $gh->precision($lat, $lon)" Returns the apparent required precision to describe the given latitude and longitude. .SH "CONSTANTS" .IX Header "CONSTANTS" .SS "\s-1ADJ_LEFT, ADJ_RIGHT, ADJ_TOP, ADJ_BOTTOM\s0" .IX Subsection "ADJ_LEFT, ADJ_RIGHT, ADJ_TOP, ADJ_BOTTOM" Used to specify the direction in \f(CW\*(C`adjacent()\*(C'\fR .SH "PERFORMANCE" .IX Header "PERFORMANCE" Here's the output from running benchmark/encode.pl: .PP .Vb 2 \& 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% \-\- .Ve .PP Obviously, the benefit of doing this calculation in \s-1XS\s0 becomes larger with higher precision, but generaly you don't need precision > 10. .SH "LICENSE" .IX Header "LICENSE" This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .PP See http://www.perl.com/perl/misc/Artistic.html .SH "AUTHOR" .IX Header "AUTHOR" Copyright (c) 2010 Daisuke Maki