{"id":13652477,"url":"https://github.com/qdrvm/scale-codec-cpp","last_synced_at":"2025-04-23T03:30:52.088Z","repository":{"id":41657099,"uuid":"421340061","full_name":"qdrvm/scale-codec-cpp","owner":"qdrvm","description":"Designing a Better World Through Decentralized Technologies","archived":false,"fork":true,"pushed_at":"2024-10-16T14:22:04.000Z","size":335,"stargazers_count":4,"open_issues_count":7,"forks_count":6,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-10-30T01:37:03.172Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"Harrm/scale-codec","license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/qdrvm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2021-10-26T08:20:02.000Z","updated_at":"2024-10-16T14:22:08.000Z","dependencies_parsed_at":"2023-09-05T02:32:55.202Z","dependency_job_id":null,"html_url":"https://github.com/qdrvm/scale-codec-cpp","commit_stats":null,"previous_names":["qdrvm/scale-codec-cpp","soramitsu/scale-codec-cpp"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qdrvm%2Fscale-codec-cpp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qdrvm%2Fscale-codec-cpp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qdrvm%2Fscale-codec-cpp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qdrvm%2Fscale-codec-cpp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qdrvm","download_url":"https://codeload.github.com/qdrvm/scale-codec-cpp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250365330,"owners_count":21418670,"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":[],"created_at":"2024-08-02T02:00:59.680Z","updated_at":"2025-04-23T03:30:52.082Z","avatar_url":"https://github.com/qdrvm.png","language":"C++","readme":"# SCALE codec C++ implementation\n**SCALE (Simple Concatenated Aggregate Little-Endian)** is a lightweight serialization format commonly used in blockchain applications.\nMore details in [spec](https://docs.polkadot.com/polkadot-protocol/basics/data-encoding/#scale-codec) from Polkadot.\n\nIt allows encoding and decoding following data types:\n* Built-in integer types specified by size:\n  * ```uint8_t```, ```int8_t```\n  * ```uint16_t```, ```int16_t```\n  * ```uint32_t```, ```int32_t```\n  * ```uint64_t```, ```int64_t```\n* Multiprecision integer from boost:\n  * ```uint128_t```, ```int128_t```\n  * ```uint256_t```, ```int256_t```\n  * ```uint512_t```, ```int512_t```\n  * ```uint1024_t```, ```int1024_t```\n* boolean values\n* pairs, tuples and other structurally bindable types (limited by N members)\n* aggregates limited by N field (except array, that coded as collection)\n* compact integers represented by CompactInteger type (classic and JAM-compatible). **Unsigned only!**\n* optional values represented by ```std::optional\u003cT\u003e``` and ```boost::optional\u003cT\u003e```\n  * as special case of optional values ```*::optional\u003cbool\u003e``` is encoded using one byte following specification.\n* various collections of items\n  * if item codable\n  * encodes item by item in order of forward iterator\n  * decodes items by inserting in order as encoded\n* variants represented by ```std::variant\u003cT...\u003e``` and ```boost::variant\u003cT...\u003e```\n\n## encode(value, encoder)\nIt is function is in charge of encoding of value and store to backend set in encoder\n\n## decode(value, encoder)\nIt is function is in charge of read and decode data from backend set in encoder and initialize provided variable\n\n## Encoder \nclass Encoder is in charge of encoding data\nIt receives values over `encode()` function and store encoded data into EncoderBackend\nAdditionally it receive values over `\u003c\u003c` operator.\n\n## Decoder \nclass Decoder is in charge of decoding data\nIt initializes provided value over `decode()` function by decoded value from encoded source data\nAdditionally it initialize provided values over `\u003e\u003e` operator.\n\n## Example \n```c++\nstd::vector\u003cuint8_t\u003e out;\nToBytes encoder(out); // Encoder which used backend 'to bytes'\n\nuint32_t ui32 = 123u;\nuint8_t ui8 = 234u;\nstd::string str = \"asdasdasd\";\nauto * raw_str = \"zxczxczx\";\nbool b = true;\nCompactInteger ci = 123456789;\nboost::variant\u003cuint8_t, uint32_t, CompactInteger\u003e vint = CompactInteger(12345);\nstd::optional\u003cstd::string\u003e opt_str = \"asdfghjkl\";\nstd::optional\u003cbool\u003e opt_bool = false;\nstd::pair\u003cuint8_t, uint32_t\u003e pair{1u, 2u};\nstd::vector\u003cuint32_t\u003e coll_ui32 = {1u, 2u, 3u, 4u};\nstd::vector\u003cstd::string\u003e coll_str = {\"asd\", \"fgh\", \"jkl\"};\nstd::vector\u003cstd::vector\u003cint32_t\u003e\u003e coll_coll_i32 = {{1, 2, 3}, {4, 5, 6, 7}};\n\ntry {\n  // functional style\n  encode(ui32, encoder); \n  encode(ui8, encoder); \n  encode(str, encoder); \n  // combine for one call\n  encode(std::tie(raw_str, b, ci, vint), encoder);\n  // stream-style\n  encoder \u003c\u003c opt_str \u003c\u003c opt_bool \u003c\u003c pair \u003c\u003c coll_ui32 \u003c\u003c coll_str \u003c\u003c coll_coll_i32;\n} catch (std::runtime_error \u0026e) {\n  // handle error\n  // for example make and return outcome::result\n  return outcome::failure(e.code());\n}\n```\nYou can now get encoded data:\n```c++\nauto in = out;;\n```\nNow you can decode that data back:\n```c++\nFromBytes decoder(in); // Decoder which used backend 'from bytes'\n\nuint32_t ui32 = 0u;\nuint8_t ui8 = 0u;\nstd::string str;\nbool b = true;\nCompactInteger ci;\nboost::variant\u003cuint8_t, uint32_t, CompactInteger\u003e vint;\nstd::optional\u003cstd::string\u003e opt_str;\nstd::optional\u003cbool\u003e opt_bool;\nstd::pair\u003cuint8_t, uint32_t\u003e pair{};\nstd::vector\u003cuint32_t\u003e coll_ui32;\nstd::vector\u003cstd::string\u003e coll_str;\nstd::vector\u003cstd::vector\u003cint32_t\u003e\u003e coll_coll_i32;\ntry {\n  // functional style\n  decode(ui32, decoder); \n  decode(ui8, decoder); \n  decode(str, decoder); \n  // combine for one call\n  decode(std::tie(raw_str, b, ci, vint), decoder);\n  // stream-style\n  decoder \u003e\u003e opt_str \u003e\u003e opt_bool \u003e\u003e pair \u003e\u003e coll_ui32 \u003e\u003e coll_str \u003e\u003e coll_coll_i32;\n} catch (std::system_error \u0026e) {\n  // handle error\n}\n```\nNow we have variables initialized by decoded values\n\n## Custom types\nYou may need to encode or decode custom data types, you have to define custom `encode()` and `decode()` function.\nPlease note, that your custom data types must be default-constructible.\n```c++\nstruct MyType {\n    int a = 0;\n    std::string b;\n    \n    friend void encode(const MyType \u0026v, Encoder \u0026encoder) {\n      encoder \u003c\u003c a;\n      encode(b, encoder);\n    }\n    friend void decode(MyType \u0026v, Decoder \u0026decoder) {\n      decoder \u003e\u003e a;\n      decode(b, decoder);\n    }\n};\n```\nNow you can use them in collections, optionals and variants\n```c++\nstd::vector\u003cuint8_t\u003e out;\nEncoderToVector encoder(out)\nstd::vector\u003cMyType\u003e src_vec = {{1, \"asd\"}, {2, \"qwe\"}};\ntry { \n  encoder \u003c\u003c src_vec;\n} catch (...) {\n  // handle error\n}\n\nstd::vector\u003cuint8_t\u003e in = {...};\nDecoderFromSpan decoder(in);\nstd::vector\u003cMyType\u003e dst_vec;\ntry {\n  decode(dst, decoder);\n} catch (...) {\n  // handle error\n}\n```\n\n## Convenience functions\nLibrary provides ready well done function to encode/decode in one line. You should just use import it in you namespace: \n\n```c++\n// template \u003ctypename T\u003e \n// outcome::result\u003cstd::vector\u003cuint8_t\u003e\u003e encode(T \u0026\u0026value);\nusing ::scale::impl::bytes::encode;\n\nSomeClass object = {...};\nauto res = encode(object); // \u003c- Just one-line call\nif (res.has_value()) {\n  std::vector\u003cuint8_t\u003e encoded = std::move(res.value()); // Bytes of encoded data\n}\n\n// template \u003ctypename T\u003e \n// outcome::result\u003cT\u003e decode(const RangeOfBytes auto\u0026 span);\nusing ::scale::impl::memory::decode;\n\nBytesArray data = {...};\nauto res = decode\u003cSomeClass\u003e(data); // \u003c- Just one-line call\nif (res.has_value()) {\n  SomeClass object = std::move(res.value()); // Decoded value\n}\n\nusing ::scale::impl::bytes::EncoderToVector;\n\nSomeClass object = {...};\nstd::vector\u003cuint8_t\u003e out;\nEncoderToVector encoder;\ntry {\n    encoder \u003c\u003c object;\n    // or encode(object, decoder);\n    std::vector\u003cuint8_t\u003e encoded = std::move(res.value())\n} catch ...\n\nusing ::scale::impl::bytes::DecoderFromBytes;\n\nBytesArray in = {...};\nDecoderFromSpan decoder(in);\ntry {\n    Object object;\n    decoder \u003e\u003e object;\n    // or decode(object, decoder);\n} catch ...\n\n```\n","funding_links":[],"categories":["SCALE Codec"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqdrvm%2Fscale-codec-cpp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqdrvm%2Fscale-codec-cpp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqdrvm%2Fscale-codec-cpp/lists"}