normalize-css-z 0.7.0

Normalization of a CSS z-index value to a 32-bit floating-point number (well, kind of...)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

# Normalization of a CSS z-index value to a 32-bit floating-point number

[![crate](https://img.shields.io/crates/v/normalize-css-z.svg)](https://crates.io/crates/normalize-css-z)
[![documentation](https://docs.rs/normalize-css-z/badge.svg)](https://docs.rs/normalize-css-z)
[![build status](https://github.com/sjinno/normalize-css-z/actions/workflows/ci.yml/badge.svg)](https://github.com/sjinno/normalize-css-z/actions)

## Note

This project is a work in progress, so please watch for a new release and ensure to use the latest version.

## Origin

I struggled to map CSS z-index values to 32-bit floating-point numbers between 0.0 and 1.0 because dividing a large number by another large number, such as `2_147_483_646.0 / 2_147_483_647.0`, does not yield precise results.

To illustrate the issue, here are some examples (see [playground](https://play.rust-lang.org/?version=stable&mode=debug&edition=2021&gist=d46e7034b55a1fd0362d1ef3f000304a)):

```
2_147_483_646.0 / 2_147_483_647.0 = 1.0
2_147_483_645.0 / 2_147_483_647.0 = 1.0
2_147_483_644.0 / 2_147_483_647.0 = 1.0
2_147_483_643.0 / 2_147_483_647.0 = 1.0
2_147_483_642.0 / 2_147_483_647.0 = 1.0
2_147_483_641.0 / 2_147_483_647.0 = 1.0
2_147_483_640.0 / 2_147_483_647.0 = 1.0
2_147_483_639.0 / 2_147_483_647.0 = 1.0
2_147_483_638.0 / 2_147_483_647.0 = 1.0
2_147_483_637.0 / 2_147_483_647.0 = 1.0
```

I spent some time experimenting to figure out a reasonable approach to this challenge, and I may have finally found a way to manage the headache of mapping CSS z-index values.

## Usage

Run the following Cargo command in your project directory:

```zsh
cargo add normalize-css-z
```

Or add the following line to your Cargo.toml:

```toml
[dependencies]
normalize-css-z = "0.7"
```

And in your Rust file:

```rs
use normalize_css_z::normalize;

fn main() {
    let z_ = 2_147_483_647;
    if let Some(z) = normalize(z_) {
        // Do something with `z`.
    } else {
        // Handle unsupported z-index.
    }
}
```

## Custom lower, middle, and upper ranges are now available under the 'custom' feature flag as of version 0.6

**NOTE:** This version has not been thoroughly tested yet.

To use, add the following line to your Cargo.toml:

```toml
[dependencies]
normalize-css-z = { version = "0.7", features = ["custom"] }
```

And in your Rust file:

```rs
use normalize_css_z::{
    normalizer::Normalizer,
    ranges::RangesBuilder,
};

fn main() {
    let builder = RangesBuilder::default()
        .with_lower(0..=100)
        .with_middle(101..=200)
        .with_upper(201..=300);
    let normalizer = Normalizer::new(builder.build());

    if let Some(z) = normalizer.calc(0) {
        // Do something with `z`.
    } else {
        // Handle unsupported z-index.
    }
}
```

## Supported ranges of z-indexes

| LOWER                             | MIDDLE                   | UPPER                           |
| --------------------------------- | ------------------------ | ------------------------------- |
| `-2_147_483_647..=-2_139_095_039` | `-4_194_303..=4_194_304` | `2_139_095_040..=2_147_483_647` |

### Total number of supported z-indexes (as of 1/16/2024)

8,388,608 \* 3 + 1 = 25,165,825

## License

Licensed under either of

- [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
- [MIT license](http://opensource.org/licenses/MIT)

at your option.