> ## Documentation Index
> Fetch the complete documentation index at: https://hypotenuse.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# plstd: The C△ Standard Library Reference and Guide

> plstd is the official C△ standard library. Each module is a self-contained .plib file with no headers, preprocessor, or separate implementation files.

`plstd` is the official standard library for C△. Unlike C and C++ where you juggle `.h` headers, preprocessor guards, and separate implementation files, every plstd library lives in a single `.plib` file written entirely in C△ — the same language you write your own code in. A `.plib` file is complete and self-contained: no header-implementation split, no separate preprocessor pass, just C△ code that can use every language feature including `dynam` arrays, `typed struct` inheritance, and `asm` blocks for low-level operations.

## What's in plstd

<CardGroup cols={2}>
  <Card title="Output" icon="terminal">
    `printd` and `printfs` — type-aware single-value printing and formatted output with f-string interpolation and `%`-style specifiers.
  </Card>

  <Card title="Strings" icon="text-size">
    `strcmp`, `strcpy`, `strcat`, `strlen`, `strdup`, `strchr`, `strstr`, `strncpy`, `strncat`, `strncmp` — a full suite of string operations built on top of C△'s first-class `string` type.
  </Card>

  <Card title="File I/O" icon="file">
    The `streamer` library provides file read/write operations for portable I/O across supported platforms.
  </Card>

  <Card title="Architecture-Aware" icon="microchip">
    plstd uses conditional compilation to ship optimized implementations for x86\_64 Linux and ARM64 macOS. The compiler picks the right path automatically — you never need to think about it.
  </Card>
</CardGroup>

## Importing plstd

You can import plstd at any level of granularity — pull in everything, cherry-pick individual functions, or skip imports entirely and let the compiler sort it out.

```c theme={null}
// Import everything from plstd
using <plstd>;

// Import a specific function — this rewrites the library name in the
// current file from `plstd` to `printd`. Only `printd` is in scope.
using printd from <plstd>;

// Globalize symbols so you can call them unqualified (e.g. `printd(...)`).
// `expose` takes the current library name. After `using <plstd>` that's
// `plstd`; after `using printd from <plstd>` it's `printd`.
expose plstd;       // after `using <plstd>;`
expose printd;      // after `using printd from <plstd>;`

// Explicit namespace access without exposing — use this when you haven't
// run `expose`. The namespace is whatever the current library name is.
printd@plstd("value: %d\n", 42);   // after `using <plstd>;`
printd@printd("value: %d\n", 42);  // after `using printd from <plstd>;`
```

<Tip>
  The compiler automatically imports any plstd symbol you use in your code. You still must reference a function properly, either by exposing it or by utilizing '@'.
</Tip>

## Library Locations

When the Hypotenuse Compiler resolves a `.plib` import, it searches two locations in order:

| Location | Path                  | Purpose                                                    |
| -------- | --------------------- | ---------------------------------------------------------- |
| System   | `/usr/lib/PLIBS/`     | libraries, installed by `make full-install`                |
| User     | `~/.local/lib/PLIBS/` | libraries, fallback search path if privileges aren't given |

System libraries are available to all users on the machine. User libraries are private to your account and take precedence over system libraries of the same name.

## Managing Libraries

Use the `hypotenuse` compiler driver to install or remove `.plib` files from your local library path.

```bash theme={null}
# Install a library to PLIBS
hypotenuse -i mylib.plib

# Remove a library from PLIBS
hypotenuse -r mylib
```

<Note>
  `hypotenuse -i` installs into your user library path (`~/.local/lib/PLIBS/`) or `/usr/lib/PLIBS/` if present.
</Note>

## Writing Your Own Library

Creating a `.plib` library is no different from writing any other C△ code. Use the same `.ctri` syntax, leverage every C△ feature you need, and wrap your exports in a `space` (namespace) block to avoid name collisions with user code.

```c yourlib.plib theme={null}
space mylib {
    int add(int a, int b) {
        return a + b;
    }
}
```

Once you've written your library, install it and import it like any other plstd module:

```c theme={null}
// After running: hypotenuse -i yourlib.plib

// Import the whole library
using <yourlib>;

// Or import a single symbol
using add from "yourlib";

// Or access explicitly with the namespace operator
int result = add@mylib(3, 4);
```

<Accordion title="Can I use asm blocks in my library?">
  Yes. C△ `asm` blocks work inside `.plib` files just as they do in regular `.ctri` source files. Use `#ifdef __x86_64__` and `#ifdef __aarch64__` guards if you need architecture-specific paths.
</Accordion>