The open-location-code Reference Manual

This is the open-location-code Reference Manual, version 2.2, generated automatically by Declt version 4.0 beta 2 "William Riker" on Wed May 15 06:25:23 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 open-location-code

Open Location Code library.

Author

Ralph Schleicher <>

License

Modified BSD License

Version

2.2

Dependencies
  • alexandria (system).
  • iterate (system).
Source

open-location-code.asd.

Child Component

open-location-code.lisp (file).


3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


3.1 Lisp


3.1.1 open-location-code/open-location-code.asd

Source

open-location-code.asd.

Parent Component

open-location-code (system).

ASDF Systems

open-location-code.


3.1.2 open-location-code/open-location-code.lisp

Source

open-location-code.asd.

Parent Component

open-location-code (system).

Packages

open-location-code.

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 open-location-code

Open Location Code is a location encoding system for addresses, independent of street names and building numbers.

See <https://plus.codes>.

Source

open-location-code.lisp.

Nickname

olc

Use List
  • common-lisp.
  • iterate.
Public Interface
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


5.1 Public Interface


5.1.1 Ordinary functions

Function: decode (code)

Decode an Open Location Code.

Argument CODE is an Open Location Code (a string).

Primary value is a ‘code-area’ object. Secondary value is ‘:full’ or ‘:short’ if CODE is a full or short Open Location Code respectively. If CODE is a full Open Location Code the code area denotes absolute coordinates. Otherwise, the code area denotes relative coordinates, i.e. offset values in the enclosing block.

Signal an ‘invalid-code-error’ if CODE is not a valid Open Location Code.

Package

open-location-code.

Source

open-location-code.lisp.

Function: encode (latitude longitude &optional precision)

Encode a location into an Open Location Code.

First argument LATITUDE and second argument LONGITUDE denote the location in degree angle. The latitude is clipped to the closed interval [-90, 90] and the longitude is normalized to the half-closed interval [-180, 180).
Optional third argument PRECISION is the precision of the code. Default is five, i.e. a code length of ten digits.

Value is a full Open Location Code (a string).

The relation between precision, code length, and code area size is depicted in the following table.

Precision | Code Length | Width / m | Height / m ————-+————-+—————+—————
1 | 2 | 2218929.9 | 2218929.9
2 | 4 | 110946.5 | 110946.5
3 | 6 | 5547.3 | 5547.3
4 | 8 | 277.4 | 277.4
5 | 10 | 13.9 | 13.9
6 | 11 | 3.47 | 2.77
7 | 12 | 0.867 | 0.555
8 | 13 | 0.217 | 0.111
9 | 14 | 0.0542 | 0.0222
10 | 15 | 0.0135 | 0.00444

The code length is equal to the number of Open Location Code digits. Pad characters and the separator character ‘+’ are not part of the code length. The code area dimensions are calculated with a mean earth radius of 6356766 m for a code area at the equator.

Package

open-location-code.

Source

open-location-code.lisp.

Function: fullp (code)

True if an object is a valid full Open Location Code.

Argument CODE is an object of any type.

Value is true if CODE is a valid full Open Location Code. Otherwise, value is null.

Package

open-location-code.

Source

open-location-code.lisp.

Function: recover (code latitude longitude)

Recover a full Open Location Code from a short code
and a reference location.

First argument CODE is an Open Location Code (a string). Second argument LATITUDE and third argument LONGITUDE denote the reference location in degree angle. The latitude is clipped to the closed interval [-90, 90] and the longitude is normalized to the half-closed interval [-180, 180).

Value is the recovered full code. If CODE is already a full code, return CODE as is.

Signal an ‘invalid-code-error’ if CODE is not an Open Location Code.

Package

open-location-code.

Source

open-location-code.lisp.

Function: shorten (code latitude longitude)

Remove four, six, or eight digits from the front of a full Open Location Code given a reference location.

First argument CODE is a full Open Location Code (a string). Second argument LATITUDE and third argument LONGITUDE denote the reference location in degree angle. The latitude is clipped to the closed interval [-90, 90] and the longitude is normalized to the half-closed interval [-180, 180).

Value is the short code, or the original full code if the reference location is too far.

Signal a ‘full-code-error’ if CODE is not a full Open Location Code.

Package

open-location-code.

Source

open-location-code.lisp.

Function: shortp (code)

True if an object is a valid short Open Location Code.

Argument CODE is an object of any type.

Value is true if CODE is a valid full Open Location Code. Otherwise, value is null.

Package

open-location-code.

Source

open-location-code.lisp.

Function: validp (code)

True if an object is a valid sequence of Open Location Code characters.

Argument CODE is an object of any type.

Value is ‘:full’ or ‘:short’ if CODE is a valid full or short Open Location Code respectively. Otherwise, value is null.

Package

open-location-code.

Source

open-location-code.lisp.


5.1.2 Generic functions

Generic Function: center (object)

Return the center latitude and longitude as multiple values.

Package

open-location-code.

Source

open-location-code.lisp.

Methods
Method: center ((object code-area))
Generic Function: code-length (object)

Return the Open Location Code length.

Package

open-location-code.

Source

open-location-code.lisp.

Methods
Method: code-length ((precision integer))

Return the code length as a function of the precision.

Method: code-length ((object code-area))

Return the code length of the original code.

Generic Function: north-east-corner (object)

Return the upper latitude and longitude as multiple values. The upper bounds are not included in the code area except for the north pole.

Package

open-location-code.

Source

open-location-code.lisp.

Methods
Method: north-east-corner ((object code-area))
Generic Function: pad-characters (object)

Return the number of pad characters.

Package

open-location-code.

Source

open-location-code.lisp.

Methods
Method: pad-characters ((object code-area))

Return the number of pad characters in the original code.

Generic Function: precision (object)

Return the Open Location Code precision.

Package

open-location-code.

Source

open-location-code.lisp.

Methods
Method: precision ((length integer))

Return the precision as a function of the code length.

Method: precision ((object code-area))

Return the precision of the original code.

Generic Function: separator-position (object)

Return the position of the separator character.

Package

open-location-code.

Source

open-location-code.lisp.

Methods
Method: separator-position ((object code-area))

Return the position of the separator character in the original code.

Generic Function: south-west-corner (object)

Return the lower latitude and longitude as multiple values.

Package

open-location-code.

Source

open-location-code.lisp.

Methods
Method: south-west-corner ((object code-area))

5.1.3 Conditions

Condition: code-error

Base class for all Open Location Code errors.

Package

open-location-code.

Source

open-location-code.lisp.

Direct superclasses

type-error.

Direct subclasses
Condition: code-length-error

Condition for an invalid Open Location Code length.

Package

open-location-code.

Source

open-location-code.lisp.

Direct superclasses

code-error.

Condition: full-code-error

Condition for an invalid full Open Location Code.

Package

open-location-code.

Source

open-location-code.lisp.

Direct superclasses

invalid-code-error.

Condition: invalid-code-error

Condition for an invalid Open Location Code.

Package

open-location-code.

Source

open-location-code.lisp.

Direct superclasses

code-error.

Direct subclasses
Condition: short-code-error

Condition for an invalid short Open Location Code.

Package

open-location-code.

Source

open-location-code.lisp.

Direct superclasses

invalid-code-error.


5.1.4 Classes

Class: code-area

Area covered by an Open Location Code.

Package

open-location-code.

Source

open-location-code.lisp.

Direct methods
Direct slots
Slot: south

Lower latitude of the code area in degree angle.

Type

real

Initform

0

Slot: west

Lower longitude of the code area in degree angle.

Type

real

Initform

0

Slot: height

Height of the code area in degree angle.

Type

real

Initform

0

Slot: width

Width of the code area in degree angle.

Type

real

Initform

0

Slot: precision

Precision of the original code.

Type

fixnum

Initform

0

Slot: length

Code length of the original code.

Package

common-lisp.

Type

fixnum

Initform

0

Slot: plus

Position of the separator character in the original code.

Type

fixnum

Initform

0

Slot: pad

Number of pad characters in the original code.

Type

fixnum

Initform

0


5.2 Internals


5.2.1 Constants

Constant: +alphabet+

Set of valid digits, i.e. encoding characters. The character position is equal to the decimal value, i.e. weight, of the digit.

Package

open-location-code.

Source

open-location-code.lisp.

Constant: +area-height+

Vector of code area heights in descending order. Element position is the precision of the code area.

Package

open-location-code.

Source

open-location-code.lisp.

Constant: +area-width+

Vector of code area widths in descending order. Element position is the precision of the code area.

Package

open-location-code.

Source

open-location-code.lisp.

Constant: +block-divisor+

Divisor when splitting a block into sub-blocks.

Package

open-location-code.

Source

open-location-code.lisp.

Constant: +grid-columns+

Number of grid columns.

Package

open-location-code.

Source

open-location-code.lisp.

Constant: +grid-rows+

Number of grid rows.

Package

open-location-code.

Source

open-location-code.lisp.

Constant: +maximum-length+

Maximum code length excluding the plus sign character.

Package

open-location-code.

Source

open-location-code.lisp.

Constant: +maximum-precision+

Maximum number of discretization steps.

Package

open-location-code.

Source

open-location-code.lisp.


5.2.2 Macros

Macro: defconst (name value &optional doc)

Define a constant variable.

This is like ‘defconstant’ except that the initially set value is reused when the ‘defconst’ form is evaluated again.

Package

open-location-code.

Source

open-location-code.lisp.

Macro: defsubst (name arg-list &body body)

Define an inline function.

This is like ‘defun’ except that the function is globally marked for inline expansion by the compiler.

Package

open-location-code.

Source

open-location-code.lisp.


5.2.3 Ordinary functions

Function: analyse (code &optional area)

Analyse an Open Location Code.

First argument CODE is the Open Location Code (an object).
If optional second argument AREA is non-null, secondary value
is a code area object.

Primary value is ‘:full’ or ‘:short’ if CODE is a valid full or short Open Location Code respectively. Otherwise, all values are null.

Package

open-location-code.

Source

open-location-code.lisp.

Function: area-size (precision)

Return the height and width of a code area as multiple values.

Argument PRECISION is the number of discretization steps.

Package

open-location-code.

Source

open-location-code.lisp.

Function: digit (value)

Return the digit for a decimal value.

Argument VALUE has to be a non-negative integer less than 20.

Value is the digit, i.e. encoding character.

Package

open-location-code.

Source

open-location-code.lisp.

Function: digitp (char)

True if CHAR is a valid digit.

Argument CHAR has to be a character.

Value is the decimal value, i.e. weight, of the digit, or null if CHAR is an invalid digit.

Package

open-location-code.

Source

open-location-code.lisp.

Function: length-from-precision (precision)

Return the code length as a function of the precision.

Package

open-location-code.

Source

open-location-code.lisp.

Function: normalize-location (latitude longitude precision)

Clip LATITUDE to the half-closed interval [-90, 90) and normalize LONGITUDE to the half-closed interval [-180, 180). Third argument PRECISION is used to determine the height of the code area if LATITUDE denotes the north pole.

Values are latitude, longitude, and the actual precision.

Package

open-location-code.

Source

open-location-code.lisp.

Function: normalize-location* (latitude longitude precision)

Like ‘normalize-location’ but return latitude and longitude as non-negative numbers, i.e. add 90° to the latitude and 180° to the longitude.

Package

open-location-code.

Source

open-location-code.lisp.

Function: precision-from-length (length)

Return the precision as a function of the code length.

Package

open-location-code.

Source

open-location-code.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   A   C   D   E   F   G   L   M   N   P   R   S   V  
Index Entry  Section

A
analyse: Private ordinary functions
area-size: Private ordinary functions

C
center: Public generic functions
center: Public generic functions
code-length: Public generic functions
code-length: Public generic functions
code-length: Public generic functions

D
decode: Public ordinary functions
defconst: Private macros
defsubst: Private macros
digit: Private ordinary functions
digitp: Private ordinary functions

E
encode: Public ordinary functions

F
fullp: Public ordinary functions
Function, analyse: Private ordinary functions
Function, area-size: Private ordinary functions
Function, decode: Public ordinary functions
Function, digit: Private ordinary functions
Function, digitp: Private ordinary functions
Function, encode: Public ordinary functions
Function, fullp: Public ordinary functions
Function, length-from-precision: Private ordinary functions
Function, normalize-location: Private ordinary functions
Function, normalize-location*: Private ordinary functions
Function, precision-from-length: Private ordinary functions
Function, recover: Public ordinary functions
Function, shorten: Public ordinary functions
Function, shortp: Public ordinary functions
Function, validp: Public ordinary functions

G
Generic Function, center: Public generic functions
Generic Function, code-length: Public generic functions
Generic Function, north-east-corner: Public generic functions
Generic Function, pad-characters: Public generic functions
Generic Function, precision: Public generic functions
Generic Function, separator-position: Public generic functions
Generic Function, south-west-corner: Public generic functions

L
length-from-precision: Private ordinary functions

M
Macro, defconst: Private macros
Macro, defsubst: Private macros
Method, center: Public generic functions
Method, code-length: Public generic functions
Method, code-length: Public generic functions
Method, north-east-corner: Public generic functions
Method, pad-characters: Public generic functions
Method, precision: Public generic functions
Method, precision: Public generic functions
Method, separator-position: Public generic functions
Method, south-west-corner: Public generic functions

N
normalize-location: Private ordinary functions
normalize-location*: Private ordinary functions
north-east-corner: Public generic functions
north-east-corner: Public generic functions

P
pad-characters: Public generic functions
pad-characters: Public generic functions
precision: Public generic functions
precision: Public generic functions
precision: Public generic functions
precision-from-length: Private ordinary functions

R
recover: Public ordinary functions

S
separator-position: Public generic functions
separator-position: Public generic functions
shorten: Public ordinary functions
shortp: Public ordinary functions
south-west-corner: Public generic functions
south-west-corner: Public generic functions

V
validp: Public ordinary functions