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:

Collaboration diagram for Gap_Map:

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< Range >	List
	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_Map &	operator= (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_Map &	set (const Location start, const Location end)
	Sets a gap range.
Gap_Map &	set (const Gap_Map::Range &range)
	Sets a gap Range.
Gap_Map &	set (const Gap_Map::List list)
	Sets a list of gap ranges.
Gap_Map &	clear (const Location start, const Location end)
	Clears a gap range.
Gap_Map &	clear ()
	Clears the entire map.
Gap_Map &	clear (const Gap_Map::Range &range)
	Clears a gap range.
Gap_Map &	clear (const Gap_Map::List list)
	Clears a list of gap ranges.
Gap_Map &	shift (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::Aggregate *	PVL () const
	Produces a PVL rendition of the component.
idaeim::PVL::Aggregate *	PVL_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::Range &	shift (Gap_Map::Range &range, int_32 amount)
	Shifts the end points of a Range some amount.
static Gap_Map::List &	shift (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.14 2020/02/14 01:17:18)"
	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_Component &	put (const Location location, Index range, End_Point end_point)
	Puts a the value of an end-point into a gap range.
Gap_Map &	insert_range (Index range, Location start, Location end)
	Inserts a new range into the map.
Gap_Map &	remove_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.10

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:

stream	The istream from which to read the component data.
count	The number of ranges in the map.

Gap_Map	(	const Gap_Map &	map,
		bool	data_duplicate = `true`
	)

Copy constructor.

Parameters:

map	The Gap_Map to be copied.
data_duplicate	true 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:

map	The 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:

range	The gap range to get.
end_point	Either RANGE_START or RANGE_END.

Returns:: The value of the range end-point.

Exceptions:

std::out_of_range	if the range is not in the map.
std::invalid_argument	if 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:

range The gap range to get.

Returns:: A Range pair.

Exceptions:

std::out_of_range if 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:

location The 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:

start	The starting (inclusive) location byte (0-based) of the range.
end	The 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:

range The 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:

start	The starting (inclusive) location byte (0-based) of the range.
end	The 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:

range The 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:

list	The 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:

start	The starting (inclusive) location byte (0-based) of the range.
end	The 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:

range The 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:

list	The 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:

amount The 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:

location	The end-point location.
range	The gap range to modify.
end_point	Either RANGE_START or RANGE_END.

Returns:: This Data_Component.

Exceptions:

std::out_of_range	if the range is not in the map.
std::invalid_argument	if 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:

range	The Index where the new range is to be inserted in the gap map.
start	The starting (inclusive) location byte (0-based) of the range.
end	The ending (exclusive) location byte of the range.

Returns:: This Gap_Map.

Exceptions:

range_error If 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:

first	The number (0-based) of the first range to be removed.
last	The 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:

stream	The ostream where the listing will be written.
verbose	true 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:

start	The address where the data block starts (inclusive).
end	The address where the data block ends (exclusive).
threshold	The 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:

threshold The 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:

range	The Range to have its end points shifted.
amount	The 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:

list	The List containing the ranges to be shifted.
amount	The 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.14 2020/02/14 01:17:18)" [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:

Gap_Map Class Reference

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation