xtd::diagnostics::stack_frame Class Reference

#include <stack_frame.h>

Definition

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

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/xtd>
 
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& e) {
    stack_trace st;
    stack_trace st1(stack_frame(2, true));
    console::write_line(" Stack trace for Method2: {0}", st1.to_string());
    console::write_line(st.to_string());
    throw e;
  }
}
 
void method1() {
  try {
    method2(4);
  } catch (system_exception e) {
    stack_trace st;
    stack_trace st1(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.
    stack_trace st2(stack_frame(1, true));
    console::write_line(" Stack trace for next level frame: {0}", st2.to_string());
    throw e;
  }
}
 
int main() {
  try {
    method1();
  } catch (system_exception e) {
    stack_trace st;
    stack_trace st1(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.

Inherits xtd::object.

Static Public Attributes
static constexpr const uint32_t	OFFSET_UNKNOWN
	Defines the value that is returned from the get_offset() method when the offset is unknown. This field is constant.

Public Member Functions
	stack_frame ()
	Initializes a new instance of the xtd::diagnostics::stack_frame class.
	stack_frame (bool need_file_info)
	Initializes a new instance of the xtd::diagnostics::stack_frame class, optionally capturing source information.
	stack_frame (const xtd::ustring &file_name, uint32_t 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::ustring &file_name, uint32_t line_number, const xtd::ustring &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::ustring &file_name, uint32_t line_number, const xtd::ustring &method_name, uint32_t 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::ustring &file_name, uint32_t line_number, const xtd::ustring &method_name, uint32_t column_number, uint32_t offset)
	Initializes a new instance of the xtd::diagnostics::stack_frame class that contains only the given file name, line number, column number, method name, and offset.
	stack_frame (const xtd::ustring &file_name, uint32_t line_number, uint32_t 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 (size_t 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 (size_t 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.
virtual uint32_t	get_file_column_number () const
	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 uint32_t	get_file_line_number () const
	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::ustring &	get_file_name () const
	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::ustring &	get_method () const
	Gets the method in which the frame is executing.
virtual uint32_t	get_offset () const
	Gets the offset from the start of the code for the method that is being executed.
xtd::ustring	to_string () const noexcept override
	Builds a readable representation of the stack trace.
Public Member Functions inherited from xtd::object
	object ()=default
	Create a new instance of the ultimate base class object.
virtual bool	equals (const object &obj) const noexcept
	Determines whether the specified object is equal to the current object.
virtual size_t	get_hash_code () const noexcept
	Serves as a hash function for a particular type.
template<typename object_t >
std::unique_ptr< object_t >	memberwise_clone () const
	Gets the type of the current instance.
virtual xtd::ustring	to_string () const noexcept
	Returns a std::string that represents the current object.

Static Public Member Functions
static stack_frame	empty () noexcept
	Return an empty stack frame.
Static Public Member Functions inherited from xtd::object
static bool	equals (const object &object_a, const object &object_b) noexcept
	Determines whether the specified object instances are considered equal.
static bool	reference_equals (const object &object_a, const object &object_b) noexcept
	Determines whether the specified object instances are the same instance.

Constructor & Destructor Documentation

stack_frame() [1/9]

xtd::diagnostics::stack_frame::stack_frame

(

)

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

stack_frame() [2/9]

xtd::diagnostics::stack_frame::stack_frame ( size_t  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/9]

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/9]

xtd::diagnostics::stack_frame::stack_frame	(	size_t	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/9]

xtd::diagnostics::stack_frame::stack_frame	(	const xtd::ustring &	file_name,
		uint32_t	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/9]

xtd::diagnostics::stack_frame::stack_frame	(	const xtd::ustring &	file_name,
		uint32_t	line_number,
		const xtd::ustring &	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/9]

xtd::diagnostics::stack_frame::stack_frame	(	const xtd::ustring &	file_name,
		uint32_t	line_number,
		const xtd::ustring &	method_name,
		uint32_t	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/9]

xtd::diagnostics::stack_frame::stack_frame	(	const xtd::ustring &	file_name,
		uint32_t	line_number,
		uint32_t	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/9]

xtd::diagnostics::stack_frame::stack_frame	(	const xtd::ustring &	file_name,
		uint32_t	line_number,
		const xtd::ustring &	method_name,
		uint32_t	column_number,
		uint32_t	offset
	)

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

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.

Member Function Documentation

empty()

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

staticnoexcept

Return an empty stack frame.

Returns

Empty stack frame.

get_file_column_number()

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

virtual

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 uint32_t xtd::diagnostics::stack_frame::get_file_line_number ( ) const

virtual

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::ustring & xtd::diagnostics::stack_frame::get_file_name ( ) const

virtual

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::ustring & xtd::diagnostics::stack_frame::get_method ( ) const

virtual

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 uint32_t xtd::diagnostics::stack_frame::get_offset ( ) const

virtual

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::ustring 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.

Member Data Documentation

OFFSET_UNKNOWN

constexpr const uint32_t 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_limit<uint32_t>::max().

---

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

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