{"id":22301246,"url":"https://github.com/frehberg/seq-rs","last_synced_at":"2025-07-29T02:32:24.112Z","repository":{"id":57666709,"uuid":"105700981","full_name":"frehberg/seq-rs","owner":"frehberg","description":"Sequence container type for Rust","archived":false,"fork":false,"pushed_at":"2019-08-11T16:56:47.000Z","size":138,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-10-31T11:35:46.198Z","etag":null,"topics":["container","library","rust","sequence","type"],"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/frehberg.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}},"created_at":"2017-10-03T20:41:05.000Z","updated_at":"2021-10-19T09:12:31.000Z","dependencies_parsed_at":"2022-09-26T20:31:40.069Z","dependency_job_id":null,"html_url":"https://github.com/frehberg/seq-rs","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frehberg%2Fseq-rs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frehberg%2Fseq-rs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frehberg%2Fseq-rs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frehberg%2Fseq-rs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/frehberg","download_url":"https://codeload.github.com/frehberg/seq-rs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227581839,"owners_count":17789312,"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":["container","library","rust","sequence","type"],"created_at":"2024-12-03T18:19:26.426Z","updated_at":"2024-12-03T18:19:27.195Z","avatar_url":"https://github.com/frehberg.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# seq module\n\nThe module `seq` provides the lightweight, generic sequence container `Seq` for unmovable data.\n\nThe container `Seq` is linking data of hierarchical function-scopes on top of each other,\nforming sequences. A sequence can be embedded into the program during compile time.\n\nInitially a sequence is empty. A longer sequence is constructed (see `Seg::ConsRef`) attaching a\nnew _head_ to the existing sequence, representing the _tail_.  The _head_ element has a shorter\nlifetime, than all elements of the _tail_.\n\nMultiple sequences may share the same _tail_, permitting memory-efficient organisation of\nhierarchical data.\n\nThe associated methods `Seq::head` and `Seq::tail` have been defined for convenience reasons only.\nThe construction and deconstruction of a sequence is realized by the algebraic data-types of Rust\nsolely.\n\n## Usage\n\nPut this in your Cargo.toml:\n```toml\n## Cargo.toml file\n[dependencies]\nseq = \"0.6\"\n```\n\nThe \"default\" usage of this type as a queue is to use `Empty` or `ConsRef` to construct a\nqueue, and `head` and `tail` to deconstruct a queue into head and remaining\ntail of a sequence.\n\n### Lite-Seq - Without dynamic memory\nIf enabling the feature 'lite-seq', the support for the box-ed elements `Seq::ConsOwn(..)` is removed, \nlimiting the seq-containers to static elements or elements in lexical scope. This feature might\nbe interesting for `no_std` build-environments, without support for dynamic memory or `malloc`.\n\n```\n[dependencies.seq]\nfeatures = [\"lite-seq\"]\nversion = \"^0.6\"\ngit = \"https://github.com/frehberg/seq-rs.git\"\n```\n\n\n```rust\npub enum Seq\u003c'a, T: 'a\u003e {\n    Empty,\n    ConsRef(T, \u0026'a Seq\u003c'a, T\u003e),\n    ConsOwn(T, Box\u003cSeq\u003c'a, T\u003e\u003e),\n}\n```\n\n## Examples\n\nConstructing two sequences seq1 as `[1,0]` and seq2 as `[2,1,0]`, sharing data with `seq1`\n```rust\n// constructing the sequence 'seq1'\nconst seq1: Seq\u003ci32\u003e = Seq::ConsRef(1, \u0026Seq::ConsRef(0, \u0026Seq::Empty));\n\n// construction the sequence 'seq2' sharing data with 'seq1'\nconst seq2: Seq\u003ci32\u003e = Seq::ConsRef(2, \u0026seq1);\n```\nDeconstructing a sequence  into the `head` and `tail`\n```rust\nfn deconstruct\u003c'a\u003e(seq: \u0026'a Seq\u003ci32\u003e) {\n   let head = seq.head().unwrap());\n   let tail = seq.tail().unwrap();\n   // more code here\n   ///\n}\n```\nExtend an existing sequence. Note the lifetime of the return type matches the one of the tail.\n```rust\nfn extend\u003c'a\u003e(head: i32, tail: \u0026'a Seq\u003ci32\u003e) -\u003e Seq\u003c'a, i32\u003e {\n   return Seq::ConsRef(head, tail);\n}\n```\nExtend an existing sequence with dynamic element residing in heap-memory\n```rust\nfn extend_boxed\u003c'a\u003e(head: i32, tail: \u0026'a Seq\u003ci32\u003e) -\u003e Box\u003cSeq\u003c'a, i32\u003e\u003e {\n   return Box::new(Seq::ConsRef(head, tail));\n}\n```\nIterate a sequence\n```rust\nfn sum_up(seq: \u0026Seq\u003ci32\u003e) -\u003e i32 {\n   return seq.into_iter().fold(0, |x, y| x + y);\n}\n```\n\n## Memory layout\n\nThe following image illustrates the sequences `s`, `t`, `u`. The sequence `s` is a sub-sequence of `t`, and `t` \nbeing a sub-sequence of `u`; each one accessible in its function context only. One can create a new sequence containing additional elements, wihtout the need to create a copy of all elements.\n![Illustration of sequence elements in stack frames](./doc/illustration.svg)\n\nFor use-cases where a sub-routine/expression shall return a temporary extended sequence, it is possible to construct new \nsequences using elements in heap-memory. In this case these heap-elements are boxed/owned.\n![Illustration of sequence elements in stack frames and heap](./doc/illustration-with-heap.svg)\n\n## Benchmarks\nThe data structure `Seq` implements a linked list. In terms of performance it cannot compete with a native\narray. But, `Seq` ranks between the containers `Vec` and `LinkedList`.\n\nThe benchmark is a memory-intensive, recursive function call and benefits from consecutive memory;\neach recursive function-call a new integer element is appended and an iterator is cumulating all elements.\n\nAs the benchmark-chart demonstrates, the container `Seq` performs better than `Vec` and`LinkedList` for up to\n`N=16` elements; and even shows better performance than `LinkedList`, and lower variants up to a\ncertain bound. The benchmark is performed for N= 8, 16, 32, 64, 128, 256, 512.\n\nThe test-environment is using a Lenovo-x260 laptop using `rustc 1.27.0-nightly (bd40cbbe1 2018-04-14)`.\n\n```\u003e cargo bench --features benchmark```\n\n```commandline\ntest benchmark::bench_array_008  ... bench:          28 ns/iter (+/- 2)\ntest benchmark::bench_array_016  ... bench:          70 ns/iter (+/- 0)\ntest benchmark::bench_array_032  ... bench:         156 ns/iter (+/- 7)\ntest benchmark::bench_array_064  ... bench:         368 ns/iter (+/- 10)\ntest benchmark::bench_array_128  ... bench:         920 ns/iter (+/- 39)\ntest benchmark::bench_array_256  ... bench:       2,639 ns/iter (+/- 138)\ntest benchmark::bench_array_512  ... bench:       8,355 ns/iter (+/- 263)\ntest benchmark::bench_list_008   ... bench:         179 ns/iter (+/- 8)\ntest benchmark::bench_list_016   ... bench:         396 ns/iter (+/- 17)\ntest benchmark::bench_list_032   ... bench:       1,053 ns/iter (+/- 58)\ntest benchmark::bench_list_064   ... bench:       3,433 ns/iter (+/- 173)\ntest benchmark::bench_list_128   ... bench:      12,158 ns/iter (+/- 276)\ntest benchmark::bench_list_256   ... bench:      48,419 ns/iter (+/- 585)\ntest benchmark::bench_list_512   ... bench:     186,391 ns/iter (+/- 4,401)\ntest benchmark::bench_seq_008    ... bench:          44 ns/iter (+/- 1)\ntest benchmark::bench_seq_016    ... bench:         135 ns/iter (+/- 10)\ntest benchmark::bench_seq_032    ... bench:         648 ns/iter (+/- 41)\ntest benchmark::bench_seq_064    ... bench:       2,964 ns/iter (+/- 75)\ntest benchmark::bench_seq_128    ... bench:      11,654 ns/iter (+/- 278)\ntest benchmark::bench_seq_256    ... bench:      44,908 ns/iter (+/- 570)\ntest benchmark::bench_seq_512    ... bench:     175,569 ns/iter (+/- 4,009)\ntest benchmark::bench_vec_008    ... bench:          93 ns/iter (+/- 4)\ntest benchmark::bench_vec_016    ... bench:         182 ns/iter (+/- 4)\ntest benchmark::bench_vec_032    ... bench:         353 ns/iter (+/- 13)\ntest benchmark::bench_vec_064    ... bench:         676 ns/iter (+/- 8)\ntest benchmark::bench_vec_128    ... bench:       1,415 ns/iter (+/- 78)\ntest benchmark::bench_vec_256    ... bench:       3,485 ns/iter (+/- 212)\ntest benchmark::bench_vec_512    ... bench:      11,261 ns/iter (+/- 425)\n```\n\n![Benchmark chart](./doc/bench-chart.jpg)\n\nEvery element of `Seq` is causing overhead of ca 16 bytes for the discriminator, and the reference\nto the tail.\n\n## Conclusion\nThese benchmarks show, the collection `Seq` shows better performance than `Vec` for 16 elements or less, and even\nbetter performance than `LinkedList` for all test-cases up to 512 elements. In this range `Seq` benefits from stack-memory.\nWhen `N\u003e32` the performance drops, probably caused by page-faults and the need to request additional stack memory-pages from OS, getting similar to the performance of linked-lists.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrehberg%2Fseq-rs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffrehberg%2Fseq-rs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrehberg%2Fseq-rs/lists"}