Description

Information about a source location.

A SourceLocation object is simply a file name, line number, and optional column number. However, since file names are shared by many objects certain optimizations can be made to reduce the total amount of storage occupied by all the objects collectively. Although the file name storage is optimized, the objects behave as if each object has its own file name data member.

This class attempts to correct a number of issues encountered with Sg_File_Info and to make the class more suitable for use in binary analysis. Some of the corrected problems are:

The API is completely thread-safe and query operations are lock free. The objects themselves are immutable since there are no mutating API functions.

Constructors are exception safe. A failure during construction no longer leaves the shared data structures in an inconsistent state.

File names are stored only once per unique name instead of twice per unique name.

Constructors are amortized constant time instead of O(log), and furthermore, there is only one lookup operation instead of two.

Querying the file name is O(1) instead of O(log).

File names are stored as boost::filesystem::path instead of std::string, therefore there is no need for constantly converting between the two types (good user code should not use std::string for file names).

Column numbers are officially optional. No more using some user-defined special value to indicate lack of a column number.

Line and column numbers are type size_t since they're conceptually unsigned sizes. This avoids having to cast in well-written user code.

This class exists in the Rose name space instead of the global name space.

The names used in this class are camelCase instead of a weird mixture of camelCase and underscores. All names follow the ROSE Binary Analysis naming convention. In particular, property accessors are nouns without a leading "get".

Line and column numbers are conventionally one-origin values, but nothing in this API or the implementation prevents you from storing line zero and/or column zero. You're free to use zero-origin number if you desire.

This class is intended to be extended through derivation to provide additional location features such as scope information, but those things are not included here because they're not always needed or even available.

Definition at line 70 of file SourceLocation.h.

#include <Rose/SourceLocation.h>

Inheritance diagram for Rose::SourceLocation:

[legend]

Collaboration diagram for Rose::SourceLocation:

[legend]

Public Member Functions
	SourceLocation ()
	Default constructor.

	SourceLocation (const boost::filesystem::path &fileName, size_t line, const Sawyer::Optional< size_t > &column=Sawyer::Nothing())
	Construct a new source location.

virtual	~SourceLocation ()
	Destructor.

virtual std::string	toString () const override
	Convert location to string.

virtual void	print (std::ostream &) const override
	Output location to a stream.

virtual std::string	printableName () const override
	Convert location to escaped string.

virtual bool	isEqual (const Location &) const override
	Equality and inequality.

virtual bool	isValid () const override
	Test whether this object is valid.

virtual uint64_t	hash () const override
	Compute a 64-bit hash of this object.

virtual const boost::filesystem::path &	fileName () const
	File name associated with this location.

virtual size_t	line () const
	Line number.

virtual const Sawyer::Optional< size_t > &	column () const
	Column number.


virtual bool	operator< (const Location &) const override
	Ordered comparison.

virtual bool	operator<= (const Location &) const override
	Ordered comparison.

virtual bool	operator> (const Location &) const override
	Ordered comparison.

virtual bool	operator>= (const Location &) const override
	Ordered comparison.

Public Member Functions inherited from Rose::Location
virtual bool	operator== (const Location &other) const final
	Equality and inequality.

virtual bool	operator!= (const Location &other) const final
	Equality and inequality.

virtual	operator bool () const final
	Test whether this object is valid.

virtual bool	operator! () const final
	Test whether this object is empty.

virtual bool	isEmpty () const final
	Test whether this object is empty.

Static Public Member Functions
static SourceLocation	parse (const std::string &)
	Construct a new source location by parsing a string.

Constructor & Destructor Documentation

◆ SourceLocation() [1/2]

Rose::SourceLocation::SourceLocation ( )

inline

Default constructor.

The default constructor creates a location with an empty name, line zero, and no column. It's intended mainly for use in containers that require a default constructor.

Definition at line 113 of file SourceLocation.h.

◆ SourceLocation() [2/2]

Rose::SourceLocation::SourceLocation	(	const boost::filesystem::path &	fileName,
		size_t	line,
		const Sawyer::Optional< size_t > &	column = `Sawyer::Nothing()`
	)

Construct a new source location.

The behavior of this constructor is as if the file name, line, and column were all copied into data members of the new object. However, the implementation is optimized to store only one copy of each unique file name across all objects.

◆ ~SourceLocation()

virtual Rose::SourceLocation::~SourceLocation ( )

virtual

Destructor.

A special destructor is used in order to free file names that are no longer referenced by any SourceLocation object.

Member Function Documentation

◆ parse()

static SourceLocation Rose::SourceLocation::parse ( const std::string & )

static

Construct a new source location by parsing a string.

If the string ends with ":N:M" then N and M are the line and column numbers. Otherwise, if the string ends with ":N" then it has only a line number and no column number. Otherwise the line number is zero and there is no column number. Everything before the line and column is the file name. If the file name is surrounded by double quotes then the entire name is parsed as if it were a C string literal.

◆ toString()

virtual std::string Rose::SourceLocation::toString ( ) const

overridevirtual

Convert location to string.

Converts this location to a file name, line number, and optional column number. Special characters in the file name are not escaped nor is the file name enclosed in quotes. The file name is separated from the line number by a colon (no white space), and if the location has a column, the column number is separated from the line number by a colon (also no white space). An empty (default constructed) object returns an empty string.

Implements Rose::Location.

◆ print()

virtual void Rose::SourceLocation::print ( std::ostream & ) const

overridevirtual

Output location to a stream.

The format is the same as the toString method.

Implements Rose::Location.

◆ printableName()

virtual std::string Rose::SourceLocation::printableName ( ) const

overridevirtual

Convert location to escaped string.

Prints the location in a safe manner by printing the file name as a C-style string literal (with double quotes) and with all non-graphic characters except ASCII SPC escaped using only graphic characters (the usual C syntax). An empty (default constructed) object returns an empty string.

Implements Rose::Location.

◆ isEqual()

virtual bool Rose::SourceLocation::isEqual ( const Location & ) const

overridevirtual

Equality and inequality.

Two objects are equal if they have the same file name (exact match), same line number, and either the same column number or both have no column.

Implements Rose::Location.

◆ operator<()

virtual bool Rose::SourceLocation::operator< ( const Location & ) const

overridevirtual

Ordered comparison.

Compares by file name, line number, and column number, in that order. Although the sort is stable, file names are not compared lexicographically. That is, the sort will not be alphabetical – if you want an alphabetical sort then you'll need to provide a different comparator. A location with a non-existing column number is considered less than a location with column number zero.

Implements Rose::Location.

◆ operator<=()

virtual bool Rose::SourceLocation::operator<= ( const Location & ) const

overridevirtual

Ordered comparison.

Compares by file name, line number, and column number, in that order. Although the sort is stable, file names are not compared lexicographically. That is, the sort will not be alphabetical – if you want an alphabetical sort then you'll need to provide a different comparator. A location with a non-existing column number is considered less than a location with column number zero.

Implements Rose::Location.

◆ operator>()

virtual bool Rose::SourceLocation::operator> ( const Location & ) const

overridevirtual

Ordered comparison.

Compares by file name, line number, and column number, in that order. Although the sort is stable, file names are not compared lexicographically. That is, the sort will not be alphabetical – if you want an alphabetical sort then you'll need to provide a different comparator. A location with a non-existing column number is considered less than a location with column number zero.

Implements Rose::Location.

◆ operator>=()

virtual bool Rose::SourceLocation::operator>= ( const Location & ) const

overridevirtual

Ordered comparison.

Compares by file name, line number, and column number, in that order. Although the sort is stable, file names are not compared lexicographically. That is, the sort will not be alphabetical – if you want an alphabetical sort then you'll need to provide a different comparator. A location with a non-existing column number is considered less than a location with column number zero.

Implements Rose::Location.

◆ isValid()

virtual bool Rose::SourceLocation::isValid ( ) const

overridevirtual

Test whether this object is valid.

Implements Rose::Location.

◆ hash()

virtual uint64_t Rose::SourceLocation::hash ( ) const

overridevirtual

Compute a 64-bit hash of this object.

Implements Rose::Location.

◆ fileName()

virtual const boost::filesystem::path & Rose::SourceLocation::fileName ( ) const

virtual

File name associated with this location.

The behavior is as if the file name were stored as a data member of this object; that is, the reference is valid as long as this object is valid. The actual implementation optimizes name storage and therefore the reference is likely (but not guaranteed) to be valid longer than the life time of this object.

Thread safety: The referenced name is guaranteed to not change for its entire lifetime.

◆ line()

virtual size_t Rose::SourceLocation::line ( ) const

inlinevirtual

Line number.

Definition at line 188 of file SourceLocation.h.

◆ column()

virtual const Sawyer::Optional< size_t > & Rose::SourceLocation::column ( ) const

inlinevirtual

Column number.

Definition at line 193 of file SourceLocation.h.

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

SourceLocation.h

Description

Public Member Functions

Static Public Member Functions

Constructor & Destructor Documentation

◆ SourceLocation() [1/2]

◆ SourceLocation() [2/2]

◆ ~SourceLocation()

Member Function Documentation

◆ parse()

◆ toString()

◆ print()

◆ printableName()

◆ isEqual()

◆ operator<()

◆ operator<=()

◆ operator>()

◆ operator>=()

◆ isValid()

◆ hash()

◆ fileName()

◆ line()

◆ column()