# string — String Utilities

> `import { plural, justifyLeft, safeStringify } from 'puffy-core/string'`
> CJS: `const { string: { plural, justifyLeft, safeStringify } } = require('puffy-core')`
> Also available in snake_case: `justify_left`, `safe_stringify`

---

## safeStringify

Same as `JSON.stringify` but handles BigInt values (which standard JSON.stringify throws on).

### Signature

```
safeStringify(obj: any, indentation?: number) → string
```

### Examples

```js
safeStringify({ id: 123n })        // '{"id":"123"}'  — BigInt converted to string
safeStringify({ a: 1 })            // '{"a":1}'       — normal values unchanged
safeStringify({ a: 1 }, 2)         // '{\n  "a": 1\n}'  — with indentation
```

GOTCHA: BigInt values are serialized as strings, not numbers. If you parse the JSON back, you'll get `"123"` (string), not `123n` (BigInt).

---

## plural

Pluralizes one or more words based on a count. Handles special cases (irregular plurals, pronouns, verb conjugation).

### Signature

```
plural(count: number, ...words: string[]) → string
```

Parameters:
- `count`: If > 1, words are pluralized. Otherwise returned as-is.
- `...words`: One or more words to pluralize. Multiple words are joined with spaces.

Returns: Space-separated string of (possibly pluralized) words.

### Examples — Single words

```js
plural(1, 'cat')       // 'cat'
plural(2, 'cat')       // 'cats'
plural(0, 'cat')       // 'cat'     — 0 uses singular

plural(2, 'city')      // 'cities'  — y → ies
plural(2, 'City')      // 'Cities'  — preserves capitalization
```

### Examples — Pronouns and verb conjugation

```js
plural(2, 'He')        // 'They'
plural(2, 'She')       // 'They'
plural(2, 'he')        // 'they'
plural(2, 'his')       // 'their'
plural(2, 'her')       // 'their'
plural(2, 'him')       // 'them'
plural(2, 'its')       // 'their'
plural(2, 'it')        // 'they'
plural(2, 'is')        // 'are'
plural(2, 'was')       // 'were'
plural(2, 'am')        // 'are'
plural(2, 'this')      // 'these'
plural(2, 'that')      // 'those'
```

### Examples — Multiple words (common in sentences)

```js
plural(1, 'Project', 'was')     // 'Project was'
plural(2, 'Project', 'was')     // 'Projects were'

plural(1, 'She', 'is')          // 'She is'
plural(2, 'She', 'is')          // 'They are'

plural(1, 'Test record', 'is')  // 'Test record is'
plural(2, 'Test record', 'is')  // 'Test records are'
```

---

## justifyLeft

Left-aligns multi-line text by stripping common leading whitespace.

### Signature

```
justifyLeft(text: string, options?: {
	prefix?: string,
	anchorLine?: number,
	remove?: string|boolean,
	skip?: number|number[]
}) → string
```

Parameters:
- `prefix`: String prepended to each output line
- `anchorLine`: Use this line's indentation as the reference (0-indexed). Other lines are adjusted relative to it.
- `remove`: Characters to strip. `true` = use anchor line's indentation. String = exact characters to remove.
- `skip`: Line index or array of indices to exclude from output

### Examples

```js
const text = `\t\tHello,
\t\tThis is a list:
\t\t- Fruits:
\t\t\t- Apple
\t\t\t- Orange`

// Default — strips common leading whitespace
justifyLeft(text)
// 'Hello,\nThis is a list:\n- Fruits:\n- Apple\n- Orange'

// With prefix
justifyLeft(text, { prefix:'> ' })
// '> Hello,\n> This is a list:\n> - Fruits:\n> - Apple\n> - Orange'

// Anchor to line 0 — preserves line 0's indentation as baseline
justifyLeft(text, { anchorLine:0 })
// '\t\tHello,\n\t\tThis is a list:\n\t\t- Fruits:\n\t\t- Apple\n\t\t- Orange'

// Skip specific lines
justifyLeft(text, { remove:true, anchorLine:1, skip:[0,1] })
// '- Fruits:\n\t- Apple\n\t- Orange'
```