# C+

> C+ is a fast, safe systems programming language: native speed through LLVM, a borrow-checked ownership model, and two-way C ABI compatibility. The language core is small on purpose; everything else, including the standard library, is a package. This documents version 0.0.14.

## Introduction

- [Overview](https://cplus-lang.dev/docs/overview.md): What C+ is and what it leaves out: native code through LLVM, a borrow-checked ownership model, and the locked principles that keep every program locally legible.
- [Getting started](https://cplus-lang.dev/docs/getting-started.md): Install the cpc toolchain and compile your first C+ program, in both single-file and project mode.

## Language

- [Primitives & literals](https://cplus-lang.dev/docs/primitives.md): C+ primitive types and literals: sized integers and floats, bool, unit, str, raw pointers, and how integer, float, hex, binary, and character literals are written.
- [Variables & mutability](https://cplus-lang.dev/docs/variables.md): Bindings in C+: let, type inference, opt-in mut, deferred initialization, lexical scope, and module-scope const, static, and static mut.
- [Operators & arithmetic](https://cplus-lang.dev/docs/operators.md): Arithmetic in C+: overflow-checked by default with explicit wrapping operators, bitwise and shifts, byte-swap intrinsics, comparisons, and explicit width casts.
- [Control flow](https://cplus-lang.dev/docs/control-flow.md): Control flow in C+: if as statement and expression, while, the two for flavours plus iterators, loop / break / continue, and while let.
- [Functions](https://cplus-lang.dev/docs/functions.md): Functions in C+: declaration, the unit return, pub visibility, the explicit return rule, block tail expressions, generics with square brackets, and no overloading.
- [Arrays](https://cplus-lang.dev/docs/arrays.md): Fixed-size, stack-allocated, bounds-checked arrays in C+, the fill-array literal [EXPR; N] with its memset fast path, and const-named lengths.
- [Structs & methods](https://cplus-lang.dev/docs/structs-and-methods.md): Define data with struct and behaviour with impl: associated functions, instance methods, the three receiver forms, struct literals, and field visibility.
- [Enums](https://cplus-lang.dev/docs/enums.md): Plain C-like enums and tagged unions (sum types) in C+, including generic enums and the rule that type arguments are always written at the source level.
- [Pattern matching](https://cplus-lang.dev/docs/pattern-matching.md): Exhaustive match, catch-all arms, and the if let / guard let / while let binding forms for extracting values from tagged enums in C+.

## Ownership & safety

- [Ownership](https://cplus-lang.dev/docs/ownership.md): C+ ownership: move-by-default, the borrow and mut parameter markers, structural Copy, restrict, and what the compiler enforces versus what it trusts you to uphold.
- [Drop & defer](https://cplus-lang.dev/docs/drop-and-defer.md): Deterministic cleanup in C+: a drop method as your destructor, hand-freeing raw-pointer fields, and defer for LIFO scope-exit actions.
- [The borrow checker](https://cplus-lang.dev/docs/borrow-checker.md): Aliasing XOR mutability: the single rule the C+ borrow checker enforces at compile time, the common diagnostics, and how a scope boundary fixes them.
- [Error handling](https://cplus-lang.dev/docs/error-handling.md): Errors as values in C+: tagged-union results, exhaustive match, the guard let happy path, and stdlib Result and Option. No exceptions, no ? operator.

## Systems

- [FFI — calling C](https://cplus-lang.dev/docs/ffi.md): Calling C from C+ with extern fn: declaring symbols, c-string literals, raw pointers and unsafe, #[repr(C)] layout, #[link_name], Objective-C interop, and the ABI gotchas that bite.
- [Function pointers](https://cplus-lang.dev/docs/function-pointers.md): Function pointers in C+: the fn(...) -> R type, bare-name coercion, structs of callbacks, and the C convention for stateful callbacks without closures.
- [Compile-time intrinsics](https://cplus-lang.dev/docs/intrinsics.md): The #name(...) compiler intrinsics in C+: typed queries (size_of, align_of, addr_of, zero), compile-time data embedding (include_bytes, include_str, env), and CPU hints.
- [Modules & packages](https://cplus-lang.dev/docs/modules-and-packages.md): Imports in C+: single-file vs project mode, the mandatory local (./) or vendored import form, the required alias, pub for visibility, and the Cplus.toml manifest.
- [Attributes](https://cplus-lang.dev/docs/attributes.md): Attributes in C+ are pure metadata: #[test], #[repr(C)], the loop hints #[unroll] and #[vectorize_width], #[inline] control, the real-time contracts, and doc comments.
- [Threads & atomics](https://cplus-lang.dev/docs/threads.md): Concurrency in C+: spawn and join, passing data with spawn_with, the partition-and-join pattern, atomics with explicit ordering, and refcounted mutexes.
- [Async / await](https://cplus-lang.dev/docs/async.md): Async in C+: async fn returning Future[T], await, the signature rules that ban borrow-shaped parameters, and the kqueue-backed reactor for concurrent I/O.
- [SIMD types](https://cplus-lang.dev/docs/simd.md): Fixed-width SIMD as primitive types in C+: the 64/128/256-bit lane families, constructors, per-element-type methods, lane conversions, widen/narrow, reductions, masks, and the FFI boundary.
- [Real-time](https://cplus-lang.dev/docs/realtime.md): Compiler-proven real-time contracts in C+: #[realtime], #[no_alloc], #[no_block], #[max_stack], the [profile.realtime] project gate, and the lock-free rt building blocks.
- [Inline assembly](https://cplus-lang.dev/docs/inline-assembly.md): Inline assembly in C+: the #asm block, Rust-style named operands with in/out/inout and register constraints, clobbers, and #[naked] functions that supply their own prologue.

## Packages

- [Overview](https://cplus-lang.dev/docs/packages.md): How packages work in C+: the small language core plus a curated set of vendored packages, including the standard library. Deployment model and the full package list.
- [stdlib](https://cplus-lang.dev/docs/packages/stdlib.md): The C+ standard library: I/O, vectors, hash maps, files, networking, ownership wrappers (Box, Arc, Rc), concurrency, and result/option types. A vendored package, imported per module.
- [accelerate](https://cplus-lang.dev/docs/packages/accelerate.md): Bindings to Apple's Accelerate.framework: pre-tuned CPU numerics (BLAS via cblas, element-wise and reductions via vdsp) that ship in every macOS binary.
- [appkit](https://cplus-lang.dev/docs/packages/appkit.md): Typed Cocoa / AppKit bindings for native macOS desktop apps: application lifecycle, windows, views, controls, and closure-free callbacks.
- [arena](https://cplus-lang.dev/docs/packages/arena.md): A growable, multi-chunk bump-pointer arena for allocate-many, free-all workloads like parsers, compilers, and request-scoped allocations.
- [clap](https://cplus-lang.dev/docs/packages/clap.md): Command-line argument parsing with a fluent builder: flags, long and short options, positional arguments, and typed match accessors.
- [jni](https://cplus-lang.dev/docs/packages/jni.md): Minimal Java Native Interface bindings: #[repr(C)] mirrors of the JVM dispatch tables, called through a function-pointer table exactly as C's JNI does.
- [json](https://cplus-lang.dev/docs/packages/json.md): A typed-enum JSON parser and serializer: a recursive Value enum, parse and to_string entry points, and is_* / as_* accessors. Drops payloads recursively.
- [log](https://cplus-lang.dev/docs/packages/log.md): A leveled, zero-allocation structured logger to stderr: configure level and colors once, then log at trace / debug / info / warn / error with no malloc per call.
- [metal](https://cplus-lang.dev/docs/packages/metal.md): Typed Metal and MPS bindings for Apple GPU compute: devices, command queues, buffers, compute pipelines, and pre-tuned MPS matmul / FFT / softmax.
- [simd](https://cplus-lang.dev/docs/packages/simd.md): 3D math on f32x4 plus integer-widening lane helpers: Vec3, Vec4, Mat4x4, and composable integer lane ops like a 16-lane signed-byte dot product.
- [static-arena](https://cplus-lang.dev/docs/packages/static-arena.md): A fixed-size bump-pointer arena whose buffer lives on the stack or in static storage: zero malloc, zero free, composes with the #[no_alloc] real-time contract.
- [uuid](https://cplus-lang.dev/docs/packages/uuid.md): RFC 4122 v4 UUIDs sourced from /dev/urandom, portable across macOS, Linux, and BSD. Generate, parse, and format with an infallible to_string.
- [rt](https://cplus-lang.dev/docs/packages/rt.md): Lock-free, allocation-free real-time building blocks: the SpscRingU64 ring and FixedPoolU64 object pool, plus the rt_darwin platform controls (clock, thread QoS, page locking).

## Reference

- [Tooling — cpc](https://cplus-lang.dev/docs/tooling.md): The cpc command-line tool: build and check, release mode, fmt, test, the code-graph queries, MCP server, IR and assembly emission, and linking against Apple frameworks.
- [Error codes](https://cplus-lang.dev/docs/error-codes.md): An index of the C+ compiler diagnostics (E0300 through E0909 and the W0001 / W0002 warnings): what each code means and the typical fix. Every diagnostic carries a span and often a machine-applicable suggestion.
- [C+ for LLMs](https://cplus-lang.dev/docs/llms.md): Why C+ is shaped for model-generated code: a small surface, specific diagnostics, a resolved code graph queryable over MCP, hand-emitted LLVM IR, and contracts the compiler can check.

## Guides

- [Your first C+ program](https://cplus-lang.dev/guides/your-first-cplus-program): Install the toolchain, write a real C+ program, and learn the write, audit, run loop that C+ is built around. No prior systems experience needed.
- [Structs, ownership, and errors in C+](https://cplus-lang.dev/guides/structs-ownership-and-errors): Model your data with structs and methods, understand C+ ownership without the borrow-checker fight, and handle errors as plain values. With verified, runnable examples.
- [FFI, real-time, and performance in C+](https://cplus-lang.dev/guides/ffi-realtime-and-performance): Call C and let C call you back, give the optimizer the aliasing facts it needs, and let the compiler prove a hot path never allocates or blocks. All with verified examples.
- [Writing correct C+: a guide for language models](https://cplus-lang.dev/guides/writing-correct-cplus): A dense generation guide for an LLM about to write or edit C+. The compiler-enforced rules, the canonical patterns, the things never to propose, and the self-audit loop.
- [Navigate C+ by its code graph, not grep](https://cplus-lang.dev/guides/code-graph-not-grep): How a language model understands a C+ codebase using cpc's resolved, typed code graph (cpc query and cpc mcp) instead of grep: precise definitions, callers, and a one-call context pack.
- [Should your team adopt C+?](https://cplus-lang.dev/guides/should-your-team-adopt-cplus): An honest evaluation brief for technical leaders: what C+ is, where it fits, how adoption works, what the risks are, and when not to use it.

## Examples

- [Ray tracer](https://cplus-lang.dev/examples/raytracer): A complete path tracer in one C+ file: 10 spheres with Lambertian, metal, and dielectric materials, rendered to a PPM image. Full source, a walkthrough, the numbers it produces, and how to reproduce them.

## Optional

- [Full documentation](https://cplus-lang.dev/llms-full.txt): every manual page for v0.0.14 concatenated as one markdown document