Sawyer::Container::AddressMap< A, T > Class Template Reference

Description

template<class A, class T = boost::uint8_t>
class Sawyer::Container::AddressMap< A, T >

A mapping from address space to values.

This object maps addresses (actually, intervals thereof) to values. Addresses must be an integral unsigned type but values may be any type as long as they are default constructible and copyable. The address type is usually an integral type whose width is the log base 2 of the size of the address space; the value type is often unsigned 8-bit bytes.

An address map accomplishes the mapping by inheriting from an IntervalMap, whose intervals are Interval and whose values are AddressSegment<A,T>. The AddressSegment objects point to reference-counted Buffer objects that hold the values. The same values can be mapped at different addresses by inserting segments at those addresses that point to a common buffer.

An address map implements read and write concepts for copying values between user-supplied buffers and the storage areas referenced by the map. Many of the address map methods operate over a region of the map described by a set of constraints that are matched within the map. Constraints are indicated by listing them before the map I/O operation, but they do not modify the map in any way–they exist outside the map. Constraints are combined by logical conjunction. For instance, the AddressMap::next method returns the lowest address that satisfies the given constraints, or nothing. If we wanted to search for the lowest address beteen 1000 and 1999 inclusive, that has read access but not write access, we would do so like this:

Optional<Address> x = map.within(1000,1999).require(READABLE).prohibit(WRITABLE).next();

In fact, by making use of the Sawyer::Optional API, we can write a loop that iterates over such addresses, although there may be more efficient ways to do this than one address at a time:

for (Address x=1000; map.within(x,1999).require(READABLE).prohibit(WRITABLE).next().assignTo(x); ++x) ...

The next example shows how to read a buffer's worth of values anchored at a particular starting value. The read method returns an address interval to indicate what addresses were accessed, but in this case we're only interested in the number of such addresses since we know the starting address.

Value buf[10];
size_t nAccessed = map.at(1000).limit(10).read(buf).size();

An interval return value is more useful when we don't know where the operation occurs until after it occurs. For instance, to read up to 10 values that are readable at or beyond some address:

Value buf[10]
Interval<Address> accessed = map.atOrAfter(1000).limit(10).require(READABLE).read(buf);

Since all map operations take the same constraints, it is possible to rewrite the previous for loop so that instead of searching for an address it actually reads data. Here's a loop that prints all the data that's readable but not writable and falls between two addresses, regardless of what other segments also exist in that same interval:

static const size_t bufsz = 256;
Value buf[bufsz];
Address addr = 1000;
while (Interval accessed = map.within(addr, 1999).require(READABLE).prohibit(WRITABLE).limit(bufsz).read(buf)) {
    for (Address i=accessed.least(); i<=accessed.greatest(); ++i)
        std::cout <<i <<": " <<buf[i-accessed.least()] <<"\n";
    addr += accessed.size();
}

Most I/O methods require that constraints match only contiguous addresses. If there is an intervening address that does not satisfy the constraint, including addresses that are not mapped, then the matched range terminates at the non-matching address. However, the MATCH_NONCONTIGUOUS flag can be used to relax this, in which case the matched interval of addresses may include addresses that are not mapped. Regardless of whether contiguous addresses are required, the returned interval of addresses will never contain an address that is mapped and does not also satisfy the constraints. I/O operations (read and write) require contiguous addresses, but some other methods don't. For instance, the expressions

Interval<Address> found1 = map.within(100,200).require(READABLE).available(MATCH_CONTIGUOUS);
Interval<Address> found2 = map.within(100,200).require(READABLE).available(MATCH_NONCONTIGUOUS);

are the same except the second one returns an interval that might include non-mapped addresses. A few methods go even further and are able to operate across mapped addresses that don't satisfy the segment constraints, skipping over the addresses that don't satisfy the constraints. For instance, the prune and keep functions operate this way so that a call like:

map.within(100,200).require(READABLE).prohibit(WRITABLE).keep();

will discard all addresses except keeping those which are between 100 and 200 (inclusive) and which are readable but not writable. The documentation for each method states whether the default is contiguous matching, non-contiguous matching, or skipping over whole segments, and the method can take a bit flag (MatchFlags) to change its default behavior (with some restrictions).

One of the MatchFlags bits indicates whether the constraint should match the lowest or highest possible addresses. The default is to match the constraint at the lowest possible addresses. Matching at the highest addresses is useful when iterating backward. For instance, if one wants to read up to 1024 values that end at address 1023 but is not sure how many prior addresses are readable, he could use backward matching. This is much more efficient than the alternative of searching backward one address at a time, and is simpler than doing an explicit binary search:

Value buf[1024];
Interval<Address> accessed = map.at(1023).limit(1024).read(buf, MATCH_BACKWARD);

Backward and forward I/O behaves identically as far as which array element holds which value. In all cases array element zero contains the value at the lowest address read or written.

Here's an example that creates two buffers (they happen to point to arrays that the Buffer objects do not own), maps them at addresses in such a way that part of the smaller of the two buffers occludes the larger buffer, and then performs a write operation that touches parts of both buffers. We then rewrite part of the mapping and do another write operation:

using namespace Sawyer::Container;
 
typedef unsigned Address;
typedef Interval<Address> Addresses;
typedef Buffer<Address, char>::Ptr BufferPtr;
typedef AddressSegment<Address, char> Segment;
typedef AddressMap<Address, char> MemoryMap;
 
// Create some buffer objects
char data1[15];
memcpy(data1, "---------------", 15);
BufferPtr buf1 = Sawyer::Container::StaticBuffer<Address, char>::instance(data1, 15);
char data2[5];
memcpy(data2, "##########", 10);
BufferPtr buf2 = Sawyer::Container::StaticBuffer<Address, char>::instance(data2, 5); // using only first 5 bytes
 
// Map data2 into the middle of data1
MemoryMap map;
map.insert(Addresses::baseSize(1000, 15), Segment(buf1));
map.insert(Addresses::baseSize(1005,  5), Segment(buf2)); 
 
// Write across both buffers and check that data2 occluded data1
Addresses accessed = map.at(1001).limit(13).write("bcdefghijklmn");
ASSERT_always_require(accessed.size()==13);
ASSERT_always_require(0==memcmp(data1, "-bcde-----klmn-", 15));
ASSERT_always_require(0==memcmp(data2,      "fghij#####", 10));
 
// Map the middle of data1 over the top of data2 again and check that the mapping has one element. I.e., the three
// separate parts were recombined into a single entry since they are three consecutive areas of a single buffer.
map.insert(Addresses::baseSize(1005, 5), Segment(buf1, 5));
ASSERT_always_require(map.nSegments()==1);
 
// Write some data again
accessed = map.at(1001).limit(13).write("BCDEFGHIJKLMN");
ASSERT_always_require(accessed.size()==13);
ASSERT_always_require(0==memcmp(data1, "-BCDEFGHIJKLMN-", 15));
ASSERT_always_require(0==memcmp(data2,      "fghij#####", 10));

Microsoft C++ compilers

Microsoft Visual Studio 12 2013 (MSVC 18.0.30501.0) and possibly other versions look up non-dependent names in template base classes in violation of C++ standards and apparently no switch to make their behavior compliant with the standard. This causes problems for AddressMap because unqualified references to Interval should refer to the Sawyer::Container::Interval class template, but instead they refer to the Interval typedef in the base class. Our work around is to qualify all occurrences of Interval where Microsoft compilers go wrong.

Definition at line 1012 of file AddressMap.h.

#include <Sawyer/AddressMap.h>

Inheritance diagram for Sawyer::Container::AddressMap< A, T >:

Collaboration diagram for Sawyer::Container::AddressMap< A, T >:

Classes
class	Visitor
	Base class for traversals. More...

Public Types
typedef A	Address
	Type for addresses.
typedef T	Value
	Type of data stored in the address space.
typedef AddressSegment< A, T >	Segment
	Type of segments stored by this map.
typedef Sawyer::Container::Buffer< Address, Value >	Buffer
typedef Super::Node	Node
	Storage node containing interval/segment pair.
typedef Super::ValueIterator	SegmentIterator
	Iterates over segments in the map.
typedef Super::ConstValueIterator	ConstSegmentIterator
	Iterators over segments in the map.
typedef Super::ConstIntervalIterator	ConstIntervalIterator
	Iterates over address intervals in the map.
typedef Super::NodeIterator	NodeIterator
	Iterates over address interval, segment pairs in the map.
typedef Super::ConstNodeIterator	ConstNodeIterator
	Iterates over address interval/segment pairs in the map.
Public Types inherited from Sawyer::Container::IntervalMap< I, T, Policy >
typedef I	Interval
	Interval type.
typedef T	Value
	Value type.
typedef Container::Map< Interval, Value, IntervalCompare >	Map
	Type of the underlying map.
typedef Map::Node	Node
	Storage node.
typedef Map::ConstKeyIterator	ConstIntervalIterator
	Interval iterator.
typedef Map::ValueIterator	ValueIterator
	Value iterator.
typedef Map::ConstValueIterator	ConstValueIterator
	Value iterator.
typedef Map::NodeIterator	NodeIterator
	Node iterator.
typedef Map::ConstNodeIterator	ConstNodeIterator
	Node iterator.

Public Member Functions
	AddressMap ()
	Constructs an empty address map.
	AddressMap (const AddressMap &other, bool copyOnWrite=false)
	Copy constructor.
void	checkConsistency () const
	Check map consistency.
Address	nSegments () const
	Number of segments contained in the map.
Optional< Address >	next (const AddressMapConstraints< const AddressMap > &c, MatchFlags flags=0) const
	Minimum or maximum address that satisfies constraints.
Sawyer::Container::Interval< Address >	available (const AddressMapConstraints< const AddressMap > &c, MatchFlags flags=0) const
	Adress interval that satisfies constraints.
bool	exists (const AddressMapConstraints< const AddressMap > &c, MatchFlags flags=0) const
	Determines if an address exists with the specified constraints.
Sawyer::Container::Interval< Address >	unmapped (Address boundary, MatchFlags flags=0) const
	Find unmapped interval.
Optional< Address >	findFreeSpace (size_t nValues, size_t alignment=1, Sawyer::Container::Interval< Address > restriction=Sawyer::Container::Interval< Address >::whole(), MatchFlags flags=0) const
	Find free space.
void	prune (const AddressMapConstraints< AddressMap > &c, MatchFlags flags=0)
	Prune away addresses that match constraints.
void	keep (const AddressMapConstraints< AddressMap > &c, MatchFlags flags=0)
	Keep only addresses that match constraints.
void	changeAccess (unsigned requiredAccess, unsigned prohibitedAccess, const AddressMapConstraints< AddressMap > &c, MatchFlags flags=0)
	Change access bits for addresses that match constraints.
AddressMapConstraints< const AddressMap >	require (unsigned x) const
	Constraint: required access bits.
AddressMapConstraints< AddressMap >	require (unsigned x)
	Constraint: required access bits.
AddressMapConstraints< const AddressMap >	prohibit (unsigned x) const
	Constraint: prohibited access bits.
AddressMapConstraints< AddressMap >	prohibit (unsigned x)
	Constraint: prohibited access bits.
AddressMapConstraints< const AddressMap >	access (unsigned x) const
	Constraint: required and prohibited access bits.
AddressMapConstraints< AddressMap >	access (unsigned x)
	Constraint: required and prohibited access bits.
AddressMapConstraints< const AddressMap >	substr (const std::string &x) const
	Constraint: segment name substring.
AddressMapConstraints< AddressMap >	substr (const std::string &x)
	Constraint: segment name substring.
AddressMapConstraints< const AddressMap >	at (Address x) const
	Constraint: anchor point.
AddressMapConstraints< AddressMap >	at (Address x)
	Constraint: anchor point.
AddressMapConstraints< const AddressMap >	at (const Sawyer::Container::Interval< Address > &x) const
	Constraint: anchored interval.
AddressMapConstraints< AddressMap >	at (const Sawyer::Container::Interval< Address > &x)
	Constraint: anchored interval.
AddressMapConstraints< const AddressMap >	limit (size_t x) const
	Constraint: limit matched size.
AddressMapConstraints< AddressMap >	limit (size_t x)
	Constraint: limit matched size.
AddressMapConstraints< const AddressMap >	atOrAfter (Address x) const
	Constraint: address lower bound.
AddressMapConstraints< AddressMap >	atOrAfter (Address x)
	Constraint: address lower bound.
AddressMapConstraints< const AddressMap >	atOrBefore (Address x) const
	Constraint: address upper bound.
AddressMapConstraints< AddressMap >	atOrBefore (Address x)
	Constraint: address upper bound.
AddressMapConstraints< const AddressMap >	within (const Sawyer::Container::Interval< Address > &x) const
	Constraint: address lower and upper bounds.
AddressMapConstraints< AddressMap >	within (const Sawyer::Container::Interval< Address > &x)
	Constraint: address lower and upper bounds.
AddressMapConstraints< const AddressMap >	within (Address x, Address y) const
	Constraint: address lower and upper bounds.
AddressMapConstraints< AddressMap >	within (Address x, Address y)
	Constraint: address lower and upper bounds.
AddressMapConstraints< const AddressMap >	baseSize (Address base, Address size) const
	Constraint: address lower and upper bounds.
AddressMapConstraints< AddressMap >	baseSize (Address base, Address size)
	Constraint: address lower and upper bounds.
AddressMapConstraints< const AddressMap >	after (Address x) const
	Constraint: address lower bound.
AddressMapConstraints< AddressMap >	after (Address x)
	Constraint: address lower bound.
AddressMapConstraints< const AddressMap >	before (Address x) const
	Constraint: address upper bound.
AddressMapConstraints< AddressMap >	before (Address x)
	Constraint: address upper bound.
AddressMapConstraints< const AddressMap >	singleSegment () const
	Constraint: single segment.
AddressMapConstraints< AddressMap >	singleSegment ()
	Constraint: single segment.
AddressMapConstraints< const AddressMap >	segmentPredicate (SegmentPredicate< Address, Value > *p) const
	Constraint: arbitrary segment constraint.
AddressMapConstraints< AddressMap >	segmentPredicate (SegmentPredicate< Address, Value > *p)
	Constraint: arbitrary segment constraint.
AddressMapConstraints< const AddressMap >	any () const
	Constraint: matches anything.
AddressMapConstraints< AddressMap >	any ()
	Constraint: matches anything.
AddressMapConstraints< const AddressMap >	none () const
	Constraint: matches nothing.
AddressMapConstraints< AddressMap >	none ()
	Constraint: matches nothing.
boost::iterator_range< SegmentIterator >	segments ()
	Iterator range for all segments.
boost::iterator_range< ConstSegmentIterator >	segments () const
	Iterator range for all segments.
boost::iterator_range< ConstSegmentIterator >	segments (const AddressMapConstraints< const AddressMap > &c, MatchFlags flags=0) const
	Segments that overlap with constraints.
boost::iterator_range< SegmentIterator >	segments (const AddressMapConstraints< AddressMap > &c, MatchFlags flags=0)
	Iterator range for all segments.
boost::iterator_range< NodeIterator >	nodes ()
	Iterator range for nodes.
boost::iterator_range< ConstNodeIterator >	nodes () const
	Iterator range for nodes.
boost::iterator_range< ConstNodeIterator >	nodes (const AddressMapConstraints< const AddressMap > &c, MatchFlags flags=0) const
	Nodes that overlap with constraints.
boost::iterator_range< NodeIterator >	nodes (const AddressMapConstraints< AddressMap > &c, MatchFlags flags=0)
	Nodes that overlap with constraints.
ConstNodeIterator	findNode (const AddressMapConstraints< const AddressMap > &c, MatchFlags flags=0) const
	Find node containing address.
NodeIterator	findNode (const AddressMapConstraints< AddressMap > &c, MatchFlags flags=0)
	Find node containing address.
template<typename Functor >
void	traverse (Functor &functor, const AddressMapConstraints< const AddressMap > &c, MatchFlags flags=0) const
	Invoke a function on each address interval.
template<typename Functor >
void	traverse (Functor &functor, const AddressMapConstraints< AddressMap > &c, MatchFlags flags=0)
	Invoke a function on each address interval.
void	traverse (Visitor &visitor, const AddressMapConstraints< const AddressMap > &c, MatchFlags flags=0) const
	Invoke a function on each address interval.
void	traverse (Visitor &visitor, const AddressMapConstraints< AddressMap > &c, MatchFlags flags=0)
	Invoke a function on each address interval.
Sawyer::Container::Interval< Address >	read (Value *buf, const AddressMapConstraints< const AddressMap > &c, MatchFlags flags=0) const
	Reads data into the supplied buffer.
Sawyer::Container::Interval< Address >	read (std::vector< Value > &buf, const AddressMapConstraints< const AddressMap > &c, MatchFlags flags=0) const
	Reads data into the supplied buffer.
Sawyer::Container::Interval< Address >	write (const Value *buf, const AddressMapConstraints< AddressMap > &c, MatchFlags flags=0)
	Writes data from the supplied buffer.
Sawyer::Container::Interval< Address >	write (const std::vector< Value > &buf, const AddressMapConstraints< AddressMap > &c, MatchFlags flags=0)
	Writes data from the supplied buffer.
Public Member Functions inherited from Sawyer::Container::IntervalMap< I, T, Policy >
	IntervalMap ()
	Default constructor.
template<class Interval2 , class T2 , class Policy2 >
	IntervalMap (const IntervalMap< Interval2, T2, Policy2 > &other)
	Copy constructor.
template<class Interval2 , class T2 , class Policy2 >
IntervalMap &	operator= (const IntervalMap< Interval2, T2, Policy2 > &other)
	Assignment operator.
boost::iterator_range< ConstIntervalIterator >	intervals () const
	Iterators for traversing keys.
Interval	firstUnmapped (typename Interval::Value minAddr) const
	Find the first unmapped region.
Interval	lastUnmapped (typename Interval::Value maxAddr) const
	Find the last unmapped region.
bool	exists (const typename Interval::Value &size) const
	Returns true if element exists.
Optional< Value >	getOptional (const typename Interval::Value &scalar) const
	Lookup and return a value or nothing.
const Value &	getOrDefault (const typename Interval::Value &scalar) const
	Lookup and return a value or a default.
bool	isEmpty () const
	Determine if the container is empty.
size_t	nIntervals () const
	Number of nodes in the container.
Interval::Value	size () const
	Returns the number of values represented by this container.
Interval::Value	least () const
	Returns the minimum scalar key.
Interval::Value	greatest () const
	Returns the maximum scalar key.
Optional< typename Interval::Value >	least (typename Interval::Value lowerLimit) const
	Returns the limited-minimum scalar key.
Optional< typename Interval::Value >	greatest (typename Interval::Value upperLimit) const
	Returns the limited-maximum scalar key.
Optional< typename Interval::Value >	leastUnmapped (typename Interval::Value lowerLimit) const
	Returns the limited-minimum unmapped scalar key.
Optional< typename Interval::Value >	greatestUnmapped (typename Interval::Value upperLimit) const
	Returns the limited-maximum unmapped scalar key.
Interval	hull () const
	Returns the range of values in this map.
void	clear ()
	Empties the container.
void	erase (const Interval &erasure)
	Erase the specified interval.
template<typename T2 , class Policy2 >
void	eraseMultiple (const IntervalMap< Interval, T2, Policy2 > &other)
	Erase intervals specified in another IntervalMap.
void	insert (Interval key, Value value, bool makeHole=true)
	Insert a key/value pair.
template<typename T2 , class Policy2 >
void	insertMultiple (const IntervalMap< Interval, T2, Policy2 > &other, bool makeHole=true)
	Insert values from another container.
bool	overlaps (const Interval &interval) const
bool	isOverlapping (const Interval &interval) const
template<typename T2 , class Policy2 >
bool	overlaps (const IntervalMap< Interval, T2, Policy2 > &other) const
template<typename T2 , class Policy2 >
bool	isOverlapping (const IntervalMap< Interval, T2, Policy2 > &other) const
bool	isDistinct (const Interval &interval) const
template<typename T2 , class Policy2 >
bool	isDistinct (const IntervalMap< Interval, T2, Policy2 > &other) const
bool	contains (Interval key) const
template<typename T2 , class Policy2 >
bool	contains (const IntervalMap< Interval, T2, Policy2 > &other) const
boost::iterator_range< NodeIterator >	nodes ()
	Iterators for traversing nodes.
boost::iterator_range< ConstNodeIterator >	nodes () const
	Iterators for traversing nodes.
boost::iterator_range< ValueIterator >	values ()
	Iterators for traversing values.
boost::iterator_range< ConstValueIterator >	values () const
	Iterators for traversing values.
NodeIterator	lowerBound (const typename Interval::Value &scalar)
	Find the first node whose interval ends at or above the specified scalar key.
ConstNodeIterator	lowerBound (const typename Interval::Value &scalar) const
	Find the first node whose interval ends at or above the specified scalar key.
NodeIterator	upperBound (const typename Interval::Value &scalar)
	Find the first node whose interval begins above the specified scalar key.
ConstNodeIterator	upperBound (const typename Interval::Value &scalar) const
	Find the first node whose interval begins above the specified scalar key.
const Value &	operator[] (const typename Interval::Value &scalar) const
	Returns a reference to an existing value.
const Value &	get (const typename Interval::Value &scalar) const
	Returns a reference to an existing value.
Value &	getOrElse (const typename Interval::Value &scalar, Value &dflt)
	Lookup and return a value or something else.
const Value &	getOrElse (const typename Interval::Value &scalar, const Value &dflt) const
	Lookup and return a value or something else.
NodeIterator	findPrior (const typename Interval::Value &scalar)
	Find the last node whose interval starts at or below the specified scalar key.
ConstNodeIterator	findPrior (const typename Interval::Value &scalar) const
	Find the last node whose interval starts at or below the specified scalar key.
NodeIterator	find (const typename Interval::Value &scalar)
	Find the node containing the specified scalar key.
ConstNodeIterator	find (const typename Interval::Value &scalar) const
	Find the node containing the specified scalar key.
boost::iterator_range< NodeIterator >	findAll (const Interval &interval)
	Finds all nodes overlapping the specified interval.
boost::iterator_range< ConstNodeIterator >	findAll (const Interval &interval) const
	Finds all nodes overlapping the specified interval.
NodeIterator	findFirstOverlap (const Interval &interval)
	Find first interval that overlaps with the specified interval.
ConstNodeIterator	findFirstOverlap (const Interval &interval) const
	Find first interval that overlaps with the specified interval.
template<typename T2 , class Policy2 >
std::pair< NodeIterator, typename IntervalMap< Interval, T2, Policy2 >::ConstNodeIterator >	findFirstOverlap (typename IntervalMap::NodeIterator thisIter, const IntervalMap< Interval, T2, Policy2 > &other, typename IntervalMap< Interval, T2, Policy2 >::ConstNodeIterator otherIter)
	Find first interval that overlaps with any in another container.
template<typename T2 , class Policy2 >
std::pair< ConstNodeIterator, typename IntervalMap< Interval, T2, Policy2 >::ConstNodeIterator >	findFirstOverlap (typename IntervalMap::ConstNodeIterator thisIter, const IntervalMap< Interval, T2, Policy2 > &other, typename IntervalMap< Interval, T2, Policy2 >::ConstNodeIterator otherIter) const
	Find first interval that overlaps with any in another container.
NodeIterator	firstFit (const typename Interval::Value &size, NodeIterator start)
	Find the first fit node at or after a starting point.
ConstNodeIterator	firstFit (const typename Interval::Value &size, ConstNodeIterator start) const
	Find the first fit node at or after a starting point.
NodeIterator	bestFit (const typename Interval::Value &size, NodeIterator start)
	Find the best fit node at or after a starting point.
ConstNodeIterator	bestFit (const typename Interval::Value &size, ConstNodeIterator start) const
	Find the best fit node at or after a starting point.

Additional Inherited Members
Static Public Member Functions inherited from Sawyer::Container::IntervalMap< I, T, Policy >
template<class IMap >
static IntervalMapTraits< IMap >::NodeIterator	findPriorImpl (IMap &imap, const typename Interval::Value &scalar)
	Find the last node whose interval starts at or below the specified scalar key.
template<class IMap >
static IntervalMapTraits< IMap >::NodeIterator	findImpl (IMap &imap, const typename Interval::Value &scalar)
	Find the node containing the specified scalar key.
template<class IMap >
static boost::iterator_range< typename IntervalMapTraits< IMap >::NodeIterator >	findAllImpl (IMap &imap, const Interval &interval)
	Finds all nodes overlapping the specified interval.
template<class IMap >
static IntervalMapTraits< IMap >::NodeIterator	findFirstOverlapImpl (IMap &imap, const Interval &interval)
	Find first interval that overlaps with the specified interval.
template<class IMap , typename T2 , class Policy2 >
static std::pair< typename IntervalMapTraits< IMap >::NodeIterator, typename IntervalMap< Interval, T2, Policy2 >::ConstNodeIterator >	findFirstOverlapImpl (IMap &imap, typename IntervalMapTraits< IMap >::NodeIterator thisIter, const IntervalMap< Interval, T2, Policy2 > &other, typename IntervalMap< Interval, T2, Policy2 >::ConstNodeIterator otherIter)
	Find first interval that overlaps with any in another container.
template<class IMap >
static IntervalMapTraits< IMap >::NodeIterator	firstFitImpl (IMap &imap, const typename Interval::Value &size, typename IntervalMapTraits< IMap >::NodeIterator start)
	Find the first fit node at or after a starting point.
template<class IMap >
static IntervalMapTraits< IMap >::NodeIterator	bestFitImpl (IMap &imap, const typename Interval::Value &size, typename IntervalMapTraits< IMap >::NodeIterator start)
	Find the best fit node at or after a starting point.

Member Typedef Documentation

Address

template<class A , class T = boost::uint8_t>

typedef A Sawyer::Container::AddressMap< A, T >::Address

Type for addresses.

This should be an unsigned type.

Definition at line 1017 of file AddressMap.h.

Value

template<class A , class T = boost::uint8_t>

typedef T Sawyer::Container::AddressMap< A, T >::Value

Type of data stored in the address space.

Definition at line 1018 of file AddressMap.h.

Segment

template<class A , class T = boost::uint8_t>

typedef AddressSegment<A, T> Sawyer::Container::AddressMap< A, T >::Segment

Type of segments stored by this map.

Definition at line 1019 of file AddressMap.h.

Buffer

template<class A , class T = boost::uint8_t>

typedef Sawyer::Container::Buffer<Address, Value> Sawyer::Container::AddressMap< A, T >::Buffer

Definition at line 1020 of file AddressMap.h.

Node

template<class A , class T = boost::uint8_t>

typedef Super::Node Sawyer::Container::AddressMap< A, T >::Node

Storage node containing interval/segment pair.

Definition at line 1021 of file AddressMap.h.

SegmentIterator

template<class A , class T = boost::uint8_t>

typedef Super::ValueIterator Sawyer::Container::AddressMap< A, T >::SegmentIterator

Iterates over segments in the map.

Definition at line 1022 of file AddressMap.h.

ConstSegmentIterator

template<class A , class T = boost::uint8_t>

typedef Super::ConstValueIterator Sawyer::Container::AddressMap< A, T >::ConstSegmentIterator

Iterators over segments in the map.

Definition at line 1023 of file AddressMap.h.

ConstIntervalIterator

template<class A , class T = boost::uint8_t>

typedef Super::ConstIntervalIterator Sawyer::Container::AddressMap< A, T >::ConstIntervalIterator

Iterates over address intervals in the map.

Definition at line 1024 of file AddressMap.h.

NodeIterator

template<class A , class T = boost::uint8_t>

typedef Super::NodeIterator Sawyer::Container::AddressMap< A, T >::NodeIterator

Iterates over address interval, segment pairs in the map.

Definition at line 1025 of file AddressMap.h.

ConstNodeIterator

template<class A , class T = boost::uint8_t>

typedef Super::ConstNodeIterator Sawyer::Container::AddressMap< A, T >::ConstNodeIterator

Iterates over address interval/segment pairs in the map.

Definition at line 1026 of file AddressMap.h.

Constructor & Destructor Documentation

AddressMap() [1/2]

template<class A , class T = boost::uint8_t>

Sawyer::Container::AddressMap< A, T >::AddressMap ( )

inline

Constructs an empty address map.

Definition at line 1038 of file AddressMap.h.

AddressMap() [2/2]

template<class A , class T = boost::uint8_t>

Sawyer::Container::AddressMap< A, T >::AddressMap ( const AddressMap< A, T > &  other, bool  copyOnWrite = false  )

inline

Copy constructor.

The new address map has the same addresses mapped to the same buffers as the other map. The buffers themselves are not copied since they are reference counted.

If copyOnWrite is set then the buffers are marked so that any subsequent write to that buffer via the write method from any AddressMap object will cause a new copy to be created and used by the AddressMap that's doing the writing. One should be careful when buffers are intended to be shared because setting the copy-on-write bit on the buffer will cause the sharing to be broken. For example, if map1 is created and then copied into map2 with the copy-on-write bit cleared, then any writes to the buffer via map1 will be visible when reading from map2 and vice versa. However, if map3 is then created by copying either map1 or map2 with the copy-on-write bit set, then writes to any of the three maps will cause that map to obtain an independent copy of the buffer, effectively removing the sharing that was intended between map1 and map2. Another thing to be aware of is that some buffer types will return a different buffer type when they're copied. For instance, copying a StaticBuffer or MappedBuffer will return an AllocatingBuffer.

Definition at line 1055 of file AddressMap.h.

References Sawyer::Container::IntervalMap< I, T, Policy >::values().

Member Function Documentation

require() [1/2]

template<class A , class T = boost::uint8_t>

AddressMapConstraints< const AddressMap > Sawyer::Container::AddressMap< A, T >::require ( unsigned  x ) const

inline

Constraint: required access bits.

Constrains address to those that have all of the access bits that are set in x.

Definition at line 1069 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::require().

require() [2/2]

template<class A , class T = boost::uint8_t>

AddressMapConstraints< AddressMap > Sawyer::Container::AddressMap< A, T >::require ( unsigned  x )

inline

Constraint: required access bits.

Constrains address to those that have all of the access bits that are set in x.

Definition at line 1072 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::require().

prohibit() [1/2]

template<class A , class T = boost::uint8_t>

AddressMapConstraints< const AddressMap > Sawyer::Container::AddressMap< A, T >::prohibit ( unsigned  x ) const

inline

Constraint: prohibited access bits.

Constrains addresses to those that have none of the access bits that are set in x.

Definition at line 1082 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::prohibit().

prohibit() [2/2]

template<class A , class T = boost::uint8_t>

AddressMapConstraints< AddressMap > Sawyer::Container::AddressMap< A, T >::prohibit ( unsigned  x )

inline

Constraint: prohibited access bits.

Constrains addresses to those that have none of the access bits that are set in x.

Definition at line 1085 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::prohibit().

access() [1/2]

template<class A , class T = boost::uint8_t>

AddressMapConstraints< const AddressMap > Sawyer::Container::AddressMap< A, T >::access ( unsigned  x ) const

inline

Constraint: required and prohibited access bits.

Constrains address to those that have the specified access bits. This method is the same as calling require with the specified bit vector, and prohibit with the inverted bit vector.

Definition at line 1096 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::access().

access() [2/2]

template<class A , class T = boost::uint8_t>

AddressMapConstraints< AddressMap > Sawyer::Container::AddressMap< A, T >::access ( unsigned  x )

inline

Constraint: required and prohibited access bits.

Constrains address to those that have the specified access bits. This method is the same as calling require with the specified bit vector, and prohibit with the inverted bit vector.

Definition at line 1099 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::access().

substr() [1/2]

template<class A , class T = boost::uint8_t>

AddressMapConstraints< const AddressMap > Sawyer::Container::AddressMap< A, T >::substr ( const std::string &  x ) const

inline

Constraint: segment name substring.

Constrains addresses to those that belong to a segment that contains string x as part of its name.

Definition at line 1109 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::substr().

substr() [2/2]

template<class A , class T = boost::uint8_t>

AddressMapConstraints< AddressMap > Sawyer::Container::AddressMap< A, T >::substr ( const std::string &  x )

inline

Constraint: segment name substring.

Constrains addresses to those that belong to a segment that contains string x as part of its name.

Definition at line 1112 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::substr().

at() [1/4]

template<class A , class T = boost::uint8_t>

AddressMapConstraints< const AddressMap > Sawyer::Container::AddressMap< A, T >::at ( Address  x ) const

inline

Constraint: anchor point.

Constrains addresses to a sequence that begins at x. If address x is not part of the addresses matched by the other constraints, then no address matches.

Definition at line 1123 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::at().

at() [2/4]

template<class A , class T = boost::uint8_t>

AddressMapConstraints< AddressMap > Sawyer::Container::AddressMap< A, T >::at ( Address  x )

inline

Constraint: anchor point.

Constrains addresses to a sequence that begins at x. If address x is not part of the addresses matched by the other constraints, then no address matches.

Definition at line 1126 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::at().

at() [3/4]

template<class A , class T = boost::uint8_t>

AddressMapConstraints< const AddressMap > Sawyer::Container::AddressMap< A, T >::at ( const Sawyer::Container::Interval< Address > &  x ) const

inline

Constraint: anchored interval.

Constrains addresses so that the lowest or highest matched address is the specified anchor point. When matching constraints in the forward direction (the default) then the anchor must be the lowest address, and when matching in the backward direction the anchor must be the highest address. The direction is specified by an argument to the operation.

For instance:

map.at(100).limit(10).read(buf);               // 1
map.at(100).limit(10).read(buf, MATCH_BACKWARD); // 2

Expression 1 reads up to 10 values such that the lowest value read is at address 100, while expression 2 reads up to 10 values such that the highest value read is at address 100. In both cases, if address 100 is not mapped (or otherwise does not satisfy the constraints) then nothing is read.

Definition at line 1150 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::at().

at() [4/4]

template<class A , class T = boost::uint8_t>

AddressMapConstraints< AddressMap > Sawyer::Container::AddressMap< A, T >::at ( const Sawyer::Container::Interval< Address > &  x )

inline

Constraint: anchored interval.

Constrains addresses so that the lowest or highest matched address is the specified anchor point. When matching constraints in the forward direction (the default) then the anchor must be the lowest address, and when matching in the backward direction the anchor must be the highest address. The direction is specified by an argument to the operation.

For instance:

map.at(100).limit(10).read(buf);               // 1
map.at(100).limit(10).read(buf, MATCH_BACKWARD); // 2

Expression 1 reads up to 10 values such that the lowest value read is at address 100, while expression 2 reads up to 10 values such that the highest value read is at address 100. In both cases, if address 100 is not mapped (or otherwise does not satisfy the constraints) then nothing is read.

Definition at line 1153 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::at().

limit() [1/2]

template<class A , class T = boost::uint8_t>

AddressMapConstraints< const AddressMap > Sawyer::Container::AddressMap< A, T >::limit ( size_t  x ) const

inline

Constraint: limit matched size.

Constrains the matched addresses so that at most x addresses match. Forward matching matches the first x addresses while backward matching matches the last x addresses.

Definition at line 1164 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::limit().

limit() [2/2]

template<class A , class T = boost::uint8_t>

AddressMapConstraints< AddressMap > Sawyer::Container::AddressMap< A, T >::limit ( size_t  x )

inline

Constraint: limit matched size.

Constrains the matched addresses so that at most x addresses match. Forward matching matches the first x addresses while backward matching matches the last x addresses.

Definition at line 1167 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::limit().

atOrAfter() [1/2]

template<class A , class T = boost::uint8_t>

AddressMapConstraints< const AddressMap > Sawyer::Container::AddressMap< A, T >::atOrAfter ( Address  x ) const

inline

Constraint: address lower bound.

Constrains matched addresses so that they are all greater than or equal to x.

Definition at line 1177 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::atOrAfter().

Referenced by Sawyer::Container::AddressMapConstraints< AddressMap >::at().

atOrAfter() [2/2]

template<class A , class T = boost::uint8_t>

AddressMapConstraints< AddressMap > Sawyer::Container::AddressMap< A, T >::atOrAfter ( Address  x )

inline

Constraint: address lower bound.

Constrains matched addresses so that they are all greater than or equal to x.

Definition at line 1180 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::atOrAfter().

atOrBefore() [1/2]

template<class A , class T = boost::uint8_t>

AddressMapConstraints< const AddressMap > Sawyer::Container::AddressMap< A, T >::atOrBefore ( Address  x ) const

inline

Constraint: address upper bound.

Constrains matched addresses so that they are all less than or equal to x.

Definition at line 1190 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::atOrBefore().

atOrBefore() [2/2]

template<class A , class T = boost::uint8_t>

AddressMapConstraints< AddressMap > Sawyer::Container::AddressMap< A, T >::atOrBefore ( Address  x )

inline

Constraint: address upper bound.

Constrains matched addresses so that they are all less than or equal to x.

Definition at line 1193 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::atOrBefore().

within() [1/4]

template<class A , class T = boost::uint8_t>

AddressMapConstraints< const AddressMap > Sawyer::Container::AddressMap< A, T >::within ( const Sawyer::Container::Interval< Address > &  x ) const

inline

Constraint: address lower and upper bounds.

Constrains matched addresses so they are all within the specified interval.

Definition at line 1203 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::within().

within() [2/4]

template<class A , class T = boost::uint8_t>

AddressMapConstraints< AddressMap > Sawyer::Container::AddressMap< A, T >::within ( const Sawyer::Container::Interval< Address > &  x )

inline

Constraint: address lower and upper bounds.

Constrains matched addresses so they are all within the specified interval.

Definition at line 1206 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::within().

within() [3/4]

template<class A , class T = boost::uint8_t>

AddressMapConstraints< const AddressMap > Sawyer::Container::AddressMap< A, T >::within ( Address  x, Address  y  ) const

inline

Constraint: address lower and upper bounds.

Constrains matched addresses so they are all greater than or equal to x and less than or equal to y.

Definition at line 1216 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::within().

within() [4/4]

template<class A , class T = boost::uint8_t>

AddressMapConstraints< AddressMap > Sawyer::Container::AddressMap< A, T >::within ( Address  x, Address  y  )

inline

Constraint: address lower and upper bounds.

Constrains matched addresses so they are all greater than or equal to x and less than or equal to y.

Definition at line 1219 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::within().

baseSize() [1/2]

template<class A , class T = boost::uint8_t>

AddressMapConstraints< const AddressMap > Sawyer::Container::AddressMap< A, T >::baseSize ( Address  base, Address  size  ) const

inline

Constraint: address lower and upper bounds.

Specifies lower and upper bounds. The upper bound is specified indirectly by a size.

Definition at line 1229 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::baseSize(), and Sawyer::Container::IntervalMap< I, T, Policy >::size().

baseSize() [2/2]

template<class A , class T = boost::uint8_t>

AddressMapConstraints< AddressMap > Sawyer::Container::AddressMap< A, T >::baseSize ( Address  base, Address  size  )

inline

Constraint: address lower and upper bounds.

Specifies lower and upper bounds. The upper bound is specified indirectly by a size.

Definition at line 1232 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::baseSize(), and Sawyer::Container::IntervalMap< I, T, Policy >::size().

after() [1/2]

template<class A , class T = boost::uint8_t>

AddressMapConstraints< const AddressMap > Sawyer::Container::AddressMap< A, T >::after ( Address  x ) const

inline

Constraint: address lower bound.

Constrains matched addresses so that they are all greater than x.

Definition at line 1242 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::after().

after() [2/2]

template<class A , class T = boost::uint8_t>

AddressMapConstraints< AddressMap > Sawyer::Container::AddressMap< A, T >::after ( Address  x )

inline

Constraint: address lower bound.

Constrains matched addresses so that they are all greater than x.

Definition at line 1245 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::after().

before() [1/2]

template<class A , class T = boost::uint8_t>

AddressMapConstraints< const AddressMap > Sawyer::Container::AddressMap< A, T >::before ( Address  x ) const

inline

Constraint: address upper bound.

Constrains matched addresses so that they are all less than x.

Definition at line 1255 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::before().

before() [2/2]

template<class A , class T = boost::uint8_t>

AddressMapConstraints< AddressMap > Sawyer::Container::AddressMap< A, T >::before ( Address  x )

inline

Constraint: address upper bound.

Constrains matched addresses so that they are all less than x.

Definition at line 1258 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::before().

singleSegment() [1/2]

template<class A , class T = boost::uint8_t>

AddressMapConstraints< const AddressMap > Sawyer::Container::AddressMap< A, T >::singleSegment ( ) const

inline

Constraint: single segment.

Constrains matched addresses so that they all come from the same segment.

Definition at line 1268 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::singleSegment().

singleSegment() [2/2]

template<class A , class T = boost::uint8_t>

AddressMapConstraints< AddressMap > Sawyer::Container::AddressMap< A, T >::singleSegment ( )

inline

Constraint: single segment.

Constrains matched addresses so that they all come from the same segment.

Definition at line 1271 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::singleSegment().

segmentPredicate() [1/2]

template<class A , class T = boost::uint8_t>

AddressMapConstraints< const AddressMap > Sawyer::Container::AddressMap< A, T >::segmentPredicate ( SegmentPredicate< Address, Value > *  p ) const

inline

Constraint: arbitrary segment constraint.

Constraints matched addresses to those for which the chain of segment predicates return true.

Definition at line 1281 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::segmentPredicate().

segmentPredicate() [2/2]

template<class A , class T = boost::uint8_t>

AddressMapConstraints< AddressMap > Sawyer::Container::AddressMap< A, T >::segmentPredicate ( SegmentPredicate< Address, Value > *  p )

inline

Constraint: arbitrary segment constraint.

Constraints matched addresses to those for which the chain of segment predicates return true.

Definition at line 1284 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::segmentPredicate().

any() [1/2]

template<class A , class T = boost::uint8_t>

AddressMapConstraints< const AddressMap > Sawyer::Container::AddressMap< A, T >::any ( ) const

inline

Constraint: matches anything.

The null constraint matches any mapped address.

Definition at line 1294 of file AddressMap.h.

any() [2/2]

template<class A , class T = boost::uint8_t>

AddressMapConstraints< AddressMap > Sawyer::Container::AddressMap< A, T >::any ( )

inline

Constraint: matches anything.

The null constraint matches any mapped address.

Definition at line 1297 of file AddressMap.h.

none() [1/2]

template<class A , class T = boost::uint8_t>

AddressMapConstraints< const AddressMap > Sawyer::Container::AddressMap< A, T >::none ( ) const

inline

Constraint: matches nothing.

Constrains addresses so that none of them can match.

Definition at line 1307 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::none().

Referenced by Sawyer::Container::AddressMapConstraints< AddressMap >::at(), Sawyer::Container::AddressMapConstraints< AddressMap >::at(), Sawyer::Container::AddressMapConstraints< AddressMap >::atOrAfter(), Sawyer::Container::AddressMapConstraints< AddressMap >::atOrBefore(), and Sawyer::Container::AddressMapConstraints< AddressMap >::limit().

none() [2/2]

template<class A , class T = boost::uint8_t>

AddressMapConstraints< AddressMap > Sawyer::Container::AddressMap< A, T >::none ( )

inline

Constraint: matches nothing.

Constrains addresses so that none of them can match.

Definition at line 1310 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::none().

checkConsistency()

template<class A , class T = boost::uint8_t>

void Sawyer::Container::AddressMap< A, T >::checkConsistency ( ) const

inline

Check map consistency.

Performs the following consistency checks and throws an std::runtime_error if something is wrong.

• A segment should not have a null buffer pointer.

• Checks that the buffers of the map are appropriate sizes for the address interval in which they're mapped.

Definition at line 1322 of file AddressMap.h.

References Sawyer::Container::Interval< T >::greatest(), Sawyer::Container::Interval< T >::least(), Sawyer::Container::AddressMap< A, T >::nodes(), and Sawyer::Container::Interval< T >::size().

Referenced by Sawyer::Container::AddressMap< A, T >::read(), and Sawyer::Container::AddressMap< A, T >::write().

nSegments()

template<class A , class T = boost::uint8_t>

Address Sawyer::Container::AddressMap< A, T >::nSegments ( ) const

inline

Number of segments contained in the map.

Multiple segments may be pointing to the same underlying buffer, and the number of segments is not necessarily the same as the net number of segments inserted and erased. For instance, if a segment is inserted for addresses [0,99] and then a different segment is inserted at [50,59], the map will contain three segments at addresses [0,49], [50,59], and [60,99], although the first and third segment point into different parts of the same buffer.

Definition at line 1347 of file AddressMap.h.

References Sawyer::Container::IntervalMap< I, T, Policy >::nIntervals().

segments() [1/4]

template<class A , class T = boost::uint8_t>

boost::iterator_range< SegmentIterator > Sawyer::Container::AddressMap< A, T >::segments ( )

inline

Iterator range for all segments.

This is just an alias for the values method defined in the super class.

Definition at line 1354 of file AddressMap.h.

References Sawyer::Container::IntervalMap< I, T, Policy >::values().

segments() [2/4]

template<class A , class T = boost::uint8_t>

boost::iterator_range< ConstSegmentIterator > Sawyer::Container::AddressMap< A, T >::segments ( ) const

inline

Iterator range for all segments.

This is just an alias for the values method defined in the super class.

Definition at line 1355 of file AddressMap.h.

References Sawyer::Container::IntervalMap< I, T, Policy >::values().

segments() [3/4]

template<class A , class T = boost::uint8_t>

boost::iterator_range< ConstSegmentIterator > Sawyer::Container::AddressMap< A, T >::segments ( const AddressMapConstraints< const AddressMap< A, T > > &  c, MatchFlags  flags = 0  ) const

inline

Segments that overlap with constraints.

Returns an iterator range for the first longest sequence of segments that all at least partly satisfy the specified constraints. Constraints are always matched at the address level and the return value consists of those segments that contain at least one matched address. Constraints normally match contiguous addresses, and therefore the returned list will be segments that are contiguous. Disabling the contiguous constraint with the MATCH_NONCONTIGUOUS flag relaxes the requirement that addresses be contiguous, although it still enforces that the matched interval contains only addresses that satisfy the constraints or addresses that are not mapped.

The following example finds the first sequence of one or more segments having "IAT" as a substring in their name and returns the longest sequence at that position. The sequence is then used to remove execute permission from each segment.

typedef AddressMap<Address,Value>::Segment Segment;
for (Segment &segment: map.substr("IAT").segments(MATCH_NONCONTIGUOUS))
    segment.accessibility(segment.accessibility() & ~EXECUTABLE);

Definition at line 1378 of file AddressMap.h.

segments() [4/4]

template<class A , class T = boost::uint8_t>

boost::iterator_range< SegmentIterator > Sawyer::Container::AddressMap< A, T >::segments ( const AddressMapConstraints< AddressMap< A, T > > &  c, MatchFlags  flags = 0  )

inline

Iterator range for all segments.

This is just an alias for the values method defined in the super class.

Definition at line 1387 of file AddressMap.h.

nodes() [1/4]

template<class A , class T = boost::uint8_t>

boost::iterator_range< NodeIterator > Sawyer::Container::AddressMap< A, T >::nodes ( )

inline

Iterator range for nodes.

This is just an alias for the Vertices and Edges method defined in the super class. See also the overloaded method of the same name that takes a constraint and thus returns only some nodes.

Definition at line 1402 of file AddressMap.h.

References Sawyer::Container::IntervalMap< I, T, Policy >::nodes().

Referenced by Sawyer::Container::AddressMap< A, T >::checkConsistency(), Sawyer::Container::AddressMap< A, T >::findNode(), Sawyer::Container::AddressMap< A, T >::findNode(), and Sawyer::Container::AddressMap< A, T >::write().

nodes() [2/4]

template<class A , class T = boost::uint8_t>

boost::iterator_range< ConstNodeIterator > Sawyer::Container::AddressMap< A, T >::nodes ( ) const

inline

Iterator range for nodes.

This is just an alias for the Vertices and Edges method defined in the super class. See also the overloaded method of the same name that takes a constraint and thus returns only some nodes.

Definition at line 1403 of file AddressMap.h.

References Sawyer::Container::IntervalMap< I, T, Policy >::nodes().

nodes() [3/4]

template<class A , class T = boost::uint8_t>

boost::iterator_range< ConstNodeIterator > Sawyer::Container::AddressMap< A, T >::nodes ( const AddressMapConstraints< const AddressMap< A, T > > &  c, MatchFlags  flags = 0  ) const

inline

Nodes that overlap with constraints.

Returns an iterator range for the first longest sequence of interval/segment nodes that all at least partly satisfy the specified constraints. Constraints are always matched at the address level and the return value consists of those nodes that contain at least one matched address. Constraints normally match contiguous addresses, and therefore the returned list will be nodes that are contiguous. Disabling the contiguous constraint with the MATCH_NONCONTIGUOUS flag relaxes the requirement that addresses be contiguous, although it still enforces that the matched interval contains only addresses that satisfy the constraints or addresses that are not mapped.

The following example finds the first sequence of one or more segments having addresses between 1000 and 2000 and "IAT" as part of their name and prints their address interval and name:

typedef AddressMap<Address,Value>::Node Node;
for (const Node &node: map.within(1000,2000).substr("IAT").nodes(MATCH_NONCONTIGUOUS))
    std::cout <<"segment at " <<node.key() <<" named " <<node.value().name() <<"\n";

Definition at line 1426 of file AddressMap.h.

nodes() [4/4]

template<class A , class T = boost::uint8_t>

boost::iterator_range< NodeIterator > Sawyer::Container::AddressMap< A, T >::nodes ( const AddressMapConstraints< AddressMap< A, T > > &  c, MatchFlags  flags = 0  )

inline

Nodes that overlap with constraints.

Returns an iterator range for the first longest sequence of interval/segment nodes that all at least partly satisfy the specified constraints. Constraints are always matched at the address level and the return value consists of those nodes that contain at least one matched address. Constraints normally match contiguous addresses, and therefore the returned list will be nodes that are contiguous. Disabling the contiguous constraint with the MATCH_NONCONTIGUOUS flag relaxes the requirement that addresses be contiguous, although it still enforces that the matched interval contains only addresses that satisfy the constraints or addresses that are not mapped.

The following example finds the first sequence of one or more segments having addresses between 1000 and 2000 and "IAT" as part of their name and prints their address interval and name:

typedef AddressMap<Address,Value>::Node Node;
for (const Node &node: map.within(1000,2000).substr("IAT").nodes(MATCH_NONCONTIGUOUS))
    std::cout <<"segment at " <<node.key() <<" named " <<node.value().name() <<"\n";

Definition at line 1435 of file AddressMap.h.

next()

template<class A , class T = boost::uint8_t>

Optional< Address > Sawyer::Container::AddressMap< A, T >::next ( const AddressMapConstraints< const AddressMap< A, T > > &  c, MatchFlags  flags = 0  ) const

inline

Minimum or maximum address that satisfies constraints.

This method returns the minimum or maximum address that satisfies the constraints, depending on whether the direction is forward or backward. It is named "next" because it is often used in loops that iterate over addresses. For instance, the following loop iterates over all readable addresses one at a time (there are more efficient ways to do this).

typedef AddressMap<Address,Value> Map;
Map map = ...;
for (Address a=0; map.atOrAfter(a).require(READABLE).next().assignTo(a); ++a) {
    ...
    if (a == map.hull().greatest())
        break;
}       

The conditional break at the end of the loop is to handle the case where a is the largest possible address, and incrementing it would result in an overflow back to a smaller address. The hull method returns in constant time, but a slightly faster test (that is also more self-documenting) is:

if (a == boost::integer_traits<Address>::const_max)
    break;

Backward iterating is similar:

typedef AddressMap<Address,Value> Map;
Map map = ...;
for (Address a=map.hull().greatest(); map.atOrBefore(a).require(READABLE).next(MATCH_BACKWARD).assignTo(a); --a) {
    ...
    if (a == map.hull().least())
        break;
}

Definition at line 1482 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::limit().

Referenced by Sawyer::Container::AddressMap< A, T >::exists().

available()

template<class A , class T = boost::uint8_t>

Sawyer::Container::Interval< Address > Sawyer::Container::AddressMap< A, T >::available ( const AddressMapConstraints< const AddressMap< A, T > > &  c, MatchFlags  flags = 0  ) const

inline

Adress interval that satisfies constraints.

Returns the lowest or highest (depending on direction) largest address interval that satisfies the specified constraints. The interval can be contiguous (the default), or it may contain unmapped addresses. In any case, all mapped addresses in the returned interval satisfy the constraints.

Definition at line 1496 of file AddressMap.h.

exists()

template<class A , class T = boost::uint8_t>

bool Sawyer::Container::AddressMap< A, T >::exists ( const AddressMapConstraints< const AddressMap< A, T > > &  c, MatchFlags  flags = 0  ) const

inline

Determines if an address exists with the specified constraints.

Checking for existence is just a wrapper around next. For instance, these two statements both check whether the address 1000 exists and has execute permission:

if (map.at(1000).require(EXECUTABLE).exists()) ...
if (map.at(1000).require(EXECUTABLE).next()) ...

Definition at line 1512 of file AddressMap.h.

References Sawyer::Container::AddressMap< A, T >::next().

findNode() [1/2]

template<class A , class T = boost::uint8_t>

ConstNodeIterator Sawyer::Container::AddressMap< A, T >::findNode ( const AddressMapConstraints< const AddressMap< A, T > > &  c, MatchFlags  flags = 0  ) const

inline

Find node containing address.

Finds the node that contains the first (or last, depending on direction) address that satisfies the constraints.

Definition at line 1521 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::limit(), and Sawyer::Container::AddressMap< A, T >::nodes().

findNode() [2/2]

template<class A , class T = boost::uint8_t>

NodeIterator Sawyer::Container::AddressMap< A, T >::findNode ( const AddressMapConstraints< AddressMap< A, T > > &  c, MatchFlags  flags = 0  )

inline

Find node containing address.

Finds the node that contains the first (or last, depending on direction) address that satisfies the constraints.

Definition at line 1524 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::limit(), and Sawyer::Container::AddressMap< A, T >::nodes().

unmapped()

template<class A , class T = boost::uint8_t>

Sawyer::Container::Interval< Address > Sawyer::Container::AddressMap< A, T >::unmapped ( Address  boundary, MatchFlags  flags = 0  ) const

inline

Find unmapped interval.

Searches for the lowest (or highest if direction is MATCH_BACKWARD) interval that is not mapped and returns its address and size. The returned interval will not contain addresses that are less than (or greater than) than boundary. If no such unmapped intervals exist then the empty interval is returned.

This method does not use constraints since it searches for addresses that do not exist in the map.

Definition at line 1537 of file AddressMap.h.

References Sawyer::Container::IntervalMap< I, T, Policy >::firstUnmapped(), and Sawyer::Container::IntervalMap< I, T, Policy >::lastUnmapped().

Referenced by Sawyer::Container::AddressMap< A, T >::findFreeSpace().

findFreeSpace()

template<class A , class T = boost::uint8_t>

Optional< Address > Sawyer::Container::AddressMap< A, T >::findFreeSpace ( size_t  nValues, size_t  alignment = 1, Sawyer::Container::Interval< Address >  restriction = Sawyer::Container::Interval<Address>::whole(), MatchFlags  flags = 0  ) const

inline

Find free space.

Finds a suitable region of unmapped address space in which nValues values can be mapped. The return value is either an address where the values can be mapped, or nothing if no such unmapped region is available. The restriction can be used to restrict which addresses are considered. The return value will have the specified alignment and will be either the lowest or highest possible address depending on whether direction is forward or backward.

This method does not use constraints since it searches for addresses that do not exist in the map.

Definition at line 1550 of file AddressMap.h.

References Sawyer::Container::Interval< T >::greatest(), Sawyer::Container::Interval< T >::isEmpty(), Sawyer::Container::Interval< T >::least(), Sawyer::Container::Interval< T >::size(), Sawyer::Container::AddressMap< A, T >::unmapped(), and Sawyer::Container::Interval< T >::whole().

traverse() [1/4]

template<class A , class T = boost::uint8_t>

template<typename Functor >

void Sawyer::Container::AddressMap< A, T >::traverse ( Functor &  functor, const AddressMapConstraints< const AddressMap< A, T > > &  c, MatchFlags  flags = 0  ) const

inline

Invoke a function on each address interval.

The functor is invoked with the following arguments: the memory map and an interval. If the functor returns false then the traversal is terminated. To facilitate the use of function-local types for the functor without requiring the use of explicit template parameters, one may pass a subclass of Visitor as the functor.

This example shows one way to print the names of segments that overlap with a given interval:

typedef AddressMap<unsigned, char> Map;
struct: Visitor {
    bool operator()(const Map &map, const Interval<unsigned> &interval) {
        const Map::Segment &segment = map.at(interval.least()).findNode()->value();
        std::cerr <<"segment \"" <<segment.name() <<"\"\n";
        return true;
    }
} visitor;
Map map = ...;
Interval<unsigned> where = ...;
map.within(where).traverse(visitor);

Definition at line 1632 of file AddressMap.h.

traverse() [2/4]

template<class A , class T = boost::uint8_t>

template<typename Functor >

void Sawyer::Container::AddressMap< A, T >::traverse ( Functor &  functor, const AddressMapConstraints< AddressMap< A, T > > &  c, MatchFlags  flags = 0  )

inline

Invoke a function on each address interval.

The functor is invoked with the following arguments: the memory map and an interval. If the functor returns false then the traversal is terminated. To facilitate the use of function-local types for the functor without requiring the use of explicit template parameters, one may pass a subclass of Visitor as the functor.

This example shows one way to print the names of segments that overlap with a given interval:

typedef AddressMap<unsigned, char> Map;
struct: Visitor {
    bool operator()(const Map &map, const Interval<unsigned> &interval) {
        const Map::Segment &segment = map.at(interval.least()).findNode()->value();
        std::cerr <<"segment \"" <<segment.name() <<"\"\n";
        return true;
    }
} visitor;
Map map = ...;
Interval<unsigned> where = ...;
map.within(where).traverse(visitor);

Definition at line 1643 of file AddressMap.h.

traverse() [3/4]

template<class A , class T = boost::uint8_t>

void Sawyer::Container::AddressMap< A, T >::traverse ( Visitor &  visitor, const AddressMapConstraints< const AddressMap< A, T > > &  c, MatchFlags  flags = 0  ) const

inline

Invoke a function on each address interval.

The functor is invoked with the following arguments: the memory map and an interval. If the functor returns false then the traversal is terminated. To facilitate the use of function-local types for the functor without requiring the use of explicit template parameters, one may pass a subclass of Visitor as the functor.

This example shows one way to print the names of segments that overlap with a given interval:

typedef AddressMap<unsigned, char> Map;
struct: Visitor {
    bool operator()(const Map &map, const Interval<unsigned> &interval) {
        const Map::Segment &segment = map.at(interval.least()).findNode()->value();
        std::cerr <<"segment \"" <<segment.name() <<"\"\n";
        return true;
    }
} visitor;
Map map = ...;
Interval<unsigned> where = ...;
map.within(where).traverse(visitor);

Definition at line 1653 of file AddressMap.h.

traverse() [4/4]

template<class A , class T = boost::uint8_t>

void Sawyer::Container::AddressMap< A, T >::traverse ( Visitor &  visitor, const AddressMapConstraints< AddressMap< A, T > > &  c, MatchFlags  flags = 0  )

inline

Invoke a function on each address interval.

The functor is invoked with the following arguments: the memory map and an interval. If the functor returns false then the traversal is terminated. To facilitate the use of function-local types for the functor without requiring the use of explicit template parameters, one may pass a subclass of Visitor as the functor.

This example shows one way to print the names of segments that overlap with a given interval:

typedef AddressMap<unsigned, char> Map;
struct: Visitor {
    bool operator()(const Map &map, const Interval<unsigned> &interval) {
        const Map::Segment &segment = map.at(interval.least()).findNode()->value();
        std::cerr <<"segment \"" <<segment.name() <<"\"\n";
        return true;
    }
} visitor;
Map map = ...;
Interval<unsigned> where = ...;
map.within(where).traverse(visitor);

Definition at line 1656 of file AddressMap.h.

read() [1/2]

template<class A , class T = boost::uint8_t>

Sawyer::Container::Interval< Address > Sawyer::Container::AddressMap< A, T >::read ( Value *  buf, const AddressMapConstraints< const AddressMap< A, T > > &  c, MatchFlags  flags = 0  ) const

inline

Reads data into the supplied buffer.

Reads data into an array or STL vector according to the specified constraints. If the array is a null pointer then no data is read or copied and the return value indicates what addresses would have been accessed. When the buffer is an STL vector the constraints are augmented by also limiting the number of items accessed; the caller must do that explicitly for arrays. The return value is the interval of addresses that were read.

The constraints are usually curried before the actual read call, as in this example that reads up to 10 values starting at some address and returns the number of values read:

Value buf[10];
size_t nRead = map.at(start).limit(10).read(buf).size();

The following loop reads and prints all the readable values from a memory map using a large buffer for efficiency:

std::vector<Value> buf(1024);
while (Interval<Address> accessed = map.atOrAfter(a).read(buf)) {
    a = accessed.least();
    for (const Value &v: buf)
        std::cout <<a++ <<": " <<v <<"\n";
    if (accessed.greatest()==map.hull().greatest())
        break; // to handle case when a++ overflowed
}

Reading can also be performed backward, such as this example that reads up to ten values such that the last value read is at address 999. The buffer will always contain results in address order, with the first element of the buffer being the value that was read with the lowest address.

Value buf[10];
size_t nRead = map.at(999).limit(10).read(buf, MATCH_BACKWARD).size();

Definition at line 1700 of file AddressMap.h.

References Sawyer::Container::AddressMap< A, T >::checkConsistency(), Sawyer::Container::Interval< T >::isEmpty(), Sawyer::Container::Interval< T >::least(), and Sawyer::Container::Interval< T >::size().

Referenced by Sawyer::Container::AddressMap< A, T >::read().

read() [2/2]

template<class A , class T = boost::uint8_t>

Sawyer::Container::Interval< Address > Sawyer::Container::AddressMap< A, T >::read ( std::vector< Value > &  buf, const AddressMapConstraints< const AddressMap< A, T > > &  c, MatchFlags  flags = 0  ) const

inline

Reads data into the supplied buffer.

Reads data into an array or STL vector according to the specified constraints. If the array is a null pointer then no data is read or copied and the return value indicates what addresses would have been accessed. When the buffer is an STL vector the constraints are augmented by also limiting the number of items accessed; the caller must do that explicitly for arrays. The return value is the interval of addresses that were read.

The constraints are usually curried before the actual read call, as in this example that reads up to 10 values starting at some address and returns the number of values read:

Value buf[10];
size_t nRead = map.at(start).limit(10).read(buf).size();

The following loop reads and prints all the readable values from a memory map using a large buffer for efficiency:

std::vector<Value> buf(1024);
while (Interval<Address> accessed = map.atOrAfter(a).read(buf)) {
    a = accessed.least();
    for (const Value &v: buf)
        std::cout <<a++ <<": " <<v <<"\n";
    if (accessed.greatest()==map.hull().greatest())
        break; // to handle case when a++ overflowed
}

Reading can also be performed backward, such as this example that reads up to ten values such that the last value read is at address 999. The buffer will always contain results in address order, with the first element of the buffer being the value that was read with the lowest address.

Value buf[10];
size_t nRead = map.at(999).limit(10).read(buf, MATCH_BACKWARD).size();

Definition at line 1723 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::limit(), and Sawyer::Container::AddressMap< A, T >::read().

write() [1/2]

template<class A , class T = boost::uint8_t>

Sawyer::Container::Interval< Address > Sawyer::Container::AddressMap< A, T >::write ( const Value *  buf, const AddressMapConstraints< AddressMap< A, T > > &  c, MatchFlags  flags = 0  )

inline

Writes data from the supplied buffer.

Copies data from an array or STL vector into the underlying address map buffers corresponding to the specified constraints. If the array is a null pointer then no data is written and the return value indicates what addresses would have been accessed. The constraints are agumented by also requiring that the addresses be contiguous and lack the IMMUTABLE bit, and in the case of STL vectors that not more data is written thn what is in the vector. The return value is the interval of addresses that were written.

The Access::IMMUTABLE bit is usually used to indicate that a buffer cannot be modified (for instance, the buffer is memory allocated with read-only access by POSIX mmap).

The constraints are usually curried before the actual read call, as in this example that writes the vector's values into the map at the first writable address greater than or equal to 1000.

std::vector<Value> buffer = {...};
Interval<Address> written = map.atOrAfter(1000).require(WRITABLE).write(buffer);

Writing can also be performed backward, such as this example that writes up to ten values such that the last value written is at address 999. The buffer contains values in their address order.

Value buf[10] = { ... };
size_t nWritten = map.at(999).limit(10).write(buf, MATCH_BACKWARD).size();

Definition at line 1761 of file AddressMap.h.

References Sawyer::Container::Interval< T >::baseSize(), Sawyer::Container::AddressMap< A, T >::checkConsistency(), Sawyer::Container::Interval< T >::isEmpty(), Sawyer::Container::Interval< T >::least(), Sawyer::Container::IntervalMap< I, T, Policy >::lowerBound(), Sawyer::Container::AddressMap< A, T >::nodes(), Sawyer::Container::AddressMapConstraints< AddressMap >::prohibit(), and Sawyer::Container::Interval< T >::size().

Referenced by Sawyer::Container::AddressMap< A, T >::write().

write() [2/2]

template<class A , class T = boost::uint8_t>

Sawyer::Container::Interval< Address > Sawyer::Container::AddressMap< A, T >::write ( const std::vector< Value > &  buf, const AddressMapConstraints< AddressMap< A, T > > &  c, MatchFlags  flags = 0  )

inline

Writes data from the supplied buffer.

Copies data from an array or STL vector into the underlying address map buffers corresponding to the specified constraints. If the array is a null pointer then no data is written and the return value indicates what addresses would have been accessed. The constraints are agumented by also requiring that the addresses be contiguous and lack the IMMUTABLE bit, and in the case of STL vectors that not more data is written thn what is in the vector. The return value is the interval of addresses that were written.

The Access::IMMUTABLE bit is usually used to indicate that a buffer cannot be modified (for instance, the buffer is memory allocated with read-only access by POSIX mmap).

The constraints are usually curried before the actual read call, as in this example that writes the vector's values into the map at the first writable address greater than or equal to 1000.

std::vector<Value> buffer = {...};
Interval<Address> written = map.atOrAfter(1000).require(WRITABLE).write(buffer);

Writing can also be performed backward, such as this example that writes up to ten values such that the last value written is at address 999. The buffer contains values in their address order.

Value buf[10] = { ... };
size_t nWritten = map.at(999).limit(10).write(buf, MATCH_BACKWARD).size();

Definition at line 1804 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::limit(), and Sawyer::Container::AddressMap< A, T >::write().

prune()

template<class A , class T = boost::uint8_t>

void Sawyer::Container::AddressMap< A, T >::prune ( const AddressMapConstraints< AddressMap< A, T > > &  c, MatchFlags  flags = 0  )

inline

Prune away addresses that match constraints.

Removes all addresses for which the constraints match. The addresses need not be contiguous in memory (in fact, noncontiguous is the default), and the matching segments need not be consecutive segments. In other words, the interval over which this function operates can include segments that do not satisfy the constraints (and are not pruned). For instance, to remove all segments that are writable regardless of whether other segments are interspersed:

map.require(WRITABLE).contiguous(false).prune();

See also

keep

Definition at line 1821 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::addressConstraints(), Sawyer::Container::IntervalMap< I, T, Policy >::erase(), Sawyer::Container::IntervalSet< I >::insert(), and Sawyer::Container::IntervalSet< I >::intervals().

keep()

template<class A , class T = boost::uint8_t>

void Sawyer::Container::AddressMap< A, T >::keep ( const AddressMapConstraints< AddressMap< A, T > > &  c, MatchFlags  flags = 0  )

inline

Keep only addresses that match constraints.

Keeps only those addresses that satisfy the given constraints, discarding all others. The addresses need not be contiguous (in fact, noncontiguous is the default), and the matching segments need not be consecutive segments. In other words, the interval over which this function operates can include segments that do not satisfy the constraints (and are pruned). For instance, to remove all segments that are not writable regardless of whether other segments are interspersed:

map.require(WRITABLE).contiguous(false).keep();

See also

prune

Definition at line 1848 of file AddressMap.h.

References Sawyer::Container::AddressMapConstraints< AddressMap >::addressConstraints(), Sawyer::Container::IntervalMap< I, T, Policy >::erase(), Sawyer::Container::IntervalSet< I >::insert(), Sawyer::Container::IntervalSet< I >::intervals(), and Sawyer::Container::IntervalSet< I >::invert().

changeAccess()

template<class A , class T = boost::uint8_t>

void Sawyer::Container::AddressMap< A, T >::changeAccess ( unsigned  requiredAccess, unsigned  prohibitedAccess, const AddressMapConstraints< AddressMap< A, T > > &  c, MatchFlags  flags = 0  )

inline

Change access bits for addresses that match constraints.

For all addresses that satisfy the specified constraints, add the requiredAccess and remove the prohibitedAccess bits. The addresses need not be contiguous (in fact, noncontiguous is the default), and the matching segments need not be consecutive segments. In other words, the interval over which this function operates can include addresses that do not satisfy the constraints and whose access bits are not modified. For instance, to add execute permission and remove write permission for all segments containing the string ".text":

map.substr(".text").changeAccess(EXECUTABLE, WRITABLE);

To set access bits to a specific value, supply the complement as the second argument. The following code changes all addresses between a specified range so that only the READABLE and WRITABLE bits are set and no others:

unsigned newAccess = READABLE | WRITABLE;
map.within(100,200).changeAccess(newAccess, ~newAccess);

Definition at line 1882 of file AddressMap.h.

References Sawyer::Container::AddressSegment< A, T >::accessibility(), Sawyer::Container::AddressMapConstraints< AddressMap >::addressConstraints(), Sawyer::Container::IntervalMap< I, T, Policy >::insert(), Sawyer::Container::Interval< T >::least(), and Sawyer::Container::AddressSegment< A, T >::offset().

---

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

• AddressMap.h