ROSE  0.10.7.0
Classes | Public Member Functions | Static Public Member Functions | List of all members
Rose::SourceLocation Class Reference

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:

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 55 of file SourceLocation.h.

#include <SourceLocation.h>

Public Member Functions

 SourceLocation ()
 Default constructor. More...
 
 SourceLocation (const boost::filesystem::path &fileName, size_t line, const Sawyer::Optional< size_t > &column=Sawyer::Nothing())
 Construct a new source location. More...
 
 ~SourceLocation ()
 Destructor. More...
 
bool isEmpty () const
 Test whether object is empty. More...
 
const boost::filesystem::path & fileName () const
 File name associated with this location. More...
 
size_t line () const
 Line number. More...
 
const Sawyer::Optional< size_t > & column () const
 Column number. More...
 
std::string toString () const
 Convert location to string. More...
 
std::string printableName () const
 Convert location to escaped string. More...
 
void print (std::ostream &) const
 Output location to a stream. More...
 
 operator unspecified_bool () const
 Type for Boolean context. More...
 
bool operator== (const SourceLocation &other) const
 Equality and inequality. More...
 
bool operator!= (const SourceLocation &other) const
 Equality and inequality. More...
 
int compare (const SourceLocation &other) const
 Ordered comparison. More...
 
bool operator< (const SourceLocation &other) const
 Ordered comparison. More...
 
bool operator<= (const SourceLocation &other) const
 Ordered comparison. More...
 
bool operator> (const SourceLocation &other) const
 Ordered comparison. More...
 
bool operator>= (const SourceLocation &other) const
 Ordered comparison. More...
 

Static Public Member Functions

static SourceLocation parse (const std::string &)
 Construct a new source location by parsing a string. More...
 

Constructor & Destructor Documentation

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 87 of file SourceLocation.h.

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.

Rose::SourceLocation::~SourceLocation ( )

Destructor.

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

Member Function Documentation

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.

bool Rose::SourceLocation::isEmpty ( ) const

Test whether object is empty.

This object is empty if and only if it was default constructed. A non-default constructed object having an empty file name is not considered to be an empty object. This is useful for distinguishing default constructed objects from those that indicate a present but unknown location.

Referenced by operator unspecified_bool().

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

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.

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

Line number.

Definition at line 125 of file SourceLocation.h.

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

Column number.

Definition at line 130 of file SourceLocation.h.

bool Rose::SourceLocation::operator== ( const SourceLocation other) const

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.

bool Rose::SourceLocation::operator!= ( const SourceLocation other) const
inline

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.

Definition at line 141 of file SourceLocation.h.

int Rose::SourceLocation::compare ( const SourceLocation other) const

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.

Referenced by operator<(), operator<=(), operator>(), and operator>=().

bool Rose::SourceLocation::operator< ( const SourceLocation other) const
inline

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.

Definition at line 155 of file SourceLocation.h.

References compare().

bool Rose::SourceLocation::operator<= ( const SourceLocation other) const
inline

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.

Definition at line 158 of file SourceLocation.h.

References compare().

bool Rose::SourceLocation::operator> ( const SourceLocation other) const
inline

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.

Definition at line 161 of file SourceLocation.h.

References compare().

bool Rose::SourceLocation::operator>= ( const SourceLocation other) const
inline

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.

Definition at line 164 of file SourceLocation.h.

References compare().

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

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.

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

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.

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

Output location to a stream.

The format is the same as the toString method.

Rose::SourceLocation::operator unspecified_bool ( ) const
inline

Type for Boolean context.

Implicit conversion to a type that can be used in a boolean context such as an if or while statement. The value in Boolean context is the inverse of what isEmpty would return.

Definition at line 199 of file SourceLocation.h.

References isEmpty().


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