xtd - Reference Guide  0.2.0
Modern c++17/20 framework to create console, GUI and unit test applications on Windows, macOS, Linux, iOS and android.
Static Public Attributes | Public Member Functions | Static Public Member Functions | List of all members
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 st1(stack_frame(2, true));
console::write_line(" Stack trace for Method2: {0}", st1.to_string());
throw e;
}
}
void method1() {
try {
method2(4);
} catch (system_exception e) {
console::write_line(" Stack trace for Method1: {0}", st1.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) {
console::write_line(" Stack trace for Main: {0}", st1.to_string());
}
console::write_line("Press Enter to exit.");
}
// 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.

Static Public Attributes

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

Public Member Functions

 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_t 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_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. More...
 
 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. More...
 
 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. More...
 
 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. More...
 
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. More...
 
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. More...
 
virtual const xtd::ustringget_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. More...
 
virtual const xtd::ustringget_method () const
 Gets the method in which the frame is executing. More...
 
virtual uint32_t get_offset () const
 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...
 
- Public Member Functions inherited from xtd::object
 object ()=default
 Create a new instance of the ultimate base class object. More...
 
virtual 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
 Gets the type of the current instance. More...
 

Static Public Member Functions

static stack_frame empty () noexcept
 Return an empty stack frame. 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_frameThe 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_infotrue 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_frameThe number of frames up the stack to skip.
need_file_infotrue 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_nameThe file name.
line_numberThe 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_nameThe file name.
line_numberThe line number in the specified file.
method_nameThe 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_nameThe file name.
line_numberThe line number in the specified file.
method_nameThe method name.
offsetThe 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_nameThe file name.
line_numberThe line number in the specified file.
method_nameThe method name.
column_numberThe 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_nameThe file name.
line_numberThe line number in the specified file.
method_nameThe method name.
offsetThe 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.
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.
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.
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.
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.
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 = std::numeric_limits<uint32_t>::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_t>::max().

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