# Standard Library Overview

## What is the Standard Library?

The Baba Yaga standard library provides a comprehensive set of functions for common operations. Everything is a function - even operators like `+` and `*` are just functions under the hood.

## Core Categories

### Arithmetic Functions
```plaintext
/* Basic arithmetic */
add 5 3;           /* 8 */
subtract 10 4;     /* 6 */
multiply 6 7;      /* 42 */
divide 20 5;       /* 4 */
modulo 17 5;       /* 2 */
power 2 8;         /* 256 */
negate 42;         /* -42 */
```

### Comparison Functions
```plaintext
/* Comparisons return booleans */
equals 5 5;        /* true */
notEquals 3 7;     /* true */
lessThan 3 7;      /* true */
greaterThan 10 5;  /* true */
lessEqual 5 5;     /* true */
greaterEqual 8 3;  /* true */
```

### Logical Functions
```plaintext
/* Logical operations */
logicalAnd true false;  /* false */
logicalOr true false;   /* true */
logicalXor true true;   /* false */
logicalNot true;        /* false */
```

### Higher-Order Functions
```plaintext
/* Function manipulation */
compose @double @increment 5;  /* 12 */
pipe @increment @double 5;     /* 12 */
apply @add 3 4;                /* 7 */
curry @add 3;                  /* function that adds 3 */
```

### Collection Functions
```plaintext
/* Working with collections */
map @double {1, 2, 3};         /* {2, 4, 6} */
filter @is_even {1, 2, 3, 4};  /* {2, 4} */
reduce @add 0 {1, 2, 3};       /* 6 */
each @add {1, 2} {10, 20};     /* {11, 22} */
```

### Enhanced Combinators
```plaintext
/* Utility functions */
identity 42;                   /* 42 */
constant 5 10;                 /* 5 */
flip @subtract 5 10;           /* 5 (10 - 5) */
on @length @add "hello" "world"; /* 10 */
both @is_even @is_positive 6;  /* true */
either @is_even @is_negative 6; /* true */
```

## Table Operations (`t.` namespace)

All table operations are immutable and return new tables:

```plaintext
/* Table-specific operations */
data : {a: 1, b: 2, c: 3};
doubled : t.map @double data;           /* {a: 2, b: 4, c: 6} */
filtered : t.filter @is_even data;      /* {b: 2} */
updated : t.set data "d" 4;             /* {a: 1, b: 2, c: 3, d: 4} */
removed : t.delete data "b";            /* {a: 1, c: 3} */
merged : t.merge data {d: 4, e: 5};     /* {a: 1, b: 2, c: 3, d: 4, e: 5} */
value : t.get data "a";                 /* 1 */
has_key : t.has data "b";               /* true */
count : t.length data;                  /* 3 */
```

## When to Use Which Function

- **Use `map`** for transforming every element in a collection
- **Use `filter`** for selecting elements that match a condition
- **Use `reduce`** for combining all elements into a single value
- **Use `each`** for element-wise operations across multiple collections
- **Use `t.map`/`t.filter`** when you want to emphasize table operations
- **Use `compose`** for mathematical-style function composition (right-to-left)
- **Use `pipe`** for pipeline-style composition (left-to-right)

## Common Patterns

```plaintext
/* Data processing pipeline */
data : {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
is_even : x -> x % 2 = 0;
double : x -> x * 2;
sum : x -> reduce @add 0 x;

/* Process: filter evens, double them, sum the result */
result : sum map @double filter @is_even data;
/* Result: 60 */

/* Table transformation */
users : {
  alice: {name: "Alice", age: 25},
  bob: {name: "Bob", age: 30}
};
get_age : x -> x.age;
is_adult : x -> x >= 18;
format_age : x -> x + " years old";

/* Get formatted ages of adult users */
adult_ages : map @format_age filter @is_adult map @get_age users;
/* Result: {alice: "25 years old", bob: "30 years old"} */
```

## Next Steps

Now that you understand the standard library, explore:
- [Advanced Combinators](14_Advanced_Combinators.md) for complex patterns
- [IO Operations](12_IO_Operations.md) for input/output
- [Error Handling](13_Error_Handling.md) for robust programs