{"id":21948013,"url":"https://github.com/kojobailey/binary-cpp-library","last_synced_at":"2025-03-22T17:10:22.281Z","repository":{"id":232976672,"uuid":"785701874","full_name":"KojoBailey/binary-cpp-library","owner":"KojoBailey","description":"A C++11 library for parsing the binary data of files and whatnot both easily and cleanly.","archived":false,"fork":false,"pushed_at":"2025-01-21T13:52:12.000Z","size":52,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-18T04:12:52.263Z","etag":null,"topics":["binary","cplusplus","cpp","cpp20","cpp23","hpp","library","single-include"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KojoBailey.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2024-04-12T12:48:02.000Z","updated_at":"2025-01-28T13:28:42.000Z","dependencies_parsed_at":"2024-04-19T15:53:37.554Z","dependency_job_id":null,"html_url":"https://github.com/KojoBailey/binary-cpp-library","commit_stats":null,"previous_names":["kojobailey/binary-cpp-library"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KojoBailey%2Fbinary-cpp-library","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KojoBailey%2Fbinary-cpp-library/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KojoBailey%2Fbinary-cpp-library/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KojoBailey%2Fbinary-cpp-library/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KojoBailey","download_url":"https://codeload.github.com/KojoBailey/binary-cpp-library/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244991166,"owners_count":20543627,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["binary","cplusplus","cpp","cpp20","cpp23","hpp","library","single-include"],"created_at":"2024-11-29T05:11:26.908Z","updated_at":"2025-03-22T17:10:22.258Z","avatar_url":"https://github.com/KojoBailey.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# [binary++](https://github.com/KojoBailey/binary-cpp-library)\nThis library for **C++20 and newer** assists reading from and writing to **binary data**, making use of my own experience as a reverse engineer.\n\nIt aims to:\n- Make use of modern C++ features where **useful** (i.e. `std::endian` and co.).\n- Be as **open-purposed** as possible for a wide range of use cases.\n- Mirror the **standard library's style** for interface.\n- Receive updates as necessary.\n\n## Table of Contents\n- [Dependencies](#dependencies)\n- [Usage](#usage)\n- [Documentation](#documentation)\n    - [`binary{}`](#binary-1)\n    - [`load()`](#load)\n    - [`clear()`](#clear)\n    - [`data()`](#data)\n    - [`size()`](#size)\n    - [`set_endian()`](#set_endian)\n    - [`read()`](#read)\n    - [`write()`](#write)\n    - [`get_pos()`](#get_pos)\n    - [`set_pos()`](#set_pos)\n    - [`change_pos()`](#change_pos)\n    - [`align_by()`](#align_by)\n    - [`dump_file()`](#dump_file)\n\n## Dependencies\nHere is the full list of includes used by this library:\n```cpp\n#include \u003cbit\u003e\n#include \u003ccstring\u003e    \n#include \u003cfstream\u003e\n#include \u003ccstdint\u003e\n#include \u003cstring_view\u003e\n#include \u003ctype_traits\u003e\n#include \u003cvector\u003e\n```\n\nOtherwise, no external dependencies are used.\n\n## Usage\nWith a single header file at only ~10KB, it's very easy to start using this library. Support for build systems like **CMake** may be added in the future.\n\n```cpp\n#include \u003ckojo/binary.hpp\u003e // or something along those lines.\n```\n\nA `binary` class is provided, under the `kojo` namespace, and can be initialised via a **file path** as an `std::string`, the **address** of the start of some data, or **another `binary` object**.\n\nAlternatively, you can default initialise, and instead use `.load()` later on. Note that this will clear any data you may have had loaded into the object previously.\n\n```cpp\n#include \u003ckojo/binary.hpp\u003e\n\nint main() {\n    std::vector\u003cchar\u003e some_data = {'S', 'o', 'm', 'e', ' ', 'd', 'a', 't', 'a', '.'};\n\n    // Initialising\n    kojo::binary from_file{\"./example/file/path.bin\"};\n    kojo::binary from_address{some_data.data()};\n    kojo::binary from_object{from_file};\n\n    // Using `load()`\n    kojo::binary from_file;\n    from_file.load(\"./example/file/path.bin\");\n    kojo::binary from_address;\n    from_address.load(some_data.data());\n    kojo::binary load_from_object;\n    from_object.load(\u0026from_file);\n}\n```\n\n## Documentation\nHere is a list of every publicly-accessible element for the `binary` class, with examples:\n\n### `binary{}`\nThe **constructor**. Either initialises a `binary` object that is empty, or with either a file (via filepath) or binary data.\n```cpp\nbinary();\nbinary(std::string path_input, size_t start = 0, size_t size = -1);\nbinary(void* pointer, size_t start = 0, size_t size = -1);\nbinary(binary\u0026 binary_data, size_t start = 0, size_t size = -1);\n```\n\n```cpp\n// Initialise as empty:\nkojo::binary ex_empty;\n\n// Initialise from filepath:\nkojo::binary ex_filepath{\"./example/file/path.bin\"};\n\nstd::filesystem::path path = \"another/example/file/path.bin\";\nkojo::binary ex_fspath{path.string()};\n\n// Initialise from address:\nstd::vector\u003cchar\u003e vec = {'S', 'o', 'm', 'e', ' ', 'd', 'a', 't', 'a', '.'};\nkojo::binary ex_vector{vec.data(), 0, vec.size()};\nkojo::binary ex_vectorsect{vec.data(), 5, 4}; // Only contains \"data\"\n\n// Initialise from another binary object:\nkojo::binary ex_object{ex_vector}; // Contains \"Some data.\"\n```\n\n### `load()`\nSame as the constructors, but can be used after initialisation, clearing all existing data.\n```cpp\nvoid load(std::string path_input, size_t start = 0, size_t size = -1);\nvoid load(void* pointer, size_t start = 0, size_t size = -1);\nvoid load(binary\u0026 binary_data, size_t start = 0, size_t size = -1);\n```\n```cpp\nkojo::binary foo;\n\n// Load from filepath:\nfoo.load(\"./example/file/path.bin\");\n\nstd::filesystem::path path = \"another/example/file/path.bin\";\nfoo.load(path.string());\n\n// Load from address:\nstd::vector\u003cchar\u003e vec = {'S', 'o', 'm', 'e', ' ', 'd', 'a', 't', 'a', '.'};\nfoo.load(vec.data(), 0, vec.size());\nfoo.load(vec.data(), 5, 4); // Only contains \"data\"\n\n// Load from another binary object:\nkojo::binary boo{vec.data(), 0, vec.size()};\nfoo.load(boo); // Contains \"Some data.\"\n```\n\n### `clear()`\nClears all stored data and resets the position back to 0.\n```cpp\nvoid clear();\n```\n```cpp\nkojo::binary writer;\nwriter.write\u003cstd::string\u003e(\"Gone... Reduced to atoms.\");\nwriter.clear();\nwriter.write\u003cstd::string\u003e(\"Out with the old...\");\n\nkojo::binary reader{writer};\nstd::cout \u003c\u003c reader.read\u003cstd::string\u003e(); // \"Out with the old...\"\n```\n\n### `data()`\nReturns a pointer to the data accessed by the object, whether that be internally or externally stored.\n```cpp\nunsigned char* data();\n```\n```cpp\nkojo::binary foo;\nfoo.write\u003cchar\u003e('B');\nfoo.write\u003cstd::string\u003e(\"azinga!\");\nstd::cout \u003c\u003c foo.data(); // \"Bazinga!\"\n```\n\n### `size()`\nReturns the size of the internally-stored data if existing, or `-1` otherwise.\n```cpp\nsize_t size();\n```\n```cpp\nkojo::binary foo;\nfoo.write\u003cstd::uint64_t\u003e(23, std::endian::big);\nfoo.write\u003cstd::uint32_t\u003e(420, std::endian::big);\nstd::cout \u003c\u003c foo.size(); // 12\n```\n\n### `set_endian()`\nSets the endianness of an **integer** to big or little. Mostly exists for internal use.\n```cpp\ntemplate \u003ctypename T\u003e T set_endian(T value, std::endian endianness);\n    static_assert(std::is_integral\u003cT\u003e::value, \"T must be an integral type.\");\n```\n```cpp\nkojo::binary foo;\nstd::uint32_t number = foo.set_endian(1, std::endian::big); // 00 00 00 01\nnumber = foo.set_endian(number, std::endian::little);       // 01 00 00 00\n```\n\n### `read()`\nReads from data into a specified type, that being an integer, `char`, or `std::string`.\n```cpp\ntemplate \u003ctypename T\u003e T read(std::endian endianness, size_t offset = 0);\n    static_assert(std::is_integral\u003cT\u003e::value, \"T must be an integral type.\");\ntemplate \u003ctypename T\u003e typename std::enable_if\u003cstd::is_same\u003cT, char\u003e::value, char\u003e::type read(size_t offset = 0);\ntemplate \u003ctypename T\u003e typename std::enable_if\u003cstd::is_same\u003cT, std::string\u003e::value, std::string\u003e::type read(size_t size = 0, size_t offset = 0);\n```\n```cpp\nstd::vector\u003cchar\u003e vec{17, 1,  0, 0, 'h', 'P', 'N', 'G', 'J', 'o', 'h', 'n', '\\0', 'B'};\nkojo::binary foo{vec.data(), 0, vec.size()};\n\nstd::cout \u003c\u003c foo.read\u003cstd::uint32_t\u003e(std::endian::little); // 273\nstd::cout \u003c\u003c foo.read\u003cchar\u003e(); // 'h'\nstd::cout \u003c\u003c foo.read\u003cstd::string\u003e(3); // \"PNG\"\nstd::cout \u003c\u003c foo.read\u003cstd::string\u003e(); // \"John\"\n```\n\n### `write()`\nWrites specified data at the end of the internally-stored data. Cannot overwrite.\n```cpp\ntemplate \u003ctypename T\u003e void write(T value, endian endianness);\n    static_assert(std::is_integral\u003cT\u003e::value, \"T must be an integral type.\");\ntemplate \u003ctypename T\u003e void write(typename std::enable_if\u003cstd::is_same\u003cT, char\u003e::value, char\u003e::type value);\ntemplate \u003ctypename T\u003e void write(typename std::enable_if\u003cstd::is_same\u003cT, std::string\u003e::value, std::string\u003e::type value, size_t length = 0);\ntemplate \u003ctypename T\u003e void write(typename std::enable_if\u003cstd::is_same\u003cT, std::vector\u003cunsigned char\u003e\u003e::value, std::vector\u003cunsigned char\u003e\u003e::type\u0026 value);\n```\n```cpp\nkojo::binary foo;\nfoo.write\u003cstd::int64_t\u003e(-281029, std::endian::big);\nfoo.write\u003cstd::uint16_t\u003e(934, std::endian::little);\nfoo.write\u003cchar\u003e('E');\nfoo.write\u003cstd::string\u003e(\"Die Speisekarte, bitte.\"); // Null-terminated.\nfoo.write\u003cstd::string\u003e(\"NUCC\", 4); // Not null-terminated.\nstd::vector\u003cunsigned char\u003e vec{'a', 'B', 'c', 'D'};\nfoo.write\u003cstd::vector\u003cunsigned char\u003e\u003e(vec);\n```\n\n### `get_pos()`\nReturns the current position in the data.\n```cpp\nsize_t get_pos();\n```\n```cpp\nkojo::binary foo;\nstd::cout \u003c\u003c foo.get_pos(); // 0\nfoo.write\u003cstd::uint32_t\u003e(5, std::endian::big);\nstd::cout \u003c\u003c foo.get_pos(); // 4\nfoo.write\u003cstd::string\u003e(\"YouGotCAGEd\");\nstd::cout \u003c\u003c foo.get_pos(); // 16\n```\n\n### `set_pos()`\nSets the current position in the data.\n```cpp\nvoid set_pos(size_t pos);\n```\n```cpp\nkojo::binary foo;\nfoo.write\u003cstd::string\u003e(\"Goodbye JoJo!\");\nfoo.set_pos(0);\nstd::cout \u003c\u003c foo.read\u003cstd::string\u003e(); // \"Goodbye JoJo!\"\n```\n\n### `change_pos()`\nChanges the position in data by an offset, positive or negative.\n```cpp\nvoid change_pos(std::int64_t offset);\n```\n```cpp\nkojo::binary foo;\nfoo.write\u003cstd::string\u003e(\"Goodbye JoJo!\");\nfoo.set_pos(0);\nfoo.change_pos(8);\nstd::cout \u003c\u003c foo.read\u003cstd::string\u003e(); // \"JoJo!\"\n```\n\n### `align_by()`\nChanges the position in data to the next multiple of a specified integer.\n```cpp\nvoid align_by(size_t bytes);\n```\n```cpp\nkojo::binary foo;\nfoo.write\u003cstd::string\u003e(\"ABCDEFGHGood grief.\");\nfoo.set_pos(0);\nfoo.change_pos(5);\nfoo.align_by(4);\nstd::cout \u003c\u003c foo.read\u003cstd::string\u003e(); // \"Good grief.\"\n```\n\n### `dump_file()`\nOutputs the data to a file at a specified path.\n```cpp\nvoid dump_file(std::string output_path);\n```\n```cpp\nkojo::binary foo;\nfoo.write\u003cstd::string\u003e(\"Coca Cola espuma\");\nfoo.dump_file(\"./some_path.bin\");\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkojobailey%2Fbinary-cpp-library","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkojobailey%2Fbinary-cpp-library","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkojobailey%2Fbinary-cpp-library/lists"}