# Time Slices

`TSSlice` and `TSSlices` represent time intervals using offset ranges. They are
useful for segment arithmetic: intersections, unions, gap detection, and array
indexing.

## Creating Slices

```python
from sgnts.base import TSSlice, TSSlices, Offset

# From raw offsets
s = TSSlice(start=0, stop=16384)

# From seconds (converted to offsets)
s = TSSlice(start=Offset.fromsec(0), stop=Offset.fromsec(1.0))
```

A `TSSlices` is an ordered collection:

```python
from sgnts.base import TSSlice, TSSlices

slices = TSSlices([
    TSSlice(start=0, stop=16384),
    TSSlice(start=32768, stop=49152),
])
```

## Slice Properties

```python
from sgnts.base import TSSlice

s = TSSlice(start=0, stop=16384)
print(s.start)             # 0
print(s.stop)              # 16384
print(s.stop - s.start)    # 16384 (span in offset units)
```

## Intersection

Find the overlap between two slices:

```python
from sgnts.base import TSSlice

a = TSSlice(start=0, stop=32768)
b = TSSlice(start=16384, stop=49152)

overlap = a & b  # TSSlice(start=16384, stop=32768)
```

For finding the common region across all slices in a collection, use
`intersection()`:

```python
from sgnts.base import TSSlice, TSSlices

slices = TSSlices([TSSlice(0, 32768), TSSlice(16384, 49152)])
result = slices.intersection()  # TSSlice(start=16384, stop=32768)
```

To find common regions across multiple `TSSlices` objects, use
`intersection_of_multiple()`:

```python
from sgnts.base import TSSlice, TSSlices

s1 = TSSlices([TSSlice(0, 32768)])
s2 = TSSlices([TSSlice(16384, 49152)])

result = TSSlices.intersection_of_multiple([s1, s2])
```

## Union

Merge overlapping or adjacent slices using `+` on individual `TSSlice` objects:

```python
from sgnts.base import TSSlice

a = TSSlice(0, 16384)
b = TSSlice(16384, 32768)

result = a + b  # [TSSlice(start=0, stop=32768)]
```

## Gap Detection

Find gaps within a range by inverting a slice collection:

```python
from sgnts.base import TSSlice, TSSlices

segments = TSSlices([
    TSSlice(0, 16384),
    TSSlice(32768, 49152),
])

# Invert within a bounding range to find gaps
gaps = segments.invert(TSSlice(0, 49152))
# TSSlices([TSSlice(16384, 32768)])
```

## Simplification

Merge overlapping slices in a collection:

```python
from sgnts.base import TSSlice, TSSlices

messy = TSSlices([
    TSSlice(0, 16384),
    TSSlice(8192, 32768),
])

clean = messy.simplify()  # TSSlices([TSSlice(0, 32768)])
```

## Other Operations

**Difference** — returns the non-overlapping parts of two slices:

```python
from sgnts.base import TSSlice

a = TSSlice(start=0, stop=32768)
b = TSSlice(start=16384, stop=49152)

diff = a - b  # [TSSlice(0, 16384), TSSlice(32768, 49152)]
```

**Split** — divide a slice at a specific offset:

```python
from sgnts.base import TSSlice

left, right = TSSlice(0, 32768).split(16384)
```

**Search** — find slices that overlap a given range, optionally truncating them
to fit:

```python
from sgnts.base import TSSlice, TSSlices

slices = TSSlices([TSSlice(0, 16384), TSSlice(32768, 49152)])
result = slices.search(TSSlice(8192, 32768), align=True)
```

## Aligning to a Sample Rate

Snap slice boundaries to sample boundaries at a given rate:

```python
from sgnts.base import TSSlice, TSSlices

slices = TSSlices([TSSlice(start=100, stop=20000)])
aligned = slices.align_to_rate(target_rate=2048)
```
