vpf_table_header.h

Go to the documentation of this file.

/*! \file
  \brief  The VPFTableHeader class.

  \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_TABLE_HEADER_H
#define _VPF_TABLE_HEADER_H

#include "vpf_util.h"

namespace disti
{
// forward ref
class VPFFile;

/** reads and encapsulates a VPF table header */
class VPFTableHeader
{
public:
    /**< VPF table column definition */
    class ColumnDefinition
    {
    public:
        /** Check structure facilitates ensuring that table header column definitions
          * match a known spec */
        struct Check
        {
            const char*       name;        /**< name of column */
            VPFUtil::DataType dataType;    /**< type of data in column */
            VPFUtil::KeyType  keyType;     /**< key type for column */
            int               numElements; /**< number of data elements in column (-1 for var length) */
        };

        /** Construct a VPF table column definition read from the given file.  Input file
          * should be "seeked" to beginning of column definition and will end "seeked" one past
          * end of column separator
          * \param infile input file to read description from
          */
        ColumnDefinition( VPFFile& infile );

        /** Dtor */
        ~ColumnDefinition();

        /** Determine if a valid column definition was read
         * \return true if valid else false
         */
        bool IsValid( void ) const { return ( _isValid ); }

        /** Get the name of the column
          * \return name of the column else "" if not valid
          */
        const char* GetName( void ) const { return ( _name ); };

        /** Get the data type of the column
         * \return data type of the column
         */
        VPFUtil::DataType GetDataType( void ) const { return ( _dataType ); }

        /** Get the number of data elements in the column
          * \return number of data elements in the column (-1 indicates variable length)
          */
        int GetNumberOfElements( void ) const { return ( _numElements ); }

        /** Get the key type for the column
          * \return key type for the column
          */
        VPFUtil::KeyType GetKeyType( void ) const { return ( _keyType ); }

        /** Get description of column
          * \return description of column else NULL if not valid
          */
        const char* GetDescription( void ) const { return ( _description ); }

        /** Get the value description table name of the column
          * \return value description table name of the column else "" if not valid
          */
        const char* GetValueDescriptionTableName( void ) const { return ( _valDescTableName ); }

        /** Get the thematic indexes name of the column
          * \return thematic indexes name of the column else "" if not valid
          */
        const char* GetThematicIndexName( void ) const { return ( _thematicIndexName ); }

        /** Get the narrative table name of the column
          * \return narrative table name of the column else "" if not valid
          */
        const char* GetNarrativeTableName( void ) const { return ( _narrativeTableName ); }

        /** Determine if this column definition matches the given column check
          * \param colCheck column check
          * \param colCanBeNULL [optional, defaults to false] true if column can optionally be a NULL data type
          *                     and pass this check test
          * \return true if matches else false
          */
        bool CheckDefinition( const Check& colCheck, const bool colCanBeNULL = false ) const;

    protected:
        enum
        {
            NAME_LENGTH = 17u
        }; /**< length of name field plus delimiter */
        enum
        {
            VAL_DESC_TABLE_NAME_LENGTH = 13u
        }; /**< length of value description table name plus delimeter */
        enum
        {
            THEMATIC_INDEXES_NAME_LENGTH = 13u
        }; /**< length of thematic index name plus delimiter */
        enum
        {
            NARRATIVE_TABLE_NAME_LENGTH = 13u
        }; /**< length of narrative table name plus delimiter */

        VPFUtil::WarningBool _isValid;                                                /**< true if a valid definition was read else false */
        char                 _name[ NAME_LENGTH + 1u ];                               /**< column name plus one for terminator */
        VPFUtil::DataType    _dataType;                                               /**< column data type */
        int                  _numElements;                                            /**< number of elements in column else -1 for variable length */
        VPFUtil::KeyType     _keyType;                                                /**< column key type */
        char*                _description;                                            /**< column description (meaning) */
        char                 _valDescTableName[ VAL_DESC_TABLE_NAME_LENGTH + 1u ];    /**< value description table name plus one for terminator */
        char                 _thematicIndexName[ THEMATIC_INDEXES_NAME_LENGTH + 1u ]; /**< thematic indexes name plus one for terminator */
        char                 _narrativeTableName[ NARRATIVE_TABLE_NAME_LENGTH + 1u ]; /**< narrative table name plus one for terminator */

        /**  Read the number of elements and populate _numElements accordingly.
          * _numElements gets -1 if variable length is indicated.  Input file should be
          * "seeked" to num elements field and will end "seeked" one past column def delimiter
          * \param infile input file to read number of elements
          * \return true on success else false
          */
        bool ReadNumElements( VPFFile& infile );

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

    /** array of column definition pointers */
    typedef VPFUtil::PointerArray<ColumnDefinition> ColumnDefinitionArray;

    /**  Read the table header from the given VPF file.  Infile will be "seeked" to just past
      * the header on success.
      * \param infile VPF file to read header from (must be "seeked" to start of file)
      */
    VPFTableHeader( VPFFile& infile );

    /**  Get the endian mode read from the table header
      * \return the endian mode from the table header
      */
    VPFUtil::EndianMode GetEndianMode( void ) const { return ( _endianMode ); }

    /**  Get the description from the table header
      * /return description from the table header
      */
    const char* GetDescription( void ) const { return ( _description ); }

    /**  Get the filename of a narrative file associated with the table header
      * \return narrative filename
      */
    const char* GetNarrativeFilename( void ) const { return ( _narrativeFile ); }

    /** Get the number of columns in the table
      * \return number of columns in the table
      */
    unsigned int GetColumnCount( void ) const { return ( _columnDefs.GetCount() ); }

    /** Get a column definition for a given column in the table
      * \param index zero based index into columns
      * \return column definition at index else NULL
     */
    const ColumnDefinition* GetColumnDefinition( unsigned int index ) const
    {
        return ( _columnDefs.GetPointer( index ) );
    }

    /** Find the column index to the column in the table header with the given column name
      * \param colName name of desired column
      * \param colIndex [out] receives zero based column index on success
      * \return true if column found else false
      */
    bool FindColumn( const char* const colName, unsigned int& colIndex ) const;

    /** \return True if the header was read successfully from the file */
    bool IsValid( void ) const { return ( _isValid ); }

protected:
    enum
    {
        DESCRIPTION_LENGTH = 81u
    }; /**< length of description field plus delimiter */
    enum
    {
        NARRATIVE_FILE_LENGTH = 13u
    }; /**< length of narrative filename plus delimiter */

    VPFUtil::WarningBool  _isValid;                                     /**< true if header was read successfully else false */
    VPFUtil::EndianMode   _endianMode;                                  /**< endian mode of data in table */
    char                  _description[ DESCRIPTION_LENGTH + 1u ];      /**< table description plus terminator */
    char                  _narrativeFile[ NARRATIVE_FILE_LENGTH + 1u ]; /**< narrative file name plus terminator */
    ColumnDefinitionArray _columnDefs;                                  /**< column definitions in header */

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

} // end namespace disti

#endif // _VPF_TABLE_HEADER_H