micro_os_plus::micro_test_plus::located_name Class Reference

A name of a suite or of a test case, with the location where it was given. More...

#include "micro-os-plus/micro-test-plus.h"

Public Member Functions
template<std::size_t N>
	located_name (const char(&name)[N], const reflection::source_location &location=reflection::source_location::current())
	Constructs the name from an array of characters, capturing the location of the caller.
	located_name (const std::string &name, const reflection::source_location &location=reflection::source_location::current())
	Constructs the name from a standard string, capturing the location of the caller.
template<typename Pointer_T> requires (std::is_same_v<Pointer_T, const char*> or std::is_same_v<Pointer_T, char*> or std::is_null_pointer_v<Pointer_T>)
	located_name (Pointer_T name, const reflection::source_location &location=reflection::source_location::current())
	Constructs the name from a C string, capturing the location of the caller.
	located_name (std::string &&name, const reflection::source_location &location=reflection::source_location::current())
	Constructs the name from a temporary standard string, capturing the location of the caller.
	located_name (std::string_view name, const reflection::source_location &location=reflection::source_location::current())
	Constructs the name from a string view, capturing the location of the caller.
const reflection::source_location &	location (void) const noexcept
	Returns the location where the name was given.
const char *	name (void) const noexcept
	Returns the name.

Private Attributes
reflection::source_location	location_
	The location where the name was given.
std::string	name_
	The copy of the name.

Detailed Description

The name parameter of suite::test(), test_case::test(), test_each(), runner::add_suite(), runner::add_top_suite(), and the static_suite constructors. The constructors are not explicit, so a string literal, a const char*, a std::string, or a std::string_view passed as the name converts implicitly; the default argument of the constructors is evaluated at the place of the conversion, which is the call in the user code, so the location is captured without an additional argument (which could not follow the variadic arguments of these functions).

The name is copied, so the argument need not outlive the call, and a std::string_view need not be null-terminated; a temporary std::string is moved. The copy of a test case name lives until the end of the call to test(), within which the test case runs, so the memory used does not grow with the number of test cases; the suites, which run later, keep their name, moved, until they are destroyed.

The location of a test case is used to report a failure that is not associated with a check, such as an exception escaping the test case body; the suites keep their location, but do not report it.

Since a conversion sequence may include only one user-defined conversion, an argument that converts to const char*, to std::string, or to std::string_view via a user-defined conversion operator must be converted explicitly.

A helper function that adds test cases on behalf of its caller can take a const located_name& parameter and pass it to test(), so that the reported location is that of the call to the helper, not that of the call to test() inside the helper.

Example

namespace mt = micro_os_plus::micro_test_plus;
 
void
check_answer (mt::suite& ts, const mt::located_name& name, int v)
{
  ts.test (name, [v] (auto& t) { t.expect (mt::eq (v, 42)); });
}

Since

6.0.0

Definition at line 176 of file test.h.

Constructor & Destructor Documentation

located_name() [1/5]

template<typename Pointer_T>
requires (std::is_same_v<Pointer_T, const char*> or std::is_same_v<Pointer_T, char*> or std::is_null_pointer_v<Pointer_T>)

micro_os_plus::micro_test_plus::located_name::located_name	(	Pointer_T	name,
		const reflection::source_location &	location = reflection::source_location::current () )

Selected for the char pointers; the text must be null-terminated. The arrays, including the string literals, are taken by the constructor for arrays, which does not read beyond the array.

Template Parameters

Pointer_T

The pointer type: a pointer to char, possibly const, or std::nullptr_t.

Parameters

name	The name or description, used in reports; copied. A null pointer is an empty name.
location	The location of the conversion, defaulting to the call in the user code.

Copies the name, or stores an empty name if the pointer is null, and the location; the control characters of the name are escaped. When called implicitly, the location is the place of the conversion, in the user code.

Definition at line 101 of file test-inlines.h.

      : name_{ name != nullptr ? name : "" }, location_{ location }
  {
    detail::escape_control_characters (name_);
  }

References located_name(), location(), name(), and name_.

Referenced by located_name().

located_name() [2/5]

template<std::size_t N>

micro_os_plus::micro_test_plus::located_name::located_name	(	const char(&)	name[N],
		const reflection::source_location &	location = reflection::source_location::current () )

Selected for the arrays, including the string literals. The name ends at the first null character or at the end of the array, whichever comes first, so that an array that is full, without a terminator, such as a fixed-size name field, is not read beyond its end.

Template Parameters

N	The number of elements of the array.

Parameters

name	The name or description, used in reports; copied.
location	The location of the conversion, defaulting to the call in the user code.

Copies the characters up to the first null character, or all the elements of the array if there is none, and stores the location; when called implicitly, the location is the place of the conversion, in the user code.

Definition at line 116 of file test-inlines.h.

      : name_{ std::string_view{ name, N }.substr (
            0, std::string_view{ name, N }.find ('\0')) },
        location_{ location }
  {
    detail::escape_control_characters (name_);
  }

References micro_os_plus::micro_test_plus::detail::escape_control_characters(), location(), location_, name(), and name_.

located_name() [3/5]

micro_os_plus::micro_test_plus::located_name::located_name ( const std::string & name, const reflection::source_location & location = reflection::source_location::current () )

inline

Parameters

name	The name or description, used in reports; copied.
location	The location of the conversion, defaulting to the call in the user code.

Copies the content of the string, and stores the location; when called implicitly, the location is the place of the conversion, in the user code.

Definition at line 131 of file test-inlines.h.

      : name_{ name }, location_{ location }
  {
    detail::escape_control_characters (name_);
  }

References micro_os_plus::micro_test_plus::detail::escape_control_characters(), location(), location_, name(), and name_.

located_name() [4/5]

micro_os_plus::micro_test_plus::located_name::located_name ( std::string && name, const reflection::source_location & location = reflection::source_location::current () )

inline

Parameters

name	The name or description, used in reports; moved.
location	The location of the conversion, defaulting to the call in the user code.

Takes over the content of the string, without copying it, and stores the location; when called implicitly, the location is the place of the conversion, in the user code.

Definition at line 144 of file test-inlines.h.

      : name_{ std::move (name) }, location_{ location }
  {
    detail::escape_control_characters (name_);
  }

References micro_os_plus::micro_test_plus::detail::escape_control_characters(), location(), location_, name(), and name_.

located_name() [5/5]

micro_os_plus::micro_test_plus::located_name::located_name ( std::string_view name, const reflection::source_location & location = reflection::source_location::current () )

inline

Parameters

name	The name or description, used in reports; copied, so the view need not be null-terminated.
location	The location of the conversion, defaulting to the call in the user code.

Copies the characters of the view, which need not be null-terminated, and stores the location; when called implicitly, the location is the place of the conversion, in the user code.

Definition at line 157 of file test-inlines.h.

      : name_{ name }, location_{ location }
  {
    detail::escape_control_characters (name_);
  }

References micro_os_plus::micro_test_plus::detail::escape_control_characters(), location(), location_, name(), and name_.

Member Function Documentation

location()

const reflection::source_location & micro_os_plus::micro_test_plus::located_name::location ( void ) const

inlinenodiscardnoexcept

Parameters

None.

Returns

A reference to the stored source location.

Returns a reference to the location stored in location_.

Definition at line 179 of file test-inlines.h.

  {
    return location_;
  }

References location_.

Referenced by located_name(), located_name(), located_name(), located_name(), located_name(), micro_os_plus::micro_test_plus::detail::runnable_base::accepts_test_case(), micro_os_plus::micro_test_plus::runner::add_top_suite(), micro_os_plus::micro_test_plus::test_case::fail_unexpected_exception(), micro_os_plus::micro_test_plus::runner::reject_call(), micro_os_plus::micro_test_plus::test_case::report_misdirected_test(), and micro_os_plus::micro_test_plus::detail::test_each_value().

name()

const char * micro_os_plus::micro_test_plus::located_name::name ( void ) const

inlinenodiscardnoexcept

Parameters

None.

Returns

A pointer to the null-terminated name, valid while this object exists and is not modified.

Returns name_.c_str().

Definition at line 169 of file test-inlines.h.

  {
    return name_.c_str ();
  }

References name_.

Referenced by located_name(), located_name(), located_name(), located_name(), located_name(), micro_os_plus::micro_test_plus::suite::suite(), micro_os_plus::micro_test_plus::detail::runnable_base::accepts_test_case(), micro_os_plus::micro_test_plus::runner::add_suite(), micro_os_plus::micro_test_plus::runner::add_top_suite(), micro_os_plus::micro_test_plus::test_case::report_misdirected_test(), micro_os_plus::micro_test_plus::suite::test(), micro_os_plus::micro_test_plus::test_case::test(), and micro_os_plus::micro_test_plus::detail::test_each_value().

Member Data Documentation

location_

reflection::source_location micro_os_plus::micro_test_plus::located_name::location_

private

Captured by the default argument of the constructor, at the place of the conversion to located_name.

Definition at line 298 of file test.h.

Referenced by located_name(), located_name(), located_name(), located_name(), and location().

name_

std::string micro_os_plus::micro_test_plus::located_name::name_

private

Owned, so that the name does not depend on the lifetime of the argument; the name of the node points into it.

Definition at line 289 of file test.h.

Referenced by located_name(), located_name(), located_name(), located_name(), located_name(), and name().

---

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

• test.h
• test-inlines.h