Health formatting helpers

Formatting of durations, distances and paces for the health UI. More...

Macros
#define	MAX_TEXT_NODES   5
	Maximum number of text nodes needed in a text node container.
#define	HEALTH_WHOLE_AND_DECIMAL_LENGTH   (sizeof("00.0") + 4)
	Buffer size for a "00.0" formatted value, with 4 extra bytes for translations.

Functions
int	health_util_format_hours_and_minutes (char *buffer, size_t buffer_size, int duration_s, void *i18n_owner)
	Format a duration as hours and minutes, e.g.
GTextNodeText *	health_util_create_text_node (int buffer_size, GFont font, GColor color, GTextNodeContainer *container)
	Create a text node with its own buffer and add it to a container.
GTextNodeText *	health_util_create_text_node_with_text (const char *text, GFont font, GColor color, GTextNodeContainer *container)
	Create a text node showing a string and add it to a container.
int	health_util_format_hours_minutes_seconds (char *buffer, size_t buffer_size, int duration_s, bool leading_zero, void *i18n_owner)
	Format a duration as hours, minutes and seconds, e.g.
int	health_util_format_minutes_and_seconds (char *buffer, size_t buffer_size, int duration_s, void *i18n_owner)
	Format a duration as minutes and seconds, e.g.
void	health_util_duration_to_hours_and_minutes_text_node (int duration_s, void *i18n_owner, GFont number_font, GFont units_font, GColor color, GTextNodeContainer *container)
	Add text nodes showing a duration as hours and minutes, e.g.
void	health_util_convert_fraction_to_whole_and_decimal_part (int numerator, int denominator, int *whole_part, int *decimal_part)
	Split a fraction into whole and tenths parts, rounded to the nearest tenth.
int	health_util_format_whole_and_decimal (char *buffer, size_t buffer_size, int numerator, int denominator)
	Format a fraction with one decimal, e.g.
int	health_util_get_distance_factor (void)
	Get the number of meters in the user's distance unit.
time_t	health_util_get_pace (int time_s, int distance_meter)
	Compute a pace in the user's distance unit.
const char *	health_util_get_distance_string (const char *miles_string, const char *km_string)
	Pick the units string matching the user's distance unit.
int	health_util_format_distance (char *buffer, size_t buffer_size, uint32_t distance_m)
	Format a distance in the user's distance unit with one decimal, e.g.
void	health_util_convert_distance_to_whole_and_decimal_part (int distance_m, int *whole_part, int *decimal_part)
	Convert a distance to the user's distance unit, as whole and tenths parts.

Detailed Description

Formatting of durations, distances and paces for the health UI.

Distances follow the user's distance units preference (miles or kilometers).

char buf[HEALTH_WHOLE_AND_DECIMAL_LENGTH];
 
health_util_format_distance(buf, sizeof(buf), distance_m); // "4.2"
const char *units = health_util_get_distance_string("mi", "km");

Macro Definition Documentation

HEALTH_WHOLE_AND_DECIMAL_LENGTH

#define HEALTH_WHOLE_AND_DECIMAL_LENGTH   (sizeof("00.0") + 4)

Buffer size for a "00.0" formatted value, with 4 extra bytes for translations.

MAX_TEXT_NODES

#define MAX_TEXT_NODES   5

Maximum number of text nodes needed in a text node container.

Function Documentation

health_util_convert_distance_to_whole_and_decimal_part()

void health_util_convert_distance_to_whole_and_decimal_part	(	int	distance_m,
		int *	whole_part,
		int *	decimal_part
	)

Convert a distance to the user's distance unit, as whole and tenths parts.

Parameters

	distance_m	Distance, in meters.
[out]	whole_part	Whole part.
[out]	decimal_part	Tenths digit.

health_util_convert_fraction_to_whole_and_decimal_part()

void health_util_convert_fraction_to_whole_and_decimal_part	(	int	numerator,
		int	denominator,
		int *	whole_part,
		int *	decimal_part
	)

Split a fraction into whole and tenths parts, rounded to the nearest tenth.

For example, 5/2 gives 2 and 5.

Parameters

	numerator	Numerator.
	denominator	Denominator.
[out]	whole_part	Whole part.
[out]	decimal_part	Tenths digit.

health_util_create_text_node()

GTextNodeText * health_util_create_text_node	(	int	buffer_size,
		GFont	font,
		GColor	color,
		GTextNodeContainer *	container
	)

Create a text node with its own buffer and add it to a container.

Parameters

buffer_size	Size of the text buffer allocated with the node.
font	Font of the node.
color	Color of the node.
container	Container the node is added to, or NULL.

Returns

New text node.

health_util_create_text_node_with_text()

GTextNodeText * health_util_create_text_node_with_text	(	const char *	text,
		GFont	font,
		GColor	color,
		GTextNodeContainer *	container
	)

Create a text node showing a string and add it to a container.

Parameters

text	Text, which must outlive the node.
font	Font of the node.
color	Color of the node.
container	Container the node is added to, or NULL.

Returns

New text node.

health_util_duration_to_hours_and_minutes_text_node()

void health_util_duration_to_hours_and_minutes_text_node	(	int	duration_s,
		void *	i18n_owner,
		GFont	number_font,
		GFont	units_font,
		GColor	color,
		GTextNodeContainer *	container
	)

Add text nodes showing a duration as hours and minutes, e.g.

"12h 59min".

Under an hour only minutes are shown, whole hours only show hours, and 0 is "0h". Units are vertically aligned to the bottom of the numbers.

Parameters

duration_s	Duration, in seconds.
i18n_owner	i18n owner; call i18n_free_all() on it after use.
number_font	Font of the numbers.
units_font	Font of the units.
color	Color of all nodes.
container	Container the nodes are added to.

health_util_format_distance()

int health_util_format_distance	(	char *	buffer,
		size_t	buffer_size,
		uint32_t	distance_m
	)

Format a distance in the user's distance unit with one decimal, e.g.

"42.3".

Parameters

[out]	buffer	Output string.
	buffer_size	Size of buffer.
	distance_m	Distance, in meters.

Returns

snprintf() result.

health_util_format_hours_and_minutes()

int health_util_format_hours_and_minutes	(	char *	buffer,
		size_t	buffer_size,
		int	duration_s,
		void *	i18n_owner
	)

Format a duration as hours and minutes, e.g.

"12H 59M".

Under an hour only minutes are shown ("59M"), whole hours only show hours ("12H"), and 0 is "0H".

Parameters

[out]	buffer	Output string.
	buffer_size	Size of buffer.
	duration_s	Duration, in seconds.
	i18n_owner	i18n owner; call i18n_free_all() on it after use.

Returns

Number of characters written, excluding the terminator, snprintf-style.

health_util_format_hours_minutes_seconds()

int health_util_format_hours_minutes_seconds	(	char *	buffer,
		size_t	buffer_size,
		int	duration_s,
		bool	leading_zero,
		void *	i18n_owner
	)

Format a duration as hours, minutes and seconds, e.g.

"1:15:32".

Hours are omitted under an hour ("5:32").

Parameters

[out]	buffer	Output string.
	buffer_size	Size of buffer.
	duration_s	Duration, in seconds.
	leading_zero	Whether to pad the first field to two digits.
	i18n_owner	i18n owner; call i18n_free_all() on it after use.

Returns

snprintf() result.

health_util_format_minutes_and_seconds()

int health_util_format_minutes_and_seconds	(	char *	buffer,
		size_t	buffer_size,
		int	duration_s,
		void *	i18n_owner
	)

Format a duration as minutes and seconds, e.g.

"5:32".

Parameters

[out]	buffer	Output string.
	buffer_size	Size of buffer.
	duration_s	Duration, in seconds.
	i18n_owner	i18n owner; call i18n_free_all() on it after use.

Returns

snprintf() result.

health_util_format_whole_and_decimal()

int health_util_format_whole_and_decimal	(	char *	buffer,
		size_t	buffer_size,
		int	numerator,
		int	denominator
	)

Format a fraction with one decimal, e.g.

"42.3".

Parameters

[out]	buffer	Output string.
	buffer_size	Size of buffer.
	numerator	Numerator.
	denominator	Denominator.

Returns

snprintf() result.

health_util_get_distance_factor()

int health_util_get_distance_factor

(

void

)

Get the number of meters in the user's distance unit.

Returns

Meters per mile or per kilometer.

health_util_get_distance_string()

const char * health_util_get_distance_string	(	const char *	miles_string,
		const char *	km_string
	)

Pick the units string matching the user's distance unit.

Parameters

miles_string	String for miles.
km_string	String for kilometers.

Returns

One of the strings.

health_util_get_pace()

time_t health_util_get_pace	(	int	time_s,
		int	distance_meter
	)

Compute a pace in the user's distance unit.

Parameters

time_s	Time, in seconds.
distance_meter	Distance, in meters.

Returns

Seconds per mile or kilometer, 0 if distance_meter is 0.