# Downstream --- Rust Implementation

![downstream wordmark](https://raw.githubusercontent.com/mmore500/downstream/master/docs/assets/downstream-wordmark.png)

![Crates.io Version](https://img.shields.io/crates/v/downstream)
[![CI](https://github.com/mmore500/downstream/actions/workflows/rust-ci.yaml/badge.svg?branch=rust)](https://github.com/mmore500/downstream/actions/workflows/rust-ci.yaml?query=branch:rust)
[![GitHub stars](https://img.shields.io/github/stars/mmore500/downstream.svg?style=flat-square&logo=github&label=Stars&logoColor=white)](https://github.com/mmore500/downstream)
[![DOI](https://zenodo.org/badge/776865597.svg)](https://zenodo.org/doi/10.5281/zenodo.10866541)

downstream provides efficient, constant-space implementations of stream curation algorithms.

-   Free software: MIT license
-   Documentation: <https://mmore500.github.io/downstream>

## Installation

Add downstream as a dependency in your `Cargo.toml`:

```toml
[dependencies]
downstream = ">=0.0.0"
```

## API Reference

See the [Python quickstart](https://mmore500.github.io/downstream/quickstart) for outline and intuition.

Each algorithm variant is accessible through the `downstream::dstream` module:

* Circular: `downstream::dstream::CircularAlgo`
* Compressing: `downstream::dstream::CompressingAlgo`
* Steady: `downstream::dstream::SteadyAlgo`
* Sticky: `downstream::dstream::StickyAlgo`
* Stretched: `downstream::dstream::StretchedAlgo`
* Tilted: `downstream::dstream::TiltedAlgo`

See [selecting a dstream algorithm](https://mmore500.github.io/downstream/algorithm) for more information.

#### `has_ingest_capacity`
```rust
pub fn has_ingest_capacity<Uint: downstream::_auxlib::UnsignedTrait>(S: Uint, T: Uint) -> bool
```
Determines if there is capacity to ingest a data item at logical time `T`.

* `Uint`: Integer type (e.g., `u32`)
* `S`: Buffer size (must be a power of two)
* `T`: Stream position of data item (zero-indexed)

#### `assign_storage_site`
```rust
pub fn assign_storage_site<Uint: downstream::_auxlib::UnsignedTrait>(S: Uint, T: Uint) -> Option<Uint>
```
Site selection algorithm for steady curation. Returns selected site or `None` if data should be discarded.

* `Uint`: Integer type (e.g., `u32`)
* `S`: Buffer size (must be a power of two)
* `T`: Stream position of data item (zero-indexed)

### `_assign_storage_site` (low-level interface)
```rust
pub fn _assign_storage_site<Uint: downstream::_auxlib::UnsignedTrait>(S: Uint, T: Uint) -> Uint
```
Returns `S` if data should be discarded.

## Citing

If downstream contributes to a scientific publication, please cite it as

> Yang C., Wagner J., Dolson E., Zaman L., & Moreno M. A. (2025). Downstream: efficient cross-platform algorithms for fixed-capacity stream downsampling. arXiv preprint arXiv:2506.12975. https://doi.org/10.48550/arXiv.2506.12975

```bibtex
@misc{yang2025downstream,
      doi={10.48550/arXiv.2506.12975},
      url={https://arxiv.org/abs/2506.12975},
      title={Downstream: efficient cross-platform algorithms for fixed-capacity stream downsampling},
      author={Connor Yang and Joey Wagner and Emily Dolson and Luis Zaman and Matthew Andres Moreno},
      year={2025},
      eprint={2506.12975},
      archivePrefix={arXiv},
      primaryClass={cs.DS},
}
```

And don't forget to leave a [star on GitHub](https://github.com/mmore500/downstream/stargazers)!
