{"id":28302616,"url":"https://github.com/taylordotfish/tagged-pointer","last_synced_at":"2025-06-14T05:31:57.909Z","repository":{"id":57669219,"uuid":"348617759","full_name":"taylordotfish/tagged-pointer","owner":"taylordotfish","description":"Platform-independent space-efficient tagged pointers in Rust","archived":false,"fork":false,"pushed_at":"2025-06-10T18:59:04.000Z","size":116,"stargazers_count":18,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-06-10T20:00:00.676Z","etag":null,"topics":["memory-efficient","platform-independent","pointer","rust","tag","tagged-pointers"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/taylordotfish.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,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-03-17T07:29:42.000Z","updated_at":"2025-06-10T18:59:08.000Z","dependencies_parsed_at":"2025-06-10T19:55:03.000Z","dependency_job_id":null,"html_url":"https://github.com/taylordotfish/tagged-pointer","commit_stats":{"total_commits":17,"total_committers":1,"mean_commits":17.0,"dds":0.0,"last_synced_commit":"04e9ca8aa794b7c162967d94d5f8589705253ac6"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taylordotfish%2Ftagged-pointer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taylordotfish%2Ftagged-pointer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taylordotfish%2Ftagged-pointer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taylordotfish%2Ftagged-pointer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/taylordotfish","download_url":"https://codeload.github.com/taylordotfish/tagged-pointer/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taylordotfish%2Ftagged-pointer/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259144751,"owners_count":22811926,"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":["memory-efficient","platform-independent","pointer","rust","tag","tagged-pointers"],"created_at":"2025-05-23T21:11:54.559Z","updated_at":"2025-06-14T05:31:57.877Z","avatar_url":"https://github.com/taylordotfish.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"tagged-pointer\n==============\n\nThis crate provides an implementation of [tagged pointers]: a\nspace-efficient representation of a pointer and integer tag. In particular,\nboth [`TaggedPtr`] and [`Option\u003cTaggedPtr\u003e`] are the size of a pointer\ndespite containing both a pointer and tag.\n\n[tagged pointers]: https://en.wikipedia.org/wiki/Tagged_pointer\n\nThis crate depends only on [`core`], so it can be used in `no_std`\nenvironments.\n\n[`core`]: https://doc.rust-lang.org/core/\n\nExample\n-------\n\n```rust\nuse core::mem::size_of;\nuse core::ptr::NonNull;\nuse tagged_pointer::TaggedPtr;\n\n#[repr(align(4))]\nstruct Item(u32, u32);\n\n// `TaggedPtr` and `Option\u003cTaggedPtr\u003e` are both the size of a pointer:\nassert_eq!(size_of::\u003cTaggedPtr\u003cItem, 2\u003e\u003e(), size_of::\u003c*mut ()\u003e());\nassert_eq!(size_of::\u003cOption\u003cTaggedPtr\u003cItem, 2\u003e\u003e\u003e(), size_of::\u003c*mut ()\u003e());\n\nlet item1 = Item(1, 2);\nlet item2 = Item(3, 4);\n\n// We can store two bits of the tag, since `Item` has an alignment of 4.\nlet tp1 = TaggedPtr::\u003c_, 2\u003e::new(NonNull::from(\u0026item1), 1);\nlet tp2 = TaggedPtr::\u003c_, 2\u003e::new(NonNull::from(\u0026item2), 3);\n\nlet (ptr1, tag1) = tp1.get();\nlet (ptr2, tag2) = tp2.get();\n\nassert_eq!((ptr1, tag1), (NonNull::from(\u0026item1), 1));\nassert_eq!((ptr2, tag2), (NonNull::from(\u0026item2), 3));\n```\n\nPlatform considerations\n-----------------------\n\nThe number of tag bits that can be stored in a pointer of a given type\ndepends on the type’s alignment. However, the alignment of many types is\n[platform-specific][primitive-layout]: `u64`, for example, could have an\nalignment of 8 on one platform and 4 on another.\n\nTherefore, it is highly recommended to use [`#[repr(align)]`][repr-align]\nto guarantee a minimum alignment, defining a wrapper type if necessary:\n\n```rust\n// This won't work on systems where `u64` has an alignment of 4!\nlet x: u64 = 123;\nlet tp = TaggedPtr::\u003cu64, 3\u003e::new(NonNull::from(\u0026x), 0b101);\n\n// Instead, do this:\n#[repr(align(8))]\nstruct MyU64(pub u64);\n\nlet x = MyU64(123);\nlet tp = TaggedPtr::\u003cMyU64, 3\u003e::new(NonNull::from(\u0026x), 0b101);\n```\n\n[primitive-layout]:\n https://doc.rust-lang.org/reference/type-layout.html#primitive-data-layout\n[repr-align]:\n https://doc.rust-lang.org/reference/type-layout.html#the-alignment-modifiers\n\nAssumptions\n-----------\n\nThis crate avoids making assumptions about the representations of pointers.\nIn particular, it does not cast pointers to `usize` and assume that the\nlower bits of that number can be used for tagging. There exist\narchitectures that do not allow reusing the lower bits of aligned pointers\nin this manner, and even if none are currently supported by Rust, that\ncould change in the future. This crate’s approach also works better with\n[strict provenance].\n\n[strict provenance]: https://github.com/rust-lang/rust/issues/95228\n\nPreviously, this crate relied on assumptions about the behavior of\n[`pointer::align_offset`][align_offset] in certain circumstances. These\nassumptions were effectively always true, but were not strictly guaranteed,\nso a fallback implementation was provided with the crate feature\n`fallback`, which would avoid relying on this assumption at the cost of\nspace efficiency.\n\nHowever, as of Rust 1.78, this assumption is no longer necessary:\n`align_offset` is [guaranteed to behave as required][121201].\n\n[align_offset]:\n https://doc.rust-lang.org/std/primitive.pointer.html#method.align_offset\n[121201]: https://github.com/rust-lang/rust/pull/121201/\n\n[`TaggedPtr`]: https://docs.rs/tagged-pointer/0.2/tagged_pointer/struct.TaggedPtr.html\n[`Option\u003cTaggedPtr\u003e`]: https://doc.rust-lang.org/std/option/enum.Option.html\n\nDocumentation\n-------------\n\n[Documentation is available on docs.rs.](https://docs.rs/tagged-pointer)\n\nLicense\n-------\n\ntagged-pointer is licensed under version 2 of the Apache License. See\n[LICENSE](LICENSE).\n\nContributing\n------------\n\nBy contributing to tagged-pointer, you agree that your contribution may be used\naccording to the terms of tagged-pointer’s license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftaylordotfish%2Ftagged-pointer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftaylordotfish%2Ftagged-pointer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftaylordotfish%2Ftagged-pointer/lists"}