Classes
class	RecursiveDirectoryRange

class	DirectoryRange

struct	Color

Functions
template<typename T >
bool	unordered_vector_erase (std::vector< T > &vec, T element)

template<typename T >
bool	vectors_have_same_content (std::vector< T > vec_1, std::vector< T > vec_2)

u64	get_bit (const u64 value, const u64 index)

u64	set_bit (const u64 value, const u64 index)

u64	clear_bit (const u64 value, const u64 index)

u64	toggle_bit (const u64 value, const u64 index)

template<typename T >
bool	ends_with (const T &s, const T &end)

template<typename T >
bool	starts_with (const T &s, const T &start)

template<typename T >
bool	is_digits (const T &s)

template<typename T >
bool	is_integer (const T &s)

template<typename T >
bool	is_floating_point (const T &s)

template<typename T >
std::vector< T >	split (const T &s, const char delim, bool obey_brackets=false)

template<typename T >
T	ltrim (const T &s, const char *to_remove=" \t\r\n")

template<typename T >
T	rtrim (const T &s, const char *to_remove=" \t\r\n")

template<typename T >
T	trim (const T &s, const char *to_remove=" \t\r\n")

template<typename T >
T	replace (const T &str, const T &search, const T &replace)

template<typename Iterator , class Transform >
std::string	join (const std::string &joiner, const Iterator &begin, const Iterator &end, const Transform &transform)

template<typename T , class Transform >
std::string	join (const std::string &joiner, const T &items, const Transform &transform)

template<typename T >
std::string	join (const std::string &joiner, const T &items)

template<typename T >
T	to_upper (const T &s)

template<typename T >
T	to_lower (const T &s)

template<typename T >
u32	num_of_occurrences (const T &s, const T &substr)

template<typename T , template< typename, typename... > class Container, typename... Args>
std::vector< T >	to_vector (const Container< T, Args... > &container)

template<typename T , template< typename, typename... > class Container, typename... Args>
std::set< T >	to_set (const Container< T, Args... > &container)

template<typename T1 , typename T2 >
bool	is_subset (const T1 &subset, const T2 &superset)

bool	file_exists (const std::string &filename)

bool	folder_exists_and_is_accessible (const std::filesystem::path &path)

std::filesystem::path	which (const std::string &name, const std::string &path="")

std::filesystem::path	get_binary_directory ()

std::filesystem::path	get_base_directory ()

std::filesystem::path	get_library_directory ()

std::filesystem::path	get_share_directory ()

std::filesystem::path	get_user_share_directory ()

std::filesystem::path	get_config_directory ()

std::filesystem::path	get_user_config_directory ()

std::filesystem::path	get_default_log_directory (std::filesystem::path source_file="")

std::vector< std::filesystem::path >	get_gate_library_directories ()

std::vector< std::filesystem::path >	get_plugin_directories ()

std::filesystem::path	get_first_directory_exists (std::vector< std::filesystem::path > path_hints)

std::filesystem::path	get_file (std::string file_name, std::vector< std::filesystem::path > path_hints)

Result< std::filesystem::path >	get_unique_temp_directory (const std::string &prefix="", const u32 max_attempts=5)

std::string	get_open_source_licenses ()

Result< u64 >	wrapped_stoull (const std::string &s, const u32 base=10)

Result< u32 >	wrapped_stoul (const std::string &s, const u32 base=10)

Detailed Description

Contains general-purpose utility functions for strings, containers, bit manipulation, and file system paths.

Function Documentation

◆ clear_bit()

u64 hal::utils::clear_bit	(	const u64	value,
		const u64	index
	)

inline

Clear a single bit of an integer to 0.

Parameters

[in]	value	- The integer value.
[in]	index	- The bit position.

Returns: The manipulated value.

Definition at line 124 of file utils.h.

References index.

◆ ends_with()

template<typename T >

bool hal::utils::ends_with	(	const T &	s,
		const T &	end
	)

Checks whether a string ends with another string.

Parameters

[in]	s	- The string to analyze.
[in]	end	- The ending to check for.

Returns: true if s ends with end, false otherwise.

Definition at line 149 of file utils.h.

Referenced by hal::PluginPythonShell::exec(), and hal::plugin_manager::has_valid_file_extension().

◆ file_exists()

bool hal::utils::file_exists ( const std::string & filename )

Check whether a file exists.

Parameters

[in] filename - The file to check.

Returns: true if file exists, false otherwise.

Definition at line 31 of file utils.cpp.

Referenced by hal::CliExtensionsPerfTest::handle_cli_call().

◆ folder_exists_and_is_accessible()

bool hal::utils::folder_exists_and_is_accessible ( const std::filesystem::path & path )

Check whether a directory exists and access rights are granted.

Parameters

[in] path - The directory to check.

Returns: true if path exists and is accessible, false otherwise.

Definition at line 37 of file utils.cpp.

◆ get_base_directory()

std::filesystem::path hal::utils::get_base_directory ( )

Get the base path to the HAL installation.

Use Environment Variable HAL_BASE_PATH
If current executable is hal (not e.g. python3 interpreter) use it's path to determine base path.
Try to find hal executable in path and use its base path.

Returns: The path.

Definition at line 100 of file utils.cpp.

References die, get_binary_directory(), and which().

Referenced by hal::core_utils_init(), get_config_directory(), get_library_directory(), and get_share_directory().

◆ get_binary_directory()

std::filesystem::path hal::utils::get_binary_directory ( )

Get the path to the executable of HAL.

Returns: The path.

Definition at line 70 of file utils.cpp.

References size.

Referenced by hal::core_utils_init(), and get_base_directory().

◆ get_bit()

u64 hal::utils::get_bit	(	const u64	value,
		const u64	index
	)

inline

Get a single bit of an integer value.

Parameters

[in]	value	- The integer value.
[in]	index	- The bit position.

Returns: The specified bit (0 or 1).

Definition at line 100 of file utils.h.

References index.

◆ get_config_directory()

std::filesystem::path hal::utils::get_config_directory ( )

Get the path to the read-only global configuration directory of HAL.
The resulting path is relative to the binary directory.

Returns: The path.

Definition at line 164 of file utils.cpp.

References get_base_directory(), and get_first_directory_exists().

◆ get_default_log_directory()

std::filesystem::path hal::utils::get_default_log_directory ( std::filesystem::path source_file = "" )

Get the path to the default directory for log files.
If a netlist source file is provided, the function returns the parent directory, otherwise get_user_share_directory() / "log".

Parameters

[in] source_file - The netlist source file.

Returns: The path.

Definition at line 179 of file utils.cpp.

References get_user_share_directory().

Referenced by hal::core_utils_init().

◆ get_file()

std::filesystem::path hal::utils::get_file	(	std::string	file_name,
		std::vector< std::filesystem::path >	path_hints
	)

Search for the given filename in all paths provided by the path hints (searched in order).

Parameters

[in]	file_name	- The filename to search for.
[in]	path_hints	- A vector of hints.

Returns: The first to match or an empty string if no match is found.

Definition at line 220 of file utils.cpp.

Referenced by hal::gate_library_manager::get_gate_library(), and hal::plugin_manager::get_plugin_path().

◆ get_first_directory_exists()

std::filesystem::path hal::utils::get_first_directory_exists ( std::vector< std::filesystem::path > path_hints )

Get the first directory out of all the path hints that exists (searched in order).

Parameters

[in] path_hints - A vector of hints.

Returns: The first existing path or an empty string if none of them exists.

Definition at line 207 of file utils.cpp.

Referenced by get_config_directory(), and get_share_directory().

◆ get_gate_library_directories()

std::vector< std::filesystem::path > hal::utils::get_gate_library_directories ( )

Get the paths to the locations where gate libraries are searched.
Contains the share and user share directories.

Returns: A vector of paths.

Definition at line 186 of file utils.cpp.

References get_share_directory(), and get_user_share_directory().

Referenced by hal::core_utils_init(), hal::gate_library_manager::get_all_path(), hal::gate_library_manager::get_gate_library(), and hal::gate_library_manager::load_all().

◆ get_library_directory()

std::filesystem::path hal::utils::get_library_directory ( )

Get the path to the shared and static libraries of HAL.
The resulting path is relative to the binary directory.

Returns: The path.

Definition at line 129 of file utils.cpp.

References get_base_directory().

Referenced by hal::core_utils_init(), hal::PluginPythonShell::exec(), get_plugin_directories(), and hal::PythonContext::initializeContext().

◆ get_open_source_licenses()

std::string hal::utils::get_open_source_licenses ( )

Get the licenses of all embedded OpenSource Projects.

Returns: The open source licenses.

Definition at line 299 of file utils.cpp.

Referenced by hal::AboutDialog::AboutDialog().

◆ get_plugin_directories()

std::vector< std::filesystem::path > hal::utils::get_plugin_directories ( )

Get the paths to the locations where plugins are searched.
Contains the library and user share directories.

Returns: A vector of paths.

Definition at line 195 of file utils.cpp.

References get_library_directory(), and get_user_share_directory().

Referenced by hal::core_utils_init(), and hal::PythonContext::initializeContext().

◆ get_share_directory()

std::filesystem::path hal::utils::get_share_directory ( )

Get the path to the shared objects of HAL.
The resulting path is relative to the binary directory.

Returns: The path.

Definition at line 149 of file utils.cpp.

References get_base_directory(), and get_first_directory_exists().

Referenced by hal::core_utils_init(), and get_gate_library_directories().

◆ get_unique_temp_directory()

Result< std::filesystem::path > hal::utils::get_unique_temp_directory	(	const std::string &	prefix = `""`,
		const u32	max_attempts = `5`
	)

Try to generate a unique temporary directory.

Parameters

[in]	prefix	- A prefix that is added in front of the unique identifier. Defaults to an empty string.
[in]	max_attempts	- The maximum amount of attempts before the function fails. Defaults to `5`.

Returns: OK and the created directory path on success, an error otherwise.

Definition at line 276 of file utils.cpp.

References ERR, and OK.

Referenced by hal::resynthesis::generate_resynth_netlist_for_boolean_functions(), hal::resynthesis::resynthesize_gate(), hal::resynthesis::resynthesize_gates(), and hal::resynthesis::resynthesize_subgraph().

◆ get_user_config_directory()

std::filesystem::path hal::utils::get_user_config_directory ( )

Get the path to the configuration directory of the user.
This is ~/.config/hal on Unix.

Returns: The path.

Definition at line 172 of file utils.cpp.

Referenced by hal::core_utils_init(), hal::PluginGui::exec(), and hal::NetlistSimulatorControllerPlugin::on_load().

◆ get_user_share_directory()

std::filesystem::path hal::utils::get_user_share_directory ( )

Get the path to shared objects and files provided by the user.
This is ~/.local/share/hal on Unix.

Returns: The path.

Definition at line 157 of file utils.cpp.

Referenced by hal::core_utils_init(), get_default_log_directory(), get_gate_library_directories(), and get_plugin_directories().

◆ is_digits()

template<typename T >

bool hal::utils::is_digits ( const T & s )

Checks whether a string contains only digits.

Parameters

[in] s - The string to analyze.

Returns: true if s contains only digits, false otherwise.

Definition at line 188 of file utils.h.

◆ is_floating_point()

template<typename T >

bool hal::utils::is_floating_point ( const T & s )

Checks whether a string represents a real number.

Parameters

[in] s - The string to analyze.

Returns: true if s contains a real number, false otherwise.

Definition at line 220 of file utils.h.

◆ is_integer()

template<typename T >

bool hal::utils::is_integer ( const T & s )

Checks whether a string represents an integer.

Parameters

[in] s - The string to analyze.

Returns: true if s contains an integer, false otherwise.

Definition at line 200 of file utils.h.

◆ is_subset()

template<typename T1 , typename T2 >

bool hal::utils::is_subset	(	const T1 &	subset,
		const T2 &	superset
	)

Check whether one container is a subset of another container. The function checks whether all elements of the subset container are contained in the superset container.

Parameters

[in]	subset	- The container containing the possible subset.
[in]	superset	- The container containing the possible superset.

Returns: true if the subset container actually is a subset of the superset, false otherwise.

Definition at line 541 of file utils.h.

Referenced by hal::module_identification::Result::create_modules_in_netlist().

◆ join() [1/3]

template<typename Iterator , class Transform >

std::string hal::utils::join	(	const std::string &	joiner,
		const Iterator &	begin,
		const Iterator &	end,
		const Transform &	transform
	)

Join all elements of a iterator range with a joiner-string. A transformation is applied to all elements of the collections before joining.

Parameters

[in]	joiner	- The string joining the elements.
[in]	begin	- The start iterator.
[in]	end	- The end iterator.
[in]	transform	- The transformation function.

Returns: The joined string.

Definition at line 414 of file utils.h.

Referenced by hal::module_identification::FunctionalCandidate::add_all_shifted_operand(), hal::module_identification::FunctionalCandidate::add_selected_shifted_operand(), hal::dataflow::analyze(), hal::module_identification::Result::create_modules_in_netlist(), hal::module_identification::FunctionalCandidate::get_candidate_info(), hal::module_identification::VerifiedCandidate::get_candidate_info(), hal::module_identification::VerifiedCandidate::get_name(), join(), hal::ProgramOptions::parse(), hal::ProgramArguments::set_option(), and hal::dataflow::Result::write_txt().

◆ join() [2/3]

template<typename T >

std::string hal::utils::join	(	const std::string &	joiner,
		const T &	items
	)

Join all elements of a collection with a joiner-string.

Parameters

[in]	joiner	- The string joining the elements.
[in]	items	- The collection of elements to join.

Returns: The joined string.

Definition at line 453 of file utils.h.

References join().

◆ join() [3/3]

template<typename T , class Transform >

std::string hal::utils::join	(	const std::string &	joiner,
		const T &	items,
		const Transform &	transform
	)

Join all elements of a collection with a joiner-string. A transformation is applied to all elements of the collections before joining.

Parameters

[in]	joiner	- The string joining the elements.
[in]	items	- The collection of elements to join.
[in]	transform	- The transformation function.

Returns: The joined string.

Definition at line 440 of file utils.h.

References join().

◆ ltrim()

template<typename T >

T hal::utils::ltrim	(	const T &	s,
		const char *	to_remove = `" \t\r\n"`
	)

Remove any leading whitespace characters from the beginning of a string.

Parameters

[in]	s	- The string to trim.
[in]	to_remove	- The characters to remove.

Returns: The trimmed string.

Definition at line 316 of file utils.h.

References hal::T.

◆ num_of_occurrences()

template<typename T >

u32 hal::utils::num_of_occurrences	(	const T &	s,
		const T &	substr
	)

Count occurences of a substring in a string.

Parameters

[in]	s	- The string containing the substring.
[in]	substr	- The substring.

Returns: The number of occurrences.

Definition at line 494 of file utils.h.

◆ replace()

template<typename T >

T hal::utils::replace	(	const T &	str,
		const T &	search,
		const T &	replace
	)

Replace all occurences of a substring within a string with another string.

Parameters

[in]	str	- The initial string.
[in]	search	- The targetted substring.
[in]	replace	- The replacement string.

Returns: String with replaced substrings.

Definition at line 384 of file utils.h.

References hal::T.

Referenced by hal::LogicEvaluatorDialog::compile(), hal::verilator::escape_net_name(), hal::verilator::converter::get_provided_models(), and hal::GenlibWriter::write().

◆ rtrim()

template<typename T >

T hal::utils::rtrim	(	const T &	s,
		const char *	to_remove = `" \t\r\n"`
	)

Remove any trailing whitespace characters from the end of a string.

Parameters

[in]	s	- The string to trim.
[in]	to_remove	- The characters to remove.

Returns: The trimmed string.

Definition at line 338 of file utils.h.

References hal::T.

Referenced by hal::PythonContext::forwardStdout().

◆ set_bit()

u64 hal::utils::set_bit	(	const u64	value,
		const u64	index
	)

inline

Set a single bit of an integer to 1.

Parameters

[in]	value	- The integer value.
[in]	index	- The bit position.

Returns: The manipulated value.

Definition at line 112 of file utils.h.

References index.

◆ split()

template<typename T >

std::vector<T> hal::utils::split	(	const T &	s,
		const char	delim,
		bool	obey_brackets = `false`
	)

Split a string into a vector of strings. The split delimiter can be specified by the user.
The delimiters are removed in the splitting process.
To avoid splitting within brackets, set obey_brackets to true.

Parameters

[in]	s	- The string to split.
[in]	delim	- The delimiter, indicating where to split.
[in]	obey_brackets	- Flag to indicate whether brackets are obeyed.

Returns: The vector of strings.

Definition at line 239 of file utils.h.

References hal::T.

Referenced by hal::PluginPythonShell::exec(), hal::module_identification::FunctionalCandidate::identify_control_signals(), and which().

◆ starts_with()

template<typename T >

bool hal::utils::starts_with	(	const T &	s,
		const T &	start
	)

Checks whether a string begins with another string.

Parameters

[in]	s	- The string to analyze.
[in]	start	- The beginning to check for.

Returns: true if s begins with start, false otherwise.

Definition at line 169 of file utils.h.

Referenced by hal::dataflow::Result::create_modules().

◆ to_lower()

template<typename T >

T hal::utils::to_lower ( const T & s )

Convert a string to lower case.

Parameters

[in] s - The string to convert.

Returns: The lower case string.

Definition at line 479 of file utils.h.

References hal::T.

Referenced by hal::netlist_parser_manager::can_parse(), hal::gate_library_parser_manager::register_parser(), hal::netlist_parser_manager::register_parser(), hal::gate_library_writer_manager::register_writer(), and hal::netlist_writer_manager::register_writer().

◆ to_set()

template<typename T , template< typename, typename... > class Container, typename... Args>

std::set<T> hal::utils::to_set ( const Container< T, Args... > & container )

inline

Turn a given iterable collection into a set.

Parameters

[in] container - The input collection.

Returns: The set containing all items copied from the collection.

Definition at line 527 of file utils.h.

◆ to_upper()

template<typename T >

T hal::utils::to_upper ( const T & s )

Convert a string to upper case.

Parameters

[in] s - The string to convert.

Returns: The upper case string.

Definition at line 465 of file utils.h.

References hal::T.

◆ to_vector()

template<typename T , template< typename, typename... > class Container, typename... Args>

std::vector<T> hal::utils::to_vector ( const Container< T, Args... > & container )

inline

Turn a given iterable collection into a vector.

Parameters

[in] container - The input collection.

Returns: The vector containing all items copied from the collection.

Definition at line 515 of file utils.h.

Referenced by hal::z3_utils::compare_netlists(), hal::z3_utils::Converter::convert_z3_expr_to_func(), hal::Gate::get_resolved_boolean_function(), hal::LUTTableModel::setBooleanFunction(), and hal::solve_fsm::solve_fsm_brute_force().

◆ toggle_bit()

u64 hal::utils::toggle_bit	(	const u64	value,
		const u64	index
	)

inline

Toggle a single bit of an integer.

Parameters

[in]	value	- The integer value.
[in]	index	- The bit position.

Returns: The manipulated value.

Definition at line 136 of file utils.h.

References index.

◆ trim()

template<typename T >

T hal::utils::trim	(	const T &	s,
		const char *	to_remove = `" \t\r\n"`
	)

Remove any leading and trailing whitespace characters from the beginning and the end of a string.

Parameters

[in]	s	- The string to trim.
[in]	to_remove	- The characters to remove.

Returns: The trimmed string.

Definition at line 360 of file utils.h.

References hal::T.

Referenced by hal::ProgramOptions::add_flags(), hal::gate_library_parser_manager::register_parser(), hal::netlist_parser_manager::register_parser(), hal::gate_library_writer_manager::register_writer(), hal::netlist_writer_manager::register_writer(), hal::Gate::set_name(), hal::Module::set_name(), hal::Net::set_name(), and hal::Grouping::set_name().

◆ unordered_vector_erase()

template<typename T >

bool hal::utils::unordered_vector_erase	(	std::vector< T > &	vec,
		T	element
	)

inline

Erase the first occurence of a given element from an unordered vector.

Parameters

[in]	vec	- The unordered vector.
[in]	element	- The element to delete.

Returns: true on success, false otherwise.

Definition at line 60 of file utils.h.

◆ vectors_have_same_content()

template<typename T >

bool hal::utils::vectors_have_same_content	(	std::vector< T >	vec_1,
		std::vector< T >	vec_2
	)

Check whether two vectors have the same content regardless of their order.

Parameters

[in]	vec_1	- First vector.
[in]	vec_2	- Second vector.

Returns: true if the vectors have the same content, false otherwise.

Definition at line 80 of file utils.h.

◆ which()

std::filesystem::path hal::utils::which	(	const std::string &	name,
		const std::string &	path = `""`
	)

Locate an executable in the given path environment.

Parameters

[in]	name	- The name of the executable.
[in]	path	- The search path (defaults to PATH environment variable).

Returns: The path if an executable is found, an empty path otherwise.

Definition at line 243 of file utils.cpp.

References name, split(), and UNUSED.

Referenced by get_base_directory().

◆ wrapped_stoul()

Result< u32 > hal::utils::wrapped_stoul	(	const std::string &	s,
		const u32	base = `10`
	)

A safe wrapper around the std::stoul function that provides a Result<> for error handling instead of exceptions.

Parameters

[in]	s	- The string represntation of the number.
[in]	base	- The base of the integer, defaults to 10.

Returns: OK and an integer on success, an ERROR otherwise.

Definition at line 714 of file utils.cpp.

References ERR, and OK.

◆ wrapped_stoull()

Result< u64 > hal::utils::wrapped_stoull	(	const std::string &	s,
		const u32	base = `10`
	)

A safe wrapper around the std::stoull function that provides a Result<> for error handling instead of exceptions.

Parameters

[in]	s	- The string represntation of the number.
[in]	base	- The base of the integer, defaults to 10.

Returns: OK and an integer on success, an ERROR otherwise.

Definition at line 696 of file utils.cpp.

References ERR, and OK.

Classes

Functions

Detailed Description

Function Documentation

◆ clear_bit()

◆ ends_with()

◆ file_exists()

◆ folder_exists_and_is_accessible()

◆ get_base_directory()

◆ get_binary_directory()

◆ get_bit()

◆ get_config_directory()

◆ get_default_log_directory()

◆ get_file()

◆ get_first_directory_exists()

◆ get_gate_library_directories()

◆ get_library_directory()

◆ get_open_source_licenses()

◆ get_plugin_directories()

◆ get_share_directory()

◆ get_unique_temp_directory()

◆ get_user_config_directory()

◆ get_user_share_directory()

◆ is_digits()

◆ is_floating_point()

◆ is_integer()

◆ is_subset()

◆ join() [1/3]

◆ join() [2/3]

◆ join() [3/3]

◆ ltrim()

◆ num_of_occurrences()

◆ replace()

◆ rtrim()

◆ set_bit()

◆ split()

◆ starts_with()

◆ to_lower()

◆ to_set()

◆ to_upper()

◆ to_vector()

◆ toggle_bit()

◆ trim()

◆ unordered_vector_erase()

◆ vectors_have_same_content()

◆ which()

◆ wrapped_stoul()

◆ wrapped_stoull()