vpf_util.h

Go to the documentation of this file.

/*! \file
  \brief  Util functions for VPF

  \par Copyright Information

  Copyright (c) 2017 The DiSTI Corporation.<br>
  11301 Corporate Blvd; Suite 100<br>
  Orlando, Florida 32817<br>
  USA<br>
  <br>
  All rights reserved.<br>

  This Software contains proprietary trade secrets of DiSTI and may not be
reproduced, in whole or part, in any form, or by any means of electronic,
mechanical, or otherwise, without the written permission of DiSTI.  Said
permission may be derived through the purchase of applicable DiSTI product
licenses which detail the distribution rights of this content and any
Derivative Works based on this or other copyrighted DiSTI Software.

  NO WARRANTY. THE SOFTWARE IS PROVIDED "AS-IS," WITHOUT WARRANTY OF ANY KIND,
AND ANY USE OF THIS SOFTWARE PRODUCT IS AT YOUR OWN RISK. TO THE MAXIMUM EXTENT
PERMITTED BY APPLICABLE LAW, DISTI AND ITS SUPPLIERS DISCLAIM ALL WARRANTIES
AND CONDITIONS, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY AND/OR FITNESS FOR A
PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITH REGARD TO THE SOFTWARE.

  LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW,
IN NO EVENT SHALL DISTI OR ITS SUPPLIERS BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION,
DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS
INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR
INABILITY TO USE THE SOFTWARE, EVEN IF DISTI HAS BEEN ADVISED OF THE POSSIBILITY
OF SUCH DAMAGES.  DISTI'S ENTIRE LIABILITY AND YOUR EXCLUSIVE REMEDY SHALL NOT
EXCEED FIVE DOLLARS (US$5.00).

  The aforementioned terms and restrictions are governed by the laws of the
State of Florida and the United States of America.

*/
#ifndef _VPF_UTIL_H
#define _VPF_UTIL_H

#include <float.h>
#include <stdlib.h>
#include <string.h>

#if !defined( _WIN32 )
#    include <math.h>
#endif

#if defined( DISTI_VPF_DEBUG )
#    include <stdio.h>
#endif // DISTI_VPF_DEBUG

// turn on DistiVPFAssert when DISTI_VPF_DEBUG is defined
#if defined( DISTI_VPF_DEBUG )
#    include <assert.h>
#    if defined( _WIN32 )
#        if defined( GLS_DEBUG )
// use assert macro in DISTI_VPF_DEBUG / _WIN32 / _DEBUG builds
#            define DistiVPFAssert( _expr ) assert( ( _expr ) )
#        else
// use breakpt interrupt in DISTI_VPF_DEBUG / _WIN32 / non _DEBUG builds
#            define DistiVPFAssert( _expr ) \
                if( !( _expr ) )            \
                {                           \
                    __asm int 3             \
                }
#        endif // _DEBUG
#    else
// use assert macro in DISTI_VPF_DEBUG / non _WIN32 builds
#        define DistiVPFAssert( _expr ) assert( ( _expr ) )
#    endif // _WIN32
#else
// disable DistiVPFAssert when DISTI_VPF_DEBUG is not defined
#    define DistiVPFAssert( _expr )
#endif // DISTI_VPF_DEBUG

namespace disti
{
/** collection of VPF related utility functions, types, and constants */
class VPFUtil
{
public:
    static const char* const DHT_NAME;               /**< name of database header table */
    static const char* const LAT_NAME;               /**< name of library attribute table */
    static const char* const BROWSE_LIB_NAME;        /**< name of browse library */
    static const char* const LHT_NAME;               /**< name of library header table */
    static const char* const GRT_NAME;               /**< name of geographic reference table */
    static const char* const CAT_NAME;               /**< name of coverage attribute table */
    static const char* const FCS_NAME;               /**< name of feature class schema table */
    static const char* const FCA_NAME;               /**< name of feature class attribute table */
    static const char* const NRAT_NAME;              /**< name of notes related attribute table */
    static const char* const CVDT_NAME;              /**< name of character value descriptor table */
    static const char* const IVDT_NAME;              /**< name of integer value descriptor table */
    static const char* const CND_NAME;               /**< name of connected node primitive table */
    static const char* const END_NAME;               /**< name of entity node primitive table */
    static const char* const EDG_NAME;               /**< name of edge primitive table */
    static const char* const FAC_NAME;               /**< name of face primitive table */
    static const char* const TXT_NAME;               /**< name of text primitive table */
    static const char* const RNG_NAME;               /**< name of ring table */
    static const char* const EBR_NAME;               /**< name of edge bounding rectangle table */
    static const char* const FBR_NAME;               /**< name of face bounding rectangle table */
    static const char* const TILEREF_COV_NAME;       /**< name of the tileref coverage */
    static const char* const LIBREF_COV_NAME;        /**< name of the libref coverage */
    static const char* const LIB_COV_NAME;           /**< name of the library coverage */
    static const char* const TILEREF_AFT_NAME;       /**< name of the tileref area feature table */
    static const char* const LIBREF_LFT_NAME;        /**< name of the libref line feature table */
    static const char* const POINT_FEATURE_EXT;      /**< file extension for a point feature table */
    static const char* const LINE_FEATURE_EXT;       /**< file extension for a line feature table */
    static const char* const AREA_FEATURE_EXT;       /**< file extension for an area feature table */
    static const char* const TEXT_FEATURE_EXT;       /**< file extension for a text feature table */
    static const char* const LINE_FEATURE_JOIN_EXT;  /**< file extension for a line join table */
    static const char* const AREA_FEATURE_JOIN_EXT;  /**< file extension for an area join table */
    static const char* const COMPLEX_FEATURE_EXT;    /**< file extension for a complex feature table */
    static const char* const ID_COLUMN_NAME;         /**< name of ID column in any VPF table (always first column) */
    static const char* const TILE_ID_COLUMN_NAME;    /**< name of tile ID column in a VPF table */
    static const char* const END_ID_COLUMN_NAME;     /**< name of entity node ID column in a VPF table */
    static const char* const RIGHT_FACE_COLUMN_NAME; /**< name of right face column in a VPF table */
    static const char* const LEFT_FACE_COLUMN_NAME;  /**< name of left face column in a VPF table */
    static const char* const RIGHT_EDGE_COLUMN_NAME; /**< name of right edge column in a VPF table */
    static const char* const LEFT_EDGE_COLUMN_NAME;  /**< name of left edge column in a VPF table */
    static const char* const EDGE_ID_COLUMN_NAME;    /**< name of edge ID column in a VPF table */
    static const char* const TEXT_ID_COLUMN_NAME;    /**< name of text ID column in a VPF table */
    static const char* const FACC_CODE_COLUMN_NAME;  /**< name of facc code column in a VPF table */

    enum
    {
        FACC_CODE_LENGTH = 5u
    }; /**< length of a FACC code in a VPF table _not_ including a terminator */

    typedef float          Float32; /**< 32-bit floating point */
    typedef double         Float64; /**< 64-bit floating point */
    typedef unsigned short UInt16;  /**< 16-bit VPF unsigned integer */
    typedef unsigned int   UInt32;  /**< 32-bit VPF unsigned integer */

    /** enum of byte ordering modes */
    enum EndianMode
    {
        ENDIAN_MODE_LITTLE,
        ENDIAN_MODE_BIG
    };

    /** possible VPF data types */
    enum DataType
    {
        DATA_TYPE_TEXT,              /**< text */
        DATA_TYPE_TEXT_LATIN,        /**< text Level 1, Latin 1 - ISO 8859 */
        DATA_TYPE_TEXT_FULL_LATIN,   /**< text Level 2, Full Latin - ISO 6937 */
        DATA_TYPE_TEXT_MULTILINGUAL, /**< text Level 3, Multilingual ISO 10646 */
        DATA_TYPE_SHORT_FLOAT,       /**< IEEE 784 single precision float 32-bits */
        DATA_TYPE_LONG_FLOAT,        /**< IEEE 784 double precision float 64-bits */
        DATA_TYPE_SHORT_INTEGER,     /**< 16-bit integer */
        DATA_TYPE_LONG_INTEGER,      /**< 32-bit integer */
        DATA_TYPE_2D_COORD_SHORT,    /**< 2D coordinate of short float */
        DATA_TYPE_2D_COORD_LONG,     /**< 2D coordinate of long float */
        DATA_TYPE_3D_COORD_SHORT,    /**< 3D coordinate of short float */
        DATA_TYPE_3D_COORD_LONG,     /**< 3D coordinate of long float */
        DATA_TYPE_DATE_TIME,         /**< Date and Time */
        DATA_TYPE_NULL,              /**< NULL field */
        DATA_TYPE_TRIPLET            /**< Triplet ID */
    };

    /** possible VPF table column key types */
    enum KeyType
    {
        KEY_TYPE_PRIMARY,    /**< primary key */
        KEY_TYPE_UNIQUE,     /**< unique key */
        KEY_TYPE_NON_UNIQUE, /**< non unique key */
    };

    /** possible VPF feature types */
    enum FeatureType
    {
        FEATURE_TYPE_POINT,
        FEATURE_TYPE_LINE,
        FEATURE_TYPE_AREA,
        FEATURE_TYPE_TEXT,
        FEATURE_TYPE_COMPLEX
    };

    /** security classifications */
    enum SecurityClass
    {
        SECURITY_CLASS_TOP_SECRET,
        SECURITY_CLASS_SECRET,
        SECURITY_CLASS_CONFIDENTIAL,
        SECURITY_CLASS_RESTRICTED,
        SECURITY_CLASS_UNCLASSIFIED
    };

    /** 2D float coord */
    struct Coord2DShort
    {
        Float32 x, y;
    };

    /** 2D double coord */
    struct Coord2DLong
    {
        Float64 x, y;
    };

    /** 3D float coord */
    struct Coord3DShort
    {
        Float32 x, y, z;
    };

    /** 3D double coord */
    struct Coord3DLong
    {
        Float64 x, y, z;
    };

    /** VPF triplet contains information for crossing tile boundaries */
    struct Triplet
    {
        bool   rowIDValid;
        UInt32 rowID;
        bool   tileIDValid;
        UInt32 tileID;
        bool   externalIDValid;
        UInt32 externalID;
        bool   reservedValid;
        UInt32 reserved;
    };

    /** VPF date and time string */
    struct DateTime
    {
        enum
        {
            DATE_TIME_LENGTH = 20u
        }; /**< length of a date time field */

        char dateStr[ DATE_TIME_LENGTH + 1u ]; /**< date and time plus one for terminator */
    };

#if defined( DISTI_VPF_DEBUG )
    /** debug class for trapping when a bool is set to false with operator= */
    class WarningBool
    {
    public:
        /** Ctor
              * \param initialVal initial boolean value (does not warn here if false)
              */
        WarningBool( const bool initialVal )
            : _val( initialVal )
        {}

        /** Assign a boolean value - warn if false
              * \param val new value 
              * \return ref to this
              */
        WarningBool& operator=( const bool val );

        /** Get the contained boolean value
              * \return contained boolean value
              */
        operator bool( void ) const { return ( _val ); }

    protected:
        bool _val; /**< actual boolean value */
    };
#else
    typedef bool WarningBool;
#endif // DISTI_VPF_DEBUG

    /** encapsulates a growable array of pointers */
    template<class T>
    class PointerArray
    {
    public:
        /** default initial size of array */
        enum
        {
            DEFAULT_INITIAL_SIZE = 16u
        };

        /** Ctor 
          * \param initialSize [optional, defaults to DEFAULT_INITIAL_SIZE] initial size of array (>0)
          */
        PointerArray( const unsigned int initialSize = DEFAULT_INITIAL_SIZE )
            : _isValid( false )
            , _arraySize( initialSize )
            , _arrayCount( 0u )
            , _pointers( NULL )
        {
            _isValid  = ( _arraySize > 0u );
            _pointers = (T**)( _isValid ? malloc( sizeof( T* ) * _arraySize ) : NULL );
            _isValid  = ( NULL != _pointers );

            // clear pointer array
            if( _isValid )
            {
                memset( _pointers, 0, sizeof( T* ) * _arraySize );
            }
        }

        /** Dtor */
        ~PointerArray()
        {
            if( NULL != _pointers )
            {
                // destroy objects
                for( unsigned int index = 0u; index < _arrayCount; ++index )
                {
                    delete( _pointers[ index ] );
                    _pointers[ index ] = NULL;
                }

                // destroy pointer array
                free( _pointers );
                _pointers = NULL;
            }
        }

        /** Insert a pointer into the array at the end of the array
          * \param p pointer to add (non NULL)
          * \return true on success else false
          */
        bool InsertPointer( T* const p )
        {
            bool success = ( _isValid && ( NULL != p ) );

            if( success )
            {
                // need to grow array ?
                if( _arrayCount == _arraySize )
                {
                    // grow array (double size)
                    const unsigned int newArraySize = ( 2u * _arraySize );
                    T**                newArray     = (T**)realloc( _pointers, sizeof( T* ) * newArraySize );
                    _isValid = success = ( NULL != newArray );

                    if( success )
                    {
                        // clear added pointers
                        memset( &( newArray[ _arraySize ] ), 0, sizeof( T* ) * _arraySize );
                        // store new array and size
                        _pointers  = newArray;
                        _arraySize = newArraySize;
                    }
                }

                // insert if (any) grow array operation succeeded
                if( success )
                {
                    // insert new pointer
                    _pointers[ _arrayCount++ ] = p;
                }
            }

            return ( success );
        }

        /** Move a pointer from one index in the array to another index in the array.
          * array elements are shifted down accordingly.
          * \param curIndex current index of pointer
          * \param newIndex new desired index of pointer
          * \return true if success else false
          */
        bool MovePointer( const unsigned int curIndex, const unsigned int newIndex )
        {
            bool success = ( _isValid && ( curIndex < _arrayCount ) && ( newIndex < _arrayCount ) );

            if( success )
            {
                // hold temp copy of pointer to move
                T* const temp = _pointers[ curIndex ];

                // remove pointer (move up pointers after this pointer)
                {
                    for( unsigned int index = ( curIndex + 1u ); index < _arrayCount; ++index )
                    {
                        _pointers[ index - 1u ] = _pointers[ index ];
                    }
                }

                {
                    // move back pointers after the new pointer index
                    for( unsigned int index = ( _arrayCount - 1u ); index > newIndex; --index )
                    {
                        _pointers[ index ] = _pointers[ index - 1u ];
                    }
                }

                // store pointer into new location
                _pointers[ newIndex ] = temp;
            }

            return ( success );
        }

        /** Get number of pointers in the array
          * \return number of pointers in the array
          */
        unsigned int GetCount( void ) const { return ( _arrayCount ); }

        /** Get a pointer in the array
          * \param index zero based index into array
          * \return pointer at index else NULL
          */
        T* GetPointer( const unsigned int index )
        {
            return ( ( ( NULL != _pointers ) && ( index < _arrayCount ) ) ? _pointers[ index ] : NULL );
        }

        /** Get a const pointer in the array
          * \param index zero based index into array
          * \return pointer at index else NULL
          */
        const T* GetPointer( const unsigned int index ) const
        {
            return ( ( ( NULL != _pointers ) && ( index < _arrayCount ) ) ? _pointers[ index ] : NULL );
        }

        /** Determine if the array is in a valid state
          * \return true if valid else false
          */
        bool IsValid( void ) const { return ( _isValid ); }

    protected:
        WarningBool  _isValid;    /**< true if array is valid else false */
        unsigned int _arraySize;  /**< length of _pointers pointer array */
        unsigned int _arrayCount; /**< number of elements in _pointers pointer array */
        T**          _pointers;   /**< array of T pointers */

    private:
        // Disable implicit generated members
        PointerArray& operator=( const PointerArray& rhs );
        PointerArray( const PointerArray& src );
    };

    /** encapsulates full path / full filename to a directory / file */
    class FilePath
    {
    public:
        /** directory separator char */
        static const char DIR_SEPARATOR;

        /** Ctor */
        FilePath( void );

        /** copy Ctor */
        FilePath( const FilePath& src );

        /** Construct from a path
          * \param path path
          * \param isDirectory true if path is a directory path else false
          */
        FilePath( const char* const path, const bool isDirectory );

        /** Append a filename or directory name. Check IsValid()
          * \param name name of file or directory (should not end in DIR_SEPARATOR)
          * \param isDirectory true if appending a directory name else false
          * \param forceUpperCase [optional, defaults to true] true to force appended string to all uppercase
          * \param killTrailingWS [optional, defaults to true] true to kill any traling whitespace in appended string
          * \return updated path string
          */
        const char* Append( const char* const name, const bool isDirectory, const bool forceUpperCase = true,
            const bool killTrailingWS = true );

        /** Determine if the path is valid
          * \return true if valid else false
          */
        bool IsValid( void ) const { return ( _isValid ); }

        /** Get the file path string
          * \return the file path string
          */
        const char* GetFilePath( void ) const { return ( _pathStr ); }

    protected:
        /** longest possible path */
        enum
        {
            MAX_PATH_LENGTH = 512
        };

        WarningBool _isValid;                         /**< true if path is valid else false */
        char        _pathStr[ MAX_PATH_LENGTH + 1u ]; /**< full path plus terminator */

    private:
        // Disable implicit generated members
        FilePath& operator=( const FilePath& rhs );
    };

    /**  Construct an UInt16 from tow bytes of data read from a VPF file, correcting for
      * source and target endian mode as needed.
      * \param intData tow bytes of data
      * \param srcMode endian mode of intData
      * \return UInt16 integer value
      */
    static UInt32 DecodeUInt16( const unsigned char* const intData, const EndianMode srcMode );

    /**  Construct an UInt32 from four bytes of data read from a VPF file, correcting for
      * source and target endian mode as needed.
      * \param intData four bytes of data
      * \param srcMode endian mode of intData
      * \return UInt32 integer value
      */
    static UInt32 DecodeUInt32( const unsigned char* const intData, const EndianMode srcMode );

    /**  Construct a Float32 from four bytes of data read from a VPF file, correcting for
      * source and target endian mode as needed.
      * \param floatData four bytes of data
      * \param srcMode endian mode of floatData
      * \return Float32 value
      */
    static Float32 DecodeFloat32( const unsigned char* const floatData, const EndianMode srcMode );

    /**  Construct a Float64 from eight bytes of data read from a VPF file, correcting for
      * source and target endian mode as needed.
      * \param floatData eight bytes of data
      * \param srcMode endian mode of floatData
      * \return Float64 value
      */
    static Float64 DecodeFloat64( const unsigned char* const floatData, const EndianMode srcMode );

    /** Determine if the given Float32 is a NULL value
      * \param f Float32 in question
      * \return true if NULL else false
      */
    static bool IsFloat32NULL( const Float32 f )
    {
#ifdef _WIN32
        return ( 0 != _isnan( f ) );
#else
        return ( 0 != isnan( f ) );
#endif
    }

    /** Determine if the given Float64 is a NULL value
      * \param f Float64 in question
      * \return true if NULL else false
      */
    static bool IsFloat64NULL( const Float64 f )
    {
#ifdef _WIN32
        return ( 0 != _isnan( f ) );
#else
        return ( 0 != isnan( f ) );
#endif
    }

    /** Determine if the given UInt16 is NULL value
      * \param i UInt16 in question
      * \return true if NULL else false
      */
    static bool IsUInt16NULL( const UInt16 i ) { return ( UINT16_NULL_VALUE == i ); }

    /** Determine if the given UInt32 is NULL value
      * \param i UInt32 in question
      * \return true if NULL else false
      */
    static bool IsUInt32NULL( const UInt32 i ) { return ( UINT32_NULL_VALUE == i ); }

    /** Determine if the given text value is a NULL value
      * \param txt text in question
      * \return true if NULL text value else NULL
      */
    static bool IsTextNULL( const char* const txt )
    {
        return ( ( NULL != txt ) && VPFUtil::StricmpWS( "N/A", txt ) );
    }

    /** Kill any trailing white space in the given string
      * \param src string in question
      */
    static void KillTrailingWS( char* const src );

    /** Perform a lower case comparison of the two strings, stopping at the first whitespace character
      * \param s1 first string to compare
      * \param s2 second string to compare
      * \return true if strings match else false
      */
    static bool StricmpWS( const char* const s1, const char* const s2 );

    /** Determine if a file exists
      * \param fname name of file
      * \return true if file exists else false
      */
    static bool FileExists( const char* const fname );

    /** Decode a feature type character indicator from a VPF table into a feature type
      * \param featTypeChar feature type character indicator
      * \param &featType [out] gets feature type on success
      * \return true on success else false
      */
    static bool DecodeFeatureType( const char featTypeChar, FeatureType& featType );

    /** Decode a security class character indicator from a VPF table into a security class
      * \param securityClassChar security class character indicator
      * \param &securityClass [out] gets security class on success
      * \return true on success else false
      */
    static bool DecodeSecurityClass( const char securityClassChar, SecurityClass& securityClass );

protected:
    /** a NULL UInt16 value */
    enum
    {
        UINT16_NULL_VALUE = 0x8000u
    };
    /** a NULL UInt32 value */
    enum
    {
        UINT32_NULL_VALUE = 0x80000000U
    };

    static const EndianMode _targetEndianMode; /**< endian mode of target architecture */

    /**  Swap (reverse) the given two byte buffer if its endian mode does not match the
      * mode of the endian mode of the target architecture
      * \param src source data to swap (must be at least 2 bytes long)
      * \param dst [out] receives potentially swapped data (must be at least 2 bytes long)
      * \param srcMode endian mode of source data
      */
    static void SwapTwo( const unsigned char* const src, unsigned char* const dst, const EndianMode srcMode );

    /**  Swap (reverse) the given four byte buffer if its endian mode does not match the
      * mode of the endian mode of the target architecture
      * \param src source data to swap (must be at least 4 bytes long)
      * \param dst [out] receives potentially swapped data (must be at least 4 bytes long)
      * \param srcMode endian mode of source data
      */
    static void SwapFour( const unsigned char* const src, unsigned char* const dst, const EndianMode srcMode );

    /**  Swap (reverse) the given eight byte buffer if its endian mode does not match the
      * mode of the endian mode of the target architecture
      * \param src source data to swap (must be at least 8 bytes long)
      * \param dst [out] receives potentially swapped data (must be at least 8 bytes long)
      * \param srcMode endian mode of source data
      */
    static void SwapEight( const unsigned char* const src, unsigned char* const dst, const EndianMode srcMode );
};

} // end namespace disti

#endif // _VPF_UTIL_H