### Example: Get Entry by Path Source: https://github.com/openzim/libzim/blob/main/_autodocs/archive.md Demonstrates how to retrieve an entry from the archive using its file path. ```cpp auto entry = archive.getEntryByPath("index.html"); ``` -------------------------------- ### Simple ZIM Creation Example Source: https://github.com/openzim/libzim/blob/main/_autodocs/creator.md Demonstrates the basic steps for creating a ZIM file using the Creator class. This includes configuring verbose output, compression, starting creation, adding metadata, adding content via StringItem, and finishing creation. ```cpp #include #include int main() { zim::writer::Creator creator; creator.configVerbose(true); creator.configCompression(zim::Compression::Zstd); creator.startZimCreation("example.zim"); // Add metadata creator.addMetadata("Title", "My Archive"); creator.addMetadata("Creator", "Me"); // Add content auto item = zim::writer::StringItem::create( "index.html", "text/html;charset=utf-8", "Home Page", zim::writer::Hints(), "

Welcome

" ); creator.addItem(item); creator.setMainPath("index.html"); creator.finishZimCreation(); return 0; } ``` -------------------------------- ### Install Libzim Source: https://github.com/openzim/libzim/blob/main/README.md Install the compiled Libzim libraries and headers to the system. This command may require root privileges. ```bash ninja -C build install ``` -------------------------------- ### Manually install Ninja Source: https://github.com/openzim/libzim/blob/main/README.md Steps to manually build and install Ninja from its source code repository. This is an alternative if Ninja is not readily available. ```bash git clone git://github.com/ninja-build/ninja.git cd ninja git checkout release ./configure.py --bootstrap mkdir ../bin cp ninja ../bin cd .. ``` -------------------------------- ### Manually install Meson using virtualenv Source: https://github.com/openzim/libzim/blob/main/README.md Steps to manually install Meson within a Python virtual environment. This is useful if Meson is not available through system package managers. ```bash virtualenv -p python3 ./ # Create virtualenv source bin/activate # Activate the virtualenv pip3 install meson # Install Meson hash -r # Refresh bash paths ``` -------------------------------- ### Get Final Item from Entry (libzim7) Source: https://github.com/openzim/libzim/blob/main/docs/6to7.md This example shows how to resolve a redirection chain and get the final item associated with an entry in libzim7. ```c++ auto entry = [...]; // Resolve any redirection chain and return the final item. auto item = entry.getItem(true); auto blob = item.getData() ``` -------------------------------- ### FileItem Constructor Example Source: https://github.com/openzim/libzim/blob/main/_autodocs/creator.md Demonstrates how to create and add a FileItem to a creator instance. Ensure the necessary headers and item types are included. ```cpp auto item = std::make_shared( "image.png", "image/png", "Image", zim::writer::Hints(), "/path/to/image.png" ); creator.addItem(item); ``` -------------------------------- ### Start ZIM Creation Source: https://github.com/openzim/libzim/blob/main/_autodocs/creator.md Initializes the ZIM file creation process at the specified filepath. This method must be called after all configurations and before adding any items. ```cpp creator.startZimCreation("output.zim"); ``` -------------------------------- ### Full Configuration Example for Zim Creation Source: https://github.com/openzim/libzim/blob/main/_autodocs/configuration.md Demonstrates a comprehensive configuration for creating a ZIM archive, including verbose output, Zstd compression, cluster size, English full-text indexing, and worker thread settings. ```cpp zim::writer::Creator creator; creator.configVerbose(true) .configCompression(zim::Compression::Zstd) .configClusterSize(1024 * 1024) // 1MB clusters .configIndexing(true, "en") // English fulltext .configNbWorkers(4); // 4 worker threads creator.startZimCreation("output.zim"); // ... add items ... creator.finishZimCreation(); ``` -------------------------------- ### Search Result Pagination Example Source: https://github.com/openzim/libzim/blob/main/_autodocs/search-suggest.md Demonstrates how to paginate through search results by calculating the total number of pages and fetching results page by page. ```cpp zim::Query query("computer"); auto search = searcher.search(query); int per_page = 20; int estimated = search.getEstimatedMatches(); int total_pages = (estimated + per_page - 1) / per_page; for (int page = 0; page < total_pages; page++) { int offset = page * per_page; auto results = search.getResults(offset, per_page); std::cout << "Page " << (page + 1) << std::endl; for (auto& it : results) { std::cout << it->getTitle() << std::endl; } } ``` -------------------------------- ### Create a zim file using libzim6 Source: https://github.com/openzim/libzim/blob/main/docs/6to7.md Example of creating a zim file in libzim6 by instantiating a custom creator, adding content and redirect articles, and finishing the creation process. ```c++ int main() { MyCreator creator(); creator.startZimCreation("out_file.zim"); std::shared_ptr article = std::make_shared("A article", "A/article", "text/html", "A content"); creator.addArticle(article); std::shared_ptr redirect = std::make_shared("A redirect", "A/redirect", "A/article"); creator.addArticle(redirect); creator.finishZimCreation(); } ``` -------------------------------- ### Suggestions for Auto-Complete Example Source: https://github.com/openzim/libzim/blob/main/_autodocs/search-suggest.md Uses SuggestionSearcher to find auto-complete suggestions based on a given prefix and prints the top 10 results. ```cpp zim::SuggestionSearcher suggester(archive); std::string prefix = "phy"; auto suggestions = suggester.suggest(prefix); std::cout << "Suggestions for '" << prefix << "':" << std::endl; auto results = suggestions.getResults(0, 10); for (auto& it : results) { std::cout << " " << it->getTitle() << std::endl; } ``` -------------------------------- ### Get Item Data Source: https://github.com/openzim/libzim/blob/main/_autodocs/entry-item.md Retrieves the content data as a Blob, starting from a specified byte offset. If no offset is provided, it starts from the beginning. ```cpp Blob getData(offset_type offset=0) const; ``` ```cpp auto item = entry.getItem(); auto full_data = item.getData(); auto partial = item.getData(100); // Skip first 100 bytes ``` -------------------------------- ### libzim 6 Searching Example Source: https://github.com/openzim/libzim/blob/main/docs/6to7.md Demonstrates how to perform a search in libzim 6 using the `zim::Search` class. This involves creating a file object, initializing a search, setting a query and range, and iterating through results. ```c++ auto f = zim::File("foo.zim"); auto search = zim::Search(&f); search.set_query("bar"); search.set_range(10, 30); for (auto it =search.begin(); it!=search.end(); it++) { std::cout << "Found result " << it.get_url() << std::endl; } ``` -------------------------------- ### Deprecated Method Usage Source: https://github.com/openzim/libzim/blob/main/_autodocs/utilities.md Example of how to use the DEPRECATED macro to mark a method as obsolete. ```cpp // Deprecated method DEPRECATED std::set Archive::getIllustrationSizes() const; ``` -------------------------------- ### Get Item Directly with Redirection Handling Source: https://github.com/openzim/libzim/blob/main/docs/usage.md Retrieves an entry by its path and then directly gets its associated item, automatically handling any redirections. It then prints the path of the item and its data. ```c++ auto entry = archive.getEntryByPath("foo"); auto item = entry.getItem(true); if (entry.isRedirect()) { std::cout << "Entry " << entry.getPath() << " is a entry pointing to the item " << item.getPath() << std::endl; } else { std::cout << entry.getPath() << " should be equal to " << item.getPath() << std::endl; } std::cout << "The item data is " << item.getData() << std::endl; ``` -------------------------------- ### Get Entry by Title String Source: https://github.com/openzim/libzim/blob/main/_autodocs/archive.md Retrieves an Entry object by its string title. Throws EntryNotFound if the title does not exist. ```cpp Entry getEntryByTitle(const std::string& title) const; ``` -------------------------------- ### Get All Illustration Information Source: https://github.com/openzim/libzim/blob/main/_autodocs/archive.md Retrieves a collection of all available illustration information objects. ```cpp IllustrationInfos getIllustrationInfos() const; ``` -------------------------------- ### Basic Full-Text Search Example Source: https://github.com/openzim/libzim/blob/main/_autodocs/search-suggest.md Performs a basic full-text search for a query, retrieves estimated matches, and iterates through the first 10 results, printing their paths and snippets. ```cpp #include #include int main() { try { zim::Archive archive("indexed.zim"); zim::Searcher searcher(archive); zim::Query query("physics"); auto search = searcher.search(query); std::cout << "Found ~" << search.getEstimatedMatches() << " results" << std::endl; auto results = search.getResults(0, 10); for (auto it = results.begin(); it != results.end(); ++it) { std::cout << it->getPath() << " (score: " << it->getScore() << ")" << std::endl; std::cout << " " << it->getSnippet() << std::endl; } } catch (const std::exception& e) { std::cerr << "Error: " << e.what() << std::endl; } return 0; } ``` -------------------------------- ### Example: Validate ZIM Archive Integrity Source: https://github.com/openzim/libzim/blob/main/_autodocs/archive.md Demonstrates how to set up and run specific integrity checks (CHECKSUM, DIRENT_ORDER) on a ZIM file and handle potential failures. ```cpp zim::IntegrityCheckList checks; checks[zim::IntegrityCheck::CHECKSUM] = 1; checks[zim::IntegrityCheck::DIRENT_ORDER] = 1; if (!zim::validate("file.zim", checks)) { std::cerr << "Integrity checks failed" << std::endl; } ``` -------------------------------- ### Get All Metadata Keys Source: https://github.com/openzim/libzim/blob/main/_autodocs/archive.md Retrieves a vector of strings containing the names of all available metadata entries. ```cpp std::vector getMetadataKeys() const; ``` -------------------------------- ### Get Main Entry Source: https://github.com/openzim/libzim/blob/main/_autodocs/archive.md Retrieves the main or home page entry of the archive. Throws `EntryNotFound` if no main entry is specified. ```cpp Entry getMainEntry() const; ``` -------------------------------- ### Multi-Archive Search Example Source: https://github.com/openzim/libzim/blob/main/_autodocs/search-suggest.md Demonstrates searching across multiple ZIM archives simultaneously and identifying the source archive for each result. ```cpp std::vector archives = { zim::Archive("wiki.zim"), zim::Archive("books.zim") }; zim::Searcher multi_searcher(archives); zim::Query query("evolution"); auto search = multi_searcher.search(query); auto results = search.getResults(0, 20); for (auto it = results.begin(); it != results.end(); ++it) { int file_idx = it->getFileIndex(); std::cout << "[Archive " << file_idx << "] " << it->getPath() << std::endl; } ``` -------------------------------- ### Configure Full-Text Indexing Source: https://github.com/openzim/libzim/blob/main/_autodocs/configuration.md Enables Xapian full-text search index creation for an archive. Requires libzim compiled with Xapian support and the Xapian library installed. Specify the language for text analysis. ```cpp creator.configIndexing(true, "en"); // Enable English indexing ``` -------------------------------- ### Get Item from Entry Source: https://github.com/openzim/libzim/blob/main/_autodocs/entry-item.md Retrieves the content item associated with an entry. Set `follow` to true to automatically resolve redirects. ```cpp Item getItem(bool follow=false) const; ``` ```cpp // Safe access for any entry auto item = entry.getItem(true); // Auto-follows redirects // Check first if (!entry.isRedirect()) { auto item = entry.getItem(false); } ``` -------------------------------- ### Get Article by URL (libzim6) Source: https://github.com/openzim/libzim/blob/main/docs/6to7.md In libzim6, accessing an article required a File instance and manual checking for article validity. ```c++ auto f = zim::File("foo.zim"); auto a = f.getArticleByUrl("A/index.html"); if (!a.good()) { std::cerr << "No article A/index.html" << std::endl; } ``` -------------------------------- ### Get Entry by Path (libzim7) Source: https://github.com/openzim/libzim/blob/main/docs/6to7.md In libzim7, entries are accessed via a zim::Archive instance, and a zim::EntryNotFound exception is raised if the entry is not found. ```c++ auto a = zim::Archive("foo.zim"); try { auto e = a.getEntryByPath("index.html"); } catch (zim::EntryNotFound& e) { std::cerr << "No entry index.html" << std::endl; } ``` -------------------------------- ### libzim 6 Suggestion Example Source: https://github.com/openzim/libzim/blob/main/docs/6to7.md Shows how to enable suggestion mode in libzim 6 by setting `set_suggestion_mode(true)` on the `zim::Search` object before iterating through results. This was used for both suggestion and full-text search if no suggestion database was present. ```c++ auto f = zim::File("foo.zim"); auto search = zim::Search(&f); search.set_query("bar"); search.set_range(10, 30); search.set_suggestion_mode(true); // <<< for (auto it =search.begin(); it!=search.end(); it++) { std::cout << "Found result " << it.get_url() << std::endl; } ``` -------------------------------- ### Iterate Articles by URL (libzim6) Source: https://github.com/openzim/libzim/blob/main/docs/6to7.md Libzim6 used begin* methods to get an iterator for articles, which you would then compare against end(). ```c++ auto file = [...]; for(auto it = file.beginByUrl(); it!=file.end(); it++) { auto article = *it; [...] } ``` -------------------------------- ### Check Entry Type and Get Item (libzim7) Source: https://github.com/openzim/libzim/blob/main/docs/6to7.md In libzim7, entries can be redirects or items. A zim::Item contains the actual data. ```c++ auto entry = [...]; if (entry.isRedirect()) { auto target = entry.getRedirectEntry(); } else { auto item = entry.getItem(); auto blob = item.getData(); } ``` -------------------------------- ### Finding Archive Entries by Path Prefix Source: https://github.com/openzim/libzim/blob/main/_autodocs/utilities.md Shows how to use a range-based for loop to find and iterate over archive entries whose paths start with a specified prefix. ```cpp // Find entries with prefix for (const auto& entry : archive.findByPath("An")) { std::cout << entry.getPath() << std::endl; } ``` -------------------------------- ### Find Articles by URL Prefix (libzim6) Source: https://github.com/openzim/libzim/blob/main/docs/6to7.md To iterate on articles starting with a URL prefix in libzim6, you used find() and manually checked the URL prefix in a loop. ```c++ auto file = [...]; auto it = file.find("A/ind"); while(!it.is_end() && it->getUrl().startWith("A/ind")) { auto article = *it; [...] it++; } ``` -------------------------------- ### Get Metadata by Name Source: https://github.com/openzim/libzim/blob/main/_autodocs/archive.md Retrieves the content of a specific metadata entry by its name. Throws EntryNotFound if the metadata does not exist. ```cpp std::string getMetadata(const std::string& name) const; ``` -------------------------------- ### Get Entry by Path String Source: https://github.com/openzim/libzim/blob/main/_autodocs/archive.md Retrieves an Entry object by its string path. Handles both new and old namespace schemes. Throws EntryNotFound if the path does not exist. ```cpp Entry getEntryByPath(const std::string& path) const; ``` -------------------------------- ### Get Library and Dependency Versions Source: https://github.com/openzim/libzim/blob/main/_autodocs/README.md Retrieves a map containing the versions of the libzim library and its dependencies. Iterate through the map to display each name-version pair. ```cpp auto versions = zim::getVersions(); for (const auto& [name, version] : versions) { std::cout << name << ": " << version << std::endl; } ``` -------------------------------- ### Find Entries by Title Prefix Source: https://github.com/openzim/libzim/blob/main/_autodocs/archive.md Searches for articles whose titles start with a given prefix. Returns an empty range if no matches are found. ```cpp EntryRange findByTitle(std::string title) const; ``` -------------------------------- ### Get Blob Data Pointer Source: https://github.com/openzim/libzim/blob/main/_autodocs/entry-item.md Returns a pointer to the start of the Blob's data. Returns null if the Blob is empty. ```cpp const char* data() const; ``` -------------------------------- ### Catch InvalidType Source: https://github.com/openzim/libzim/blob/main/_autodocs/errors.md Shows how to catch an InvalidType exception, for example, when trying to get an item from a redirect entry without specifying to follow the redirect. ```cpp try { auto item = entry.getItem(false); // Throws if entry is a redirect } catch (const zim::InvalidType& e) { std::cerr << "Wrong entry type: " << e.what() << std::endl; } ``` -------------------------------- ### Find Entries by Path Prefix Source: https://github.com/openzim/libzim/blob/main/docs/usage.md Finds entries in the archive whose paths start with a given prefix. This is useful for partial matching of entry paths. ```c++ for (auto entry: archive.findEntryByPath("fo")) { std::cout << "Entry " << entry.getPath() << " should starts with fo." << std::endl; } ``` -------------------------------- ### Get Data Blob from Item Source: https://github.com/openzim/libzim/blob/main/_autodocs/entry-item.md Retrieves a specified number of bytes from an item starting at a given offset. Returns fewer bytes if the end of the data is reached. ```cpp Blob getData(offset_type offset, size_type size) const; ``` ```cpp // Read 1KB chunk auto chunk = item.getData(0, 1024); std::cout << chunk.size() << " bytes read" << std::endl; ``` -------------------------------- ### Perform Suggestion Search Source: https://github.com/openzim/libzim/blob/main/_autodocs/search-suggest.md Get search suggestions based on a query prefix. The `suggest()` method returns a `SuggestionSearch` object containing potential matches. ```cpp SuggestionSearch suggest(const std::string& query); ``` ```cpp auto suggestions = suggester.suggest("phy"); // Titles starting with "phy" ``` -------------------------------- ### Check Article Type and Get Data (libzim6) Source: https://github.com/openzim/libzim/blob/main/docs/6to7.md Libzim6 articles could be redirects or contain data. You had to check the type before using the appropriate method. ```c++ auto article = [...]; if (article.isRedirect()) { auto target = article.getRedirectArticle(); } else { auto blob = article.getData(); } ``` -------------------------------- ### ZIM Creation with Full-Text Indexing Source: https://github.com/openzim/libzim/blob/main/_autodocs/creator.md Shows how to enable full-text indexing for a ZIM file during creation. Use configIndexing to enable and specify the language. ```cpp creator.configIndexing(true, "en"); // Enable English indexing creator.startZimCreation("indexed.zim"); // ... add items ... creator.finishZimCreation(); ``` -------------------------------- ### Search Result Set Iteration Source: https://github.com/openzim/libzim/blob/main/_autodocs/search-suggest.md Iterate through a collection of search results. Use `begin()` and `end()` to get iterators for the result set, and `size()` to get the number of results. ```cpp class SearchResultSet { public: typedef SearchIterator iterator; iterator begin() const; iterator end() const; int size() const; }; ``` ```cpp for (auto it = results.begin(); it != results.end(); ++it) { std::cout << it->getPath() << ": " << it->getScore() << std::endl; } ``` -------------------------------- ### Monitoring libzim Cache Usage Source: https://github.com/openzim/libzim/blob/main/_autodocs/utilities.md Provides code examples for checking the current usage and maximum size of both the cluster cache and the directory entry (dirent) cache within libzim. ```cpp // Check cluster cache usage size_t max_cluster = zim::getClusterCacheMaxSize(); size_t used_cluster = zim::getClusterCacheCurrentSize(); double percent = (double)used_cluster / max_cluster * 100; std::cout << "Cluster cache: " << percent << "% full" << std::endl; // Check dirent cache usage size_t max_dirents = archive.getDirentCacheMaxSize(); size_t used_dirents = archive.getDirentCacheCurrentSize(); std::cout << "Dirent cache: " << used_dirents << "/" << max_dirents << std::endl; ``` -------------------------------- ### ZIM Creation with Custom Item Implementation Source: https://github.com/openzim/libzim/blob/main/_autodocs/creator.md Demonstrates creating a ZIM file using a custom item class that inherits from BasicItem. The custom item provides its own ContentProvider. ```cpp class MyItem : public zim::writer::BasicItem { public: MyItem(const std::string& path, const std::string& content) : BasicItem(path, "text/plain", path, zim::writer::Hints()), m_content(content) {} std::unique_ptr getContentProvider() const override { return std::make_unique(m_content); } private: std::string m_content; }; auto item = std::make_shared("test.txt", "Hello World"); creator.addItem(item); ``` -------------------------------- ### Get Immediate Redirect Target Entry Source: https://github.com/openzim/libzim/blob/main/_autodocs/entry-item.md Retrieves the directly targeted entry for a redirect, without resolving the entire chain. Throws an exception if the entry is not a redirect. ```cpp Entry getRedirectEntry() const; ``` ```cpp auto direct_target = entry.getRedirectEntry(); ``` -------------------------------- ### Get Blob Size Source: https://github.com/openzim/libzim/blob/main/_autodocs/entry-item.md Returns the size of the Blob in bytes. ```cpp size_type size() const; ``` -------------------------------- ### Create a Basic Text Query Source: https://github.com/openzim/libzim/blob/main/_autodocs/search-suggest.md Instantiate a Query object with a simple text string to define search terms. This is the most basic way to set up a search query. ```cpp zim::Query query("machine learning"); ``` -------------------------------- ### startZimCreation(const std::string& filepath) Source: https://github.com/openzim/libzim/blob/main/_autodocs/creator.md Initializes the ZIM file creation process at the specified file path. This method must be called after all configuration settings have been applied and before any items are added to the archive. It may throw various exceptions if the file cannot be opened or written to. ```APIDOC ## startZimCreation(const std::string& filepath) ### Description Initializes ZIM file creation. Must be called after configuration and before adding items. ### Parameters: #### Parameters - `filepath` (const std::string&) - Path for output ZIM file ### Throws: Various exceptions if file cannot be opened/written. ### Example: ```cpp creator.startZimCreation("output.zim"); ``` ``` -------------------------------- ### Get Entry by Path and Check Type Source: https://github.com/openzim/libzim/blob/main/docs/usage.md Retrieves an entry by its path and checks if it's a redirection or an item. If it's a redirection, it prints the path of the redirected entry; otherwise, it prints the data of the item. ```c++ auto entry = archive.getEntryByPath("foo"); if (entry.isRedirect()) { std::cout << "This is a redirection to " << entry.getRedirectEntry().getPath() << std::endl(); } else { std::cout << "This is a item with content : " << entry.getItem().getData() << std::endl(); } ``` -------------------------------- ### Create a zim file using libzim7 Source: https://github.com/openzim/libzim/blob/main/docs/6to7.md Simplified zim file creation in libzim7 using the default Creator, adding redirects and items directly. ```c++ int main() { zim::writer::Creator creator; creator.startZimCreation(); creator.addRedirection("A/redirect", "A redirect", "A/article"); std::shared_ptr item = std::make_shared("article", "text/html", "A article", {}, "A content"); creator.addItem(item); creator.finishZimCreation(); } ``` -------------------------------- ### Get Direct Access Information for Uncompressed Items Source: https://github.com/openzim/libzim/blob/main/_autodocs/entry-item.md Provides file and offset information for uncompressed items, enabling direct file access to bypass libzim for optimization. Use getData() for compressed items. ```cpp zim::ItemDataDirectAccessInfo getDirectAccessInformation() const; ``` ```cpp auto info = item.getDirectAccessInformation(); if (info.isValid()) { // Item is stored uncompressed int fd = open(info.filename.c_str(), O_RDONLY); lseek(fd, info.offset, SEEK_SET); char buffer[1024]; read(fd, buffer, 1024); close(fd); } else { // Item is compressed, use getData() auto blob = item.getData(); } ``` -------------------------------- ### Get Archive UUID Source: https://github.com/openzim/libzim/blob/main/_autodocs/archive.md Retrieves the unique identifier (UUID) of the archive. Returns a Uuid object. ```cpp Uuid getUuid() const; ``` -------------------------------- ### Iterate and Print Metadata Source: https://github.com/openzim/libzim/blob/main/_autodocs/archive.md Demonstrates how to retrieve all metadata keys and then print each key along with its corresponding value. ```cpp auto keys = archive.getMetadataKeys(); for (const auto& key : keys) { std::cout << key << ": " << archive.getMetadata(key) << std::endl; } ``` -------------------------------- ### Compile Libzim Documentation Source: https://github.com/openzim/libzim/blob/main/README.md Compile Libzim along with its documentation by passing the -Ddoc=true option to Meson and then running the 'doc' target with Ninja. ```bash meson . build -Ddoc=true ninja -C build doc ``` -------------------------------- ### Get Current Cluster Cache Size Source: https://github.com/openzim/libzim/blob/main/_autodocs/archive.md Retrieves the current memory usage in bytes of the cluster cache. ```cpp size_t getClusterCacheCurrentSize(); ``` -------------------------------- ### Get Directory Entry Cache Current Size Source: https://github.com/openzim/libzim/blob/main/_autodocs/archive.md Retrieves the current number of directory entries being cached. ```cpp size_t getDirentCacheCurrentSize() const; ``` -------------------------------- ### Construct Archive with Open Configuration Source: https://github.com/openzim/libzim/blob/main/_autodocs/archive.md Constructs an archive with custom open configuration. For split files, use the logical path (foo.zim). Throws ZimFileFormatError. ```cpp Archive(const std::string& fname, OpenConfig openConfig); ``` ```cpp zim::OpenConfig config; config.preloadXapianDb(false); zim::Archive archive("file.zim", config); ``` -------------------------------- ### Get Directory Entry Cache Max Size Source: https://github.com/openzim/libzim/blob/main/_autodocs/archive.md Retrieves the maximum number of directory entries that can be cached. ```cpp size_t getDirentCacheMaxSize() const; ``` -------------------------------- ### Get Archive Checksum Source: https://github.com/openzim/libzim/blob/main/_autodocs/archive.md Retrieves the stored checksum of the archive. Returns an empty string if no checksum is present. ```cpp std::string getChecksum() const; ``` -------------------------------- ### Build and test Libzim with default test data Source: https://github.com/openzim/libzim/blob/main/README.md Standard workflow to configure, build, download test data, and run tests for Libzim. Assumes default test data directory. ```bash meson . build # Configure the project (using default directory for test data) cd build ninja # Build ninja download_test_data # Download the test data meson test # Test ``` -------------------------------- ### Get Entry Index Source: https://github.com/openzim/libzim/blob/main/_autodocs/entry-item.md Retrieves the internal index used to identify an entry within the ZIM archive. ```cpp entry_index_type getIndex() const; ``` -------------------------------- ### Configure Creator Performance Settings Source: https://github.com/openzim/libzim/blob/main/_autodocs/configuration.md Set the number of worker threads, cluster size, and verbosity for archive creation. Use hardware concurrency for optimal performance and disable progress output for cleaner logs. ```cpp creator.configNbWorkers(std::thread::hardware_concurrency()); creator.configClusterSize(2 * 1024 * 1024); // Larger clusters creator.configVerbose(false); // Disable progress output ``` -------------------------------- ### Get Entry Title Source: https://github.com/openzim/libzim/blob/main/_autodocs/entry-item.md Retrieves the human-readable title of an entry. Note that multiple entries can share the same title. ```cpp std::string getTitle() const; ``` -------------------------------- ### Uninstall Libzim Source: https://github.com/openzim/libzim/blob/main/README.md Remove the installed Libzim libraries and headers from the system. This command may require root privileges. ```bash ninja -C build uninstall ``` -------------------------------- ### Create and Use SuggestionSearcher Source: https://github.com/openzim/libzim/blob/main/docs/usage.md Demonstrates how to create a SuggestionSearcher, perform a search for a given term, and retrieve a set of suggestion results. This is useful for finding suggestions when the search term might appear in the middle of a suggestion. ```c++ // Create a searcher, something to search on an archive zim::SuggestionSearcher searcher(archive); // Create a search for the specified query zim::SuggestionSearch search = searcher.search("bar"); // Now we can get some result from the search. // 20 results starting from offset 10 (from 10 to 30) zim::SuggestionResultSet results = search.getResults(10, 20); // SearchResultSet is iterable for(auto entry: results) { std::cout << entry.getPath() << std::endl; } ``` -------------------------------- ### Get Global Cluster Cache Max Size Source: https://github.com/openzim/libzim/blob/main/_autodocs/archive.md Retrieves the maximum size in bytes that the cluster cache can occupy. ```cpp size_t getClusterCacheMaxSize(); ``` -------------------------------- ### Compile Libzim with Static Libraries Source: https://github.com/openzim/libzim/blob/main/README.md Compile Libzim using Meson and Ninja, specifically requesting statically linked libraries by using the --default-library=static option. ```bash meson . build --default-library=static ninja -C build ``` -------------------------------- ### Initialize Suggestion Searcher Source: https://github.com/openzim/libzim/blob/main/_autodocs/search-suggest.md Create a `SuggestionSearcher` instance to perform title-based searches on an archive. This is faster than full-text search and works even without a full-text index. ```cpp explicit SuggestionSearcher(const Archive& archive); ``` ```cpp zim::SuggestionSearcher suggester(archive); ``` -------------------------------- ### Get Total Entry Count Source: https://github.com/openzim/libzim/blob/main/_autodocs/archive.md Returns the count of all entries in the archive, including internal entries, metadata, and indexes. ```cpp entry_index_type getAllEntryCount() const; ``` -------------------------------- ### Configure Archive Opening with Builder Pattern Source: https://github.com/openzim/libzim/blob/main/_autodocs/configuration.md Use the builder pattern to fluently set multiple configuration options for opening an archive. ```cpp zim::OpenConfig config; config.preloadXapianDb(false) .preloadDirentRanges(3); zim::Archive archive("file.zim", config); ``` -------------------------------- ### Get Blob End Pointer Source: https://github.com/openzim/libzim/blob/main/_autodocs/entry-item.md Returns a pointer to one byte past the end of the Blob's data. ```cpp const char* end() const; ``` -------------------------------- ### Get Item Size Source: https://github.com/openzim/libzim/blob/main/_autodocs/entry-item.md Retrieves the total size of an item in bytes. This is useful for verifying data integrity after retrieval. ```cpp size_type getSize() const; ``` ```cpp auto item = entry.getItem(); std::cout << "Item size: " << item.getSize() << " bytes" << std::endl; // Verify data retrieval auto data = item.getData(); assert(data.size() == item.getSize()); ``` -------------------------------- ### Geographic Search Example Source: https://github.com/openzim/libzim/blob/main/_autodocs/search-suggest.md Performs a geographic search for a query within a specified radius around given coordinates. ```cpp zim::Query query("restaurants"); query.setGeorange(40.7128, -74.0060, 5000); // NYC, 5km auto search = searcher.search(query); ``` -------------------------------- ### Open Archive with Default Configuration Source: https://github.com/openzim/libzim/blob/main/_autodocs/configuration.md Opens a libzim archive using the default OpenConfig settings, which typically includes preloading the Xapian database. ```cpp zim::Archive archive("file.zim"); // Uses default OpenConfig ``` -------------------------------- ### findByPath(path) Source: https://github.com/openzim/libzim/blob/main/_autodocs/archive.md Performs a prefix-based search for entries starting with the specified path. Returns an empty range if no matches are found. ```APIDOC ## findByPath(path) ### Description Performs a prefix-based search for entries. Returns an empty range if no matches are found. ### Parameters #### Path Parameters - **path** (`std::string`) - The path prefix to search for. ### Returns `EntryRange` - A range of entries starting with the specified path prefix. ### Example ```cpp for (const auto& entry : archive.findByPath("A/")) { // All entries in path order starting with "A/" } ``` ``` -------------------------------- ### Attributes Initialization and Parsing Source: https://github.com/openzim/libzim/blob/main/_autodocs/utilities.md Demonstrates how to create and initialize a zim::Attributes object, either by direct assignment, using an initializer list, or by parsing a string. ```cpp zim::Attributes attrs; attrs["width"] = "100"; attrs["height"] = "100"; // Or initialize with list zim::Attributes attrs2 = { {"width", "200"}, {"height", "200"} }; // Or parse from string zim::Attributes attrs3 = zim::Attributes::parse("width=300&height=300"); ``` -------------------------------- ### Get Random Entry Source: https://github.com/openzim/libzim/blob/main/_autodocs/archive.md Retrieves a random entry from the front articles. Throws `EntryNotFound` if no valid random entry is available. ```cpp Entry getRandomEntry() const; ``` -------------------------------- ### Initialize Searcher with a Single Archive Source: https://github.com/openzim/libzim/blob/main/_autodocs/search-suggest.md Create a Searcher instance to perform full-text searches on a single ZIM archive. Ensure the archive has a Xapian fulltext index. ```cpp zim::Archive archive("example.zim"); zim::Searcher searcher(archive); ``` -------------------------------- ### Creator() Source: https://github.com/openzim/libzim/blob/main/_autodocs/creator.md Constructs an empty creator in an unconfigured state. It initializes with default settings for verbosity, compression, indexing, worker threads, and cluster size. ```APIDOC ## Creator() ### Description Constructs empty creator in unconfigured state. ### Default Settings: - `verbose` = false - `compression` = `Compression::Zstd` - `withIndex` = false - `nbWorkers` = 4 - `clusterSize` = default (usually ~1MB uncompressed) - `indexingLanguage` = "" (no indexing) ``` -------------------------------- ### Core API Documentation Overview Source: https://github.com/openzim/libzim/blob/main/_autodocs/INDEX.md This section outlines the core API documentation files available for libzim, covering various aspects of the library's functionality. ```APIDOC ## Core API Documentation This section provides a detailed breakdown of the API documentation available for the libzim library, organized by functionality. ### README.md **Description**: Main entry point and overview, including quick start examples, module organization, thread safety, error handling, and performance considerations. ### archive.md **Description**: Documentation for the Archive class, focusing on reading ZIM files. It covers constructors, entry access methods, metadata, iteration, prefix-based search, integrity checking, and cache management. ### entry-item.md **Description**: Details the Entry and Item classes for content access. Covers entry properties, item data retrieval, and the Blob class, with examples for reading HTML and streaming large files. ### creator.md **Description**: Documentation for the Creator class, used for writing ZIM archives. Includes configuration methods, item addition, item class implementations, ContentProvider interface, and error handling patterns. ### search-suggest.md **Description**: Covers full-text search and title suggestions. Features the Searcher class, Query class, Search and Suggestion iterators, and examples for geographic search and pagination. ### types.md **Description**: Defines type aliases, enumerations, and structures used within libzim, including entry index types, compression formats, entry orders, integrity checks, and various configuration-related structures. ### errors.md **Description**: Details the exception classes and error handling mechanisms in libzim, including the exception hierarchy, specific error types for format violations, entry not found, and creator errors, along with recovery strategies. ### configuration.md **Description**: Explains configuration options for opening and creating ZIM files, including cache tuning, performance guides, validation, and integrity check configuration. ### utilities.md **Description**: Lists utility functions and helper classes, such as version information retrieval, string formatting, ICU configuration, UUID generation, MIME type constants, and API export macros. ``` -------------------------------- ### Get Media Entry Count Source: https://github.com/openzim/libzim/blob/main/_autodocs/archive.md Counts archive entries classified by MIME type. Returns an entry index type. ```cpp entry_index_type getMediaCount() const; ``` -------------------------------- ### Safe Entry Access in libzim Source: https://github.com/openzim/libzim/blob/main/_autodocs/utilities.md Demonstrates three methods for safely accessing archive entries: checking existence before access, using try-catch blocks for exceptions, and utilizing helper functions like hasMainEntry. ```cpp // Safe: Check before accessing if (archive.hasEntryByPath("path")) { auto entry = archive.getEntryByPath("path"); // Use entry } // Safe: Use try-catch try { auto entry = archive.getEntryByPath("path"); } catch (const zim::EntryNotFound&) { std::cout << "Entry not found" << std::endl; } // Safe: Use the has* helper if (archive.hasMainEntry()) { auto main = archive.getMainEntry(); } ``` -------------------------------- ### Configure Verbosity and Compression Source: https://github.com/openzim/libzim/blob/main/_autodocs/creator.md Chains configuration methods for verbosity and compression. Use configVerbose to print processing information and configCompression to set the compression algorithm. ```cpp creator.configVerbose(true) .configCompression(zim::Compression::Zstd); ``` -------------------------------- ### String and File Conversion from Blob Source: https://github.com/openzim/libzim/blob/main/_autodocs/utilities.md Shows how to convert a libzim Blob object to a std::string or stream its content directly to a file. ```cpp zim::Blob blob = item.getData(); std::string content(blob); // Convert to string // Or stream to file std::ofstream file("output.txt"); file << blob; ``` -------------------------------- ### Compile Libzim with Meson and Ninja Source: https://github.com/openzim/libzim/blob/main/README.md Compile Libzim using Meson to configure the build and Ninja to perform the compilation. By default, this creates dynamically linked libraries. ```bash meson . build ninja -C build ``` -------------------------------- ### Get Item MIME Type Source: https://github.com/openzim/libzim/blob/main/_autodocs/entry-item.md Retrieves the MIME type of the item's content, indicating its format (e.g., 'text/html', 'image/png'). ```cpp std::string getMimetype() const; ``` -------------------------------- ### Configure Archive Preloading Options Source: https://github.com/openzim/libzim/blob/main/_autodocs/configuration.md Set preloading decisions for reading archives to optimize performance. Enable Xapian database preloading for interactive use and preload dirent ranges for frequent lookups. ```cpp OpenConfig config; config.preloadXapianDb(true); // For interactive use config.preloadDirentRanges(5); // For many lookups ``` -------------------------------- ### configIndexing(bool indexing, const std::string& language) Source: https://github.com/openzim/libzim/blob/main/_autodocs/creator.md Enables or disables full-text indexing for the ZIM archive and specifies the indexing language. Requires libzim to be built with Xapian support. Returns a reference to the Creator object for chaining. ```APIDOC ## configIndexing(bool indexing, const std::string& language) ### Description Enables Xapian fulltext indexing. Requires libzim built with Xapian support. ### Parameters: #### Parameters - `indexing` (bool) - Enable fulltext indexing - `language` (const std::string&) - Indexing language ### Returns: `Creator&` ### Languages: Standard language codes (e.g., "en", "fr", "de", "zh") ### Example: ```cpp creator.configIndexing(true, "en"); // English fulltext search ``` ``` -------------------------------- ### Configure Creator Output Compression and Cluster Size Source: https://github.com/openzim/libzim/blob/main/_autodocs/configuration.md Set the compression algorithm and adjust the cluster size for the output archive. Zstd compression is recommended for a balance between speed and compression ratio. ```cpp creator.configCompression(zim::Compression::Zstd); creator.configClusterSize(1 * 1024 * 1024); // Balance ``` -------------------------------- ### Direct Item Access Usage Source: https://github.com/openzim/libzim/blob/main/_autodocs/utilities.md Demonstrates how to check if an item supports direct file access using getDirectAccessInformation() and isValid(). If valid, it shows how to open the file and seek to the offset; otherwise, it suggests using getData() for compressed items. ```cpp auto item = entry.getItem(); auto access_info = item.getDirectAccessInformation(); if (access_info.isValid()) { // Item is uncompressed; direct file access possible std::ifstream file(access_info.filename); file.seekg(access_info.offset); // Read directly from file } else { // Item is compressed; use getData() auto blob = item.getData(); } ``` -------------------------------- ### Handle Redirects in libzim Source: https://github.com/openzim/libzim/blob/main/_autodocs/entry-item.md Demonstrates how to check if an entry is a redirect and retrieve either the immediate target or the final item in a redirect chain. ```cpp auto entry = archive.getEntryByPath("Redirect_Page"); if (entry.isRedirect()) { // Get immediate target auto direct = entry.getRedirectEntry(); std::cout << "Redirects to: " << direct.getPath() << std::endl; // Or follow entire chain auto final_item = entry.getRedirect(); std::cout << "Final item: " << final_item.getPath() << std::endl; } else { auto item = entry.getItem(); std::cout << "Direct content" << std::endl; } ``` -------------------------------- ### Enable Verbose Output for Creator Source: https://github.com/openzim/libzim/blob/main/_autodocs/configuration.md Configure the libzim creator to print processing progress and diagnostic information to the console during archive creation. ```cpp creator.configVerbose(true); // Enable progress output ``` -------------------------------- ### Get Entry by Title Index Source: https://github.com/openzim/libzim/blob/main/_autodocs/archive.md Retrieves an Entry object using its index in the title order. Throws std::out_of_range if the index is invalid. ```cpp Entry getEntryByTitle(entry_index_type idx) const; ``` -------------------------------- ### Get Entry by Path Index Source: https://github.com/openzim/libzim/blob/main/_autodocs/archive.md Retrieves an Entry object using its index in the path order. Throws std::out_of_range if the index is invalid. ```cpp Entry getEntryByPath(entry_index_type idx) const; ``` -------------------------------- ### Get Illustration Information by Dimensions and Scale Source: https://github.com/openzim/libzim/blob/main/_autodocs/archive.md Retrieves illustration information objects that match specified width, height, and minimum scale criteria. ```cpp IllustrationInfos getIllustrationInfos(uint32_t w, uint32_t h, float minScale) const; ``` -------------------------------- ### Creating a ZIM File Source: https://github.com/openzim/libzim/blob/main/_autodocs/README.md Creates a new ZIM file with specified compression, indexing, and worker configurations. Adds metadata and content items, then finalizes the creation process. ```cpp #include #include int main() { zim::writer::Creator creator; // Configure creator.configCompression(zim::Compression::Zstd) .configIndexing(true, "en") .configNbWorkers(4); // Start creation creator.startZimCreation("output.zim"); // Add metadata creator.addMetadata("Title", "My Archive"); creator.addMetadata("Creator", "Me"); // Add content auto item = zim::writer::StringItem::create( "index.html", "text/html;charset=utf-8", "Home Page", zim::writer::Hints(), "

Welcome

" ); creator.addItem(item); // Set main page and finish creator.setMainPath("index.html"); creator.finishZimCreation(); return 0; } ``` -------------------------------- ### Get Illustration Item by Info Source: https://github.com/openzim/libzim/blob/main/_autodocs/archive.md Retrieves an illustration as an Item object using IllustrationInfo parameters. Throws EntryNotFound if no matching illustration is found. ```cpp Item getIllustrationItem(const IllustrationInfo& ii) const; ``` -------------------------------- ### Get Metadata Item by Name Source: https://github.com/openzim/libzim/blob/main/_autodocs/archive.md Retrieves an Item object associated with a specific metadata entry name. Throws EntryNotFound if the metadata does not exist. ```cpp Item getMetadataItem(const std::string& name) const; ``` -------------------------------- ### Get User Entry Count Source: https://github.com/openzim/libzim/blob/main/_autodocs/archive.md Returns the count of user-accessible entries in the archive. This is equivalent to getAllEntryCount() if there's no distinction between user and internal entries. ```cpp entry_index_type getEntryCount() const; ``` -------------------------------- ### Custom Archive Open Configuration Source: https://github.com/openzim/libzim/blob/main/_autodocs/archive.md Illustrates how to customize the archive opening process by disabling full-text index loading and limiting the preloading of directory entry ranges. ```cpp zim::OpenConfig config; config.preloadXapianDb(false); // Skip fulltext index loading config.preloadDirentRanges(5); // Load 5 dirent ranges zim::Archive archive("file.zim", config); ``` -------------------------------- ### Get Library Version Information Source: https://github.com/openzim/libzim/blob/main/_autodocs/utilities.md Retrieves version information for libzim and its dependencies. Use this function to inspect the versions of the libraries your application is linked against. ```cpp #include #include int main() { auto versions = zim::getVersions(); for (const auto& [name, version] : versions) { std::cout << name << ": " << version << std::endl; } return 0; } ``` -------------------------------- ### Get Redirect Target Entry Index Source: https://github.com/openzim/libzim/blob/main/_autodocs/entry-item.md Returns the internal index of the immediately targeted entry for a redirect. Throws an exception if the entry is not a redirect. ```cpp entry_index_type getRedirectEntryIndex() const; ``` -------------------------------- ### Configure Xapian Support during Build Source: https://github.com/openzim/libzim/blob/main/_autodocs/configuration.md Control Xapian full-text search support during the Meson build process. Set '-Dwith_xapian=true' to enable (default) or '-Dwith_xapian=false' to disable. ```bash meson . build -Dwith_xapian=true # Enable (default) ``` ```bash meson . build -Dwith_xapian=false # Disable ``` -------------------------------- ### Get Entry Path Source: https://github.com/openzim/libzim/blob/main/_autodocs/entry-item.md Retrieves the unique path identifier for an entry. The format may include a namespace prefix depending on the ZIM scheme. ```cpp std::string getPath() const; ``` -------------------------------- ### Optimize Direct File Access in libzim Source: https://github.com/openzim/libzim/blob/main/_autodocs/entry-item.md Shows how to obtain direct access information for an entry, allowing for faster disk reads of uncompressed files, or falling back to libzim decompression. ```cpp auto item = archive.getEntryByPath("image.png"); auto access_info = item.getDirectAccessInformation(); if (access_info.isValid()) { // Direct disk read (faster for large uncompressed files) std::ifstream file(access_info.filename); file.seekg(access_info.offset); std::vector buffer(item.getSize()); file.read(buffer.data(), item.getSize()); } else { // Use libzim decompression auto blob = item.getData(); std::vector buffer(blob.data(), blob.data() + blob.size()); } ``` -------------------------------- ### Iterating Archive Entries by Path Source: https://github.com/openzim/libzim/blob/main/_autodocs/utilities.md Shows how to use a range-based for loop to iterate through archive entries ordered by their paths. ```cpp // Iterate by path order for (const auto& entry : archive.iterByPath()) { std::cout << entry.getPath() << std::endl; } ``` -------------------------------- ### getData(offset, size) Source: https://github.com/openzim/libzim/blob/main/_autodocs/entry-item.md Retrieves a specified number of bytes from an item starting at a given offset. It returns fewer bytes if the end of the data is reached. ```APIDOC ## getData(offset_type offset, size_type size) ### Description Returns exactly `size` bytes starting at `offset`. Returns less if approaching end of data. ### Method const ### Parameters #### Path Parameters - **offset** (offset_type) - Required - Byte offset to start - **size** (size_type) - Required - Number of bytes to read ### Response #### Success Response - **Blob** - Data blob of specified size. ### Request Example ```cpp // Read 1KB chunk auto chunk = item.getData(0, 1024); std::cout << chunk.size() << " bytes read" << std::endl; ``` ``` -------------------------------- ### Iterate Entries by Path Source: https://github.com/openzim/libzim/blob/main/_autodocs/archive.md Provides an iterable range of all user entries sorted by path. ```cpp EntryRange iterByPath() const; ``` ```cpp for (const auto& entry : archive.iterByPath()) { std::cout << entry.getPath() << std::endl; } ``` -------------------------------- ### Iterate Entries by Path (libzim7) Source: https://github.com/openzim/libzim/blob/main/docs/6to7.md Libzim7 provides a zim::Archive::EntryRange for easy iteration over entries by path. ```c++ auto archive = [...]; for(auto entry : archive.iterByPath()) { [...] } ``` -------------------------------- ### Get Redirect Target Item Source: https://github.com/openzim/libzim/blob/main/_autodocs/entry-item.md Follows the entire redirect chain to return the final target item. This method detects and handles circular redirects. ```cpp Item getRedirect() const; ``` ```cpp if (entry.isRedirect()) { auto target_item = entry.getRedirect(); std::cout << target_item.getPath() << std::endl; } ``` -------------------------------- ### Configure Creator for Memory-Constrained Systems Source: https://github.com/openzim/libzim/blob/main/_autodocs/configuration.md Optimize creator settings for memory-constrained environments. Use a single worker thread and smaller cluster sizes to reduce memory overhead during archive creation. ```cpp creator.configNbWorkers(1); // Single thread creator.configClusterSize(512 * 1024); // Small clusters ```