# flip_flop.rs

> This library implements the [flip-flop operator from Perl and Ruby](https://en.wikipedia.org/wiki/Flip-flop_(programming)) as a Rust macro.

## Changelog

* April 1, 2024: Version 1.0.0.

## Usage

The `flip_flop!` macro accepts two boolean expressions wrapped in parentheses and separated by either 2 dots (`..`) or 3 dots (`...`):

```rust,ignore
flip_flop!((x == 5)..(x == 10))
// or
flip_flop!((x == 5)...(x == 10))
```

The macro returns true from when the left expression is true until the right expression is true by maintaining a hidden bool state.

The difference between `..` and `...` is that with `...`, the right expression is also evaluated when the left expression first becomes true, which makes it possible for the flip-flop internal state to be reset in the same iteration. This behavior matches that of [Perl](https://perldoc.perl.org/perlop#Range-Operators).

The internal state of the operator is stored in a static `AtomicBool` and is therefore shared among threads, mirroring the behavior of Perl.

## Example

The print statement in the following code is executed from when `i == 5` becomes true until `i == 10` becomes true.

```rust
<%= File.read("examples/basic.rs").strip %>
```

Output:

```text
<%= `cargo run --example basic`.strip %>
```

## Extracting Sequence Example

The following code extracts all sequences starting with `1` followed by any numbers until finding a `2`.

```rust
<%= File.read("examples/sequence.rs").strip %>
```

Output:

```text
<%= `cargo run --example sequence`.strip %>
```

## FizzBuzz Example

This is the classic FizzBuzz problem implemented using the flip-flop operator. [Source](https://juliansimioni.com/blog/deconstructing-fizz-buzz-with-flip-flops-in-ruby/).

```rust
<%= File.read("examples/fizzbuzz.rs").strip %>
```

Output (after removing text hidden by `\r`):

```text
<%= `cargo run --example fizzbuzz`.split("\n").take(16).map { _1.gsub(/.*\r(.+)/, '\1') }.join("\n").gsub("\r", "") %>
…
```

## Bugs

The behavior of this crate should match that of Perl and Ruby, but there may be edge cases that are not handled correctly. If you find any, please open an issue (or a pull request)!

## License

This project is licensed under either of

 * Apache License, Version 2.0, (https://www.apache.org/licenses/LICENSE-2.0)
 * MIT license (https://opensource.org/licenses/MIT)

at your option.