Stateless utility functions shared across VLink subsystems. More...

Functions
VLINK_EXPORT int	to_int (const std::string &str, int dv=0) noexcept
	Parses an integer string with auto base detection (`0x` -> hex, leading `0` -> octal, otherwise decimal). More...

VLINK_EXPORT int64_t	to_long (const std::string &str, int64_t dv=0, int offset=0) noexcept
	Parses a 64-bit integer string with optional trailing-character allowance. More...

VLINK_EXPORT std::string	double_to_string (double value, int precision=2) noexcept
	Formats a `double` with the requested decimal precision. More...

VLINK_EXPORT uint64_t	hash_combine (uint64_t a, uint64_t b) noexcept
	Combines two 64-bit hash values into one via a Murmur-style mix. More...

VLINK_EXPORT void	replace_string (std::string &str, const std::string &from, const std::string &to) noexcept
	Replaces all occurrences of `from` in `str` with `to` in place. More...

VLINK_EXPORT std::string	trim_string (const std::string &str) noexcept
	Returns `str` with leading and trailing whitespace removed. More...

VLINK_EXPORT std::string_view	trim_string_view (std::string_view str) noexcept
	Trims whitespace from both sides of a `string_view` without allocating. More...

VLINK_EXPORT std::wstring	string_to_wstring (const std::string &input) noexcept
	Converts UTF-8 to a wide-character string. More...

VLINK_EXPORT std::string	wstring_to_string (const std::wstring &input) noexcept
	Converts a wide-character string to UTF-8. More...

VLINK_EXPORT std::string	string_local_to_utf8 (const std::string &local_str) noexcept
	Converts a system-locale string to UTF-8. More...

VLINK_EXPORT std::string	string_utf8_to_local (const std::string &utf8_str) noexcept
	Converts UTF-8 to the active system locale on Windows; pass-through on POSIX. More...

VLINK_EXPORT std::string	path_to_string (const std::filesystem::path &path) noexcept
	Converts a filesystem path to a portable UTF-8 string. More...

VLINK_EXPORT std::vector< std::string >	split (const std::string &str, char f=',') noexcept
	Splits a string by a single-character delimiter; empty parts are skipped. More...

VLINK_EXPORT std::vector< std::string_view >	split_view (std::string_view str, char f=',') noexcept
	Splits a `string_view` by a delimiter and returns non-owning views. More...

VLINK_EXPORT std::vector< std::string >	split_any (const std::string &str, std::string_view delimiters=" ,") noexcept
	Splits a string by any delimiter in `delimiters`; each token is trimmed and empty tokens are skipped. More...

VLINK_EXPORT std::vector< std::string_view >	split_any_view (std::string_view str, std::string_view delimiters=" ,") noexcept
	Splits a view by any delimiter in `delimiters` and returns non-owning trimmed views. More...

VLINK_EXPORT std::string	escape_field (std::string_view value) noexcept
	Percent-encodes one field of a delimiter-separated text frame. More...

VLINK_EXPORT std::string	unescape_field (std::string_view value) noexcept
	Reverses `escape_field` encoding. More...

VLINK_EXPORT uint32_t	get_hash_code (const std::string &str) noexcept
	Maps a string to a 32-bit code. More...

VLINK_EXPORT std::string	format_milliseconds (int64_t milliseconds, bool show_millis) noexcept
	Renders a millisecond duration as a human-readable time string. More...

VLINK_EXPORT std::string	format_date (int64_t nanoseconds_since_epoch) noexcept
	Renders a nanosecond Unix timestamp as `"YYYY-MM-DD @c HH:MM:SS.mmm"` in UTC. More...

VLINK_EXPORT std::string	format_time_diff (int32_t milliseconds) noexcept
	Renders a millisecond time delta as `"HH:MM:SS:mmm"`. More...

VLINK_EXPORT std::string	format_hex_number (int64_t hex_number) noexcept
	Renders a signed 64-bit integer as a `"0x..."` hex literal. More...

VLINK_EXPORT std::string	format_hex_number (uint64_t hex_number) noexcept
	Renders an unsigned 64-bit integer as a `"0x..."` hex literal. More...

VLINK_EXPORT std::string	format_file_size (size_t size) noexcept
	Renders a byte count as a KB / MB / GB string with two decimal places. More...

VLINK_EXPORT std::string	format_rate_size (size_t size) noexcept
	Renders a byte-per-second rate as a B/s, KB/s, MB/s or GB/s string. More...

VLINK_EXPORT int64_t	convert_date_to_timestamp (const std::string &date) noexcept
	Parses a `"%Y/%m/%d @c %H:%M:%S"` (optionally `":<ms>"`) date into a Unix nanosecond timestamp. More...

template<uint8_t SizeT>
bool	has_startwith (const std::string &str, const char(&target)[SizeT]) noexcept
	Compile-time prefix check against a string literal. More...

template<uint8_t SizeT>
bool	has_endwith (const std::string &str, const char(&target)[SizeT]) noexcept
	Compile-time suffix check against a string literal. More...

constexpr bool	has_startwith (std::string_view str, std::string_view target) noexcept
	Constexpr prefix check for two `string_view` values. More...

constexpr bool	has_endwith (std::string_view str, std::string_view target) noexcept
	Constexpr suffix check for two `string_view` values. More...

constexpr bool	contains_substring (std::string_view sv, std::string_view needle) noexcept
	Constexpr substring search. More...

Detailed Description

Stateless utility functions shared across VLink subsystems.

Function Documentation

◆ contains_substring()

constexpr bool vlink::Helpers::contains_substring	(	std::string_view	sv,
		std::string_view	needle
	)

inlineconstexprnoexcept

Constexpr substring search.

Parameters

sv	String to search.
needle	Substring to look for; an empty needle returns `true`.

Returns: true when sv contains needle.

◆ convert_date_to_timestamp()

VLINK_EXPORT int64_t vlink::Helpers::convert_date_to_timestamp ( const std::string & date )

noexcept

Parses a "%Y/%m/%d @c %H:%M:%S" (optionally ":<ms>") date into a Unix nanosecond timestamp.

Interpreted in the local timezone via std::mktime. ISO-8601 dashes are not accepted.

Parameters

date	Source date string.

Returns: Nanoseconds since Unix epoch, or -1 on parse failure.

◆ double_to_string()

VLINK_EXPORT std::string vlink::Helpers::double_to_string	(	double	value,
		int	precision = `2`
	)

noexcept

Formats a double with the requested decimal precision.

Parameters

value	Source value.
precision	Number of digits after the decimal point. Default: `2`.

Returns: Decimal string representation.

◆ escape_field()

VLINK_EXPORT std::string vlink::Helpers::escape_field ( std::string_view value )

noexcept

Percent-encodes one field of a delimiter-separated text frame.

Encodes %, space, :, LF and CR as uppercase XX sequences; other bytes pass through.

Parameters

value Field to encode.

Returns: Encoded field.

◆ format_date()

VLINK_EXPORT std::string vlink::Helpers::format_date ( int64_t nanoseconds_since_epoch )

noexcept

Renders a nanosecond Unix timestamp as "YYYY-MM-DD @c HH:MM:SS.mmm" in UTC.

Parameters

nanoseconds_since_epoch Source timestamp.

Returns: Formatted date string.

◆ format_file_size()

VLINK_EXPORT std::string vlink::Helpers::format_file_size ( size_t size )

noexcept

Renders a byte count as a KB / MB / GB string with two decimal places.

Parameters

size	Source value in bytes.

Returns: Human-readable size string.

◆ format_hex_number() [1/2]

VLINK_EXPORT std::string vlink::Helpers::format_hex_number ( int64_t hex_number )

noexcept

Renders a signed 64-bit integer as a "0x..." hex literal.

Parameters

hex_number Source value.

Returns: Hex literal string.

◆ format_hex_number() [2/2]

VLINK_EXPORT std::string vlink::Helpers::format_hex_number ( uint64_t hex_number )

noexcept

Renders an unsigned 64-bit integer as a "0x..." hex literal.

Parameters

hex_number Source value.

Returns: Hex literal string.

◆ format_milliseconds()

VLINK_EXPORT std::string vlink::Helpers::format_milliseconds	(	int64_t	milliseconds,
		bool	show_millis
	)

noexcept

Renders a millisecond duration as a human-readable time string.

Parameters

milliseconds	Source duration.
show_millis	When `true` the millisecond field is appended.

Returns: Formatted duration string.

◆ format_rate_size()

VLINK_EXPORT std::string vlink::Helpers::format_rate_size ( size_t size )

noexcept

Renders a byte-per-second rate as a B/s, KB/s, MB/s or GB/s string.

Parameters

size	Source rate in bytes per second.

Returns: Human-readable rate string.

◆ format_time_diff()

VLINK_EXPORT std::string vlink::Helpers::format_time_diff ( int32_t milliseconds )

noexcept

Renders a millisecond time delta as "HH:MM:SS:mmm".

Parameters

milliseconds Source delta.

Returns: Formatted delta string.

◆ get_hash_code()

VLINK_EXPORT uint32_t vlink::Helpers::get_hash_code ( const std::string & str )

noexcept

Maps a string to a 32-bit code.

If str parses as an integer it is returned as its numeric value; otherwise the result is std::hash<std::string> truncated to 32 bits. An empty string yields 0.

Parameters

str	Source string.

Returns: 32-bit code.

◆ has_endwith() [1/2]

template<uint8_t SizeT>

bool vlink::Helpers::has_endwith	(	const std::string &	str,
		const char(&)	target[SizeT]
	)

inlinenoexcept

Compile-time suffix check against a string literal.

Template Parameters

SizeT Size of target including the null terminator (deduced).

Parameters

str	String to test.
target	Literal suffix.

Returns: true when str ends with target.

◆ has_endwith() [2/2]

constexpr bool vlink::Helpers::has_endwith	(	std::string_view	str,
		std::string_view	target
	)

inlineconstexprnoexcept

Constexpr suffix check for two string_view values.

Parameters

str	String to test.
target	Suffix to check for.

Returns: true when str ends with target.

◆ has_startwith() [1/2]

template<uint8_t SizeT>

bool vlink::Helpers::has_startwith	(	const std::string &	str,
		const char(&)	target[SizeT]
	)

inlinenoexcept

Compile-time prefix check against a string literal.

Details.

Template Parameters

SizeT Size of target including the null terminator (deduced).

Parameters

str	String to test.
target	Literal prefix.

Returns: true when str starts with target.

Here is the caller graph for this function:

◆ has_startwith() [2/2]

constexpr bool vlink::Helpers::has_startwith	(	std::string_view	str,
		std::string_view	target
	)

inlineconstexprnoexcept

Constexpr prefix check for two string_view values.

Parameters

str	String to test.
target	Prefix to check for.

Returns: true when str starts with target.

◆ hash_combine()

VLINK_EXPORT uint64_t vlink::Helpers::hash_combine	(	uint64_t	a,
		uint64_t	b
	)

noexcept

Combines two 64-bit hash values into one via a Murmur-style mix.

Parameters

a	First hash value.
b	Second hash value.

Returns: Mixed hash value.

◆ path_to_string()

VLINK_EXPORT std::string vlink::Helpers::path_to_string ( const std::filesystem::path & path )

noexcept

Converts a filesystem path to a portable UTF-8 string.

Parameters

path	Source path.

Returns: UTF-8 path string.

◆ replace_string()

VLINK_EXPORT void vlink::Helpers::replace_string	(	std::string &	str,
		const std::string &	from,
		const std::string &	to
	)

noexcept

Replaces all occurrences of from in str with to in place.

Parameters

str	String mutated in place.
from	Substring to search for.
to	Replacement substring.

Here is the caller graph for this function:

◆ split()

VLINK_EXPORT std::vector<std::string> vlink::Helpers::split	(	const std::string &	str,
		char	f = `','`
	)

noexcept

Splits a string by a single-character delimiter; empty parts are skipped.

Parameters

str	Source string.
f	Delimiter character. Defaults to `'`,'.

Returns: Vector of non-empty substrings.

◆ split_any()

VLINK_EXPORT std::vector<std::string> vlink::Helpers::split_any	(	const std::string &	str,
		std::string_view	delimiters = `" ,"`
	)

noexcept

Splits a string by any delimiter in delimiters; each token is trimmed and empty tokens are skipped.

Parameters

str	Source string.
delimiters	Delimiter character set. Defaults to `" ,"`.

Returns: Vector of trimmed, non-empty tokens.

◆ split_any_view()

VLINK_EXPORT std::vector<std::string_view> vlink::Helpers::split_any_view	(	std::string_view	str,
		std::string_view	delimiters = `" ,"`
	)

noexcept

Splits a view by any delimiter in delimiters and returns non-owning trimmed views.

The caller must keep str alive while the returned views are used.

Parameters

str	Source view.
delimiters	Delimiter character set. Defaults to `" ,"`.

Returns: Vector of trimmed, non-empty views over the tokens.

◆ split_view()

VLINK_EXPORT std::vector<std::string_view> vlink::Helpers::split_view	(	std::string_view	str,
		char	f = `','`
	)

noexcept

Splits a string_view by a delimiter and returns non-owning views.

The caller must keep str alive while the returned views are used.

Parameters

str	Source view.
f	Delimiter character. Defaults to `'`,'.

Returns: Vector of non-empty views over the parts.

◆ string_local_to_utf8()

VLINK_EXPORT std::string vlink::Helpers::string_local_to_utf8 ( const std::string & local_str )

noexcept

Converts a system-locale string to UTF-8.

Performs Windows ANSI-code-page conversion; returns the input unchanged on POSIX.

Parameters

local_str Locally encoded string.

Returns: UTF-8 string, or the input when no conversion is needed.

◆ string_to_wstring()

VLINK_EXPORT std::wstring vlink::Helpers::string_to_wstring ( const std::string & input )

noexcept

Converts UTF-8 to a wide-character string.

Parameters

input UTF-8 source.

Returns: Wide-character result; empty on failure.

◆ string_utf8_to_local()

VLINK_EXPORT std::string vlink::Helpers::string_utf8_to_local ( const std::string & utf8_str )

noexcept

Converts UTF-8 to the active system locale on Windows; pass-through on POSIX.

Parameters

utf8_str UTF-8 source.

Returns: Locally encoded string.

◆ to_int()

VLINK_EXPORT int vlink::Helpers::to_int	(	const std::string &	str,
		int	dv = `0`
	)

noexcept

Parses an integer string with auto base detection (0x -> hex, leading 0 -> octal, otherwise decimal).

Parameters

str	Source string.
dv	Default value returned on parse failure. Default: `0`.

Returns: Parsed int or dv on failure.

◆ to_long()

VLINK_EXPORT int64_t vlink::Helpers::to_long	(	const std::string &	str,
		int64_t	dv = `0`,
		int	offset = `0`
	)

noexcept

Parses a 64-bit integer string with optional trailing-character allowance.

Calls std::stoll with auto base detection (0x -> hex, leading 0 -> octal, otherwise decimal). Parsing always starts at index 0; offset is the number of trailing characters the parser may leave unconsumed (for example to skip a unit suffix such as "100s" with offset == 1). Mismatched consumption returns dv.

Parameters

str	Source string.
dv	Default value on failure. Default: `0`.
offset	Number of trailing characters allowed to remain unconsumed. Default: `0`.

Returns: Parsed int64_t or dv on failure.

◆ trim_string()

VLINK_EXPORT std::string vlink::Helpers::trim_string ( const std::string & str )

noexcept

Returns str with leading and trailing whitespace removed.

Parameters

str	Source string.

Returns: Trimmed copy.

◆ trim_string_view()

VLINK_EXPORT std::string_view vlink::Helpers::trim_string_view ( std::string_view str )

noexcept

Trims whitespace from both sides of a string_view without allocating.

The returned view references the same storage as str; callers must keep the original character storage alive while using the result.

Parameters

str	Source view.

Returns: Trimmed view, or an empty view when str is empty or all whitespace.

◆ unescape_field()

VLINK_EXPORT std::string vlink::Helpers::unescape_field ( std::string_view value )

noexcept

Reverses escape_field encoding.

Decodes valid XX sequences; preserves invalid or truncated sequences verbatim so legacy frames remain parseable.

Parameters

value Encoded field.

Returns: Decoded field.

◆ wstring_to_string()

VLINK_EXPORT std::string vlink::Helpers::wstring_to_string ( const std::wstring & input )

noexcept

Converts a wide-character string to UTF-8.

Parameters

input Wide source.

Returns: UTF-8 result; empty on failure.

Functions

Detailed Description

Function Documentation

◆ contains_substring()

◆ convert_date_to_timestamp()

◆ double_to_string()

◆ escape_field()

◆ format_date()

◆ format_file_size()

◆ format_hex_number() [1/2]

◆ format_hex_number() [2/2]

◆ format_milliseconds()

◆ format_rate_size()

◆ format_time_diff()

◆ get_hash_code()

◆ has_endwith() [1/2]

◆ has_endwith() [2/2]

◆ has_startwith() [1/2]

◆ has_startwith() [2/2]

◆ hash_combine()

◆ path_to_string()

◆ replace_string()

◆ split()

◆ split_any()

◆ split_any_view()

◆ split_view()

◆ string_local_to_utf8()

◆ string_to_wstring()

◆ string_utf8_to_local()

◆ to_int()

◆ to_long()

◆ trim_string()

◆ trim_string_view()

◆ unescape_field()

◆ wstring_to_string()