Data_Block.hh

Go to the documentation of this file.

/*  Data_Block

PIRL CVS ID: $Id: Data_Block.hh,v 1.37 2007/02/01 06:08:20 castalia Exp $

Copyright (C) 2003, 2004, 2005  Arizona Board of Regents 
on behalf of the Planetary Image Research Laboratory, 
Lunar and Planetary Laboratory at the University of Arizona.

This library is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License, version 2.1,
as published by the Free Software Foundation.

This library is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with this library; if not, write to the Free Software Foundation,
Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA.
*/
#ifndef _Data_Block_
#define _Data_Block_

#include    "endian.hh"

#include    <iostream>
#include    <vector>

namespace PIRL
{
/*=****************************************************************************
    Data_Block
*/
class Data_Block
{
public:
/*==============================================================================
    Types
*/
typedef unsigned int        Index;

typedef std::vector<Index>  Value_List;

typedef void (*Copier)
    (
    unsigned char*          destination,
    int                     destination_amount,
    const unsigned char*    source,
    int                     source_amount
    );

/*==============================================================================
    Constants
*/
static const char* const
    ID;

enum Data_Order
    {
    MSB,
    LSB
    };

static const Index
    NO_INDEX;

enum Array_Index_Counts
    {
    ELEMENT_INDEX,
    INDEX_COUNT
    };
#define INDEX_COUNTS INDEX_COUNT

enum Array_Offset_Counts
    {
    ELEMENT_OFFSET,
    OFFSET_COUNT
    };
#define OFFSET_COUNTS OFFSET_COUNT

#ifndef DATA_BLOCK_LIMITS_CHECK
#define DATA_BLOCK_LIMITS_CHECK false
#endif

/*==============================================================================
    Constructors
*/
Data_Block ();

Data_Block
    (
    void* const     data,
    const Index*    offsets,
    Index           total_elements = 0,
    const Index*    array_counts = NULL,
    bool            native_order = true
    );

Data_Block
    (
    void* const         data,
    const Value_List&   offsets,
    const Value_List&   array_counts,
    bool                native_order = true
    );

Data_Block
    (
    void* const         data,
    const Value_List&   offsets,
    bool                native_order = true
    );

Data_Block
    (
    void* const     data,
    const Index*    offsets,
    Index           total_elements,
    const Index*    array_counts,
    Data_Order      data_order
    );

Data_Block
    (
    void* const         data,
    const Value_List&   offsets,
    const Value_List&   array_counts,
    Data_Order          data_order
    );

Data_Block
    (
    void* const     data,
    const Index*    offsets,
    Index           total_elements,
    Data_Order      data_order
    );

Data_Block
    (
    void* const     data,
    const Index*    offsets,
    Data_Order      data_order
    );

Data_Block
    (
    void* const         data,
    const Value_List&   offsets,
    Data_Order          data_order
    );

Data_Block
    (
    void* const     data,
    const Index*    offsets,
    const Index     indexed_counts[][2],
    Data_Order      data_order
    );

/*..............................................................................
    Copy
*/
Data_Block (const Data_Block& data_block);

Data_Block& operator= (const Data_Block& data_block);

/*..............................................................................
    Destructor
*/
/*  Destroys the Data_Block, deleting the dynamically allocated
    structure definition arrays.

    <b>N.B.</b>: The memory containing the binary data block remains
    the responsibility of the user. It may still be in use by some
    other Data_Block. If the memory was provided dynamically, the user
    must free it when it is no longer needed. 
*/
virtual ~Data_Block ();

/*==============================================================================
    Accessors
*/
/*------------------------------------------------------------------------------
    Data order
*/
bool native () const
    {return Native;}

Data_Block& native (bool native_order);

static Data_Order native_order ()
    {return host_is_high_endian () ? MSB : LSB;}

Data_Order data_order () const;

Data_Block& data_order (Data_Order order);

/*------------------------------------------------------------------------------
    Data storage
*/
unsigned char* data () const
    {return Block;}

virtual Data_Block& data (void* const block);

Index size () const
    {return (Counts.size () ? Offsets[Counts.size ()] : 0);}

/*------------------------------------------------------------------------------
    Element offsets
*/
Value_List element_offsets_list () const
    {return Offsets;}

Index* element_offsets ()
    {return &Offsets[0];}

bool element_offsets (const Value_List& offsets);

bool element_offsets (const Index* offsets, Index total_elements = NO_INDEX);

bool element_sizes (const Value_List& sizes);

bool element_sizes (const Index* sizes, Index total_elements = NO_INDEX);

Index offset_of (Index element) const;

bool offset_of (Index element, Index offset);

bool insert_element (Index offset, Index size, Index array_count = 1);

Data_Block& delete_element (Index element);

Data_Block& shift_offsets (int amount);

/*------------------------------------------------------------------------------
    number of ...
*/
Index elements () const
    {return Counts.size ();}

Index size_of (Index element) const;

bool size_of (Index element, Index size);

Index value_size_of (Index element) const;

Data_Block& value_size_of (Index element, Index size);

Index index_of (Index offset) const;

/*------------------------------------------------------------------------------
    Array value counts
*/
Value_List array_counts_list () const
    {return Counts;}

Index* array_counts ()
    {return &Counts[0];}

Data_Block& array_counts (const Value_List& counts, Index begin = 0);

Data_Block& array_counts
    (const Index* counts, Index begin = 0, Index end = NO_INDEX);

Data_Block& array_indexed_counts
    (const Index indexed_counts[][2], Index total_counts = NO_INDEX);

Data_Block& array_offset_counts
    (const Index offset_counts[][2], Index total_counts = NO_INDEX);

Index count_of (Index element) const;

Data_Block& count_of (Index element, Index count);

bool reset_counts (bool unconditional = true,
    Index begin = 0, Index end = NO_INDEX);

/*==============================================================================
    I/O
*/
/*..............................................................................
    Primary get/put generic interface
*/
Copier
    Get;

Copier
    Put;

template<typename T, bool limits_check>
const Data_Block&
get (T& value, const Index element, const Index index = 0) const
{
if (Block)
    {
    if (limits_check)
        limits_checker (element, index, true, false);
    unsigned int
        amount = (Offsets[element + 1] - Offsets[element]) / Counts[element];
    Get
        (
        reinterpret_cast<unsigned char*>(&value),   //  Destination: User Value
        sizeof (T),
        Block + Offsets[element] + (amount * index),//  Source: Data Block
        amount
        );
    }
return *this;
}

template<typename T>
const Data_Block&
get (T& value, const Index element, const Index index = 0) const
    {return get<T, DATA_BLOCK_LIMITS_CHECK> (value, element, index);}

template<typename T, bool limits_check>
T get (const Index element, const Index index = 0) const
    {
    T value;
    get<T, limits_check> (value, element, index);
    return value;
    }

template<typename T>
T get (const Index element, const Index index = 0) const
    {return get<T, DATA_BLOCK_LIMITS_CHECK> (element, index);}


template<typename T, bool limits_check>
Data_Block& put (T& value, const Index element, const Index index = 0)
{
if (Block)
    {
    if (limits_check)
        limits_checker (element, index, false, false);
    unsigned int
        amount = (Offsets[element + 1] - Offsets[element]) / Counts[element];
    Put
        (
        Block + Offsets[element] + (amount * index),//  Destination: Data Block
        amount,
        reinterpret_cast<const unsigned char*>(&value), //  Source: User Value
        sizeof (T)
        );
    }
return *this;
}

template<typename T>
Data_Block& put (T& value, const Index element, const Index index = 0)
    {return put<T, DATA_BLOCK_LIMITS_CHECK> (value, element, index);}

template<typename T, bool limits_check>
const Data_Block& get (T* array, const Index element, Index count = 0) const
{
if (Block)
    {
    if (limits_check)
        limits_checker (element, count, true, true);
    unsigned int
        amount = (Offsets[element + 1] - Offsets[element]) / Counts[element];
    if (! count || count > Counts[element])
        count = Counts[element];
    unsigned char*
        data = Block + Offsets[element];

    //  Get each array element
    while (count--)
        {
        Get (reinterpret_cast<unsigned char*>(array), sizeof (T), data, amount);
        data += amount;
        array++;
        }
    }
return *this;
}

template<typename T>
const Data_Block& get (T* array, const Index element, Index count = 0) const
    {return get<T, DATA_BLOCK_LIMITS_CHECK> (array, element, count);}


template<typename T, bool limits_check>
Data_Block& put (T* array, const Index element, Index count = 0)
{
if (Block)
    {
    if (limits_check)
        limits_checker (element, count, false, true);
    unsigned int
        amount = (Offsets[element + 1] - Offsets[element]) / Counts[element];
    if (! count || count > Counts[element])
        count = Counts[element];
    unsigned char*
        data = Block + Offsets[element];

    //  Get each array element
    while (count--)
        {
        Put (data, amount,
            reinterpret_cast<const unsigned char*>(array), sizeof (T));
        data += amount;
        array++;
        }
    }
return *this;
}

template<typename T>
Data_Block& put (T* array, const Index element, Index count = 0)
    {return put<T, DATA_BLOCK_LIMITS_CHECK> (array, element, count);}

std::istream& input  (std::istream& stream);

std::ostream& output (std::ostream& stream) const;

/*  Prints a description of the Data_Block to a stream.

    @param  stream  The ostream to which to print the description.
    @return The stream.
*/
std::ostream& print (std::ostream& stream = std::cout) const;

/*==============================================================================
    Utilities
*/
static Value_List& sizes_to_offsets (Value_List& sizes);

static Index* sizes_to_offsets (Index* sizes, Index total_elements = NO_INDEX);

static Value_List& offsets_to_sizes (Value_List& offsets);

static Index* offsets_to_sizes
    (Index* offsets, Index total_elements = NO_INDEX);

/*..............................................................................
    Static data movers.
*/
protected:

static void
get_forwards
    (
    unsigned char*          host,           //  Destination: User Value
    int                     host_amount,
    const unsigned char*    data,           //  Source: Data Block
    int                     data_amount
    );

static void
get_backwards
    (
    unsigned char*          host,           //  Destination: User Value
    int                     host_amount,
    const unsigned char*    data,           //  Source: Data Block
    int                     data_amount
    );

static void
put_forwards
    (
    unsigned char*          data,           //  Destination: Data Block
    int                     data_amount,
    const unsigned char*    host,           //  Source: User Value
    int                     host_amount
    );

static void
put_backwards
    (
    unsigned char*          data,           //  Destination: Data Block
    int                     data_amount,
    const unsigned char*    host,           //  Source: User Value
    int                     host_amount
    );

void limits_checker
    (
    const Index     element,
    const Index     index,
    bool            getter,
    bool            array
    ) const;

//..............................................................................
private:

unsigned char*
    Block;

Value_List
    Offsets;

Value_List
    Counts;

bool
    Native;

};  //  class Data_Block

/*==============================================================================
    I/O operators
*/
std::ostream& operator<<
    (std::ostream& stream, const Data_Block& data_block);

std::istream& operator>>=
    (std::istream& stream, Data_Block& data_block);

std::ostream& operator<<=
    (std::ostream& stream, const Data_Block& data_block);

}   //  namespace PIRL
#endif