/*
 * Copyright 2026 Hypergiant Galactic Systems Inc. All rights reserved.
 * This file is licensed to you under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License. You may obtain a copy
 * of the License at https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software distributed under
 * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
 * OF ANY KIND, either express or implied. See the License for the specific language
 * governing permissions and limitations under the License.
 */

import { CoordinateInput, CoordinateInternalValue, CoordinateObject, CoordinateTuple, LatLonTuple, LonLatTuple } from "./latlon/internal/normalize.js";
import { Format } from "./latlon/internal/index.js";
import { CoordinateSystem } from "./latlon/internal/coordinate-system.js";

//#region src/coordinates/coordinate.d.ts
type Coordinate = {
  /** {@interitDoc Formatter} */
  dd: Formatter;
  /** {@interitDoc Formatter} */
  ddm: Formatter;
  /** {@interitDoc Formatter} */
  dms: Formatter;
  /** {@interitDoc Formatter} */
  mgrs: Formatter;
  /** {@interitDoc Formatter} */
  utm: Formatter;
  errors: string[];
  raw: CoordinateInternalValue;
  valid: boolean;
};
/**
 * Output a string value of a coordinate using an available system. The
 * original value is preserved without conversion to an internal
 * representation - Decimal Degrees - to prevent the possibility of
 * rounding errors. All alternative values are computed from a common
 * internal value to reduce complexity.
 *
 * @link https://en.wikipedia.org/wiki/Coordinate_system
 *
 * @remarks
 * pure function
 *
 * @example
 * ```typescript
 * const create = createCoordinate(coordinateSystems.dd, 'LATLON')
 * const coord = create('89.765432109 / 123.456789012')
 *
 * // honors the instantiation format 'LATLON'
 * coord.dd() === '89.765432109 N / 123.456789012 E'
 * coord.ddm() === '89 45.92592654 N / 123 27.40734072 E'
 * coord.dms() === '89 45 55.5555924 N / 123 27 24.4404432 E'
 *
 * // change format to 'LONLAT'
 * coord.dms('LONLAT') === '123 27 24.4404432 E / 89 45 55.5555924 N'
 * ```
 */
type Formatter = (f?: Format) => string;
/**
 * Available coordinate systems for parsing, converting, and formatting geographic coordinates.
 *
 * Provides five coordinate notation systems:
 * - dd: Decimal Degrees
 * - ddm: Degrees Decimal Minutes
 * - dms: Degrees Minutes Seconds
 * - mgrs: Military Grid Reference System
 * - utm: Universal Transverse Mercator
 *
 * @example
 * ```typescript
 * const create = createCoordinate(coordinateSystems.dd, 'LATLON');
 * const coord = create('40.7128 / -74.0060');
 * ```
 *
 * @example
 * ```typescript
 * const createMGRS = createCoordinate(coordinateSystems.mgrs);
 * const coord = createMGRS('18T WL 80000 00000');
 * ```
 */
declare const coordinateSystems: Readonly<{
  readonly dd: CoordinateSystem;
  readonly ddm: CoordinateSystem;
  readonly dms: CoordinateSystem;
  readonly mgrs: CoordinateSystem;
  readonly utm: CoordinateSystem;
}>;
/**
 * Create a coordinate object enabling: lexing, parsing, validation, and
 * formatting in alternative systems and formats. The system and format will be
 * used for validation and eventually for output as defaults if no alternatives
 * are provided.
 *
 * @param initSystem - Coordinate system to use for parsing (dd, ddm, dms, mgrs, or utm from coordinateSystems). Defaults to Decimal Degrees.
 * @param initFormat - Coordinate format ordering (LATLON or LONLAT). Defaults to LATLON.
 * @returns Function that accepts coordinate string and returns Coordinate object with formatters.
 *
 * @remarks
 * pure function
 *
 * @example
 * ```typescript
 * const create = createCoordinate(coordinateSystems.dd, 'LATLON')
 * const coord = create('40.7128 / -74.0060')
 * coord.dd() // '40.7128 N / 74.006 W'
 * coord.dms() // '40 42 46.08 N / 74 0 21.6 W'
 * ```
 *
 * @example
 * ```typescript
 * const create = createCoordinate(coordinateSystems.ddm, 'LONLAT')
 * const coord = create('-74 0.36 / 40 42.768')
 * coord.ddm('LATLON') // '40 42.768 N / 74 0.36 W'
 * ```
 */
declare function createCoordinate(initSystem?: CoordinateSystem, initFormat?: Format): (input: CoordinateInput) => Coordinate;
//#endregion
export { type CoordinateInput, type CoordinateObject, type CoordinateTuple, type LatLonTuple, type LonLatTuple, coordinateSystems, createCoordinate };
//# sourceMappingURL=coordinate.d.ts.map