cs::xr_query Class Reference

Fully specifies a cross-referencing query over the tokens in an analyzed project. More...

Public Member Functions
	xr_query ()
	Constructor. More...
void	add_kind_filter (xr_kind s)
	Add a kind filter to a xr_query object. More...
void	add_kind_role_filter (xr_kind_role s)
	Add a kind-role filter to a xr_query object. More...
void	add_role_filter (xr_role s)
	Add a role filter to a xr_query object. More...
void	add_term_filter (const std::string &s)
	Add a term filter to a xr_query object. More...
void	add_term_filter (const csuint64 s)
	Add a term filter to a xr_query object. More...
std::string	as_repr () const
	Get a representation of a xr_query object that includes information useful for debugging. More...
std::string	as_string () const
	Get a simple string representation of a xr_query object. More...
void	set_cmp (xr_tuple_comparator *_cmp)
	Set the comparator that will be used to order the query results. More...
void	set_definition_filter (const xr_file_query &s)
	Set restrictions on the location of the token occurrence. More...
void	set_flags (xr_query_flags s)
	Set additional properties for a query. More...
void	set_limit (size_t s)
	Set the maximum number of query results. More...
void	set_occurrence_filter (const xr_file_query &s)
	Set restrictions on the location of the token occurrence. More...
void	set_offset (size_t s)
	Set the position in the overall result set such that the query will return results starting from this position. More...

Related Functions
(Note that these are not member functions.)
std::ostream &	operator<< (std::ostream &out, const xr_query &a)
	Print a representation of an xr_query object to the specified stream. More...

Detailed Description

Fully specifies a cross-referencing query over the tokens in an analyzed project.

The key properties of an xr_query are summarized in the following table.

Property	Description	Set With
Limit	The maximum number of query results to obtain.	set_limit()
Offset	The offset in the overall result set from which to start returning results.	set_offset()
Filters	Zero or more filters that together define the query conditions.	add_term_filter(), add_kind_filter(), add_role_filter(), add_kind_role_filter(), set_definition_filter(), set_occurrence_filter().
Flags	xr_query_flags specifying additional properties for the query.	set_flags()
Comparator	A xr_tuple_comparator that will be used to order the query result tuples.	set_cmp()

An occurrence of a token T will be included in the returned query result set if all of the following are true.

• Result set position. The tuple representing the occurrence has a suitable position in the full result set: in the range Offset..(Offset+Limit-1), where Limit is specified with set_limit() and Offset is specified with set_offset().
  • If a comparator has been specified with set_cmp(), positions are determined after the full set of query results is sorted.
  • If Limit is set to 0, the query returns all tuples at position Offset or higher.
• Name. T's name hash matches an integer value specified with add_term_filter(), OR T's name matches a std::string value specified with add_term_filter(), OR no term filters were specified.
• Kind. The occurrence kind (xr_kind) matches one of those specified with add_kind_filter() OR no kind filters were specified. If T is a procedure (procedure), its basename as retrieved by procedure::basename() is used.
• Role. The occurrence role (xr_role) matches one of those specified with add_role_filter() OR no role filters were specified.
• Kind-Role. The occurrence kind-role (xr_kind_role) matches one of those specified with add_kind_role_filter() OR no kind-role filters were specified.
• Occurrence location. The occurrence satisfies the restrictions of the occurrence filter (xr_file_query) specified with set_occurrence_filter() OR no occurrence filter was specified.
• Definition location. The definition corresponding to the occurrence satisfies the restrictions of the definition filter (xr_file_query) specified with set_definition_filter() OR no definition filter was specified.
• Flags. The occurrence satisfies the flags (xr_query_flags) specified with set_flags() OR no flags were specified.

To execute the query, use project::token_search().

Constructor & Destructor Documentation

xr_query()

cs::xr_query::xr_query ( )

inline

Constructor.

Constructs an xr_query object with:

• Limit==0
• Offset==0
• no filters
• no flags
• no comparator

Member Function Documentation

add_kind_filter()

void cs::xr_query::add_kind_filter ( xr_kind  s )

inline

Add a kind filter to a xr_query object.

Parameters

[in]

s

The filter.

Returns

void

If any kinds are specified with this method, the query will only match token occurrences whose xr_kind matches one of those kinds.

add_kind_role_filter()

void cs::xr_query::add_kind_role_filter ( xr_kind_role  s )

inline

Add a kind-role filter to a xr_query object.

Parameters

[in]

s

The filter.

Returns

void

If any kind-roles are specified with this method, the query will only match token occurrences whose xr_kind and xr_role match one of those kind-role pairs.

add_role_filter()

void cs::xr_query::add_role_filter ( xr_role  s )

inline

Add a role filter to a xr_query object.

Parameters

[in]

s

The filter.

Returns

void

If any roles are specified with this method, the query will only match token occurrences whose xr_role matches one of those roles.

add_term_filter() [1/2]

void cs::xr_query::add_term_filter ( const std::string &  s )

inline

Add a term filter to a xr_query object.

Parameters

[in]

s

The token to filter.

Returns

void

If any strings are specified with this method, the query will only match token occurrences where the token name matches one of those strings.

If any values are specified with add_term_filter(), the query will only match token occurrences for which

• the token name hash matches an integer value specified with add_term_filter(), or
• the token name matches a string value specified with add_term_filter().

A procedure name token is the procedure basename as returned by procedure::basename().

See also

add_term_filter(const csuint64)

add_term_filter() [2/2]

void cs::xr_query::add_term_filter ( const csuint64  s )

inline

Add a term filter to a xr_query object.

Parameters

[in]

s

The hash of the token to filter, as computed by xr_namehash() or returned by another function.

Returns

void

If any values are specified with add_term_filter(), the query will only match token occurrences for which

• the token name hash matches an integer value specified with add_term_filter(), or
• the token name matches a string value specified with add_term_filter().

A procedure name token is the procedure basename as returned by procedure::basename().

See also

add_term_filter(const std::string &)

as_repr()

std::string cs::xr_query::as_repr ( ) const

inline

Get a representation of a xr_query object that includes information useful for debugging.

Returns

The string representation.

as_string()

std::string cs::xr_query::as_string ( ) const

inline

Get a simple string representation of a xr_query object.

Returns

The string representation.

set_cmp()

void cs::xr_query::set_cmp ( xr_tuple_comparator *  _cmp )

inline

Set the comparator that will be used to order the query results.

Parameters

[in]

_cmp

An object of a concrete xr_tuple_comparator subclass. Specify NULL if you do not want to impose an ordering on query results.

Returns

void

When a query comparator is specified, all query results will be retrieved and ordered as specified by _cmp->operator() BEFORE imposing the query Offset and Limit. Specifying a comparator will therefore generally increase query processing time.

If you set a comparison function, query result uniquification will always take place.

• If xr_query_flags::UNIQUIFY is specified, uniquification is performed with respect to your comparison function (if the raw result set contains a subset of tuples that are all equal according to your comparison function, all but one of those tuples will be removed).
• If xr_query_flags::UNIQUIFY is not specified, uniquification is performed with respect to complete tuple uniqueness (if the raw result set contains a subset of tuples that are all idenfical across all tuple values, all but one of those tuples will be removed).

set_definition_filter()

void cs::xr_query::set_definition_filter ( const xr_file_query &  s )

inline

Set restrictions on the location of the token occurrence.

Parameters

[in]

s

The filter.

Returns

void

The query will only return tuples (xr_tuple) for which the source files and lines of the token definitions (xr_tuple::get_def_file() and xr_tuple::get_def_line(), respectively) satisfy the restrictions imposed by s.

set_flags()

void cs::xr_query::set_flags ( xr_query_flags  s )

inline

Set additional properties for a query.

Parameters

[in]

s

Flags specifying additional query properties.

Returns

void

set_limit()

void cs::xr_query::set_limit ( size_t  s )

inline

Set the maximum number of query results.

Parameters

[in]

s

The maximum number of query results.

Returns

void

The query will return at most this many tuples (xr_tuple). Set to 0 to return all results at the specified Offset position or higher.

The offset of the first result returned is specified with set_offset().

set_occurrence_filter()

void cs::xr_query::set_occurrence_filter ( const xr_file_query &  s )

inline

Set restrictions on the location of the token occurrence.

Parameters

[in]

s

The filter.

Returns

void

The query will only return tuples (xr_tuple) for which the source files and lines of the token occurrences (xr_tuple::get_file() and xr_tuple::get_line(), respectively) satisfy the restrictions imposed by s.

set_offset()

void cs::xr_query::set_offset ( size_t  s )

inline

Set the position in the overall result set such that the query will return results starting from this position.

Parameters

[in]

s

The offset in the overall result set from which to start returning result tuples (xr_tuple).

The total number of tuples returned is limited by the value specified with set_limit().

Friends And Related Function Documentation

operator<<()

std::ostream & operator<< ( std::ostream &  out, const xr_query &  a  )

related

Print a representation of an xr_query object to the specified stream.

Parameters

[in]	out	The stream to print to.
[in]	a	The xr_query object to print.

Returns

void

---

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

• cs_xref.hpp