✨ Add benchmark graphs to the documentation images (to be used soon)

benchmarks/CMakeLists.txt

@@ -98,6 +98,7 @@ add_subdirectory(conversion_speed)
 add_custom_target(ztd.text.benchmarks.all_graphs
 	COMMENT "[ztd.text] graphing all benchmarks...")
 add_dependencies(ztd.text.benchmarks.all_graphs
-	ztd.tools.benchmark_grapher.function_form
+	ztd.tools.benchmark_grapher.function_form.large
+	ztd.tools.benchmark_grapher.function_form.small
 	ztd.tools.benchmark_grapher.conversion_speed.small
 	ztd.tools.benchmark_grapher.conversion_speed.large)

benchmarks/conversion_speed/graph_config.in.json

@@ -263,7 +263,7 @@
 		{
 			"name": "noop",
 			"pattern": "noop$",
-			"description": "Measures doing literally nothing (no written expressoins/statements in the benchmarking loop). Can be useful for determining potential environment noise.",
+			"description": "Measures doing literally nothing (no written expressions/statements in the benchmarking loop). Can be useful for determining potential environment noise.",
 			"always_included": true
 		}
 	],

benchmarks/conversion_speed/include/ztd/text/benchmarks/cuneicode_helpers.hpp

@@ -47,7 +47,7 @@ struct conversion_deleter {
 
 struct registry_deleter {
 	void operator()(cnc_conversion_registry* registry) const noexcept {
-		cnc_delete_registry(registry);
+		cnc_registry_delete(registry);
 	}
 };
 

benchmarks/conversion_speed/source/cuneicode_registry.cpp

@@ -56,7 +56,7 @@
 			cnc_conversion_registry* raw_registry = nullptr;                                                        \
 			cnc_conversion* raw_conversion        = nullptr;                                                        \
 			cnc_conversion_info info              = {};                                                             \
-			const cnc_open_error err              = cnc_new_registry(&raw_registry, CNC_REGISTRY_OPTIONS_NONE);     \
+			const cnc_open_error err              = cnc_registry_new(&raw_registry, CNC_REGISTRY_OPTIONS_NONE);     \
 			if (err != CNC_OPEN_ERROR_OK) {                                                                         \
 				/* something went wrong, get out of here quick! */                                                 \
 				state.SkipWithError("conversion succeeded but produced illegitimate data");                        \
@@ -125,7 +125,7 @@
 				cnc_conversion_registry* raw_registry = nullptr;                                                   \
 				cnc_conversion* raw_conversion        = nullptr;                                                   \
 				cnc_conversion_info info              = {};                                                        \
-				const cnc_open_error err = cnc_open_registry(&raw_registry, &mbr_heap, CNC_REGISTRY_OPTIONS_NONE); \
+				const cnc_open_error err = cnc_registry_open(&raw_registry, &mbr_heap, CNC_REGISTRY_OPTIONS_NONE); \
 				if (err != CNC_OPEN_ERROR_OK) {                                                                    \
 					/* something went wrong, get out of here quick! */                                            \
 					result = false;                                                                               \

benchmarks/conversion_speed/source/cuneicode_registry.unchecked.cpp

@@ -55,7 +55,7 @@
 			cnc_conversion_registry* raw_registry = nullptr;                                                        \
 			cnc_conversion* raw_conversion        = nullptr;                                                        \
 			cnc_conversion_info info              = {};                                                             \
-			const cnc_open_error err              = cnc_new_registry(&raw_registry, CNC_REGISTRY_OPTIONS_NONE);     \
+			const cnc_open_error err              = cnc_registry_new(&raw_registry, CNC_REGISTRY_OPTIONS_NONE);     \
 			if (err != CNC_OPEN_ERROR_OK) {                                                                         \
 				/* something went wrong, get out of here quick! */                                                 \
 				state.SkipWithError("conversion succeeded but produced illegitimate data");                        \
@@ -127,7 +127,7 @@
 				cnc_conversion_registry* raw_registry = nullptr;                                                   \
 				cnc_conversion* raw_conversion        = nullptr;                                                   \
 				cnc_conversion_info info              = {};                                                        \
-				const cnc_open_error err = cnc_open_registry(&raw_registry, &mbr_heap, CNC_REGISTRY_OPTIONS_NONE); \
+				const cnc_open_error err = cnc_registry_open(&raw_registry, &mbr_heap, CNC_REGISTRY_OPTIONS_NONE); \
 				if (err != CNC_OPEN_ERROR_OK) {                                                                    \
 					/* something went wrong, get out of here quick! */                                            \
 					result = false;                                                                               \

benchmarks/function_form/CMakeLists.txt

@@ -28,49 +28,62 @@
 # =========================================================================== #
 
 # # Benchmarks
-file(GLOB_RECURSE ztd.text.benchmarks.function_form.sources
-	LIST_DIRECTORIES FALSE
-	CONFIGURE_DEPENDS
-	source/*.c source/*.cpp)
+function (generate_function_form_benchmark_targets name data_name title)
+	file(GLOB_RECURSE sources
+		LIST_DIRECTORIES FALSE
+		CONFIGURE_DEPENDS
+		source/*.c source/*.cpp)
 
-add_executable(ztd.text.benchmarks.function_form ${ztd.text.benchmarks.function_form.sources})
-target_compile_options(ztd.text.benchmarks.function_form
-	PRIVATE
-	${--utf8-literal-encoding}
-	${--utf8-source-encoding}
-	${--disable-permissive}
-	${--updated-cpp-version-flag}
-	${--warn-pedantic}
-	${--warn-all}
-	${--warn-extra}
-	${--allow-alignas-extra-padding}
-	# MSVC is BROKEN
-	# ${--warn-errors}
-)
-target_compile_definitions(ztd.text.benchmarks.function_form
-	PRIVATE
-	CATCH_CONFIG_ENABLE_BENCHMARKING=1
-)
-target_link_libraries(ztd.text.benchmarks.function_form
-	PRIVATE
-	ztd::cuneicode::benchmarks::barrier
-	ztd::cuneicode
-	benchmark::benchmark
-	${CMAKE_DL_LIBS}
-)
-target_include_directories(ztd.text.benchmarks.function_form
-	PRIVATE
-	include
-	../include
-)
-#generate_config_and_manifest_for(ztd.text.benchmarks.function_form)
-ztd_tools_add_benchmark_grapher(
-	NAME
-		function_form
-	CONFIG
-		"${CMAKE_CURRENT_SOURCE_DIR}/graph_config.json"
-	TARGETS
-		ztd.text.benchmarks.function_form
-	REPETITIONS
-		${ZTD_TEXT_BENCHMARKS_REPETITIONS}
-)
+	add_executable(ztd.text.benchmarks.function_form.${name} ${sources})
+	target_compile_options(ztd.text.benchmarks.function_form.${name}
+		PRIVATE
+		${--utf8-literal-encoding}
+		${--utf8-source-encoding}
+		${--disable-permissive}
+		${--updated-cpp-version-flag}
+		${--warn-pedantic}
+		${--warn-all}
+		${--warn-extra}
+		${--allow-alignas-extra-padding}
+		# MSVC is BROKEN
+		# ${--warn-errors}
+	)
+	target_compile_definitions(ztd.text.benchmarks.function_form.${name}
+		PRIVATE
+		CATCH_CONFIG_ENABLE_BENCHMARKING=1
+		u8_data=u8_${data_name}_data
+		u16_data=u16_${data_name}_data
+		u32_data=u32_${data_name}_data
+	)
+	target_link_libraries(ztd.text.benchmarks.function_form.${name}
+		PRIVATE
+		ztd::cuneicode::benchmarks::barrier
+		ztd::cuneicode
+		benchmark::benchmark
+		${CMAKE_DL_LIBS}
+	)
+	target_include_directories(ztd.text.benchmarks.function_form.${name}
+		PRIVATE
+		include
+		../include
+	)
+	generate_target_manifest(ztd.text.benchmarks.function_form.${name})
+	set(ZTD_TEXT_BENCHMARKS_CONVERSION_SPEED_TITLE ${title})
+	configure_file(${CMAKE_CURRENT_SOURCE_DIR}/graph_config.in.json
+		${CMAKE_CURRENT_BINARY_DIR}/graph_config.${name}.json
+		@ONLY
+	)
+	ztd_tools_add_benchmark_grapher(
+		NAME
+			function_form.${name}
+		CONFIG
+			"${CMAKE_CURRENT_BINARY_DIR}/graph_config.${name}.json"
+		TARGETS
+			ztd.text.benchmarks.function_form.${name}
+		REPETITIONS
+			${ZTD_TEXT_BENCHMARKS_REPETITIONS}
+	)
+endfunction()
+
+generate_function_form_benchmark_targets(large unicode "All Unicode Scalar Values (~4.4 MB)")
+generate_function_form_benchmark_targets(small basic_source "C Character Set (97 Bytes)")

benchmarks/function_form/graph_config.json → benchmarks/function_form/graph_config.in.json

@@ -1,5 +1,5 @@
 {
-	"name": "Function Forms",
+	"name": "@ZTD_TEXT_BENCHMARKS_FUNCTION_FORM_TITLE@",
 	"scale": {
 		"type": "relative",
 		"to": "base"
@@ -42,6 +42,11 @@
 			"name": "{ err, ptr, ptr }(T*, size_t, T*, size_t)",
 			"pattern": "structptr_ptr_size_ptr_size",
 			"description": "An indivisible unit conversion returning a structure which contains the error code with a pointer/pointer pair representing input and output, and the function input takes a two pointer/size pairs representing the input and output spans."
+		},
+		{
+			"name": "memcpy",
+			"pattern": "memcpy_",
+			"description": "Copying the data directly to the output."
 		}
 	],
 	"data_labels": [

benchmarks/function_form/source/bench.cpp

@@ -39,10 +39,30 @@
 
 #include <array>
 
-static const ztd_char32_t* expected_input     = c_span_char32_t_data(u32_unicode_data);
-static const std::size_t expected_input_size  = c_span_char32_t_size(u32_unicode_data);
-static const ztd_char8_t* expected_output     = c_span_char8_t_data(u8_unicode_data);
-static const std::size_t expected_output_size = c_span_char8_t_size(u8_unicode_data);
+static const ztd_char32_t* expected_input     = c_span_char32_t_data(u32_data);
+static const std::size_t expected_input_size  = c_span_char32_t_size(u32_data);
+static const ztd_char8_t* expected_output     = c_span_char8_t_data(u8_data);
+static const std::size_t expected_output_size = c_span_char8_t_size(u8_data);
+
+static void noop(benchmark::State& state) {
+	for (auto _ : state) { }
+}
+
+static void memcpy_(benchmark::State& state) {
+	using to_char_t = ztd_char8_t;
+	std::vector<to_char_t> output_data(expected_output, expected_output + expected_output_size);
+	for (auto _ : state) {
+		std::memcpy(output_data.data(), expected_output, expected_output_size * sizeof(ztd_char8_t));
+		state.PauseTiming();
+		const bool is_equal = std::equal(output_data.data(), output_data.data() + expected_output_size,
+		     expected_output, expected_output + expected_output_size);
+		if (!is_equal) {
+			state.SkipWithError("Data did not encode correctly.");
+			return;
+		}
+		state.ResumeTiming();
+	}
+}
 
 static void err_ptrptr_ptrsize_ptrptr_ptrsize(benchmark::State& state) {
 	std::vector<ztd_char8_t> output_buffer;
@@ -253,6 +273,8 @@ static void structptr_ptr_size_ptr_size(benchmark::State& state) {
 	}
 }
 
+BENCHMARK(noop);
+BENCHMARK(memcpy_);
 BENCHMARK(err_ptrptr_ptrsize_ptrptr_ptrsize);
 BENCHMARK(err_ptrptr_ptr_ptrptr_ptr);
 BENCHMARK(structsize_ptr_ptr_ptr_ptr);

documentation/source/img/benchmark_results/conversion_speed.large/All Unicode Scalar Values (~4.4 MB) - UTF-16 to UTF-32 (Well-Formed).png.txt

@@ -0,0 +1,46 @@
+Title: "All Unicode Scalar Values (~4.4 MB) - UTF-16 to UTF-32 (Well-Formed)". Description: "A conversion from UTF-16 data to UTF-32 data that contains no ill-formed or incomplete sequences."
+
+There are 21 groups, and 2 data labels (cpu time, real time) per each group with data. Lower is better. 
+
+- boost_text_view is 21st. Described as: "Measures the boost.text library from Zach laine and its encoding routines, partocularly the one-at-a-time views that can be fed into C and C++ algorithms using the view's iterator abstraction.".
+  This group had an error: "conversion succeeded but produced illegitimate data".
+- standard_c is 20th. It has no description.
+  Measures to a mean of "2.483957267848642" milliseconds, from 100 multi-iteration samples.
+- iconv is 19th. Described as: "Measures the libiconv (GNU version) encoding library, using its POSIX-compliant function call "iconv".".
+  Measures to a mean of "0.6440057616075917" milliseconds, from 100 multi-iteration samples.
+- icu_ucnv_convertEx is 18th. Described as: "Measures the ICU library and its conversion routines when routed through 2 generic "UConverter" converter objects.".
+  Measures to a mean of "0.42278876983269265" milliseconds, from 100 multi-iteration samples.
+- cuneicode is 17th. Described as: "Measures the ztd.cuneicode library from Shepherd's Oasis and its encoding routines, particularly the typed, non-generic C-style encoding routines.".
+  Measures to a mean of "0.4039479553095955" milliseconds, from 100 multi-iteration samples.
+- cuneicode_single is 16th. Described as: "Measures the ztd.cuneicode library from Shepherd's Oasis and its encoding routines, particularly the typed, non-generic C-style encoding routines that use the "indivisable unit fo conversion" functions.".
+  Measures to a mean of "0.3977170692719051" milliseconds, from 100 multi-iteration samples.
+- cuneicode_single_unbounded is 15th. Described as: "Measures the ztd.cuneicode library from Shepherd's Oasis and its encoding routines, particularly the typed, non-generic C-style encoding routines "indivisable unit fo conversion" functions (without providing an output size).".
+  Measures to a mean of "0.3907233217917123" milliseconds, from 100 multi-iteration samples.
+- cuneicode_unbounded is 14th. Described as: "Measures the ztd.cuneicode library from Shepherd's Oasis and its encoding routines, particularly the typed, non-generic C-style encoding routines (without providing an output size).".
+  Measures to a mean of "0.3763996061540615" milliseconds, from 100 multi-iteration samples.
+- standard_cpp is 13th. It has no description.
+  Measures to a mean of "0.28968202992241876" milliseconds, from 100 multi-iteration samples.
+- icu_ucnv_fromUChars is 12th. Described as: "Measures the ICU library conversion routine using the specific ucnv_fromUChars function.".
+  Measures to a mean of "0.22927457875011897" milliseconds, from 100 multi-iteration samples.
+- ztd_text_view is 11th. Described as: "Measures the ztd.text library conversion routine using the ztd::text::transcode_view range abstraction.".
+  Measures to a mean of "0.19970514202875128" milliseconds, from 100 multi-iteration samples.
+- ztd_text_single_unbounded is 10th. Described as: "Measures the ztd.text library conversion routine using the ztd::text::transcode_one function in a loop, with output bounds checking turned off.".
+  Measures to a mean of "0.1915290611586871" milliseconds, from 100 multi-iteration samples.
+- cuneicode_registry is 9th. Described as: "Measures the ztd.cuneicode library from Shepherd's Oasis and its encoding routines, particularly the non-typed conversion routines from its Conversion Registry abstraction with all defaults left alone.".
+  Measures to a mean of "0.17855931228313926" milliseconds, from 100 multi-iteration samples.
+- ztd_text is 8th. Described as: "Measures the ztd.text library conversion routine using the ztd::text::transcode function.".
+  Measures to a mean of "0.1757933705103841" milliseconds, from 100 multi-iteration samples.
+- ztd_text_single is 7th. Described as: "Measures the ztd.text library conversion routine using the ztd::text::transcode_one function.".
+  Measures to a mean of "0.17453995184241783" milliseconds, from 100 multi-iteration samples.
+- cuneicode_registry_unbounded is 6th. Described as: "Measures the ztd.cuneicode library from Shepherd's Oasis and its encoding routines, particularly the non-typed conversion routines from its Conversion Registry abstraction with specific conversion pathways overridden (without providing an output size).".
+  Measures to a mean of "0.16379694840230086" milliseconds, from 100 multi-iteration samples.
+- simdutf is 5th. Described as: "Measures the performance of Daniel Lemire's simdutf library, which is meant to be highly optimized and performant under all unicode workloads.".
+  Measures to a mean of "0.16083383683118363" milliseconds, from 100 multi-iteration samples.
+- ztd_text_unbounded is 4th. Described as: "Measures the ztd.text library conversion routine using the ztd::text::transcode function, with output bounds checking turned off.".
+  Measures to a mean of "0.16038049598356305" milliseconds, from 100 multi-iteration samples.
+- boost_text is 3rd. Described as: "Measures the boost.text library from Zach Laine and its encoding routines, particularly the all-at-once bulk routines.".
+  Measures to a mean of "0.1511390267814686" milliseconds, from 100 multi-iteration samples.
+- memcpy is 2nd. It has no description.
+  Measures to a mean of "0.01760095004014773" milliseconds, from 100 multi-iteration samples.
+- noop is 1st. Described as: "Measures doing literally nothing (no written expressions/statements in the benchmarking loop). Can be useful for determining potential environment noise.".
+  Measures to a mean of "2.2099819034337998e-14" milliseconds, from 100 multi-iteration samples.

documentation/source/img/benchmark_results/conversion_speed.large/All Unicode Scalar Values (~4.4 MB) - UTF-16 to UTF-32 (Well-Formed, Assumed Valid).png.txt

@@ -0,0 +1,24 @@
+Title: "All Unicode Scalar Values (~4.4 MB) - UTF-16 to UTF-32 (Well-Formed, Assumed Valid)". Description: "A conversion from UTF-16 data to UTF-32 data that contains no ill-formed or incomplete sequences."
+
+There are 10 groups, and 2 data labels (cpu time, real time) per each group with data. Lower is better. 
+
+- cuneicode_registry is 10th. Described as: "Measures the ztd.cuneicode library from Shepherd's Oasis and its encoding routines, particularly the non-typed conversion routines from its Conversion Registry abstraction with all defaults left alone.".
+  Measures to a mean of "0.16495657591972984" milliseconds, from 100 multi-iteration samples.
+- ztd_text is 9th. Described as: "Measures the ztd.text library conversion routine using the ztd::text::transcode function.".
+  Measures to a mean of "0.16473405970676966" milliseconds, from 100 multi-iteration samples.
+- cuneicode_registry_unbounded is 8th. Described as: "Measures the ztd.cuneicode library from Shepherd's Oasis and its encoding routines, particularly the non-typed conversion routines from its Conversion Registry abstraction with specific conversion pathways overridden (without providing an output size).".
+  Measures to a mean of "0.1586602921883501" milliseconds, from 100 multi-iteration samples.
+- simdutf is 7th. Described as: "Measures the performance of Daniel Lemire's simdutf library, which is meant to be highly optimized and performant under all unicode workloads.".
+  Measures to a mean of "0.15744718844992056" milliseconds, from 100 multi-iteration samples.
+- ztd_text_unbounded is 6th. Described as: "Measures the ztd.text library conversion routine using the ztd::text::transcode function, with output bounds checking turned off.".
+  Measures to a mean of "0.15675595552741758" milliseconds, from 100 multi-iteration samples.
+- ztd_text_view is 5th. Described as: "Measures the ztd.text library conversion routine using the ztd::text::transcode_view range abstraction.".
+  Measures to a mean of "0.1191431593753805" milliseconds, from 100 multi-iteration samples.
+- ztd_text_single_unbounded is 4th. Described as: "Measures the ztd.text library conversion routine using the ztd::text::transcode_one function in a loop, with output bounds checking turned off.".
+  Measures to a mean of "0.10320533234371397" milliseconds, from 100 multi-iteration samples.
+- ztd_text_single is 3rd. Described as: "Measures the ztd.text library conversion routine using the ztd::text::transcode_one function.".
+  Measures to a mean of "0.10253416468749493" milliseconds, from 100 multi-iteration samples.
+- memcpy is 2nd. It has no description.
+  Measures to a mean of "0.017595095777065077" milliseconds, from 100 multi-iteration samples.
+- noop is 1st. Described as: "Measures doing literally nothing (no written expressions/statements in the benchmarking loop). Can be useful for determining potential environment noise.".
+  Measures to a mean of "2.2099819034337998e-14" milliseconds, from 100 multi-iteration samples.