Utility Components

Supporting utilities for the libmagicxx library. More...

Files
file	percentage.hpp
	Percentage value type for progress tracking.
file	progress_tracker.hpp
	Thread-safe progress tracking for batch file operations.

Namespaces
namespace	Recognition::Utility
	Utility components for the libmagicxx library.

Concepts
concept	Recognition::Utility::RangeContainer
	Concept for types that are ranges with an accessible value_type.
concept	Recognition::Utility::StringConverter
	Concept for callables that convert a value to std::string.
concept	Recognition::Utility::FileContainer
	Concept for containers that can hold filesystem paths.

Classes
class	Recognition::Utility::Percentage
	A type-safe percentage value in the range [0, 100]. More...
class	Recognition::Utility::ProgressTracker
	Thread-safe tracker for monitoring multi-step job progress. More...
class	Recognition::Utility::MarkTrackerAsCompleted
	RAII helper that marks a ProgressTracker as completed on destruction. More...
class	Recognition::Utility::AdvanceTracker
	RAII helper that advances a ProgressTracker on destruction. More...

Typedefs
using	Recognition::Utility::SharedProgressTrackerT = std::shared_ptr<ProgressTracker>
	Shared pointer type for ProgressTracker.

Functions
SharedProgressTrackerT	Recognition::Utility::MakeSharedProgressTracker (std::uint64_t total_steps=1u) noexcept
	Factory function to create a shared ProgressTracker.
template<RangeContainer ContainerT, typename StringConverterT> requires StringConverter<typename ContainerT::value_type, StringConverterT>
std::string	Recognition::Utility::ToString (const ContainerT &container, const std::string &value_separator, StringConverterT string_converter)
	Convert a container to a string using a custom converter.
std::string	Recognition::Utility::ToString (const FileContainer auto &container, const std::string &separator=", ")
	Convert a FileContainer to a string.

Detailed Description

Supporting utilities for the libmagicxx library.

The utility module provides foundational components used by the Magic class and also available for direct use by library consumers.

Concepts

Concept	Description
RangeContainer	Types satisfying std::ranges::range with value_type
StringConverter	Callables converting a value to std::string
FileContainer	Containers of std::filesystem::path with push_back()

Classes

Class	Description
Percentage	Represents a percentage value (0-100%)
ProgressTracker	Thread-safe progress monitoring

Functions

Function	Description
ToString()	Convert containers to strings with custom separator
MakeSharedProgressTracker()	Factory for shared progress trackers

See also

Recognition::Utility namespace

Recognition::Magic::ProgressTrackerT

Typedef Documentation

SharedProgressTrackerT

using Recognition::Utility::SharedProgressTrackerT = std::shared_ptr<ProgressTracker>

Shared pointer type for ProgressTracker.

This type alias is used throughout the library for thread-safe sharing of progress trackers between threads.

See also

ProgressTracker

MakeSharedProgressTracker()

Since

10.0.0

Function Documentation

MakeSharedProgressTracker()

SharedProgressTrackerT Recognition::Utility::MakeSharedProgressTracker ( std::uint64_t total_steps = 1u )

inlinenoexcept

Factory function to create a shared ProgressTracker.

Creates a ProgressTracker wrapped in a shared_ptr for thread-safe sharing between the producer (worker) and consumer (monitor) threads.

Parameters

[in]

total_steps

Total number of steps (minimum 1, default 1).

Returns

A shared pointer to the newly created ProgressTracker.

auto tracker = MakeSharedProgressTracker(100);
 
// Pass to worker thread
auto future = std::async([tracker] {
    for (int i = 0; i < 100; ++i) {
        DoStep();
        tracker->Advance();
    }
});
 
// Monitor in main thread
while (!tracker->IsCompleted()) {
    std::println("{}", tracker->GetCompletionPercentage().ToString());
}

See also

SharedProgressTrackerT

ProgressTracker

Since

10.0.0

Examples

magic_examples.cpp.

ToString() [1/2]

template<RangeContainer ContainerT, typename StringConverterT>
requires StringConverter<typename ContainerT::value_type, StringConverterT>

std::string Recognition::Utility::ToString ( const ContainerT & container, const std::string & value_separator, StringConverterT string_converter )

inlinenodiscard

Convert a container to a string using a custom converter.

Converts each element in the container to a string using the provided converter function, then joins them with the specified separator.

Template Parameters

ContainerT	Container type satisfying RangeContainer.
StringConverterT	Callable type satisfying StringConverter.

Parameters

[in]	container	The container to convert.
[in]	value_separator	Separator string between elements.
[in]	string_converter	Callable that converts each element to string.

Returns

All elements joined as a string, or empty string if container is empty.

std::vector<int> numbers = {1, 2, 3};
auto result = ToString(numbers, ", ", [](int x) {
    return std::to_string(x);
});
// result == "1, 2, 3"

Since

10.0.0

ToString() [2/2]

std::string Recognition::Utility::ToString ( const FileContainer auto & container, const std::string & separator = ", " )

inlinenodiscard

Convert a FileContainer to a string.

Converts each path in the container to its string representation and joins them with the specified separator.

Parameters

[in]	container	The container of file paths to convert.
[in]	separator	Separator string between paths (default: ", ").

Returns

All paths joined as a string, or empty string if container is empty.

std::vector<std::filesystem::path> files = {
    "/path/to/file1.txt",
    "/path/to/file2.png"
};
std::string result = ToString(files);
// result == "/path/to/file1.txt, /path/to/file2.png"
 
std::string newlineSeparated = ToString(files, "\n");
// Each path on its own line

See also

FileContainer

Since

10.0.0