HiRISE
 Observation

Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions

Gap_Map Class Reference

A Gap_Map contains a map of data gap ranges for the file with which it is associated. More...

#include <Gap_Map.hh>

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

List of all members.

Public Types

enum  End_Point {
  RANGE_START,
  RANGE_END
}
 

Gap range end-point value symbols.

More...
enum  {
  INSIDE = -1,
  OUTSIDE = 0,
  OVERLAP = 1
}
 

Return values for in_gap(Location, Location) method.

More...
typedef u_int_32 Location
 A gap range end-point offset location value.
typedef std::pair< Location,
Location
Range
 A gap range end-point pair of offset location values.
typedef std::vector< RangeList
 A list of gap range pairs.

Public Member Functions

 Gap_Map ()
 Constructs an empty Gap_Map.
 Gap_Map (std::istream &stream, unsigned int count)
 Constructs a Gap_Map loaded from a data stream.
 Gap_Map (const Gap_Map &map, bool data_duplicate=true)
 Copy constructor.
Gap_Mapoperator= (const Gap_Map &map)
 Assigns another Gap_Map to this one.
virtual std::string id () const
 Provides the class ID on a line followed by the base Data_Component::id.
virtual const char * name () const
 Gets the NAME of this class.
virtual Location get (Index range, End_Point end_point) const
 Gets a gap range end-point value.
Gap_Map::Range gap (Index range) const
 Gets a gap Range.
Gap_Map::List gaps () const
 Gets a List of Range pairs from the map.
unsigned int total_gaps () const
 Gets the total number of gap segments in the map.
bool in_gap (const Location location) const
 Tests if a location falls in a gap range.
int in_gap (const Location start, const Location end) const
 Tests if a [start, end) range overlaps a gap range in the map.
int in_gap (const Gap_Map::Range &range) const
 Tests if a Range overlaps a gap range in the map.
Gap_Mapset (const Location start, const Location end)
 Sets a gap range.
Gap_Mapset (const Gap_Map::Range &range)
 Sets a gap Range.
Gap_Mapset (const Gap_Map::List list)
 Sets a list of gap ranges.
Gap_Mapclear (const Location start, const Location end)
 Clears a gap range.
Gap_Mapclear ()
 Clears the entire map.
Gap_Mapclear (const Gap_Map::Range &range)
 Clears a gap range.
Gap_Mapclear (const Gap_Map::List list)
 Clears a list of gap ranges.
Gap_Mapshift (int_32 amount)
 Shifts all range locations some amount.
virtual std::ostream & print (std::ostream &stream=std::cout, bool verbose=false) const
 Prints the component structure and contents.
virtual idaeim::PVL::AggregatePVL () const
 Produces a PVL rendition of the component.
idaeim::PVL::AggregatePVL_description () const
 Produces a PVL description of a Gap_Map for a PDS label.
virtual bool is_valid () const
 Tests if the component data is valid.

Static Public Member Functions

static Gap_Map::List gaps_in (void *start, void *end, unsigned int threshold=0)
 Gets a list of gap ranges in a data block.
static unsigned int sequence_threshold (unsigned int threshold=0)
 Gets the sequence threshold for determining a gap segment range, optionally setting a new threshold.
static Gap_Map::Rangeshift (Gap_Map::Range &range, int_32 amount)
 Shifts the end points of a Range some amount.
static Gap_Map::Listshift (Gap_Map::List &list, int_32 amount)
 Shifts a List of Ranges some amount.

Static Public Attributes

static const char *const ID = "UA::HiRISE::Gap_Map (1.13 2010/11/25 02:51:13)"
 Class identification name with source code version and date.
static const char *const NAME = "Gap Map"
 The component name.
static const char *const END_POINT_NAMES []
 Gap range end-point value names.
static const unsigned int DEFAULT_SEQUENCE_THRESHOLD = GAP_MAP_DEFAULT_SEQUENCE_THRESHOLD
 The default sequence of gap byte values required for a gap segment.
static const u_int_8 GAP_BYTE_VALUE = 0xFF
 The value of a "gap filled" data byte.

Protected Member Functions

virtual Data_Componentput (const Location location, Index range, End_Point end_point)
 Puts a the value of an end-point into a gap range.
Gap_Mapinsert_range (Index range, Location start, Location end)
 Inserts a new range into the map.
Gap_Mapremove_range (Index first, Index last=(Index)-1)
 Removes ranges from the map.

Detailed Description

A Gap_Map contains a map of data gap ranges for the file with which it is associated.

The map is composed of [start, end) Range value pairs where each pair defines the location of a gap segment in the associated file. The ranges are non-overlapping and ordered by increasing location values.

A data gap segment is defined as a contiguous sequence of gap byte values. The sequence threshold defines the minimum number of gap byte values that must be identified for a segment to be recognized.

N.B.: The Gap_Map is implemented as a Data_Block containing a single array element of end-point values; two per range segment.

Note: There is no Gap_Map component in an observation data file; one is generated for EDR product files. The Data_Component interface is provided for consistency with all other observation and EDR file components.

Author:
Bradford Castalia, UA/PIRL

1.8

See also:
Data_Component

Member Typedef Documentation

typedef u_int_32 Location

A gap range end-point offset location value.

typedef std::pair<Location, Location> Range

A gap range end-point pair of offset location values.

typedef std::vector<Range> List

A list of gap range pairs.


Member Enumeration Documentation

enum End_Point

Gap range end-point value symbols.

Enumerator:
RANGE_START 
RANGE_END 
anonymous enum

Return values for in_gap(Location, Location) method.

Enumerator:
INSIDE 
OUTSIDE 
OVERLAP 

Constructor & Destructor Documentation

Gap_Map (  )

Constructs an empty Gap_Map.

Gap_Map ( std::istream &  stream,
unsigned int  count 
)

Constructs a Gap_Map loaded from a data stream.

If the specified count of gap ranges can not be read from the stream the count will be adjusted to the nearest number of complete ranges actually read. Any extra bytes read are ignored. No more data is read than required for the range count specified.

Parameters:
streamThe istream from which to read the component data.
countThe number of ranges in the map.
Gap_Map ( const Gap_Map map,
bool  data_duplicate = true 
)

Copy constructor.

Parameters:
mapThe Gap_Map to be copied.
data_duplicatetrue if the data content of the copied component is to be duplicated in the copy; false if the data content is to be shared.

Member Function Documentation

Gap_Map & operator= ( const Gap_Map map )

Assigns another Gap_Map to this one.

Parameters:
mapThe Gap_Map to be assigned.

References Data_Component::operator=().

std::string id (  ) const [virtual]

Provides the class ID on a line followed by the base Data_Component::id.

Returns:
The multi-line identification string.
See also:
Data_Component::id()

Reimplemented from Data_Component.

References Gap_Map::ID.

const char * name (  ) const [virtual]

Gets the NAME of this class.

Returns:
A pointer to the constant class name C-string.
See also:
Data_Component::name()

Implements Data_Component.

References Gap_Map::NAME.

Gap_Map::Location get ( Index  range,
End_Point  end_point 
) const [virtual]

Gets a gap range end-point value.

Parameters:
rangeThe gap range to get.
end_pointEither RANGE_START or RANGE_END.
Returns:
The value of the range end-point.
Exceptions:
std::out_of_rangeif the range is not in the map.
std::invalid_argumentif an invalid end-point is specified.

References Data_Component::get(), and ID.

Gap_Map::Range gap ( Index  range ) const

Gets a gap Range.

A gap Range has start (inclusive) and end (exclusive) end-point location values as its first and second values, respectively.

Parameters:
rangeThe gap range to get.
Returns:
A Range pair.
Exceptions:
std::out_of_rangeif the range is not in the map.

References ID.

Referenced by Gap_Map::gaps().

Gap_Map::List gaps (  ) const

Gets a List of Range pairs from the map.

Returns:
A Gap_Map::List containing zero or more Range entries. Each entry is a pair of start (inclusive) and end (exclusive) values.

References Gap_Map::gap(), and Gap_Map::total_gaps().

unsigned int total_gaps (  ) const [inline]

Gets the total number of gap segments in the map.

Returns:
The total number of gap segments in the map.

References Data_Block::count_of().

Referenced by Gap_Map::gaps(), main(), Gap_Map::PVL(), and Gap_Map::PVL_description().

bool in_gap ( const Location  location ) const

Tests if a location falls in a gap range.

Parameters:
locationThe location to be tested.
Returns:
true if the location falls in a gap range; false otherwise.

Referenced by Observation::components().

int in_gap ( const Location  start,
const Location  end 
) const

Tests if a [start, end) range overlaps a gap range in the map.

Reverse range locations - in which start > end - may be specified (see the Note for the set method).

Parameters:
startThe starting (inclusive) location byte (0-based) of the range.
endThe ending (exclusive) location byte of the range.
Returns:
0 (OUTSIDE) if the range does not overlap a range in the map; -1 (INSIDE) if the range is completely within a map range; 1 (OVERLAP) if the range is only partially within a map range. Note that the return value is non-zero (true) if any portion of the range overlaps a map range.
int in_gap ( const Gap_Map::Range range ) const [inline]

Tests if a Range overlaps a gap range in the map.

Parameters:
rangeThe Range to be tested.
Returns:
0 (OUTSIDE) if the Range does not overlap a range in the map; -1 (INSIDE) if the Range is completely within a map range; 1 (OVERLAP) if the Range is only partially within a map range. Note that the return value is non-zero (true) if any portion of the Range overlaps a map range.
See also:
in_gap(const Location, const Location) const

References Gap_Map::in_gap().

Referenced by Gap_Map::in_gap().

Gap_Map & set ( const Location  start,
const Location  end 
)

Sets a gap range.

The range may overlap existing ranges in the map. A range that falls totally within an existing map range results in no change to the map. A range that extends beyond existing map ranges results in coalescing overlapped ranges: all overlapped or abutted ranges will become one range - additional ranges are removed - with its start location at the lesser of the map range and specified range start locations and its end location at the greater of the map range and specified range end locations. If the range does not overlap any existing map ranges a new range will be inserted at the appropriate place in the map.

Note: The start and end locations may be specified in descending order - with start > end. The start location will still be inclusive and the end location exclusive. Thus the reverse range [n, m), where n > m, becomes [m+1, n+1). N.B.: Reverse ranges can never include 0 because, since Location values are unsigned, an end location of -1 is interpreted as the largest possible positive value.

Parameters:
startThe starting (inclusive) location byte (0-based) of the range.
endThe ending (exclusive) location byte of the range.
Returns:
This Gap_Map.

Referenced by Observation::components(), and Observation::line().

Gap_Map& set ( const Gap_Map::Range range ) [inline]

Sets a gap Range.

Parameters:
rangeThe Range to be set.
Returns:
This Gap_Map.
See also:
set(const Location, const Location)
Gap_Map & set ( const Gap_Map::List  list )

Sets a list of gap ranges.

Parameters:
listThe list of gap ranges to be set.
Returns:
This Gap_Map.
See also:
set(const Location, const Location)
Gap_Map & clear ( const Location  start,
const Location  end 
)

Clears a gap range.

Reverse range locations - in which start > end - may be specified (see the Note for the set method).

The range may overlap existing map ranges. Completely overlapped ranges are removed. Ranges partially overlapped at the start or end have their start or end moved to the end or start of the specified range. A range that falls totally within an existing map range results in the range end being set to the specified range start and a new range inserted in the map with its start at the specified range end and its end at the map range end. A range that does not overlap any existing map ranges results in no change to the map.

Parameters:
startThe starting (inclusive) location byte (0-based) of the range.
endThe ending (exclusive) location byte of the range.
Returns:
This Gap_Map.

Referenced by Observation::components().

Gap_Map& clear (  ) [inline]

Clears the entire map.

Returns:
This Gap_Map.

References Gap_Map::clear().

Referenced by Gap_Map::clear().

Gap_Map& clear ( const Gap_Map::Range range ) [inline]

Clears a gap range.

Parameters:
rangeThe Range to be cleared.
Returns:
This Gap_Map.
See also:
clear(const Location, const Location)

References Gap_Map::clear().

Referenced by Gap_Map::clear().

Gap_Map & clear ( const Gap_Map::List  list )

Clears a list of gap ranges.

Parameters:
listThe list of gap ranges to be cleared.
Returns:
This Gap_Map.
See also:
clear(const Location, const Location)
Gap_Map & shift ( int_32  amount )

Shifts all range locations some amount.

A negative shift that would move a range start location below 0 results in the range start being clipped to 0. If the shift would move a range end location at or below 0 the range is removed from the map.

Parameters:
amountThe amount of the shift (positive or negative).
Returns:
This Gap_Map.

Referenced by Observation::components(), and Observation::line().

Data_Component & put ( const Location  location,
Index  range,
End_Point  end_point 
) [protected, virtual]

Puts a the value of an end-point into a gap range.

The gap range is reset to the new range.

Parameters:
locationThe end-point location.
rangeThe gap range to modify.
end_pointEither RANGE_START or RANGE_END.
Returns:
This Data_Component.
Exceptions:
std::out_of_rangeif the range is not in the map.
std::invalid_argumentif an invalid end-point is specified.

References ID.

Gap_Map & insert_range ( Index  range,
Location  start,
Location  end 
) [protected]

Inserts a new range into the map.

The range may not overlap any existing map ranges. The new range will be inserted before the specified range.

Parameters:
rangeThe Index where the new range is to be inserted in the gap map.
startThe starting (inclusive) location byte (0-based) of the range.
endThe ending (exclusive) location byte of the range.
Returns:
This Gap_Map.
Exceptions:
range_errorIf the range number is greater than the current number of map ranges, the start of the range is greater than or equal to the end of the preceeding map range (if there is one), or the end of the range is greater than or equal to the start of the following map range.

References ID.

Gap_Map & remove_range ( Index  first,
Index  last = (Index)-1 
) [protected]

Removes ranges from the map.

All ranges from first to last (inclusive) are removed from the map. If only one range is specified it will be the only one removed. Ranges not in the map are silently ignored.

Parameters:
firstThe number (0-based) of the first range to be removed.
lastThe number of the last range to be removed. This argument is optional.
Returns:
This Gap_Map.
ostream & print ( std::ostream &  stream = std::cout,
bool  verbose = false 
) const [virtual]

Prints the component structure and contents.

Each range of the map is printed on a separate line. Each range description line has the format:

Element@Offset:Count*Size : Start End

where:

Element
The range element number in the map (width 3).
Offset
The byte offset from the begining of the map, at byte 0, where the Element data is located (width 3).
Count
The number of values composing the Element; this should always be 2 (width 3).
Size
The size, in bytes, of each location value; this should always be 4 (width 1). Note: there is a space, a colon, and another space following this field.
Start
The starting location of the range (width 10). Note: there is a single space following this field.
End
The ending location of the range (width 10).

All parts of the listing are right justified in their space padded fields. Values that are longer than the available field width will result in a larger field to accommodate the entire value.

Parameters:
streamThe ostream where the listing will be written.
verbosetrue if the class name and ID are to be included in the listing.
Returns:
The stream that was written.

Implements Data_Component.

References ID.

Referenced by list_selections(), and main().

Aggregate * PVL (  ) const [virtual]

Produces a PVL rendition of the component.

The map is described as an Array of (start, end) Integer pairs.

Returns:
A pointer to a PVL::Aggregate. This Aggregate contains a single Array Assignment Parameter having the Gap_Map NAME .

Implements Data_Component.

References Aggregate::add(), Vectal< T >::clear(), Gap_Map::NAME, Gap_Map::RANGE_END, Gap_Map::RANGE_START, and Gap_Map::total_gaps().

Referenced by list_selections(), and main().

Aggregate * PVL_description (  ) const

Produces a PVL description of a Gap_Map for a PDS label.

The description is an OBJECT that contains the PDS parameters required to describe a data product binary data object.

Returns:
A pointer to a PVL::Aggregate. The object pointed to is a copy of an internal static object.

References Parser::get_parameters(), Gap_Map::ID, and Gap_Map::total_gaps().

bool is_valid (  ) const [virtual]

Tests if the component data is valid.

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

Implements Data_Component.

Gap_Map::List gaps_in ( void *  start,
void *  end,
unsigned int  threshold = 0 
) [static]

Gets a list of gap ranges in a data block.

The data block is scanned for data bytes with a value of GAP_BYTE_VALUE. The number of such contigous bytes must reach a threshold for a gap segment to be identified.

Parameters:
startThe address where the data block starts (inclusive).
endThe address where the data block ends (exclusive).
thresholdThe gap sequence threshold to use. If not specified (or zero) the sequence threshold is used.
Returns:
A Gap_Map::List containing the gap ranges found. This list may be empty.

Referenced by Observation::components(), and Observation::line().

unsigned int sequence_threshold ( unsigned int  threshold = 0 ) [static]

Gets the sequence threshold for determining a gap segment range, optionally setting a new threshold.

The sequence threshold is the minimum number of contiguous data bytes with a value of GAP_BYTE_VALUE that are required to identify a gap segment. The value is intialized to the DEFAULT_SEQUENCE_THRESHOLD value.

Parameters:
thresholdThe new sequence threshold amount. If not provided (or zero) a new value will not be set.
Returns:
The sequence threshold value before any new value is set.
See also:
gaps_in(void*, void*, unsigned int)

Referenced by Observation::components().

Gap_Map::Range & shift ( Gap_Map::Range range,
int_32  amount 
) [static]

Shifts the end points of a Range some amount.

If the shift would move the range end location at or below 0 the range becomes empty in the sense that both its lower and upper bounds are zero.

Parameters:
rangeThe Range to have its end points shifted.
amountThe amount of the shift (positive or negative).
Returns:
The range.
See also:
shift(int_32)
Gap_Map::List & shift ( Gap_Map::List list,
int_32  amount 
) [static]

Shifts a List of Ranges some amount.

Parameters:
listThe List containing the ranges to be shifted.
amountThe amount of the shift (positive or negative).
Returns:
The list.
See also:
shift(Gap_Map::Range&, int_32)

Member Data Documentation

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

Class identification name with source code version and date.

Reimplemented from Data_Component.

Referenced by Gap_Map::id(), and Gap_Map::PVL_description().

const char *const NAME = "Gap Map" [static]

The component name.

Referenced by Gap_Map::name(), and Gap_Map::PVL().

const char *const END_POINT_NAMES [static]
Initial value:
        {
        "start",
        "end"
        }

Gap range end-point value names.

const unsigned int DEFAULT_SEQUENCE_THRESHOLD = GAP_MAP_DEFAULT_SEQUENCE_THRESHOLD [static]

The default sequence of gap byte values required for a gap segment.

See also:
sequence_threshold(unsigned int)
const u_int_8 GAP_BYTE_VALUE = 0xFF [static]

The value of a "gap filled" data byte.

Referenced by Observation::components().


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