HiRISE
 Observation

Public Member Functions | Public Attributes | Static Public Attributes

Data_Component Class Reference

A Data_Component provides a common, virtual interface for all HiRISE Observation data blocks. More...

#include <Data_Component.hh>

Inheritance diagram for Data_Component:
Inheritance graph
[legend]
Collaboration diagram for Data_Component:
Collaboration graph
[legend]

List of all members.

Public Member Functions

 Data_Component (const char **names=NULL, unsigned int size=0, const Index *offsets=NULL, const Index indexed_arrays[][2]=NULL, Data_Order order=Data_Block::MSB)
 Constructs a Data_Component using component specifications.
 Data_Component (const Data_Component &component, bool data_duplicate=true)
 Copy constructor.
Data_Componentoperator= (const Data_Component &component)
 Assignment operator.
virtual ~Data_Component ()
 Destructor.
virtual std::string id () const
 Gets the identification of this component.
virtual const char * name () const =0
 Gets the name of the component.
const char * name (Index element) const
 Gets the name of a component Element.
virtual u_int_32 get (Index element, Index index=0) const
 Gets a value from a data Element or array entry of the component.
virtual Data_Componentput (const u_int_32 value, Index element, Index index=0)
 Puts a value into a data Element or array entry of the component.
virtual idaeim::PVL::AggregatePVL () const =0
 Produces an exhausitive PVL (Parameter Value Language) rendition of the component contents.
virtual std::ostream & print (std::ostream &stream=std::cout, bool verbose=false) const =0
 Prints a detailed description of the component structure and contents.
std::ostream & print_element (const Index element, int format=DECIMAL, std::ostream &stream=std::cout, int width=0) const
 Prints an Element description.
std::ostream & print_element (const Index element, std::ostream &stream) const
 Prints an Element description.
std::ostream & print_element_location (const Index element, std::ostream &stream=std::cout) const
 Prints the location of an Element in the component.
unsigned int element_location_print_width (Index element) const
 Gets the width of the Element location printing fields.
unsigned int name_field_width () const
 Gets the width of the Element name printing field.
Data_Componentname_field_width (unsigned int width)
 Sets the width of the Element name field for printing.
virtual bool is_valid () const =0
 Tests if the component data is valid.
Data_Blockdata (void *const block)
 Overrides the base Data_Block::data to reset Local_Data.
Data_Blockattach (void *const block, unsigned int size)
 Attaches a new block of data to the component.
Data_Componentresize (unsigned int size)
 Resizes the block of local data storage.
unsigned char * data () const
 Gets a pointer to the current component storage.
unsigned int local_data ()
 Gets the size of the local data storage area.
u_int_16 internet_checksum () const
 Calculates the Internet Checksum as per RFC 1071.

Public Attributes

static const int HEX = -1
static const int BOOLEAN = -2

Static Public Attributes

static const char *const ID = "UA::HiRISE::Data_Component (1.49 2010/11/25 02:51:13)"
 Class identification name with source code version and date.
static const int DECIMAL = 0
 Format specifier.
static const char PATHNAME_DELIMITER = FILESYSTEM_PATHNAME_DELIMITER
 Host filesystem pathname delimiter.
static const int UTC_SECONDS_PRECISION = SECONDS_PRECISION
 UTC seconds precision (digits after the decimal point).
static const char SUBSECONDS_DELIMITER = ':'
 Delimits subseconds from seconds in clock count representations.
static const char *const SPICE_METAKERNEL_VARIABLE
 The name of the environment variable for the SPICE metakernel pathname.
static const char *const DEFAULT_SPICE_METAKERNEL
 The default SPICE metakernal pathname.
static const int MRO_CLOCK_ID = MRO_CLOCK_NAIF_ID
 The ID used by NAIF for specifying the MRO clock to CSPICE routines.
static const char *const INVALID_UTC_TIME = DEFAULT_INVALID_UTC_TIME

Detailed Description

A Data_Component provides a common, virtual interface for all HiRISE Observation data blocks.

It also subclasses the Instrument class which contains the HiRISE instrument constants, and the PIRL::Data_Block for host data order independence of the component's data store.

There will be an implmentation of this interface for each specific type of Data_Component that occurs in an Observation or data product.

Author:
Bradford Castalia, UA/PIRL

1.37

See also:
UA::HiRISE::Instrument
PIRL::Data_Block
Observation

Constructor & Destructor Documentation

Data_Component ( const char **  names = NULL,
unsigned int  size = 0,
const Index offsets = NULL,
const Index  indexed_arrays[][2] = NULL,
Data_Order  order = Data_Block::MSB 
)

Constructs a Data_Component using component specifications.

Memory is allocated (size bytes) for the component's Data_Block, and initialized to 0. However, if size is 0 no memory is allocated; the Data_Block has NULL data. The memory is deleted when the component is destroyed or the data block is substituted by an external data block.

Parameters:
namesThe list of Element names in Element order. The names are expected to remain constant, so they are not copied. This list MUST be NULL terminated.
sizeThe size (bytes) of the component's data block.
offsetsThe list of Element offsets in the data block in Element order.
indexed_arraysThe list of array Element entry counts using Element index references. Components with no array Elements will not provide this.
orderThe order of data in data block. All HiRISE components are expected to be MSB ordered.
See also:
Data_Block
Data_Component ( const Data_Component component,
bool  data_duplicate = true 
)

Copy constructor.

This component is a Data_Block copy which results in taking on all of the structural characteristics of the copied component.

The data content is copied only if data_duplicate is true. If data_duplicate is true, then memory for a copy of the source component data block is allocated, and the contents of the source data block is copied into this new data block. If data_duplicate is false, then the new data block will share the data storage memory of the source data block; the source data block retains ownership of the data storage.

Parameters:
componentThe component to be copied.
data_duplicatetrue if the data content of the component is to be duplicated in the copy; false if the source component data is to be shared by this component.

References Data_Component::data(), and Data_Block::size().

~Data_Component (  ) [virtual]

Destructor.

If the data block memory for the component has not been substituted by an external data block, it is deleted.

See also:
data(void* const)

References Data_Component::data().


Member Function Documentation

Data_Component & operator= ( const Data_Component component )

Assignment operator.

Memory is allocated for a duplicate of the assigned data block storage. However, if the current data block is being locally managed (it has its own data storage) and at least as large as the assigned data block the current block is simply reused rather than replaced.

Also, a Data_Block assignment of the assigned compoent is applied to this component so it takes on all of the structural characteristics of assigned component.

Parameters:
componentThe component being assigned.

References Data_Component::data(), and Data_Block::size().

Referenced by Science_Channel_Header::operator=(), MROSP_Header::operator=(), LUT::operator=(), Image_Line::operator=(), Gap_Map::operator=(), and Engineering_Header::operator=().

string id (  ) const [virtual]

Gets the identification of this component.

The identification is the Data_Component class ID, the Instrument class ID and the Data_Block class ID each separated by a new-line. Each subclass of Data_Component is excpected to provided their own id method which provides their own class ID line preceeding this identification.

Returns:
An identification string for the component.

Reimplemented in Engineering_Header, Gap_Map, Image_Line, LUT, MROSP_Header, and Science_Channel_Header.

References Instrument::ID, and Data_Component::ID.

virtual const char* name (  ) const [pure virtual]

Gets the name of the component.

Each subclass must provide their name method.

Returns:
A constant C-string (char*) that is the name of the implementing class.

Implemented in Engineering_Header, Gap_Map, Image_Line, LUT, MROSP_Header, and Science_Channel_Header.

const char * name ( Index  element ) const

Gets the name of a component Element.

Parameters:
elementAn Element Index of the component.
elementThe Element Index.
Returns:
A constant C-string (char*) that is the name of the Element.
u_int_32 get ( Index  element,
Index  index = 0 
) const [virtual]

Gets a value from a data Element or array entry of the component.

Regardless of the precision (number of bits) of the component Element the value will always be cast up to a 32-bit integer.

Parameters:
elementAn Element Index of the component.
indexAn array Elmenent entry index.
Returns:
An unsigned integer value for the Element data.

Reimplemented from Data_Block.

Referenced by MROSP_Header::checksum(), MROSP_Header::data_amount(), Observation::data_ID(), Gap_Map::get(), Observation::line(), main(), MROSP_Header::pad_0(), MROSP_Header::pad_1(), MROSP_Header::protocol_ID(), Observation::reset_line(), MROSP_Header::sync(), MROSP_Header::transaction(), and MROSP_Header::transaction_ID().

Data_Component & put ( const u_int_32  value,
Index  element,
Index  index = 0 
) [virtual]

Puts a value into a data Element or array entry of the component.

Regardless of the precision (number of bits) of the component Element the 32-bit integer value will always be cast appropriately.

Parameters:
valueAn unsigned integer value for the Element data.
elementAn Element Index of the component.
indexAn array Elmenent entry index.
Returns:
This Data_Component.

Referenced by main(), and Science_Channel_Header::print().

virtual idaeim::PVL::Aggregate* PVL (  ) const [pure virtual]

Produces an exhausitive PVL (Parameter Value Language) rendition of the component contents.

Each Element has a parameter with its element name. All the paramters are contained in an Aggregate with the name of component.

Returns:
A pointer to a PVL::Aggregate.

Implemented in Engineering_Header, Gap_Map, Image_Line, LUT, MROSP_Header, and Science_Channel_Header.

virtual std::ostream& print ( std::ostream &  stream = std::cout,
bool  verbose = false 
) const [pure virtual]

Prints a detailed description of the component structure and contents.

The listing is expected to start with a line containing the component's name preceeded by a ">>> " marker. In verbose mode this should be immediately followed by a line containing the component's class ID.

After a blank line, each Element of the component should be listed in Element order. Typically the print_element method is used to provide a single line description of an Element. For complex Elements (e.g. packed bit fields) additional lines describing each part of the element should be provided.

When not in verbose mode, inconsequential component Elements - typically padding - will not be included in the Element listings.

Parameters:
streamThe ostream where the listing will be written.
verbosetrue if the listing is to be verbose, otherwise some structural details will be omitted for easier human consumption.
Returns:
The stream that was written.
See also:
print_element

Implemented in Engineering_Header, Gap_Map, Image_Line, LUT, MROSP_Header, and Science_Channel_Header.

ostream & print_element ( const Index  element,
int  format = DECIMAL,
std::ostream &  stream = std::cout,
int  width = 0 
) const

Prints an Element description.

The description begins with its location listing. Then each Element value is listed, space separated, in the specified format (an array Element has more than one value).

Parameters:
elementAn Index of an Element in the component.
formatThe selected format of the output.
streamThe ostream for output.
widthThe width of the representation, as applicable.
Returns:
The stream that was written.
See also:
print_element_location
print_value
std::ostream& print_element ( const Index  element,
std::ostream &  stream 
) const [inline]

Prints an Element description.

The Element is printed in DECIMAL format with 0 width.

Parameters:
elementAn Index of an Element in the component.
streamThe ostream for output.
Returns:
The stream that was written.
See also:
print_element(const Index, int, std::ostream&, int)

References Data_Component::DECIMAL, and Data_Component::print_element().

Referenced by Data_Component::print_element().

ostream & print_element_location ( const Index  element,
std::ostream &  stream = std::cout 
) const

Prints the location of an Element in the component.

The format of the location listing is:

Element@Offset:Count*Size Name: 

Element
The Element Index in the component (width 3).
Offset
The byte offset from the begining of the component, at byte 0, where the Element data is located (width 3).
Count
The number of Array entries composing the Element; a non-Array Element has a Count of 1 (width 3).
Size
The size, in bytes, of each Array entry (width 1). Note: there is a single space following this field.
Name
The name of the Element (width name_field_width). Note: there is a colon and space following this field.

All parts of the location listing are right justified in their space padded fields.

Parameters:
elementAn Index of an Element in the component.
streamThe ostream where the listing will be written.
Returns:
The stream that was written.
unsigned int element_location_print_width ( Index  element ) const

Gets the width of the Element location printing fields.

The width of the Element location field should be constant as determined by its fixed format. However, unusually large location data values or a name_field_width specification less than the length of the Element name will result in an actual field width that is longer than expected. This method prints the Element location and name to a string stream to determine its actual listing length.

Parameters:
elementAn Index of an Element in the component.
Returns:
The width of the location and name printing fields.
See also:
print_element_location
unsigned int name_field_width (  ) const

Gets the width of the Element name printing field.

Returns:
The character width of the Element name print field.
See also:
name_field_width(unsigned int)
Data_Component & name_field_width ( unsigned int  width )

Sets the width of the Element name field for printing.

To provide a nicely formatted print listing, a consistent width for the Element name field is maintained as the Name_Field_Width data member of the Data_Component. When the object is constructed the maximum length of all Elements names is determined (and saved as the Max_Name_Length data member) and the Name_Field_Width value is initialzed with the value of Max_Name_Length. When an application is printing multiple Data_Component objects it may reset the Name_Field_Width to some other value; e.g. the maximum of all name_field_width values from each Data_Component.

If the width argument is 0 then the Name_Field_Width will be reset to the Max_Name_Length value.

Parameters:
widthThe character width for the Element name print field. If the value is 0 then the width will be reset to the Max_Name_Length value.
Returns:
This Data_Component.
See also:
print_element
virtual bool is_valid (  ) const [pure virtual]

Tests if the component data is valid.

Returns:
true if the component has valid data; false otherwise.

Implemented in Engineering_Header, Gap_Map, Image_Line, LUT, MROSP_Header, and Science_Channel_Header.

Data_Block & data ( void *const   block ) [virtual]

Overrides the base Data_Block::data to reset Local_Data.

When a Data_Component is constructed it provides its own local data storage which is managed by the Data_Component. It may be appropriate to substitute an external data storage block that is managed externally.

When a new data block replaces a local block, the local block is deleted and the data storage is marked as being externally managed. If the new data block replaces an external block, the external block is not deleted; the external storage is the responsibility of the external owner.

N.B.: The contents of the previous data block are not copied into the new block.

Warning: It the responsibility of the new data block owner to ensure that it contains sufficient storage to accommodate all Elements of the component, as determined by the Data_Block::size method.

Parameters:
blockThe address of the new Data_Block storage.
Returns:
The Data_Block.
See also:
Data_Block::data(void* const)

Reimplemented from Data_Block.

Referenced by Observation::components(), Data_Component::Data_Component(), Observation::line(), Line_Cache::Line_Cache(), Line_Cache::next_line(), and Data_Component::operator=().

Data_Block & attach ( void *const   block,
unsigned int  size 
)

Attaches a new block of data to the component.

The new data block is attached to this Data_Component: ownership of the new data block is passed to this Data_Component; the data block will be deleted when this Data_Component is destroyed.

Warning: The new data block must be dynamically allocated.

When a the new data block replaces a local block at a different address, the local block is deleted. N.B.: The contents of the previous data block are not copied into the new block.

Parameters:
blockThe address of the new Data_Block storage.
sizeThe size, in bytes, of the new data block.
Returns:
The Data_Block.
Exceptions:
length_errorIf the size of the new block is insufficient to accommodate all Elements of the component, as determined by the Data_Block::size() method.
See also:
Data_Block::data(void* const)

References ID.

Data_Component & resize ( unsigned int  size )

Resizes the block of local data storage.

If the component has its own local data or has no no data block and the requested new data block size is greater than the currently allocated amount, then local data block is reallocated at the larger size and the contents of the previous data block are copied into the new data block. N.B.: The size of the local data block is never decreased (use attach instead).

Parameters:
sizeThe requested size of the local data block.
Returns:
This Data_Component.
See also:
local_data()

References ID.

unsigned char* data (  ) const [inline]

Gets a pointer to the current component storage.

Returns:
The component storage pointer.
See also:
Data_Block::data()

Reimplemented from Data_Block.

Referenced by Data_Component::internet_checksum(), LUT::is_valid(), LUT::PVL(), LUT::PVL_PDS(), and Data_Component::~Data_Component().

unsigned int local_data (  ) [inline]

Gets the size of the local data storage area.

Returns:
The size, in bytes, of the local storage area. If the data storage is being externally managed this will be zero.
See also:
data(void* const)
u_int_16 internet_checksum (  ) const

Calculates the Internet Checksum as per RFC 1071.

In outline, the Internet Checksum algorithm is very simple:

Adjacent octets to be checksummed are paired to form 16-bit integers, and the 1's complement sum of these 16-bit integers is formed.

To generate a checksum, the checksum field itself is cleared, the 16-bit 1's complement sum is computed over the octets concerned, and the 1's complement of this sum is placed in the checksum field.

To check a checksum, the 1's complement sum is computed over the same set of octets, including the checksum field. If the result is all 1 bits (-0 in 1's complement arithmetic), the check succeeds.

Suppose a checksum is to be computed over the sequence of octets A, B, C, D, ... , Y, Z. Using the notation [a,b] for the 16-bit integer a * 256 + b, where a and b are bytes, then the 16-bit 1's complement sum of these bytes is given by one of the following:

	[A,B] +' [C,D] +' ... +' [Y,Z]
	[A,B] +' [C,D] +' ... +' [Z,0]

where +' indicates 1's complement addition. These cases correspond to an even or odd count of bytes, respectively.

On a 2's complement machine, the 1's complement sum must be computed by means of an "end around carry", i.e., any overflows from the most significant bits are added into the least significant bits.

For details see: http://www.faqs.org/rfcs/rfc1071.html

Returns:
The checksum of the this Data_Component. If the component contains a valid checksum Element, the result should be 0.

References Data_Component::data(), Data_Block::Get, and Data_Block::size().

Referenced by Science_Channel_Header::is_valid(), main(), Science_Channel_Header::print(), and MROSP_Header::print().


Member Data Documentation

const char *const ID = "UA::HiRISE::Data_Component (1.49 2010/11/25 02:51:13)" [static]

Class identification name with source code version and date.

Reimplemented from Instrument.

Reimplemented in Engineering_Header, FELICS_Line_Cache, Gap_Map, Image_Line, Line_Cache, LUT, MROSP_Header, and Science_Channel_Header.

Referenced by Data_Component::id(), and main().

const int DECIMAL = 0 [static]

Format specifier.

See also:
print_value

Referenced by Data_Component::print_element().

const int HEX = -1

Referenced by main().

const int BOOLEAN = -2
const char PATHNAME_DELIMITER = FILESYSTEM_PATHNAME_DELIMITER [static]

Host filesystem pathname delimiter.

Referenced by main().

const int UTC_SECONDS_PRECISION = SECONDS_PRECISION [static]

UTC seconds precision (digits after the decimal point).

const char SUBSECONDS_DELIMITER = ':' [static]

Delimits subseconds from seconds in clock count representations.

const char *const SPICE_METAKERNEL_VARIABLE [static]
Initial value:

The name of the environment variable for the SPICE metakernel pathname.

A pathname ust be provided to a SPICE metakernel that lists a SCLK kernal for the MRO spacecraft and a leap seconds kernel. The environment variable is tried first before the fallback default.

const char *const DEFAULT_SPICE_METAKERNEL [static]
Initial value:

The default SPICE metakernal pathname.

const int MRO_CLOCK_ID = MRO_CLOCK_NAIF_ID [static]

The ID used by NAIF for specifying the MRO clock to CSPICE routines.

const char *const INVALID_UTC_TIME = DEFAULT_INVALID_UTC_TIME [static]

The documentation for this class was generated from the following files: