#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.

class core_export_ stack_frame : public xtd::object

Inheritance: xtd::object → 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/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&) {
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;
}
}
void method1() {
try {
method2(4);
} catch (const system_exception&) {
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;
}
}
auto main()->int {
try {
method1();
} catch (const system_exception&) {
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.

Examples:: csf.cpp, current_stack_frame.cpp, line_info.cpp, math_assert.cpp, stack_frame.cpp, and stack_trace_simple.cpp.

Constructors
	stack_frame ()
	Initializes a new instance of the xtd::diagnostics::stack_frame class. More...

	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. More...

	stack_frame (bool need_file_info)
	Initializes a new instance of the xtd::diagnostics::stack_frame class, optionally capturing source information. More...

	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. More...

	stack_frame (const xtd::ustring &file_name, uint32 line_number)
	Initializes a new instance of the xtd::diagnostics::stack_frame class that contains only the given file name, and line number. More...

	stack_frame (const xtd::ustring &file_name, uint32 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. More...

	stack_frame (const xtd::ustring &file_name, uint32 line_number, const xtd::ustring &method_name, uint32 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. More...

	stack_frame (const xtd::ustring &file_name, uint32 line_number, uint32 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. More...

	stack_frame (const xtd::ustring &file_name, uint32 line_number, const xtd::ustring &method_name, uint32 column_number, uint32 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. More...

Fields
static constexpr uint32	OFFSET_UNKNOWN = std::numeric_limits<uint32>::max()
	Defines the value that is returned from the get_offset() method when the offset is unknown. This field is constant. More...

static stack_frame	empty () noexcept
	Return an empty stack frame. More...

Methods
bool	equals (const stack_frame &sf) const noexcept override

virtual uint32	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. More...

virtual uint32	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. More...

virtual const xtd::ustring &	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. More...

virtual const xtd::ustring &	get_method () const noexcept
	Gets the method in which the frame is executing. More...

virtual uint32	get_offset () const noexcept
	Gets the offset from the start of the code for the method that is being executed. More...

xtd::ustring	to_string () const noexcept override
	Builds a readable representation of the stack trace. More...

Additional Inherited Members
Public Member Functions inherited from xtd::object
	object ()=default
	Create a new instance of the ultimate base class object. More...

bool	equals (const object &obj) const noexcept
	Determines whether the specified object is equal to the current object. More...

virtual size_t	get_hash_code () const noexcept
	Serves as a hash function for a particular type. More...

template<typename object_t >
std::unique_ptr< object_t >	memberwise_clone () const noexcept
	Gets the type of the current instance. More...

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. More...

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. More...

static bool	reference_equals (const object &object_a, const object &object_b) noexcept
	Determines whether the specified object instances are the same instance. More...

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	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	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	line_number,
		const xtd::ustring &	method_name,
		uint32	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	line_number,
		uint32	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	line_number,
		const xtd::ustring &	method_name,
		uint32	column_number,
		uint32	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 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 uint32 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());

Examples:: create_gtest_like_event_listener.cpp, csf.cpp, current_stack_frame.cpp, line_info.cpp, and stack_trace_simple.cpp.

◆ get_file_name()

virtual const xtd::ustring& 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());

Examples:: create_gtest_like_event_listener.cpp, csf.cpp, current_stack_frame.cpp, line_info.cpp, and stack_trace_simple.cpp.

◆ get_method()

virtual const xtd::ustring& 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());

Examples:: csf.cpp, current_stack_frame.cpp, line_info.cpp, and stack_trace_simple.cpp.

◆ get_offset()

virtual uint32 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::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 uint32 xtd::diagnostics::stack_frame::OFFSET_UNKNOWN = std::numeric_limits<uint32>::max()

static

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>::max().

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

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

Definition

Constructors

Fields

Methods

Additional Inherited Members

Constructor & Destructor Documentation

◆ stack_frame() [1/9]

◆ stack_frame() [2/9]

◆ stack_frame() [3/9]

◆ stack_frame() [4/9]

◆ stack_frame() [5/9]

◆ stack_frame() [6/9]

◆ stack_frame() [7/9]

◆ stack_frame() [8/9]

◆ stack_frame() [9/9]

Member Function Documentation

◆ empty()

◆ get_file_column_number()

◆ get_file_line_number()

◆ get_file_name()

◆ get_method()

◆ get_offset()

◆ to_string()

Member Data Documentation

◆ OFFSET_UNKNOWN