packaging and sorted-lookup changes

Author: zekageri

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to this project will be documented in this file.
 
+## [Unreleased]
+### Added
+- Optional per-table sorted-key lookup via `LangLookupMode` and `makeSortedLangTable(...)`.
+- Reusable root CMake target `esp_lang` with alias target `ESPLang::esp_lang`.
+
+### Changed
+- Standalone CMake now consistently requires C++17 and builds tests against the root library target.
+- README now documents the `format(...)` format-string contract and standalone CMake consumption.
+
 ## [0.1.0] - 2026-04-09
 ### Added
 - Initial ESPLang release.

CMakeLists.txt

@@ -5,14 +5,28 @@
 cmake_minimum_required(VERSION 3.12)
 project(ESPLang)
 
-enable_testing()
+include(CTest)
 
-set(CMAKE_CXX_STANDARD 11)
+set(CMAKE_CXX_STANDARD 17)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 
 if(${COVERAGE})
 	set(CMAKE_CXX_FLAGS "-fprofile-arcs -ftest-coverage -g -O0")
 endif()
 
-include_directories(${CMAKE_CURRENT_LIST_DIR}/src)
-add_subdirectory(test)
+add_library(esp_lang STATIC
+	src/esp_lang/lang.cpp
+)
+
+add_library(ESPLang::esp_lang ALIAS esp_lang)
+
+target_include_directories(esp_lang
+	PUBLIC
+		${CMAKE_CURRENT_LIST_DIR}/src
+)
+
+target_compile_features(esp_lang PUBLIC cxx_std_17)
+
+if(BUILD_TESTING)
+	add_subdirectory(test)
+endif()

README.md

@@ -10,7 +10,7 @@ ESPLang is a small translation table helper for ESP32 firmware. The library owns
 ## Features
 - No hardcoded languages or translation keys in the library API.
 - Pointer-only registration of user-owned translation tables.
-- Linear, key-based lookup with no order-sensitive table requirements.
+- Linear lookup by default, with optional sorted-key tables for binary-search key lookup.
 - Fallback-language lookup for missing translations.
 - No heap allocation required by the library.
 - Caller-buffer formatting through `format(...)`.
@@ -91,13 +91,15 @@ void setup() {
 Public types:
 - `using LangLanguageId = uint16_t`
 - `using LangKeyId = uint16_t`
+- `enum class LangLookupMode : uint8_t { Linear, SortedByKey }` selects per-table key lookup strategy.
 - `LangTranslationEntry { key, text }` maps one user-defined key to one translation string.
-- `LangTranslationTable { language, entries, entryCount }` groups one language with its translation entries.
+- `LangTranslationTable { language, entries, entryCount, lookupMode }` groups one language with its translation entries and lookup mode.
 - `ESPLangConfig { tables, tableCount, defaultLanguage, useDefaultFallback, fallbackLanguage, missingText }` configures the pointer-owned table set, startup language, fallback behavior, and missing-text string.
 
 Helpers:
 - `ESP_LANG_ENTRY(key, text)` creates a `LangTranslationEntry` from an enum key.
-- `makeLangTable(language, entries)` builds a `LangTranslationTable` with the correct entry count.
+- `makeLangTable(language, entries)` builds a linear `LangTranslationTable` with the correct entry count.
+- `makeSortedLangTable(language, entries)` builds a sorted-key `LangTranslationTable` that uses binary search for key lookup.
 
 Main API:
 - `bool init(const ESPLangConfig& config)` / `void deinit()` / `bool isInitialized() const`
@@ -113,23 +115,44 @@ Main API:
 
 Validation and lookup behavior:
 - `init(...)` returns `false` for null tables, zero table count, missing default language, missing explicit fallback language, invalid table storage, duplicate language tables, duplicate keys within the same language, or null text pointers.
+- `makeSortedLangTable(...)` requires entries to already be sorted by ascending key; `init(...)` rejects unsorted or duplicate keys in sorted tables.
 - `translate(key)` checks the selected language first, then the fallback language if it differs, then returns the configured missing text.
 - `translateFrom(language, key)` only searches the requested language.
 - `missingText` defaults to `"?"` when omitted or reset with `setMissingText(nullptr)`.
+- Language-table resolution remains linear even when individual tables use sorted-key lookup.
 
 ## Gotchas
 - `translateFrom(...)` does not use fallback lookup.
+- `format(...)` treats the resolved translation text as a `vsnprintf` format string. Placeholder mistakes in translation data, or mismatched argument types at the call site, become runtime formatting bugs.
 - `format(...)` returns `false` when the formatted output does not fully fit, even though the buffer may still contain truncated output.
 - `useDefaultFallback = true` resolves the effective fallback language to `defaultLanguage`.
 - Duplicate keys are only invalid within the same language table; reusing the same key across different languages is expected.
+- Sorted-key lookup is opt-in per table. The library never sorts caller data for you.
 
 ## Restrictions
 - Packaged as an ESP32 / Arduino-targeted library for ESPToolKit.
 - C++17 is required.
 - Translation tables and strings are caller-owned and must remain valid for the lifetime of the `ESPLang` instance.
 
+## Standalone CMake
+```cmake
+include(FetchContent)
+
+FetchContent_Declare(
+  esp_lang
+  GIT_REPOSITORY https://github.com/ESPToolKit/esp-lang.git
+  GIT_TAG main
+)
+
+FetchContent_MakeAvailable(esp_lang)
+
+target_link_libraries(your_target PRIVATE ESPLang::esp_lang)
+```
+
+If the source is vendored locally, `add_subdirectory(path/to/esp-lang)` exposes the same `ESPLang::esp_lang` target.
+
 ## Tests
-- Host-side tests in `test/test_esplang` cover config validation, lifecycle, lookup rules, fallback behavior, missing-text handling, and formatting behavior.
+- Host-side tests in `test/test_esplang` cover config validation, lifecycle, linear and sorted lookup rules, mixed fallback behavior, missing-text handling, and formatting behavior.
 - CI also builds the Arduino examples through both PlatformIO and Arduino CLI on the standard ESP32 board matrix.
 
 ## Formatting Baseline

src/esp_lang/lang.cpp

@@ -16,6 +16,20 @@ struct ResolvedConfig {
 	const char *missingText = kDefaultMissingText;
 };
 
+bool hasStrictlyAscendingKeys(const LangTranslationTable &table) {
+	if (table.entryCount < 2) {
+		return true;
+	}
+
+	for (size_t entryIndex = 1; entryIndex < table.entryCount; ++entryIndex) {
+		if (table.entries[entryIndex - 1].key >= table.entries[entryIndex].key) {
+			return false;
+		}
+	}
+
+	return true;
+}
+
 bool isConfigShapeValid(const ESPLangConfig &config) {
 	if (config.tables == nullptr || config.tableCount == 0) {
 		return false;
@@ -39,12 +53,20 @@ bool isConfigShapeValid(const ESPLangConfig &config) {
 				return false;
 			}
 
+			if (table.lookupMode == LangLookupMode::SortedByKey) {
+				continue;
+			}
+
 			for (size_t otherIndex = entryIndex + 1; otherIndex < table.entryCount; ++otherIndex) {
 				if (table.entries[otherIndex].key == entry.key) {
 					return false;
 				}
 			}
 		}
+
+		if (table.lookupMode == LangLookupMode::SortedByKey && !hasStrictlyAscendingKeys(table)) {
+			return false;
+		}
 	}
 
 	return true;
@@ -226,6 +248,26 @@ const char *ESPLang::findInTable(const LangTranslationTable *table, LangKeyId ke
 		return nullptr;
 	}
 
+	if (table->lookupMode == LangLookupMode::SortedByKey) {
+		size_t left = 0;
+		size_t right = table->entryCount;
+		while (left < right) {
+			const size_t middle = left + ((right - left) / 2);
+			const LangTranslationEntry &entry = table->entries[middle];
+			if (entry.key == key) {
+				return entry.text;
+			}
+
+			if (entry.key < key) {
+				left = middle + 1;
+			} else {
+				right = middle;
+			}
+		}
+
+		return nullptr;
+	}
+
 	for (size_t index = 0; index < table->entryCount; ++index) {
 		if (table->entries[index].key == key) {
 			return table->entries[index].text;

src/esp_lang/lang.h

@@ -8,6 +8,11 @@
 using LangLanguageId = uint16_t;
 using LangKeyId = uint16_t;
 
+enum class LangLookupMode : uint8_t {
+	Linear = 0,
+	SortedByKey = 1,
+};
+
 struct LangTranslationEntry {
 	LangKeyId key = 0;
 	const char *text = nullptr;
@@ -17,6 +22,7 @@ struct LangTranslationTable {
 	LangLanguageId language = 0;
 	const LangTranslationEntry *entries = nullptr;
 	size_t entryCount = 0;
+	LangLookupMode lookupMode = LangLookupMode::Linear;
 };
 
 struct ESPLangConfig {
@@ -35,7 +41,13 @@ struct ESPLangConfig {
 template <size_t N>
 constexpr LangTranslationTable
 makeLangTable(LangLanguageId language, const LangTranslationEntry (&entries)[N]) {
-	return LangTranslationTable{language, entries, N};
+	return LangTranslationTable{language, entries, N, LangLookupMode::Linear};
+}
+
+template <size_t N>
+constexpr LangTranslationTable
+makeSortedLangTable(LangLanguageId language, const LangTranslationEntry (&entries)[N]) {
+	return LangTranslationTable{language, entries, N, LangLookupMode::SortedByKey};
 }
 
 class ESPLang {

test/CMakeLists.txt

@@ -1,21 +1,10 @@
-add_library(esp_lang_core STATIC
-    ${PROJECT_SOURCE_DIR}/src/esp_lang/lang.cpp
-)
-
-target_include_directories(esp_lang_core
-    PUBLIC
-        ${PROJECT_SOURCE_DIR}/src
-)
-
-target_compile_features(esp_lang_core PUBLIC cxx_std_17)
-
 add_executable(esp_lang_tests
     test_esplang/test_esplang.cpp
 )
 
 target_link_libraries(esp_lang_tests
     PRIVATE
-        esp_lang_core
+        ESPLang::esp_lang
 )
 
 target_compile_features(esp_lang_tests PRIVATE cxx_std_17)