xtd::diagnostics::stack_frame Class Reference

Inheritance diagram for xtd::diagnostics::stack_frame:

Definition

Provides information about a xtd::diagnostics::stack_frame, which represents a function call on the call stack for the current thread.

class core_export_ stack_frame : public xtd::object

Inheritance

xtd::object → xtd::diagnostics::stack_frame

Header

#include <xtd/diagnostics/stack_frame>

Namespace

xtd::diagnostics

Library

xtd.core

Remarks

A xtd::diagnostics::stack_frame is created and pushed on the call stack for every function call made during the execution of a thread. The stack frame always includes method information, and optionally includes file name, line number, and column number information.

xtd::diagnostics::stack_frame information will be most informative with Debug build configurations. By default, Debug builds include debug symbols, while Release builds do not. The debug symbols contain most of the file, method name, line number, and column information used in constructing xtd::diagnostics::stack_frame objects.

Examples

The following example demonstrates the use of the xtd::diagnostics::stack_frame class to provide the stack frame information for a stack trace.

#include <xtd/diagnostics/stack_frame>
#include <xtd/diagnostics/stack_trace>
#include <xtd/console>
 
using namespace xtd;
using namespace xtd::diagnostics;
 
void method2(int count) {
  try {
    if (count < 5)
      throw argument_exception("count too large", "count");
  } catch (const system_exception&) {
    auto st = stack_trace {};
    auto st1 = stack_trace {stack_frame {2, true}};
    console::write_line(" Stack trace for Method2: {0}", st1.to_string());
    console::write_line(st.to_string());
    throw;
  }
}
 
void method1() {
  try {
    method2(4);
  } catch (const system_exception&) {
    auto st = stack_trace {};
    auto st1 = stack_trace {stack_frame {true}};
    console::write_line(" Stack trace for Method1: {0}", st1.to_string());
    console::write_line(st.to_string());
    // Build a stack trace for the next frame.
    auto st2 = stack_trace {stack_frame {1, true}};
    console::write_line(" Stack trace for next level frame: {0}", st2.to_string());
    throw;
  }
}
 
auto main() -> int {
  try {
    method1();
  } catch (const system_exception&) {
    auto st = stack_trace {};
    auto st1 = stack_trace {stack_frame {true}};
    console::write_line(" Stack trace for Main: {0}", st1.to_string());
    console::write_line(st.to_string());
  }
  console::write_line("Press Enter to exit.");
  console::read_key();
}
 
// This code produces the following output :
//
//  Stack trace for Method2:    at main [0x000030B0] in /!---OMITTED---!/stack_frame:line 0
//    at method2(int)
//    at method1()
//    at main
//  Stack trace for Method1:    at method1() [0x00002D20] in /!---OMITTED---!/stack_frame:line 0
//    at method1()
//    at main
//  Stack trace for next level frame:    at main [0x000030B0] in /!---OMITTED---!/stack_frame:line 0
//  Stack trace for Main:    at main [0x000030B0] in /!---OMITTED---!/stack_frame:line 0
//    at main
// Press Enter to exit.

Examples

line_info.cpp, math_assert.cpp, math_assume.cpp, math_valid.cpp, stack_frame.cpp, and user_defined_exception.cpp.

Public Fields
static constexpr xtd::size	OFFSET_UNKNOWN
	Defines the value that is returned from the get_offset() method when the offset is unknown. This field is constant.
static stack_frame	empty () noexcept
	Return an empty stack frame.

Public Constructors
	stack_frame ()
	Initializes a new instance of the xtd::diagnostics::stack_frame class.
	stack_frame (xtd::size skip_frame)
	Initializes a new instance of the xtd::diagnostics::stack_frame class that corresponds to a frame above the current stack frame.
	stack_frame (bool need_file_info)
	Initializes a new instance of the xtd::diagnostics::stack_frame class, optionally capturing source information.
	stack_frame (xtd::size skip_frame, bool need_file_info)
	Initializes a new instance of the xtd::diagnostics::stack_frame class that corresponds to a frame above the current stack frame, optionally capturing source information.
	stack_frame (const xtd::string &file_name, xtd::size line_number)
	Initializes a new instance of the xtd::diagnostics::stack_frame class that contains only the given file name, and line number.
	stack_frame (const xtd::string &file_name, xtd::size line_number, const xtd::string &method_name)
	Initializes a new instance of the xtd::diagnostics::stack_frame class that contains only the given file name, line number, and method name.
	stack_frame (const xtd::string &file_name, xtd::size line_number, const xtd::string &method_name, xtd::size column_number)
	Initializes a new instance of the xtd::diagnostics::stack_frame class that contains only the given file name, line number, and column number.
	stack_frame (const xtd::string &file_name, xtd::size line_number, xtd::size column_number)
	Initializes a new instance of the xtd::diagnostics::stack_frame class that contains only the given file name, line number, and column number.
	stack_frame (const xtd::string &file_name, xtd::size line_number, const xtd::string &method_name, xtd::size column_number, xtd::size offset)
	Initializes a new instance of the xtd::diagnostics::stack_frame class that contains only the given file name, line number, method name, column number, and offset.
	stack_frame (const xtd::source_location &source_location)
	Initializes a new instance of the xtd::diagnostics::stack_frame class that contains only the given source location.
	stack_frame (const xtd::source_location &source_location, xtd::size offset)
	Initializes a new instance of the xtd::diagnostics::stack_frame class that contains only the given given source location, and offset.
	stack_frame (xtd::null_ptr frame)
	Initializes a new empty instance of the xtd::diagnostics::stack_frame.

Public Methods
bool	equals (const stack_frame &sf) const noexcept override
	Indicates whether the current xtd::diagnostic::stack_frame is equal to another xtd::diagnostic::stack_frame.
virtual xtd::size	get_file_column_number () const noexcept
	Gets the column number in the file that contains the code that is executing. This information is typically extracted from the debugging symbols for the executable.
virtual xtd::size	get_file_line_number () const noexcept
	Gets the line number in the file that contains the code that is executing. This information is typically extracted from the debugging symbols for the executable.
virtual const xtd::string &	get_file_name () const noexcept
	Gets the file name that contains the code that is executing. This information is typically extracted from the debugging symbols for the executable.
virtual const xtd::string &	get_method () const noexcept
	Gets the method in which the frame is executing.
virtual xtd::size	get_offset () const noexcept
	Gets the offset from the start of the code for the method that is being executed.
xtd::string	to_string () const noexcept override
	Builds a readable representation of the stack trace.
virtual bool	equals (const object &obj) const noexcept
	Determines whether the specified object is equal to the current object.
template<typename object_a_t , typename object_b_t >
static bool	equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
	Determines whether the specified object instances are considered equal.

Public Static Methods
static stack_frame	current (const xtd::source_location &value=xtd::source_location::current()) noexcept
	Crates a new xtd::diagnostics::stack_frame object corresponding to the location of the call site.

Additional Inherited Members
Public Member Functions inherited from xtd::object
	object ()=default
	Create a new instance of the ultimate base class object.
virtual size_t	get_hash_code () const noexcept
	Serves as a hash function for a particular type.
virtual type_object	get_type () const noexcept
	Gets the type of the current instance.
template<typename object_t >
xtd::uptr< object_t >	memberwise_clone () const
	Creates a shallow copy of the current object.
Public Member Functions inherited from xtd::iequatable< stack_frame >
virtual bool	equals (const stack_frame &) const noexcept=0
	Indicates whether the current object is equal to another object of the same type.
Static Public Member Functions inherited from xtd::object
template<typename object_a_t , typename object_b_t >
static bool	equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
	Determines whether the specified object instances are considered equal.
template<typename object_a_t , typename object_b_t >
static bool	reference_equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
	Determines whether the specified object instances are the same instance.

Constructor & Destructor Documentation

stack_frame() [1/12]

xtd::diagnostics::stack_frame::stack_frame

(

)

Initializes a new instance of the xtd::diagnostics::stack_frame class.

stack_frame() [2/12]

xtd::diagnostics::stack_frame::stack_frame ( xtd::size  skip_frame )

explicit

Initializes a new instance of the xtd::diagnostics::stack_frame class that corresponds to a frame above the current stack frame.

Parameters

skip_frame

The number of frames up the stack to skip.

stack_frame() [3/12]

xtd::diagnostics::stack_frame::stack_frame ( bool  need_file_info )

explicit

Initializes a new instance of the xtd::diagnostics::stack_frame class, optionally capturing source information.

Parameters

need_file_info

true to capture the file name, line number, and column number of the stack frame; otherwise, false.

stack_frame() [4/12]

xtd::diagnostics::stack_frame::stack_frame	(	xtd::size	skip_frame,
		bool	need_file_info
	)

Initializes a new instance of the xtd::diagnostics::stack_frame class that corresponds to a frame above the current stack frame, optionally capturing source information.

Parameters

skip_frame	The number of frames up the stack to skip.
need_file_info	true to capture the file name, line number, and column number of the stack frame; otherwise, false.

stack_frame() [5/12]

xtd::diagnostics::stack_frame::stack_frame	(	const xtd::string &	file_name,
		xtd::size	line_number
	)

Initializes a new instance of the xtd::diagnostics::stack_frame class that contains only the given file name, and line number.

Parameters

file_name	The file name.
line_number	The line number in the specified file.

stack_frame() [6/12]

xtd::diagnostics::stack_frame::stack_frame	(	const xtd::string &	file_name,
		xtd::size	line_number,
		const xtd::string &	method_name
	)

Initializes a new instance of the xtd::diagnostics::stack_frame class that contains only the given file name, line number, and method name.

Parameters

file_name	The file name.
line_number	The line number in the specified file.
method_name	The method name.

stack_frame() [7/12]

xtd::diagnostics::stack_frame::stack_frame	(	const xtd::string &	file_name,
		xtd::size	line_number,
		const xtd::string &	method_name,
		xtd::size	column_number
	)

Initializes a new instance of the xtd::diagnostics::stack_frame class that contains only the given file name, line number, and column number.

Parameters

file_name	The file name.
line_number	The line number in the specified file.
method_name	The method name.
offset	The offset from the code for the method that is being executed.

stack_frame() [8/12]

xtd::diagnostics::stack_frame::stack_frame	(	const xtd::string &	file_name,
		xtd::size	line_number,
		xtd::size	column_number
	)

Initializes a new instance of the xtd::diagnostics::stack_frame class that contains only the given file name, line number, and column number.

Parameters

file_name	The file name.
line_number	The line number in the specified file.
method_name	The method name.
column_number	The column number in the specified file.

stack_frame() [9/12]

xtd::diagnostics::stack_frame::stack_frame	(	const xtd::string &	file_name,
		xtd::size	line_number,
		const xtd::string &	method_name,
		xtd::size	column_number,
		xtd::size	offset
	)

Initializes a new instance of the xtd::diagnostics::stack_frame class that contains only the given file name, line number, method name, column number, and offset.

Parameters

file_name	The file name.
line_number	The line number in the specified file.
method_name	The method name.
column_number	The column number in the specified file.
offset	The offset from the code for the method that is being executed.

stack_frame() [10/12]

xtd::diagnostics::stack_frame::stack_frame

(

const xtd::source_location &

source_location

)

Initializes a new instance of the xtd::diagnostics::stack_frame class that contains only the given source location.

Parameters

source_location

The source location caontaing the file name, the line number, the method name, and the column number.

stack_frame() [11/12]

xtd::diagnostics::stack_frame::stack_frame	(	const xtd::source_location &	source_location,
		xtd::size	offset
	)

Initializes a new instance of the xtd::diagnostics::stack_frame class that contains only the given given source location, and offset.

Parameters

source_location	The source location caontaing the file name, the line number, the method name, and the column number.
offset	The offset from the code for the method that is being executed.

stack_frame() [12/12]

xtd::diagnostics::stack_frame::stack_frame

(

xtd::null_ptr

frame

)

Initializes a new empty instance of the xtd::diagnostics::stack_frame.

Parameters

frame

nullptr.

Member Function Documentation

empty()

static stack_frame xtd::diagnostics::stack_frame::empty ( )

staticnoexcept

Return an empty stack frame.

Returns

Empty stack frame.

equals() [1/3]

bool xtd::diagnostics::stack_frame::equals ( const stack_frame &  sf ) const

overridenoexcept

Indicates whether the current xtd::diagnostic::stack_frame is equal to another xtd::diagnostic::stack_frame.

Parameters

sf	An object to compare with this object.

Returns

true if the current object is equal to the other parameter; otherwise, false.

get_file_column_number()

virtual xtd::size xtd::diagnostics::stack_frame::get_file_column_number ( ) const

virtualnoexcept

Gets the column number in the file that contains the code that is executing. This information is typically extracted from the debugging symbols for the executable.

Returns

The file column number, or 0 (zero) if the file column number cannot be determined.

Examples

The following example demonstrates the use of the get_file_column_number() method. This code example is part of a larger example provided for the xtd::diagnostics::stack_frame class.

// Display the stack frame properties.
stack_frame sf = st.get_frame(i);
console::write_line(" File: {}", sf.get_file_name());
console::write_line(" Line Number: {}", sf.get_file_line_number());
// Note that the column number defaults to zero when not initialized.
console::write_line(" Column Number: {}", sf.get_file_column_number());
console::write_line(" Method: {}", sf.get_method());
if (sf.get_offset() != stack_frame::OFFSET_UNKNOWN)
  console::write_line(" Offset: {}", sf.get_offset());

get_file_line_number()

virtual xtd::size xtd::diagnostics::stack_frame::get_file_line_number ( ) const

virtualnoexcept

Gets the line number in the file that contains the code that is executing. This information is typically extracted from the debugging symbols for the executable.

Returns

The file line number, or 0 (zero) if the file line number cannot be determined.

Examples

The following example demonstrates the use of the get_file_line_number() method. This code example is part of a larger example provided for the xtd::diagnostics::stack_frame class.

// Display the stack frame properties.
stack_frame sf = st.get_frame(i);
console::write_line(" File: {}", sf.get_file_name());
console::write_line(" Line Number: {}", sf.get_file_line_number());
// Note that the column number defaults to zero when not initialized.
console::write_line(" Column Number: {}", sf.get_file_column_number());
console::write_line(" Method: {}", sf.get_method());
if (sf.get_offset() != stack_frame::OFFSET_UNKNOWN)
  console::write_line(" Offset: {}", sf.get_offset());

get_file_name()

virtual const xtd::string & xtd::diagnostics::stack_frame::get_file_name ( ) const

virtualnoexcept

Gets the file name that contains the code that is executing. This information is typically extracted from the debugging symbols for the executable.

Returns

The file name, or empty ("") if the file name cannot be determined.

Examples

The following example demonstrates the use of the get_file_name() method. This code example is part of a larger example provided for the xtd::diagnostics::stack_frame class.

// Display the stack frame properties.
stack_frame sf = st.get_frame(i);
console::write_line(" File: {}", sf.get_file_name());
console::write_line(" Line Number: {}", sf.get_file_line_number());
// Note that the column number defaults to zero when not initialized.
console::write_line(" Column Number: {}", sf.get_file_column_number());
console::write_line(" Method: {}", sf.get_method());
if (sf.get_offset() != stack_frame::OFFSET_UNKNOWN)
  console::write_line(" Offset: {}", sf.get_offset());

get_method()

virtual const xtd::string & xtd::diagnostics::stack_frame::get_method ( ) const

virtualnoexcept

Gets the method in which the frame is executing.

Returns

The method in which the frame is executing.

Examples

The following example demonstrates the use of the get_method() method. This code example is part of a larger example provided for the xtd::diagnostics::stack_frame class.

// Display the stack frame properties.
stack_frame sf = st.get_frame(i);
console::write_line(" File: {}", sf.get_file_name());
console::write_line(" Line Number: {}", sf.get_file_line_number());
// Note that the column number defaults to zero when not initialized.
console::write_line(" Column Number: {}", sf.get_file_column_number());
console::write_line(" Method: {}", sf.get_method());
if (sf.get_offset() != stack_frame::OFFSET_UNKNOWN)
  console::write_line(" Offset: {}", sf.get_offset());

get_offset()

virtual xtd::size xtd::diagnostics::stack_frame::get_offset ( ) const

virtualnoexcept

Gets the offset from the start of the code for the method that is being executed.

Returns

The offset from the code for the method that is being executed.

Examples

The following example demonstrates the use of the get_offset() method. This code example is part of a larger example provided for the xtd::diagnostics::stack_frame class.

// Display the stack frame properties.
stack_frame sf = st.get_frame(i);
console::write_line(" File: {}", sf.get_file_name());
console::write_line(" Line Number: {}", sf.get_file_line_number());
// Note that the column number defaults to zero when not initialized.
console::write_line(" Column Number: {}", sf.get_file_column_number());
console::write_line(" Method: {}", sf.get_method());
if (sf.get_offset() != stack_frame::OFFSET_UNKNOWN)
  console::write_line(" Offset: {}", sf.get_offset());

to_string()

xtd::string xtd::diagnostics::stack_frame::to_string ( ) const

overridevirtualnoexcept

Builds a readable representation of the stack trace.

Returns

A readable representation of the stack trace.

Reimplemented from xtd::object.

current()

static stack_frame xtd::diagnostics::stack_frame::current ( const xtd::source_location &  value = xtd::source_location::current() )

staticnoexcept

Crates a new xtd::diagnostics::stack_frame object corresponding to the location of the call site.

Returns

The currentsouce stack frame informations.

Remarks

If xtd::diagnostics::stack_frame::current is invoked directly (via a function call that names xtd::source_location::current), it returns a source_location object with implementation-defined values representing the location of the call. The values should be affected by the #line preprocessor directive in the same manner as the predefined macros __LINE__ and __FILE__.

If xtd::diagnostics::stack_frame::current is used in a default member initializer, the return value corresponds to the location of the constructor definition or aggregate initialization that initializes the data member.

If xtd::diagnostics::stack_frame::current is used in a default argument, the return value corresponds to the location of the call to xtd::source_location::current at the call site.

If xtd::diagnostics::stack_frame::current is invoked in any other manner, the return value is unspecified.

Note

xtd::diagnostics::stack_frame::current typically requires compiler's built-in implementation.

equals() [2/3]

virtual bool xtd::object::equals ( const object &  obj ) const

virtualnoexcept

Determines whether the specified object is equal to the current object.

Parameters

obj	The object to compare with the current object.

Returns

true if the specified object is equal to the current object. otherwise, false.

Examples

The following code example compares the current instance with another object.

#include <xtd/console>
 
using namespace xtd;
 
auto main() -> int {
  auto object1 = new_ptr<object>();
  auto object2 = new_ptr<object>();
  
  auto object3 = object2;
  console::write_line(object1->equals(*object3));
  console::write_line(*object1 == *object3);
  object3 = object1;
  console::write_line(object1->equals(*object3));
  console::write_line(*object1 == *object3);
}
 
// This code produces the following output :
//
// false
// false
// true
// true

Reimplemented from xtd::object.

equals() [3/3]

template<typename object_a_t , typename object_b_t >

static bool xtd::object::equals ( const object_a_t &  object_a, const object_b_t &  object_b  )

inlinestaticnoexcept

Determines whether the specified object instances are considered equal.

Parameters

object_a	The first object to compare.
object_b	The second object to compare.

Returns

true if object_a is the same instance as object_b or if both are null references or if object_a(object_b) returns true. otherwise, false.

Examples

The following code example compares different objects.

#include <xtd/console>
 
using namespace xtd;
 
auto main() -> int {
  string s1 = "Tom";
  string s2 = "Carol";
  console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
  
  s1 = "Tom";
  s2 = "Tom";
  console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
  
  s1 = "";
  s2 = "Tom";
  console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
  
  s1 = "Carol";
  s2 = "";
  console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
  
  s1 = "";
  s2 = "";
  console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
}
 
// This code produces the following output :
//
// object::equals("Tom", "Carol") => false
// object::equals("Tom", "Tom") => true
// object::equals("", "Tom") => false
// object::equals("Carol", "") => false
// object::equals("", "") => true

Member Data Documentation

OFFSET_UNKNOWN

constexpr xtd::size xtd::diagnostics::stack_frame::OFFSET_UNKNOWN

staticconstexpr

Defines the value that is returned from the get_offset() method when the offset is unknown. This field is constant.

Remarks

The value of this constant is std::numeric_limits<xtd::size>::max().

---

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

• xtd.core/include/xtd/diagnostics/stack_frame.h