feat: add indice and indice ranges mapping functions

README.md

@@ -106,6 +106,36 @@ print(refolded_embedding.shape)
 # torch.Size([2, 5, 16]) # 2 samples, 5 words max, 16 dims
 ```
 
+### Pooling spans
+
+`lengths.make_indices_ranges` maps half open spans to storage positions,
+excluding padding even when a span crosses rows. It returns the expanded indices,
+start offsets and the span id of each selected item.
+
+```python
+import torch
+import foldedtensor as ft
+
+tensor = ft.as_folded_tensor([[1.0, 2.0], [3.0]], full_names=("sample", "word"))
+indices, offsets, spans = tensor.lengths.make_indices_ranges(
+    begins=(torch.tensor([0, 1]),),
+    ends=(torch.tensor([2, 3]),),
+    indice_dims=("word",),
+)
+pooled = torch.nn.functional.embedding_bag(
+    indices,
+    tensor.as_tensor().reshape(-1, 1),
+    offsets,
+    mode="mean",
+)
+assert pooled.tolist() == [[1.5], [2.5]]
+```
+
+Boundary mapping and expansion run in C++, using prefix offsets from the
+sequence lengths and the refolding indexer for padded layouts. Range indices are
+computed on CPU and returned on the input device. Embedding gathering and pooling
+run on the embedding tensor's device.
+
 ## Benchmarks
 
 View the comparisons of `foldedtensor` against various alternatives here: [docs/benchmarks](https://github.com/aphp/foldedtensor/blob/main/docs/benchmark.md).

changelog.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## Unreleased
+
+- Add range expansion that returns storage indices without padding
+- Preserve empty contexts and words when refolding padded layouts
+- Store dimension names and tensor axes in `FoldedTensorLayout` for span pooling before the forward pass
+- Keep explicit names and dimensions when recreating a tensor from a layout
+
 ## v0.4.0
 
 - Fix `storage` torch warning