Matcher defined by a user-provided function. More...

#include <hart_matcher_function.hpp>

Inheritance diagram for MatcherFunction< SampleType >:

Public Member Functions
	MatcherFunction (std::function< bool(const AudioBuffer< SampleType > &, const AudioBuffer< SampleType > &)> matcherFunction, const std::string &label={})
	Creates a matcher from a function that compares input and output.

	MatcherFunction (std::function< bool(const AudioBuffer< SampleType > &)> matcherFunction, const std::string &label={})
	Constructs a matcher from a function that inspects only the output.

bool	match (const AudioBuffer< SampleType > &inputAudio, const AudioBuffer< SampleType > &observedOutputAudio) override
	Tells the host if the piece of audio satisfies Matcher's condition or not.

virtual MatcherFailureDetails	getFailureDetails () const override
	Returns a description of why the match has failed.

void	represent (std::ostream &stream) const override
	Makes a text representation of this Matcher for test failure outputs.

bool	canOperatePerBlock () const override
	Tells the host if it can operate on a block-by-block basis.

void	prepare (double, size_t, size_t) override
	Prepare for processing It is guaranteed that all subsequent process() calls will be in line with the arguments received in this callback. This callback is guaranteed to be called after canOperatePerBlock() If any of the values supplied by this callback are not supported by the matcher, it is expected to act as if the match has failed when match() gets called.

Public Member Functions inherited from Matcher< SampleType, MatcherFunction< SampleType > >
virtual std::unique_ptr< MatcherBase< SampleType > >	copy () const override
	Returns a smart pointer with a copy of this object.

virtual std::unique_ptr< MatcherBase< SampleType > >	move () override
	Returns a smart pointer with a moved instance of this object.

MatcherFunction< SampleType > &	atChannels (std::initializer_list< size_t > channelsToMatch) &
	Makes this matcher check only specific channels, and ignore the rest.

MatcherFunction< SampleType > &&	atChannels (std::initializer_list< size_t > channelsToMatch) &&
	Makes this matcher check only specific channels, and ignore the rest.

MatcherFunction< SampleType > &	atChannel (size_t channelToMatch) &
	Makes this matcher check only one specific channel, and ignore the rest.

MatcherFunction< SampleType > &&	atChannel (size_t channelToMatch) &&
	Makes this matcher check only one specific channel, and ignore the rest.

MatcherFunction< SampleType > &	atAllChannels () &
	Makes this matcher check all channels.

MatcherFunction< SampleType > &&	atAllChannels () &&
	Makes this matcher check all channels.

MatcherFunction< SampleType > &	atAllChannelsExcept (std::initializer_list< size_t > channelsToSkip) &
	Makes this matcher check only specific channels, and ignore the rest.

MatcherFunction< SampleType > &&	atAllChannelsExcept (std::initializer_list< size_t > channelsToSkip) &&
	Makes this matcher check only specific channels, and ignore the rest.

void	representWithActiveChannels (std::ostream &stream) const override
	Makes a text representation of this Matcher with optional "atChannels" appendix.

Public Member Functions inherited from MatcherBase< SampleType >
virtual	~MatcherBase ()=default

	HART_DEPRECATED ("This match() overload will be removed in HART 1.0.0, use \"match (const AudioBuffer&, const AudioBuffer&)\" instead") virtual bool match(const AudioBuffer< SampleType > &observedAudio)
	Tells the host if the piece of audio satisfies Matcher's condition or not.

virtual void	reset ()
	Resets the matcher to its initial state.

Additional Inherited Members
Protected Member Functions inherited from Matcher< SampleType, MatcherFunction< SampleType > >
bool	appliesToChannel (size_t channel)
	Indicates whether this matcher should check a specific channel.

Protected Attributes inherited from Matcher< SampleType, MatcherFunction< SampleType > >
ChannelFlags	m_channelsToMatch

Related Symbols inherited from Matcher< SampleType, MatcherFunction< SampleType > >
std::ostream &	operator<< (std::ostream &stream, const MatcherBase< SampleType > &matcher)
	Prints readable text representation of the Matcher object into the I/O stream.

Detailed Description

template<typename SampleType>
class hart::MatcherFunction< SampleType >

Matcher defined by a user-provided function.

This matcher allows defining custom matching logic using a callable object (e.g. a lambda, function, or functor), instead of creating a dedicated matcher class. The function can have one of the following signatures:

bool (const AudioBuffer<SampleType>& output);
bool (const AudioBuffer<SampleType>& input,
      const AudioBuffer<SampleType>& output);

The matcher operates on the full rendered buffer and does not support per-block evaluation.

Definition at line 24 of file hart_matcher_function.hpp.

Constructor & Destructor Documentation

◆ MatcherFunction() [1/2]

template<typename SampleType >

MatcherFunction	(	std::function< bool(const AudioBuffer< SampleType > &, const AudioBuffer< SampleType > &)>	matcherFunction,
		const std::string &	label = `{}`
	)

inline

Creates a matcher from a function that compares input and output.

Parameters

matcherFunction	A callable with signature: bool (const AudioBuffer<SampleType>& input, const AudioBuffer<SampleType>& output) It should return `true` if the output satisfies the expected condition, `false` otherwise
label	Optional human-readable label used in failure reports

Definition at line 37 of file hart_matcher_function.hpp.

◆ MatcherFunction() [2/2]

template<typename SampleType >

MatcherFunction	(	std::function< bool(const AudioBuffer< SampleType > &)>	matcherFunction,
		const std::string &	label = `{}`
	)

inline

Constructs a matcher from a function that inspects only the output.

Parameters

matcherFunction	A callable with signature: bool (const AudioBuffer<SampleType>& output) It should return `true` if the output satisfies the expected condition, `false` otherwise
label	Optional human-readable label used in failure reports

Definition at line 50 of file hart_matcher_function.hpp.

Member Function Documentation

◆ match()

template<typename SampleType >

bool match	(	const AudioBuffer< SampleType > &	inputAudio,
		const AudioBuffer< SampleType > &	observedOutputAudio
	)

inlineoverridevirtual

Tells the host if the piece of audio satisfies Matcher's condition or not.

It is guaranteed to be called only after prepare(), or not be called at all. It is guaranteed to be handed a pair of AudioBuffers in line with values set by the last prepare() call. If canOperatePerBlock() has returned false, this callback is guaranteed to be handed a full piece of audio to check. Otherwise, it may still get a full piece of audio, or get data on a block-by-block basis.

Parameters

inputAudio	A piece of input audio. Some matchers may be based on a relationship between input and output, rather than checking just the output audio. And in a lot of cases Matcher can ingore the input completely.
observedOutputAudio	A piece of observed output audio to check

Returns: true if the audio satisfies the Matcher's condition, false otherwise

Reimplemented from MatcherBase< SampleType >.

Definition at line 56 of file hart_matcher_function.hpp.

◆ getFailureDetails()

template<typename SampleType >

virtual MatcherFailureDetails getFailureDetails ( ) const

inlineoverridevirtual

Returns a description of why the match has failed.

It is guaranteed to be called strictly after calling match(), or not called at all

Note: This method is a callback for the test host, so you probably don't need to call it yourself ever. If you're making a custom matcher, use it to communicate the data with test host.

Return values

MatcherFailureDetails::frame	Index of frame at which the match has failed
MatcherFailureDetails::channel	Index of channel at which the failure was detected
MatcherFailureDetails::description	Readable description of why the match has failed. Do not include the value of observed frame value or its timing in the description, as well as any of values printed by represent(), as all of this will be added to the output anyway. Also, query hart::CLIConfig for number of displayed decimal places, whenever applicable.

See also: MatcherFailureDetails

Implements MatcherBase< SampleType >.

Definition at line 67 of file hart_matcher_function.hpp.

◆ represent()

template<typename SampleType >

void represent ( std::ostream & stream ) const

inlineoverridevirtual

Makes a text representation of this Matcher for test failure outputs.

It is strongly encouraged to follow python's repr() conventions for returned text - basically, put something like "MyClass(value1, value2)" (with no quotes) into the stream whenever possible, or "<Readable info in angled brackets>" otherwise. Also, use built-in stream manipulators like hart::dbPrecision wherever applicable. Use HART_DEFINE_GENERIC_REPRESENT() to get a basic implementation for this method.

Parameters

[out] stream Output stream to write to

Implements MatcherBase< SampleType >.

Definition at line 76 of file hart_matcher_function.hpp.

◆ canOperatePerBlock()

template<typename SampleType >

bool canOperatePerBlock ( ) const

inlineoverridevirtual

Tells the host if it can operate on a block-by-block basis.

Some types of conditions absolutely require having a full piece of audio to produce an appropriate response. For example, hart::PeaksAt matcher. Those types of matchers will return false on this callback. Matcher is guaranteed to receive a full piece of audio if this callback has returned false. Otherwise, it may receive audio either block-by-block basis, or still get a full piece of audio, if the host decides to do so.

Implements MatcherBase< SampleType >.

Definition at line 81 of file hart_matcher_function.hpp.

◆ prepare()

template<typename SampleType >

void prepare	(	double	sampleRateHz,
		size_t	numChannels,
		size_t	maxBlockSizeFrames
	)

inlineoverridevirtual

Prepare for processing It is guaranteed that all subsequent process() calls will be in line with the arguments received in this callback. This callback is guaranteed to be called after canOperatePerBlock() If any of the values supplied by this callback are not supported by the matcher, it is expected to act as if the match has failed when match() gets called.

Parameters

sampleRateHz	sample rate at which the audio should be interpreted
numChannels	Number of audio channels
maxBlockSizeFrames	Maximum block size in frames (samples)

Implements MatcherBase< SampleType >.

Definition at line 82 of file hart_matcher_function.hpp.

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

include/matchers/hart_matcher_function.hpp

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ MatcherFunction() [1/2]

◆ MatcherFunction() [2/2]

Member Function Documentation

◆ match()

◆ getFailureDetails()

◆ represent()

◆ canOperatePerBlock()

◆ prepare()