mi32/latlonfm.h

Go to the documentation of this file.

/**
 * \file mi32/latlonfm.h 
 * \brief Definitions for Latitude/Longitude format conversions
 *
 * \if NODOC
 * $Id: latlonfm.h_v 1.16 2007/01/08 21:19:54 dwilliss Exp $
 *
 * $Log: latlonfm.h_v $
 * Revision 1.16  2007/01/08 21:19:54  dwilliss
 * Added GetLatLonTypeList
 *
 * Revision 1.15  2004/11/22 15:58:01  mju
 * Add more precise formats for DDD MM SS.ss... formats.
 *
 * Revision 1.14  2004/03/22 18:52:58  dwilliss
 * moving 3 functions into geom.dll
 *
 * Revision 1.13  2003/10/01 16:21:05  dwilliss
 * Fixed doxygen error
 *
 * Revision 1.12  2003/09/25 21:29:07  dwilliss
 * Don't capitalize enum any more. Genitor needed it, doxygen doesn't like it.
 *
 * Revision 1.11  2003/09/15 13:49:56  fileserver!dwilliss
 * Doxygen
 *
 * Revision 1.10  2003/09/08 20:39:21  dwilliss
 * Added doxygen tags for start/end function groups
 *
 * Revision 1.9  2003/07/24 19:46:30  mju
 * Add conversion fn returning MISTRING to avoid buffer reuse issue.
 *
 * Revision 1.8  2003/06/03 16:42:12  scowan
 * Added listitemdef get standard conversion function.
 *
 * Revision 1.7  2002/09/09 13:52:06  mju
 * Remove deprecated #defines.
 *
 * Revision 1.6  2001/12/20 21:41:23  mju
 * Enum docs.
 *
 * Revision 1.5  2001/08/07 16:57:37  mju
 * Add FLAG_Longitude360.
 *
 * Revision 1.4  2000/05/25 13:50:20  mju
 * Add see-also comments.
 *
 * Revision 1.3  2000/05/25 13:14:08  mju
 * Need to include stddefns for MI_DLLIMPORT/EXPORT defns.
 *
 * Revision 1.2  2000/05/24 23:15:38  scowan
 * Moved some functions to dll.
 *
 * Revision 1.1  2000/05/11 15:51:54  mju
 * Initial revision
 * \endif
**/

#ifndef  INC_MI32_LATLONFM_H
#define  INC_MI32_LATLONFM_H

#ifndef  INC_STDDEFN_H
#include <mi32/stddefns.h>
#endif

#ifndef  INC_MI32_MISTRING_H
#include <mi32/mistring.h>
#endif

#ifndef  INC_MI32_SIMPLEAR_H
#include <mi32/simplear.h>
#endif

#ifdef GEOMDLL
   #define GEOMLIBEXPORT MI_DLLEXPORT
#else
   #define GEOMLIBEXPORT MI_DLLIMPORT
#endif

/*----------------------------------------------------------------------------*/
/*    Lat/Lon definitions for ConverLatLonType()                              */
/*----------------------------------------------------------------------------*/

#define DMSCONV_DecDegs       0x0001
#define DMSCONV_DDDMMSS       0x0002
#define DMSCONV_Seconds       0x0004
#define DMSCONV_DF            0x0010         //!< Direction tag in front
#define DMSCONV_DB            0x0020         //!< Direction tag in back
#define DMSCONV_FS            0x0040         //!< Fractional seconds
#define DMSCONV_FM            0x0080         //!< Fractional minutes
#define DMSCONV_CD            0x0100         //!< Can be a double value
#define DMSCONV_CW            0x0200         //!< Can be a word array
#define DMSCONV_PMask         0xF000         //!< Precision mask
#define DMSCONV_PShift        12             //!< Amount to shift precision flags
#define DMSCONV_1P            0x1000         //!< 1 decimal precision
#define DMSCONV_2P            0x2000         //!< 2 decimal precision
#define DMSCONV_3P            0x3000         //!< 3 decimal precision
#define DMSCONV_6P            0x6000         //!< 6 decimal precision

enum DMSTYPE {
   DMSTYPE_None =             0,
   DMSTYPE_DecDeg =           DMSCONV_DecDegs | DMSCONV_CD,
   DMSTYPE_IDecDeg =          DMSCONV_DecDegs | DMSCONV_DF | DMSCONV_CD,
   DMSTYPE_DDDdddddd =        DMSCONV_DecDegs | DMSCONV_CD | DMSCONV_6P,
   DMSTYPE_IDDDdddddd =       DMSCONV_DecDegs | DMSCONV_DF | DMSCONV_CD | DMSCONV_6P,
   DMSTYPE_DDDMMSS =          DMSCONV_DDDMMSS | DMSCONV_CD | DMSCONV_CW,
   DMSTYPE_IDDDMMSS =         DMSCONV_DDDMMSS | DMSCONV_DF | DMSCONV_CW,
   DMSTYPE_DDDMMSSI =         DMSCONV_DDDMMSS | DMSCONV_DB | DMSCONV_CW,
   DMSTYPE_DDDMMSSS =         DMSCONV_DDDMMSS | DMSCONV_CD | DMSCONV_1P,
   DMSTYPE_IDDDMMSSS =        DMSCONV_DDDMMSS | DMSCONV_DF | DMSCONV_1P,
   DMSTYPE_DDDMMSSSI =        DMSCONV_DDDMMSS | DMSCONV_DB | DMSCONV_1P,
   DMSTYPE_DDDMMSSSS =        DMSCONV_DDDMMSS | DMSCONV_CD | DMSCONV_2P,
   DMSTYPE_IDDDMMSSSS =       DMSCONV_DDDMMSS | DMSCONV_DF | DMSCONV_2P,
   DMSTYPE_DDDMMSSSSI =       DMSCONV_DDDMMSS | DMSCONV_DB | DMSCONV_2P,
   DMSTYPE_DDDMMSSSSS =       DMSCONV_DDDMMSS | DMSCONV_CD | DMSCONV_3P,
   DMSTYPE_IDDDMMSSSSS =      DMSCONV_DDDMMSS | DMSCONV_DF | DMSCONV_3P,
   DMSTYPE_DDDMMSSSSSI =      DMSCONV_DDDMMSS | DMSCONV_DB | DMSCONV_3P,
   DMSTYPE_DDDMMSS_SS =       DMSCONV_DDDMMSS | DMSCONV_2P | DMSCONV_CD | DMSCONV_CW,
   DMSTYPE_IDDDMMSS_SS =      DMSCONV_DDDMMSS | DMSCONV_2P | DMSCONV_DF | DMSCONV_CW,
   DMSTYPE_DDDMMSS_SSI =      DMSCONV_DDDMMSS | DMSCONV_2P | DMSCONV_DB | DMSCONV_CW,
   DMSTYPE_DDDMMSS_sss =      DMSCONV_DDDMMSS | DMSCONV_3P | DMSCONV_CD | DMSCONV_CW,
   DMSTYPE_IDDDMMSS_sss =     DMSCONV_DDDMMSS | DMSCONV_3P | DMSCONV_DF | DMSCONV_CW,
   DMSTYPE_DDDMMSS_sssI =     DMSCONV_DDDMMSS | DMSCONV_3P | DMSCONV_DB | DMSCONV_CW,
   DMSTYPE_DDDMMSS_ssssss =   DMSCONV_DDDMMSS | DMSCONV_6P | DMSCONV_CD | DMSCONV_CW,
   DMSTYPE_IDDDMMSS_ssssss =  DMSCONV_DDDMMSS | DMSCONV_6P | DMSCONV_DF | DMSCONV_CW,
   DMSTYPE_DDDMMSS_ssssssI =  DMSCONV_DDDMMSS | DMSCONV_6P | DMSCONV_DB | DMSCONV_CW,
   DMSTYPE_DDDMM_MM =         DMSCONV_DDDMMSS | DMSCONV_FM | DMSCONV_CD | DMSCONV_CW,
   DMSTYPE_IDDDMM_MM =        DMSCONV_DDDMMSS | DMSCONV_FM | DMSCONV_DF | DMSCONV_CW,
   DMSTYPE_DDDMM_MMI =        DMSCONV_DDDMMSS | DMSCONV_FM | DMSCONV_DB | DMSCONV_CW,
   DMSTYPE_Seconds =          DMSCONV_Seconds | DMSCONV_CD,
   DMSTYPE_ISeconds =         DMSCONV_Seconds | DMSCONV_DF,
   DMSTYPE_SecondsI =         DMSCONV_Seconds | DMSCONV_DB,
   };

enum CONVDMSFLAGS {
   CONVDMSFLAG_None =            0,
   CONVDMSFLAG_IN_String =       0x00010000,    //!< Input buffer is a char* string
   CONVDMSFLAG_IN_WArray =       0x00020000,    //!< Input buffer is Unicode string
   CONVDMSFLAG_IN_Double =       0x00040000,    //!< Input buffer is a double
   CONVDMSFLAG_OUT_String =      0x01000000,    //!< Output buffer is a char* string
   CONVDMSFLAG_OUT_WArray =      0x02000000,    //!< Output buffer is Unicode string
   CONVDMSFLAG_OUT_Double =      0x04000000,    //!< Output buffer is a double
   CONVDMSFLAG_OUT_PutSpaces =   0x10000000,    //!< Insert spaces between degrees, minutes, seconds if applicable
   CONVDMSFLAG_OUT_IsLatitude =  0x20000000,    //!< Use direction indicator for Latitude, otherwise Longitude assumed
   };
DEFINE_ENUM_OPERATORS(CONVDMSFLAGS);

struct DMSTYPEANDNAME {
   DMSTYPE type;
   TEXTID name;
   };

/*----------------------------------------------------------------------------*/
/*    Definitions for ConvertDegsToString()                                   */
/*----------------------------------------------------------------------------*/

enum DEGTOSTRFLAGS {
   DEGTOSTRFLAG_NoDir =          0x00000000,    //!< Don't include direction (N,S,E,W) indicator
   DEGTOSTRFLAG_Longitude =      0x00000001,    //!< Format as longitude
   DEGTOSTRFLAG_Latitude =       0x00000002,    //!< Format as latitude
   DEGTOSTRFLAG_DirLast =        0x00000010,    //!< Put direction indicator last
   DEGTOSTRFLAG_DecDegs =        0x00000020,    //!< Format as decimal degrees
   DEGTOSTRFLAG_DegDecMin =      0x00000040,    //!< Format as degrees and decimal minutes
   DEGTOSTRFLAG_DegMinSec =      0x00000080,    //!< Default if no other format specified
   DEGTOSTRFLAG_Longitude360 =   0x00000100,    //!< Display in range of W360 to E360
   };
DEFINE_ENUM_OPERATORS(DEGTOSTRFLAGS);


/*----------------------------------------------------------------------------*/
/*    Function Prototypes                                                     */
/*----------------------------------------------------------------------------*/

namespace MGUI {
#ifndef GENERATING_DOXYGEN_OUTPUT
struct LISTITEMDEF;
#endif // GENERATING_DOXYGEN_OUTPUT

//! Get the standard Latitude / Longitude format list
//! @return List of standard Latitude / Longitude convert to string formats, DO NOT FREE
//! \deprecated MGUI::LISTITEMDEF is deprecated.  Use GetLatLonTypeList.
const LISTITEMDEF* GetLatLonFormatList ();
}  // End namespace MGUI


//!:Associate with "Latitude/Longitude Format Conversions"
//!\addtogroup latlonconv Latitude/Longitude Format Conversions
//!@{

//! Convert Latitude or Longitude value to char* string.
//! @return Pointer to string
//!   @see ConvLatLonToString, ConvertStringToDegs
GEOMLIBEXPORT char* ConvertDegsToString (
   char* string,                       //!< String to hold result
   double value,                       //!< Value to convert in degrees
   DEGTOSTRFLAGS flags                 //!< Flags defining format
   );

//! Convert Latitude or Longitude value to MISTRING.
//! @return MISTRING containing converted value.
//!   @see ConvLatLonToString, ConvertStringToDegs
GEOMLIBEXPORT MISTRING ConvertDegsToString (
   double value,                       //!< Value to convert in degrees
   DEGTOSTRFLAGS flags                 //!< Flags defining format
   );

//! Convert Latitude or Longitude string to decimal degrees.
//!
//! @return true if successful, false if not
//!
//! This function automatically recognizes the following formats:
//!
//!      D ddd mm ss.sss         D indicates direction (N, S, E or W)
//!      D ddd mm.mmmm           and can be anywhere in the string
//!      D ddd.ddddd
//!
//!    [-]ddd mm ss.sss       Sign (+ or -) is optional
//!    [-]ddd mm.mmmm         Negative values indicate West and South
//!    [-]ddd.ddddd           Do not type brackets []
//!
//!   @see ConvertStringToLatLon, ConvertDegsToString
GEOMLIBEXPORT bool ConvertStringToDegs (
   const char* string,
   double* value
   );

//! Convert Latitude/Longitude value to string.
//!
//! @see ConvertDegsToString, ConvStringToLatLon
GEOMLIBEXPORT void ConvLatLonToString (
   double degrees,                     //!< Value to convert
   char *string,                       //!< String to hold result
   DMSTYPE desttype,                   //!< Destination format
   CONVDMSFLAGS flags                  //!< CONVDMS_OUT_...
   );

//! Convert value to decimal degrees and/or another LatLon format.
//!
//! @return Converted value in degrees.
GEOMLIBEXPORT double ConvLatLonValue (
   const void *srcbuf,                 //!< Pointer to source value, flags determine data type
   DMSTYPE srctype,                    //!< Source format
   void *destbuf,                      //!< Pointer to destination location, NULL if not needed
   DMSTYPE desttype,                   //!< Destination format
   CONVDMSFLAGS flags                  //!< Flags for input and output type
   );

//! Convert double-precision value to decimal degrees
//!
//! @return Converted value in degrees.
inline double ConvLatLonValue (
   double value,                       //!< Value to convert
   DMSTYPE srctype                     //!< Source format
   ) {
   return (ConvLatLonValue(&value,srctype,0,DMSTYPE_None,CONVDMSFLAG_IN_Double));
   }

//! Convert string to decimal degrees.
//!
//! @return Converted value in degrees.
//!
//!   @see ConvertStringToDegs, ConvLatLonToString
GEOMLIBEXPORT double ConvStringToLatLon (
   const char *string,                    //!< String to convert
   DMSTYPE srctype,                       //!< String format
   CONVDMSFLAGS flags = CONVDMSFLAG_None  //!< None presently used
   );

//! Retrieve list of built-in latitude-longitude string formats.
//!
//! @return NULL-terminated array of strings containing format names.
//! \deprecated Use GetLatLonTypeList
GEOMLIBEXPORT const char** GetLatLonNames (void);

//! Get latitude-longitude format conversion type for given index.
//!
//! @see ConvLatLonValue, ConvLatLonToString, ConvStringToLatLon
//! \deprecated Use GetLatLonTypeList
GEOMLIBEXPORT DMSTYPE GetLatLonType (
   int index
   );


//! Retrieve list of built-in latitude-longitude string formats.
//! 
//! @see ConvLatLonValue, ConvLatLonToString, ConvStringToLatLon
GEOMLIBEXPORT ERRVALUE GetLatLonTypeList (
   SIMPLE_ARRAY<DMSTYPEANDNAME>& types
   );

//!@}

#endif   // INC_MI32_LATLONFM_H

---