@pranavpatel.ca/algo-gridpointcode/dist/GPC.d.ts

Grid Point Code (GPC) is a global geocoding system that provides a unique, lossless, and compact alphanumeric code for any geographic location (home, office, or other places). It enables precise identification and offline conversion between geographic coo

/**
 * The GPC (Grid Point Code) class provides methods for encoding geographic
 * coordinates (latitude and longitude) into a compact alphanumeric string,
 * and decoding such strings back to coordinates.
 *
 * This implementation ensures consistency, precision, and compactness
 * using a custom base-27 encoding and a fixed 11-character format.
 */
export declare class GPC {
    private static readonly MIN_LAT;
    private static readonly MAX_LAT;
    private static readonly MIN_LONG;
    private static readonly MAX_LONG;
    private static readonly MAX_POINT;
    private static readonly ELEVEN;
    private static readonly CHARACTERS;
    private static readonly GPC_LENGTH;
    private static readonly LatLongTable;
    /**
     * Encodes a latitude and longitude into a Grid Point Code (GPC).
     * @param latitude Latitude in decimal degrees.
     * @param longitude Longitude in decimal degrees.
     * @param formatted Whether to format the GPC with separators (default: true).
     * @returns A formatted or raw 11-character GPC string.
     * @throws RangeError if coordinates are out of valid range.
     */
    static encode(latitude: number, longitude: number, formatted?: boolean): string;
    /**
     * Decodes a Grid Point Code (GPC) into latitude and longitude.
     * @param gridPointCode The encoded GPC string (formatted or raw).
     * @returns A tuple [latitude, longitude] in decimal degrees.
     * @throws Error or RangeError for null, malformed, or invalid GPC strings.
     */
    static decode(gridPointCode: string): [number, number];
    /**
     * Validates the latitude and longitude ranges.
     * @param latitude Latitude in decimal degrees.
     * @param longitude Longitude in decimal degrees.
     * @returns [true, ""] if valid, otherwise [false, "LATITUDE" or "LONGITUDE"].
     */
    static isValidCoordinates(latitude: number, longitude: number): [boolean, string];
    /**
     * Validates the given Grid Point Code (GPC).
     * @param gridPointCode GPC string to validate.
     * @returns [true, ""] if valid, otherwise [false, error message].
     */
    static isValid(gridPointCode: string): [boolean, string];
    /**
     * Converts latitude and longitude into a unique numeric point ID.
     * Used internally before encoding to base-27.
     * @param lat Latitude.
     * @param long Longitude.
     * @returns A bigint representing the point.
     */
    private static getPoint;
    /**
     * Converts a decimal coordinate to a 7-part array:
     * [sign, integer, fractional_digit1...fractional_digit5]
     * @param coord Coordinate value as number.
     * @returns An array of 7 integers.
     */
    private static splitTo7;
    /**
     * Encodes a numeric point into a base-27 GPC string.
     * @param point Bigint point number.
     * @returns Encoded GPC string (unformatted).
     */
    private static encodePoint;
    /**
     * Formats an 11-character GPC into #XXXX-XXXX-XXX layout.
     * @param gpc Unformatted 11-character GPC string.
     * @returns Formatted GPC string.
     */
    private static formatGPC;
    /**
     * Validates the character content and length of a GPC string.
     * @param gpc GPC string to validate.
     * @returns [true, ""] if valid, otherwise [false, error reason].
     */
    private static validateGPC;
    /**
     * Validates that the decoded point value is within allowed range.
     * @param point GPC-decoded point.
     * @returns [true, ""] if valid, otherwise [false, "GPC_RANGE"].
     */
    private static validatePoint;
    /**
     * Decodes an 11-character GPC string into a numeric point.
     * @param gpc GPC string (unformatted).
     * @returns Decoded point as bigint.
     */
    private static decodeToPoint;
    /**
     * Converts a valid point number into latitude and longitude.
     * @param point Valid GPC-decoded point.
     * @returns Tuple [latitude, longitude] in decimal degrees.
     */
    private static getCoordinates;
    /**
     * Reconstructs lat/long 7-part arrays from a point index and fractional component.
     * Used in decoding to rebuild original coordinate precision.
     * @param index Index from table lookup.
     * @param fractional The remaining digits of the point.
     * @returns A tuple of two arrays: [lat7[], long7[]]
     */
    private static splitPointTo7;
}