{"id":50903784,"url":"https://github.com/hatimhtm/c-fundamentals","last_synced_at":"2026-06-16T05:05:29.450Z","repository":{"id":357000260,"uuid":"1153907888","full_name":"hatimhtm/c-fundamentals","owner":"hatimhtm","description":"Canonical C11 reference: 7 sorts, binary search, 4 crypto primitives (Caesar/Vigenère/XOR/SHA-256), 7 data structures (linked list, stack, queue, BST, heap, trie, hash table), POSIX systems demos. Zero deps, 1009 test assertions, ASan + UBSan clean, GCC + Clang clean.","archived":false,"fork":false,"pushed_at":"2026-05-10T20:57:51.000Z","size":81,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-10T22:24:00.856Z","etag":null,"topics":["addresssanitizer","algorithms","binary-search","binary-search-tree","c","c11","data-structure","data-structures","encryption","hash-table","heap","linked-list","makefile","open-source","sha256","sorting","systems-programming","trie","undefined-behavior-sanitizer","vigenere"],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hatimhtm.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-09T20:05:19.000Z","updated_at":"2026-05-10T20:57:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hatimhtm/c-fundamentals","commit_stats":null,"previous_names":["hatimhtm/c-fundamentals"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/hatimhtm/c-fundamentals","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hatimhtm%2Fc-fundamentals","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hatimhtm%2Fc-fundamentals/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hatimhtm%2Fc-fundamentals/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hatimhtm%2Fc-fundamentals/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hatimhtm","download_url":"https://codeload.github.com/hatimhtm/c-fundamentals/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hatimhtm%2Fc-fundamentals/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34391761,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-16T02:00:06.860Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["addresssanitizer","algorithms","binary-search","binary-search-tree","c","c11","data-structure","data-structures","encryption","hash-table","heap","linked-list","makefile","open-source","sha256","sorting","systems-programming","trie","undefined-behavior-sanitizer","vigenere"],"created_at":"2026-06-16T05:05:28.795Z","updated_at":"2026-06-16T05:05:29.445Z","avatar_url":"https://github.com/hatimhtm.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/hero-banner-dark.svg\" /\u003e\n    \u003cimg src=\"assets/hero-banner.svg\" alt=\"C Fundamentals\" width=\"100%\" /\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/hatimhtm/c-fundamentals/actions/workflows/build.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/hatimhtm/c-fundamentals/build.yml?branch=main\u0026style=for-the-badge\u0026label=CI\u0026labelColor=1A1A1A\u0026color=CCFF00\" alt=\"CI\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://hatimhtm.github.io/c-fundamentals/\"\u003e\u003cimg src=\"https://img.shields.io/badge/DOCS-DOXYGEN-CCFF00?style=for-the-badge\u0026labelColor=1A1A1A\" alt=\"API docs\" /\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/STATUS-OPEN_SOURCE-CCFF00?style=for-the-badge\u0026labelColor=1A1A1A\" alt=\"Open source\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/C-11-1A1A1A?style=for-the-badge\u0026logo=c\u0026logoColor=CCFF00\" alt=\"C11\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Tests-1009_asserts-1A1A1A?style=for-the-badge\u0026labelColor=1A1A1A\" alt=\"1009 test assertions\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Sanitizers-ASan_%2B_UBSan-1A1A1A?style=for-the-badge\u0026labelColor=1A1A1A\" alt=\"ASan + UBSan clean\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/License-MIT-1A1A1A?style=for-the-badge\u0026labelColor=1A1A1A\" alt=\"MIT License\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  📖 \u003ca href=\"https://hatimhtm.github.io/c-fundamentals/\"\u003e\u003cstrong\u003eAPI docs (Doxygen)\u003c/strong\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eA reference implementation of the algorithms, data structures, cryptographic primitives, and systems calls every C programmer eventually writes by hand. Seven sorts, binary search, four crypto primitives (Caesar with chi-squared cracker, Vigenère, XOR, SHA-256), seven data structures (linked list, stack, queue, BST, heap / priority queue, trie, hash table), POSIX systems demos. Zero dependencies, 1009 test assertions, GCC + Clang clean on Linux + macOS, AddressSanitizer + UndefinedBehaviorSanitizer in CI.\u003c/em\u003e\n\u003c/p\u003e\n\n---\n\n### `/// WHAT'S INSIDE`\n\n| Module | Highlights |\n|---|---|\n| **Sorting** | Selection · Bubble · Insertion · Quicksort (Lomuto) · Merge sort (top-down with reusable aux buffer) · Heap sort (in-place) · Radix sort (LSD, byte-by-byte counting) |\n| **Searching** | Binary search — iterative + recursive, size_t-safe midpoint, both `int` and string variants |\n| **Encryption** | Caesar cipher with chi-squared frequency-analysis cracker · Vigenère polyalphabetic cipher · XOR stream cipher · **SHA-256 from scratch** (FIPS 180-4, validated against NIST test vectors) |\n| **Data structures** | Singly-linked list · Stack (growable array) · Queue (circular buffer with O(1) push/pop) · Binary search tree · Min-heap / priority queue (with linear `heap_build`) · Trie (26-way prefix tree) · Open-addressing hash table (djb2, linear probing, tombstones, auto-resize) |\n| **Systems** | Cross-platform `sysinfo` (uname, sysctl, sysconf, getloadavg, statvfs) · `signal-demo` showing graceful SIGINT/SIGTERM handling via `sigaction` + `volatile sig_atomic_t` |\n| **Benchmarks** | Empirical comparison of all seven sorts on `n={100, 1k, 10k}` random integers, deterministic seed |\n\n---\n\n### `/// QUICK START`\n\n```bash\ngit clone https://github.com/hatimhtm/c-fundamentals.git\ncd c-fundamentals\nmake all      # 8 binaries into build/\nmake test     # 1009 assertions across 13 test suites\nmake smoke    # run every CLI once with sample input\nmake asan     # rebuild with AddressSanitizer + run tests\nmake ubsan    # rebuild with UndefinedBehaviorSanitizer + run tests\n```\n\nCompiler swap: `make clean \u0026\u0026 make all CC=clang`. Custom flags: `make CFLAGS='-O3 -march=native ...'` (the defaults already include `-Wall -Wextra -Werror -pedantic`).\n\n---\n\n### `/// SORTING`\n\n```bash\n./build/sorting --algo=quick zebra ant mouse cat\n./build/sorting --algo=heap  apple zebra mango\necho -e \"foo\\nbar\\nbaz\" | ./build/sorting --algo=merge\n```\n\nAlgorithms: `selection · insertion · bubble · quick · merge · heap · radix` (radix is integers-only, others have both `*_ints` and `*_strings`).\n\n#### Sample benchmark output\n\n```\n| Algorithm  | n=100     | n=1000    | n=10000   |\n|------------|-----------|-----------|-----------|\n| Selection  |   0.01ms  |   0.58ms  |  72.73ms  |\n| Bubble     |   0.02ms  |   1.59ms  | 251.43ms  |\n| Insertion  |   0.00ms  |   0.41ms  |  20.51ms  |\n| Quicksort  |   0.01ms  |   0.07ms  |   0.84ms  |\n| Merge      |   0.04ms  |   0.08ms  |   0.82ms  |\n```\n\nRun `./build/benchmark` to regenerate; deterministic seed = 42.\n\n---\n\n### `/// SEARCHING`\n\n```bash\n./build/bsearch 7 3 1 9 7 4 2\n# Sorted: [1, 2, 3, 4, 7, 9]\n# Target: 7\n# Result: found at index 4\n```\n\nIterative + recursive variants, [tested for equivalence](tests/test_search.c) on every value 1..21 against a known sorted array.\n\n---\n\n### `/// ENCRYPTION`\n\n```bash\n# Caesar\n./build/crypto-cli -e 3 \"Hello World\"            # Khoor Zruog\n./build/crypto-cli -c \"Khoor Zruog\"              # → Guessed shift: 3 (chi-squared)\n\n# Vigenère\n./build/crypto-cli -v --key=lemon \"attack at dawn\"   # lxfopv ef rnhr\n\n# XOR (encrypt = decrypt; output is hex since it may contain non-printables)\n./build/crypto-cli -x --key=secret \"hello\"\n\n# SHA-256\n./build/crypto-cli -s \"abc\"\n# ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad\n```\n\nThe Caesar cracker uses **chi-squared distance** against standard English letter frequencies (not the naive \"most-common-letter == E\" approach). The SHA-256 implementation is straight from FIPS 180-4 — [validated against NIST test vectors](tests/test_sha256.c) including the empty string, \"abc\", and the 56-byte boundary-padding example.\n\n---\n\n### `/// DATA STRUCTURES`\n\nEach structure is a self-contained library — no inter-module deps except where noted (heap sort delegates max-sift-down to `data_structures/heap`).\n\n| Structure | API surface | Notes |\n|---|---|---|\n| `linked_list` | push_front/back, pop_front, find, reverse, size | Singly-linked, owns nodes |\n| `cf_stack` | push, pop, peek, size, is_empty | Growable array, doubles on full (renamed from `stack` to dodge POSIX `stack_t`) |\n| `queue` | enqueue, dequeue, peek, size | Circular buffer, head + size for full/empty disambiguation |\n| `bst` | insert, contains, min, max, in_order traversal | Plain binary search tree (no balancing) |\n| `heap` | insert, extract_min, peek_min, build_min (O(n)) | Min-heap; also exposes max-sift-down for heap sort |\n| `trie` | insert, contains, starts_with | 26-way prefix tree, lowercase a-z |\n| `hash_table` | set, get, remove, contains, size | Open addressing, djb2, linear probing, tombstones, auto-resize at 0.75 load |\n\nCLI demos for `linked_list` and `hash_table`. The rest are exercised by tests:\n\n```bash\n./build/linked-list-demo 1 2 3 4 5\n./build/hash-table-demo the cat sat on the mat\n```\n\n---\n\n### `/// SYSTEMS`\n\n```bash\n./build/sysinfo -v\n# OS, hostname, release, arch\n# User: name / home / shell / UID / GID\n# CPU info (Apple sysctlbyname or Linux sysconf)\n# Memory: hw.memsize / sysconf(_SC_PHYS_PAGES)\n# Load average via getloadavg()\n# Disk: total / used / available / percent via statvfs()\n\n./build/signal-demo 30\n# Demonstrates graceful SIGINT/SIGTERM/SIGHUP handling via sigaction.\n# Press Ctrl-C to trigger graceful shutdown.\n```\n\n`sysinfo` branches on `__APPLE__` for `sysctlbyname` (CPU brand, RAM); falls back to `sysconf` on Linux/BSD. `signal-demo` is a textbook example of the safe pattern: handler sets a `volatile sig_atomic_t` flag, main loop polls.\n\n---\n\n### `/// PROJECT LAYOUT`\n\n```\nc-fundamentals/\n├── algorithms/\n│   ├── sorting/         7 sorts + benchmark + sorts.h + main\n│   ├── searching/       binary_search.c/.h + main\n│   └── encryption/      caesar, vigenere, xor_cipher, sha256 + main (crypto-cli)\n├── data_structures/\n│   ├── linked_list/     library + demo\n│   ├── stack/           library  (cf_stack_t)\n│   ├── queue/           library\n│   ├── bst/             library\n│   ├── heap/            library  (also fuels heap sort)\n│   ├── trie/            library\n│   └── hash_table/      library + demo\n├── systems/\n│   ├── sysinfo/         POSIX + Apple sysctl\n│   └── signals/         signal-demo (sigaction, sig_atomic_t)\n├── tests/               13 suites, 1009 assertions, hand-rolled macros (zero deps)\n├── .github/workflows/   GCC × Clang × Linux × macOS + ASan/UBSan jobs\n├── assets/              hero banner SVGs\n├── Makefile             8 binaries + test + smoke + asan + ubsan + install\n└── README.md\n```\n\n---\n\n### `/// TESTING`\n\nHand-rolled assertion macros — `tests/test.h` defines `ASSERT`, `ASSERT_EQ_INT`, `ASSERT_EQ_STR`, `ASSERT_EQ_SIZE`, `ASSERT_TRUE/FALSE`, `ASSERT_NULL/NOT_NULL`. Failures print location + message but **do not abort**, so a single `make test` run reports every failure in every suite at once.\n\n```\n$ make test\n…\n────────────────────\nTotal assertions: 1009\nFailures:         0\n✓ All tests passed.\n```\n\n| Suite | What it covers |\n|---|---|\n| `test_sorts` | 7 algorithms × 2 type variants + edge cases (empty / 1 / sorted / reversed) |\n| `test_search` | Iterative · recursive · empty · missing · strings · iter-vs-recursive equivalence |\n| `test_caesar` | Encrypt · decrypt · negative + large shifts · punctuation · round-trip · chi-squared crack |\n| `test_vigenere` | Textbook example · case preserved · round-trip · empty key · punctuation passthrough |\n| `test_xor` | Round-trip · zero-key identity · empty-key passthrough |\n| `test_sha256` | NIST vectors: empty string, \"abc\", 56-byte boundary; hex format invariants |\n| `test_linked_list` | Create · push front/back · find · reverse · pop empty |\n| `test_stack` | LIFO order · peek · pop empty · resize stress to 100 elements |\n| `test_queue` | FIFO order · peek · circular wraparound + resize stress |\n| `test_bst` | Insert · contains · duplicate handling · min/max · in-order yields sorted |\n| `test_heap` | Min-priority extraction · peek · empty cases · O(n) build_min |\n| `test_trie` | Insert · contains · starts_with · rejects non-{a-z} input |\n| `test_hash_table` | Create · set/get · overwrite · remove · resize-rehash · slot reuse after remove |\n\n---\n\n### `/// CI`\n\n| Job | Matrix |\n|---|---|\n| **build** | `{ubuntu-latest, macos-latest} × {gcc, clang}` — build, run tests, run smoke |\n| **sanitizers** | `ubuntu-latest × clang` — full test suite under `-fsanitize=address` then `-fsanitize=undefined`; halts on the first UB it finds |\n\nEvery push to `main` and every PR triggers all five jobs. Concurrency group cancels superseded runs.\n\n---\n\n### `/// CONTRIBUTING`\n\nPull requests welcome. The code style is K\u0026R-ish, two-space indent, snake_case, doc comments on every public function. Please:\n\n1. Keep `-Wall -Wextra -Werror -pedantic` clean on both GCC and Clang.\n2. Add tests for new code — at minimum, one positive case + one edge case.\n3. Run `make asan \u0026\u0026 make ubsan` before opening a PR.\n4. Don't introduce dependencies. If you need a hash function, write it inline.\n\n---\n\n### `/// LICENSE`\n\n[MIT](LICENSE) — use it, fork it, ship something with it.\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://hatimelhassak.is-a.dev\"\u003e\u003cimg src=\"https://img.shields.io/badge/PORTFOLIO-1A1A1A?style=for-the-badge\u0026logo=vercel\u0026logoColor=CCFF00\" alt=\"Portfolio\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://cal.com/hatimelhassak/engineering-discovery\"\u003e\u003cimg src=\"https://img.shields.io/badge/BOOK_A_CALL-CCFF00?style=for-the-badge\u0026logo=googlecalendar\u0026logoColor=1A1A1A\" alt=\"Book a call\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.linkedin.com/in/hatim-elhassak/\"\u003e\u003cimg src=\"https://img.shields.io/badge/LINKEDIN-1A1A1A?style=for-the-badge\u0026logo=linkedin\u0026logoColor=CCFF00\" alt=\"LinkedIn\" /\u003e\u003c/a\u003e\n  \u003ca href=\"mailto:hatimelhassak.official@gmail.com\"\u003e\u003cimg src=\"https://img.shields.io/badge/EMAIL-1A1A1A?style=for-the-badge\u0026logo=gmail\u0026logoColor=CCFF00\" alt=\"Email\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ccode\u003e///\u0026nbsp;\u0026nbsp;OPEN FOR NEW WORK\u0026nbsp;\u0026nbsp;///\u0026nbsp;\u0026nbsp;CONTRACT \u0026amp; FREELANCE\u0026nbsp;\u0026nbsp;///\u0026nbsp;\u0026nbsp;REMOTE WORLDWIDE\u0026nbsp;\u0026nbsp;///\u003c/code\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhatimhtm%2Fc-fundamentals","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhatimhtm%2Fc-fundamentals","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhatimhtm%2Fc-fundamentals/lists"}