---
Title: 7 Data Structures
Prev: Control Flow
Next: Type System
---

## 7. Data Structures

### 7.1 Structs

Structs define composite types with named fields.

**Definition Syntax**: `(field_types -- ) { field_names: } ::name<type_params>? struct`

**Examples**:

```
// Define Point struct - generic over coordinate types
(T T --) { x: y: } ::Point<T> struct

// Use with specific types
3.0 4.0 Point       // Creates Point with f64 fields
3 4 Point           // Creates Point with i64 fields

// More complex struct
(T U V --) { 
    width: 
    height: 
    depth: 
} ::Box3D<T U V> struct

10.0 20.0 30.0 Box3D
```

**Field Access**:
- **get**: `struct ::field get` - Consumes struct and field identifier, returns field value
- **set**: `value ::field set` - Consumes value and field identifier, returns modified struct

**Examples**:
```
point ::x get         // Get x field (consumes point and ::x)
15.0 ::x set          // Set x field to 15.0 (consumes value and ::x)

// Chaining with duplication
point dup ::x get 2 * over ::y get +     // (point.x * 2) + point.y
```

> **Note**: Structs can be generic. See [Section 10.3](./generic_programming.html#103-generic-data-structures) for details on generic data structures.

### 7.2 Unions

Unions define tagged variants, where a value is one of several possible types.

**Definition Syntax**: `(variant_types -- ) { variants } ::name<type_params>? union`

**Examples**:
```
// Option type - generic over T
(T --) { 
    Some(T) 
    None 
} ::Option<T> union

// Result type - generic over T and E
(T E --) { 
    Ok(T) 
    Err(E) 
} ::Result<T E> union

// Create union values
42 Option::Some      // Creates Option::Some(42)
Option::None         // Creates Option::None
"success" Result::Ok // Creates Result::Ok("success")
"error" Result::Err  // Creates Result::Err("error")
```

**Pattern Matching**: Unions are typically used with pattern matching ([Section 6.5](./control_flow.html#65-pattern-matching)) to handle different variants.

> **Note**: Unions can be generic. See [Section 10.3](./generic_programming.html#103-generic-data-structures) for details on generic data structures.

### 7.3 Enums

Enums define a fixed set of named values with optional integer assignments.

**Definition Syntax**: `{ variants } ::name enum`

**Examples**:
```
{ 
    Pending 1:   // Explicitly set to 1
    Active:      // Defaults to 2 (one plus the last)
    Complete 0:  // Explicitly set to 0
} ::Status enum

// Usage
Status::Pending     // Creates Status::Pending (value 1)
Status::Active      // Creates Status::Active (value 2)
Status::Complete    // Creates Status::Complete (value 0)
```

**Automatic Values**: If not specified, enum values start at 0 and increment by 1 for each subsequent variant.

### 7.4 Arrays

Arrays are homogeneous collections of values.

**Array Literals**:
```
[1 2 3 4 5]              // array of i64
[1.0 2.0 3.0]            // array of f64
[[1 2] [3 4]]            // 2D array

// Typed arrays
[1 2 3 :i16]             // array of i16
[[1.0 2.0] [3.0 4.0] :f32]  // 2D array of f32

// Arrays of structs (when Point is defined)
[{1 2} {3 4} :Point]     // array of Point structs
```

**Basic Operations**:
```
arr 2 at                 // ( array index -- element ) Access element at index
arr 1 3 slice            // ( array start end -- subarray ) Extract slice
arr length               // ( array -- length ) Get array length
```

**Array Combinators**:

These operations take TokenString arguments containing function bodies:

```
// Map - transform each element
[1 2 3 4] { 2 * } map        // => [2 4 6 8]

// Filter - keep elements matching predicate
[1 2 3 4 5] { 2 % 0 == } filter   // => [2 4]

// Reduce - fold with accumulator
[1 2 3 4] 0 { + } reduce     // => 10

// Each - apply to each element (side effects)
[[1 2] [3 4]] { sum print } each

// Foldl - left fold with accumulator
[1 2 3 4] 0 { + } foldl      // => 10 (same as reduce)

// Foldr - right fold with accumulator
[1 2 3 4] 0 { + } foldr      // => 10 (for commutative ops)
```

**Array Utilities**:
```
// Zip - combine two arrays element-wise
[1 2 3] [4 5 6] zip          // => [[1 4] [2 5] [3 6]]

// Enumerate - add indices to elements
["a" "b" "c"] enumerate      // => [[0 "a"] [1 "b"] [2 "c"]]

// Sum - sum all numeric elements
[1 2 3 4 5] sum              // => 15

// Mean - calculate average
[1 2 3 4 5] mean             // => 3.0
```

**Array Arithmetic**:
```
[1 2 3] [4 5 6] +.      // Element-wise add: [5 7 9]
[1 2 3] [4 5 6] *.      // Element-wise multiply: [4 10 18]
[1 2 3] 2 *.            // Scalar multiply: [2 4 6]
```

**Array Manipulation**:
```
[1 2 3] [4 5 6] concat  // Concatenate: [1 2 3 4 5 6]
[1 2 3] reverse         // Reverse: [3 2 1]
[[1 2] [3 4]] transpose // Transpose: [[1 3] [2 4]]
[1 2 3 4] 2 window      // Sliding window: [[1 2] [2 3] [3 4]]
```

> **Implementation Details**: Array operations implement various traits including `::ArrayOf<T>`, `::Selectable<T>`, `::Sliceable`, and `::Sized`. See [Appendix B](./complete_trait_reference.html) for complete trait definitions and [Appendix A](./standard_library.html) for the full array operation reference.

---
