![License](https://img.shields.io/badge/license-MPL--2.0-brightgreen) [![Build Status](https://travis-ci.com/qchateau/cbitstruct.svg?branch=master)](https://travis-ci.com/qchateau/cbitstruct)
# About
`cbitstruct` is a C implementation of the `bitstruct` library. Credits to Erik Moqvist for the original `bitstruct` library available on [Github](https://github.com/eerimoq/bitstruct) and [pip](https://pypi.org/project/bitstruct/).
The goal is to provide the same API an idealy to be able to interchange `import bitstruct` and `import cbitstruct as bitstruct`.
Obvious increased performance comes with limitations described below.
# Installation
```bash
pip3 install cbitstruct
```
# Documentation
Please refer to the [`bitstruct` documentation](https://bitstruct.readthedocs.io/en/latest/) as the aim of this library is to provide the same API with increased performance.
If you are not used to `bitstruct`, you should seriously consider using it first, before migrating to this library if you require higher performance.
# Limitations
| Limitation | Will it be lifted ? |
|------------|---------------------|
| All types except padding are limited to 64 bits | Maybe for 'raw' and 'text' types |
| May not work on big-endian architectures | Maybe |
| Exceptions differ from `bitstruct` | Probably not |
| CPython only | Probably not |
| Error messages are unclear | Will never be as clear as `bitstruct` |
| Python >= 3.5 | No |
Some limitations are there because I did not get the time or motivation to lift them up. Some other are deeply rooted into this library and may never be lifted.
# Performance
## Comparing to `bitstruct`
The script available in `tests/test_perf.py` measures performance comparing to the `bitstruct` library.
Here are the result "on my machine" (Ubuntu in Virtualbox on a laptop):
```
byteswap list of int | x 8.779 ( 8.638us -> 0.984us)
byteswap str | x 17.466 ( 9.158us -> 0.524us)
calcsize | x139.330 ( 61.060us -> 0.438us)
compiled pack | x 47.389 ( 35.968us -> 0.759us)
compiled pack_dict | x 27.184 ( 34.588us -> 1.272us)
compiled pack_into | x 32.037 ( 38.650us -> 1.206us)
compiled pack_into_dict | x 27.343 ( 37.718us -> 1.379us)
compiled unpack | x 33.928 ( 31.278us -> 0.922us)
compiled unpack_dict | x 21.627 ( 31.597us -> 1.461us)
compiled unpack_from | x 30.622 ( 29.977us -> 0.979us)
compiled unpack_from_dict | x 20.479 ( 30.936us -> 1.511us)
pack | x 77.003 ( 103.030us -> 1.338us)
pack_dict | x 53.254 ( 103.255us -> 1.939us)
pack_into | x 82.829 ( 119.373us -> 1.441us)
pack_into_dict | x 52.173 ( 108.135us -> 2.073us)
unpack | x 78.459 ( 91.896us -> 1.171us)
unpack_dict | x 40.287 ( 89.300us -> 2.217us)
unpack_from | x 77.027 ( 91.202us -> 1.184us)
unpack_from_dict | x 39.467 ( 88.043us -> 2.231us)
```
*Disclaimer:* these results may and will vary largely depending on the number of elements and types you pack/unpack. This script is provided as-is, and I will gladly accept an improved script providing more reliable results.
## The dict API
The `dict` API is marginally slower than the traditional one. As the packing/unpacking performance is quite high, the overhead of performing dictionary lookups and hashing significantly increas pack and unpacking duration.
Raw data
{
"_id": null,
"home_page": "https://github.com/qchateau/cbitstruct",
"name": "cbitstruct",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "bit, pack, unpack, struct, bitfield, bit parsing, bit unpack, bit pack, C",
"author": "Quentin CHATEAU",
"author_email": "quentin.chateau@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/f4/af/d7253b42a19bf01dc0dc3416ab23255e0e42af34d645d2908bb8a894afb5/cbitstruct-1.1.1.tar.gz",
"platform": null,
"description": "![License](https://img.shields.io/badge/license-MPL--2.0-brightgreen) [![Build Status](https://travis-ci.com/qchateau/cbitstruct.svg?branch=master)](https://travis-ci.com/qchateau/cbitstruct)\n\n# About\n\n`cbitstruct` is a C implementation of the `bitstruct` library. Credits to Erik Moqvist for the original `bitstruct` library available on [Github](https://github.com/eerimoq/bitstruct) and [pip](https://pypi.org/project/bitstruct/).\n\nThe goal is to provide the same API an idealy to be able to interchange `import bitstruct` and `import cbitstruct as bitstruct`.\n\nObvious increased performance comes with limitations described below.\n\n# Installation\n\n```bash\npip3 install cbitstruct\n```\n\n# Documentation\n\nPlease refer to the [`bitstruct` documentation](https://bitstruct.readthedocs.io/en/latest/) as the aim of this library is to provide the same API with increased performance.\n\nIf you are not used to `bitstruct`, you should seriously consider using it first, before migrating to this library if you require higher performance.\n\n# Limitations\n\n| Limitation | Will it be lifted ? |\n|------------|---------------------|\n| All types except padding are limited to 64 bits | Maybe for 'raw' and 'text' types |\n| May not work on big-endian architectures | Maybe |\n| Exceptions differ from `bitstruct` | Probably not |\n| CPython only | Probably not |\n| Error messages are unclear | Will never be as clear as `bitstruct` |\n| Python >= 3.5 | No |\n\nSome limitations are there because I did not get the time or motivation to lift them up. Some other are deeply rooted into this library and may never be lifted.\n\n# Performance\n\n## Comparing to `bitstruct`\n\nThe script available in `tests/test_perf.py` measures performance comparing to the `bitstruct` library.\n\nHere are the result \"on my machine\" (Ubuntu in Virtualbox on a laptop):\n```\nbyteswap list of int | x 8.779 ( 8.638us -> 0.984us)\nbyteswap str | x 17.466 ( 9.158us -> 0.524us)\ncalcsize | x139.330 ( 61.060us -> 0.438us)\ncompiled pack | x 47.389 ( 35.968us -> 0.759us)\ncompiled pack_dict | x 27.184 ( 34.588us -> 1.272us)\ncompiled pack_into | x 32.037 ( 38.650us -> 1.206us)\ncompiled pack_into_dict | x 27.343 ( 37.718us -> 1.379us)\ncompiled unpack | x 33.928 ( 31.278us -> 0.922us)\ncompiled unpack_dict | x 21.627 ( 31.597us -> 1.461us)\ncompiled unpack_from | x 30.622 ( 29.977us -> 0.979us)\ncompiled unpack_from_dict | x 20.479 ( 30.936us -> 1.511us)\npack | x 77.003 ( 103.030us -> 1.338us)\npack_dict | x 53.254 ( 103.255us -> 1.939us)\npack_into | x 82.829 ( 119.373us -> 1.441us)\npack_into_dict | x 52.173 ( 108.135us -> 2.073us)\nunpack | x 78.459 ( 91.896us -> 1.171us)\nunpack_dict | x 40.287 ( 89.300us -> 2.217us)\nunpack_from | x 77.027 ( 91.202us -> 1.184us)\nunpack_from_dict | x 39.467 ( 88.043us -> 2.231us)\n```\n\n*Disclaimer:* these results may and will vary largely depending on the number of elements and types you pack/unpack. This script is provided as-is, and I will gladly accept an improved script providing more reliable results.\n\n\n## The dict API\nThe `dict` API is marginally slower than the traditional one. As the packing/unpacking performance is quite high, the overhead of performing dictionary lookups and hashing significantly increas pack and unpacking duration.\n",
"bugtrack_url": null,
"license": "MPL-2.0",
"summary": "Faster C implementation of bitstruct",
"version": "1.1.1",
"project_urls": {
"Homepage": "https://github.com/qchateau/cbitstruct"
},
"split_keywords": [
"bit",
" pack",
" unpack",
" struct",
" bitfield",
" bit parsing",
" bit unpack",
" bit pack",
" c"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a17c332d40c952e1673f192cf21d46e493384ccdc767572ff48919b400aad635",
"md5": "f3cc8e14ab3608bf0dd38f321abb2a65",
"sha256": "09f67c0a15822b4081ef1381f0b25cd84cf23519b83ead9696f1fc2928eff11e"
},
"downloads": -1,
"filename": "cbitstruct-1.1.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "f3cc8e14ab3608bf0dd38f321abb2a65",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.6",
"size": 69503,
"upload_time": "2024-09-30T21:33:26",
"upload_time_iso_8601": "2024-09-30T21:33:26.501358Z",
"url": "https://files.pythonhosted.org/packages/a1/7c/332d40c952e1673f192cf21d46e493384ccdc767572ff48919b400aad635/cbitstruct-1.1.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "02bc221572ffe7bbcbb829d6e9120cf19b43473a53655b6eb9f51dbd7de8b1ac",
"md5": "3aacabe6cb2988f44b1c7a61c8575a07",
"sha256": "bc379915ebea545b3bf6a6054a81fa476f4b0d29485116fba4e8c33f61a52d92"
},
"downloads": -1,
"filename": "cbitstruct-1.1.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "3aacabe6cb2988f44b1c7a61c8575a07",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.6",
"size": 71451,
"upload_time": "2024-09-30T21:33:28",
"upload_time_iso_8601": "2024-09-30T21:33:28.708930Z",
"url": "https://files.pythonhosted.org/packages/02/bc/221572ffe7bbcbb829d6e9120cf19b43473a53655b6eb9f51dbd7de8b1ac/cbitstruct-1.1.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a6eaf748cb1f44478921de1e7ebf768aa356f0dfdad7baa358aea75837e0c405",
"md5": "0267be48494caa4309b4593a7280828a",
"sha256": "10d4dfb847f74b390ed526fae20ab8a03b6c118701b5ab6ddda3935a2183dd10"
},
"downloads": -1,
"filename": "cbitstruct-1.1.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "0267be48494caa4309b4593a7280828a",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.6",
"size": 72300,
"upload_time": "2024-09-30T21:33:30",
"upload_time_iso_8601": "2024-09-30T21:33:30.163900Z",
"url": "https://files.pythonhosted.org/packages/a6/ea/f748cb1f44478921de1e7ebf768aa356f0dfdad7baa358aea75837e0c405/cbitstruct-1.1.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "236882af091a856aad7b8242d29d4b3249e6d00d50e6d96ab6f0be568a07e21c",
"md5": "a847b903528c1fea2690d50244a7a52a",
"sha256": "684a03dd46390ca99cbb98dac190b55deed592570e634c34de540ae7db784984"
},
"downloads": -1,
"filename": "cbitstruct-1.1.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "a847b903528c1fea2690d50244a7a52a",
"packagetype": "bdist_wheel",
"python_version": "cp313",
"requires_python": ">=3.6",
"size": 71122,
"upload_time": "2024-09-30T21:33:31",
"upload_time_iso_8601": "2024-09-30T21:33:31.637779Z",
"url": "https://files.pythonhosted.org/packages/23/68/82af091a856aad7b8242d29d4b3249e6d00d50e6d96ab6f0be568a07e21c/cbitstruct-1.1.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2ba7ecc4649650c2519b13c593ed2af939fd2800e7cc07b1af357ebb138d4a31",
"md5": "a367d3a5fe7ca503a87f5a26ba86d2bf",
"sha256": "c63097a2838140b34928ee1c548a14a7ea538cc00b7909125585a063ee3cd53d"
},
"downloads": -1,
"filename": "cbitstruct-1.1.1-cp36-cp36m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "a367d3a5fe7ca503a87f5a26ba86d2bf",
"packagetype": "bdist_wheel",
"python_version": "cp36",
"requires_python": ">=3.6",
"size": 68137,
"upload_time": "2024-09-30T21:33:33",
"upload_time_iso_8601": "2024-09-30T21:33:33.118524Z",
"url": "https://files.pythonhosted.org/packages/2b/a7/ecc4649650c2519b13c593ed2af939fd2800e7cc07b1af357ebb138d4a31/cbitstruct-1.1.1-cp36-cp36m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f19dbfb9bed75a65ac7519151ca37ca2e673ca5c1f07612cbd6999f2c22a1559",
"md5": "ab2a849f112ab1e04be1d9e74d613b33",
"sha256": "9981be43e511acd334191ff004de319f34e527f1a11ebc4c2623c8db58b68b05"
},
"downloads": -1,
"filename": "cbitstruct-1.1.1-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "ab2a849f112ab1e04be1d9e74d613b33",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": ">=3.6",
"size": 68133,
"upload_time": "2024-09-30T21:33:34",
"upload_time_iso_8601": "2024-09-30T21:33:34.939008Z",
"url": "https://files.pythonhosted.org/packages/f1/9d/bfb9bed75a65ac7519151ca37ca2e673ca5c1f07612cbd6999f2c22a1559/cbitstruct-1.1.1-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "78053a91c92447a6d956aec9d88f137e3284be91b032aebf24828b34266a15a8",
"md5": "a6881db1f88568da29822ff9196d610d",
"sha256": "e6c1d1530044e8a81a10415d0262050d1353cc24c181c416a1b7caa771aa82e6"
},
"downloads": -1,
"filename": "cbitstruct-1.1.1-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "a6881db1f88568da29822ff9196d610d",
"packagetype": "bdist_wheel",
"python_version": "cp38",
"requires_python": ">=3.6",
"size": 69404,
"upload_time": "2024-09-30T21:33:36",
"upload_time_iso_8601": "2024-09-30T21:33:36.382175Z",
"url": "https://files.pythonhosted.org/packages/78/05/3a91c92447a6d956aec9d88f137e3284be91b032aebf24828b34266a15a8/cbitstruct-1.1.1-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e191e01ec1d7595ac801a728e5223bc6cffea252956aa30f002364fe4ad93dea",
"md5": "a3773d38646c1d1f085675d934bb921f",
"sha256": "e6590c032a1b65e8439628f3096aeee5b8e9bfa704e13509ab6e5c277404b425"
},
"downloads": -1,
"filename": "cbitstruct-1.1.1-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "a3773d38646c1d1f085675d934bb921f",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.6",
"size": 69355,
"upload_time": "2024-09-30T21:33:38",
"upload_time_iso_8601": "2024-09-30T21:33:38.426019Z",
"url": "https://files.pythonhosted.org/packages/e1/91/e01ec1d7595ac801a728e5223bc6cffea252956aa30f002364fe4ad93dea/cbitstruct-1.1.1-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f4afd7253b42a19bf01dc0dc3416ab23255e0e42af34d645d2908bb8a894afb5",
"md5": "8854cc45ae1ec0d575a17de802485824",
"sha256": "29e3a4113ac138228b8697284f8906e705a8b24851574ac60e20850e4245fca1"
},
"downloads": -1,
"filename": "cbitstruct-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "8854cc45ae1ec0d575a17de802485824",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 29972,
"upload_time": "2024-09-30T21:33:40",
"upload_time_iso_8601": "2024-09-30T21:33:40.068674Z",
"url": "https://files.pythonhosted.org/packages/f4/af/d7253b42a19bf01dc0dc3416ab23255e0e42af34d645d2908bb8a894afb5/cbitstruct-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-30 21:33:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "qchateau",
"github_project": "cbitstruct",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cbitstruct"
}