> ## 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.

# String Operations in C△: plstd String Library Guide

> C△'s first-class string type pairs with plstd's optimized string library to give you comparison, copy, concat, and search — tuned for x86_64 and ARM64.

C△ has a first-class `string` type with automatic memory management — the compiler handles allocation and deallocation so you never call `malloc` or `free` for ordinary string work. On top of that foundation, the plstd `string` library provides the full set of string utility functions you'd expect from a systems language: comparison, copying, concatenation, searching, and more. Every function in the library has architecture-optimized implementations for x86\_64 Linux and ARM64 macOS, selected automatically at compile time.

## The `string` Type

Declare a string with the `string` keyword and assign it a string literal. Concatenation uses the `+` operator, and the built-in `len()` function gives you the character count — no boilerplate, no null-terminator arithmetic.

```c theme={null}
string greeting = "Hello, world!";
string name = "Hypotenuse";

// Concatenate with the + operator
string full = greeting + " " + name;

// Get character count with len()
int l = len(greeting);  // 13
```

<Note>
  Strings in C△ are managed by the compiler. You do not need to allocate or free them manually. The compiler inserts the necessary lifetime management during compilation.
</Note>

## Comparison

Compare strings with `==` and `!=` exactly as you would with any other value. The compiler lowers these operators to `strcmp` calls automatically — you get readable code without giving up correctness.

```c theme={null}
string greeting = "Hello, world!";

if (greeting == "Hello, world!") {
    printd("match!");
}

if (greeting != "Goodbye") {
    printd("not a farewell");
}
```

<Tip>
  Prefer `==` and `!=` for equality checks in everyday code. Drop down to the explicit `strcmp` function from plstd when you need the full signed comparison result (negative, zero, or positive) — for example, when sorting strings.
</Tip>

## String Utility Functions

The plstd `string` library exposes the following functions. Import them with `using <plstd>;` or individually with `using strcmp from <plstd>;`.

<Accordion title="strcmp(a, b) — Compare two strings">
  Returns `0` if `a` and `b` are equal, a negative value if `a` sorts before `b`, and a positive value if `a` sorts after `b`.

  ```c theme={null}
  int result = strcmp("apple", "banana");
  if (result == 0) {
      printd("strings are equal");
  }
  ```
</Accordion>

<Accordion title="strncmp(a, b, n) — Compare first n characters">
  Compares up to `n` characters of `a` and `b`. Useful when you only care about a prefix.

  ```c theme={null}
  int result = strncmp("foobar", "foobaz", 5);  // compares "fooba" == "fooba" → 0
  ```
</Accordion>

<Accordion title="strcpy(dest, src) — Copy a string">
  Copies `src` into `dest` and returns `dest`. Make sure `dest` has enough space to hold `src`.

  ```c theme={null}
  string buf = "          ";   // pre-allocated space
  strcpy(buf, "hello");
  ```
</Accordion>

<Accordion title="strncpy(dest, src, n) — Copy up to n characters">
  Copies at most `n` characters from `src` into `dest`. Pads with null bytes if `src` is shorter than `n`.

  ```c theme={null}
  strncpy(buf, "hello", 3);   // copies "hel"
  ```
</Accordion>

<Accordion title="strcat(dest, src) — Concatenate strings">
  Appends `src` to the end of `dest` and returns `dest`. For most cases the `+` operator is more ergonomic; use `strcat` when working with pre-allocated buffers.

  ```c theme={null}
  string s = "Hello, ";
  strcat(s, "world!");   // s is now "Hello, world!"
  ```
</Accordion>

<Accordion title="strncat(dest, src, n) — Concatenate up to n characters">
  Appends at most `n` characters from `src` onto `dest`.

  ```c theme={null}
  strncat(s, "world!", 3);   // appends "wor"
  ```
</Accordion>

<Accordion title="strlen(s) — String length">
  Returns the number of characters in `s`, not counting the null terminator. In most C△ code you should prefer the built-in `len()` — see the section below. Use `strlen` when you need the plstd-level function explicitly.

  ```c theme={null}
  int n = strlen("hello");   // 5
  ```
</Accordion>

<Accordion title="strdup(s) — Duplicate a string">
  Allocates a new string and copies `s` into it, returning the copy.

  ```c theme={null}
  string original = "data";
  string copy = strdup(original);
  ```
</Accordion>

<Accordion title="strchr(s, c) — Find a character">
  Returns the index of the first occurrence of character `c` in `s`, or `-1` if not found.

  ```c theme={null}
  int idx = strchr("hello", 'l');   // 2
  ```
</Accordion>

<Accordion title="strstr(haystack, needle) — Find a substring">
  Returns the index of the first occurrence of `needle` in `haystack`, or `-1` if not found.

  ```c theme={null}
  int idx = strstr("hello world", "world");   // 6
  ```
</Accordion>

## Architecture Optimization

<Note>
  The plstd string library ships two implementations: `string_x86.plib` for x86\_64 Linux and `string_arm64.plib` for ARM64 macOS. Both expose identical function signatures — `string.plib` uses conditional compilation (`#ifdef __x86_64__` / `#ifdef __aarch64__`) to route each call to the appropriate backend. You never need to select an implementation yourself; the compiler handles it based on your build target.
</Note>

## Using the `len()` Built-in

`len()` is a language built-in — not a plstd function — so it requires no import and works across multiple collection types. Use it in preference to `strlen` for everyday string length checks.

```c theme={null}
// String length
string s = "hello";
int l = len(s);         // 5

// Dynamic array length
dynam int arr = [1, 2, 3];
int n = len(arr);        // 3

// Tuple length
tuple t = [1, "hi", 3.14];
int t_len = len(t);      // 3
```

`len()` works with `string`, `dynam` arrays, and `tuple` collections. For anything else, reach for the appropriate plstd function.