hex_color

A simple, lightweight library for working with RGB(A) hexadecimal colors.

![Build Status] ![Latest Version]

Documentation

Module documentation with examples. The module documentation also includes a comprehensive description of the syntax supported for parsing hex colors.

Usage

This crate is on crates.io and can be used by adding hex_color to your dependencies in your project's Cargo.toml:

toml [dependencies] hex_color = "2"

Examples

Basic parsing:

```rust use hex_color::HexColor;

let cyan = HexColor::parse("#0FF")?; assert_eq!(cyan, HexColor::CYAN);

let transparentplum = HexColor::parse("#DDA0DD80")?; asserteq!(transparent_plum, HexColor::rgba(221, 160, 221, 128));

// Strictly enforce only an RGB color through parsergb: let pink = HexColor::parsergb("#FFC0CB")?; assert_eq!(pink, HexColor::rgb(255, 192, 203));

// Strictly enforce an alpha component through parsergba: let opaquewhite = HexColor::parsergba("#FFFF")?; asserteq!(opaque_white, HexColor::WHITE); ```

Flexible constructors:

```rust use hex_color::HexColor;

let violet = HexColor::rgb(238, 130, 238); let transparentmaroon= HexColor::rgba(128, 0, 0, 128); let transparentgray = HexColor::GRAY.witha(128); let lavender = HexColor::fromu24(0x00E6E6FA); let transparentlavender = HexColor::fromu32(0xE6E6FA80); let floralwhite = HexColor::WHITE .withg(250) .with_b(240); ```

Comprehensive arithmetic:

```rust use hex_color::HexColor;

asserteq!(HexColor::BLUE + HexColor::RED, HexColor::MAGENTA); asserteq!( HexColor::CYAN.saturatingadd(HexColor::GRAY), HexColor::rgb(128, 255, 255), ); asserteq!( HexColor::BLACK.wrapping_sub(HexColor::achromatic(1)), HexColor::WHITE, ); ```

With [rand]

Using rand + std features to generate random colors via [rand][rand] out of the box:

```rust use hex_color::HexColor;

let random_rgb: HexColor = rand::random(); ```

To specify whether an RGB or RGBA color is randomly created, use HexColor::random_rgb or HexColor::random_rgba respectively:

```rust use hex_color::HexColor;

let randomrgb = HexColor::randomrgb(); let randomrgba = HexColor::randomrgba(); ```

With [serde]

Use [serde] to serialize and deserialize colors in multiple formats: u24, u32, rgb, or rgba:

```rust use hexcolor::HexColor; use serde::{Deserialize, Serialize}; use serdejson::json;

[derive(Debug, PartialEq, Deserialize, Serialize)]

struct Color { name: String, value: HexColor, }

let jsoninput = json!({ "name": "Light Coral", "value": "#F08080", }); asserteq!( serdejson::fromvalue::(json_input)?, Color { name: String::from("Light Coral"), value: HexColor::rgb(240, 128, 128), }, );

let mycolor = Color { name: String::from("Dark Salmon"), value: HexColor::rgb(233, 150, 122), }; asserteq!( serdejson::tovalue(my_color)?, json!({ "name": "Dark Salmon", "value": "#E9967A", }), );

[derive(Debug, PartialEq, Deserialize, Serialize)]

struct NumericColor { name: String, #[serde(with = "hex_color::u24")] value: HexColor, }

let jsoninput = json!({ "name": "Light Coral", "value": 0x00F08080u32, }); asserteq!( serdejson::fromvalue::(json_input)?, NumericColor { name: String::from("Light Coral"), value: HexColor::rgb(240, 128, 128), }, );

let mycolor = NumericColor { name: String::from("Dark Salmon"), value: HexColor::rgb(233, 150, 122), }; asserteq!( serdejson::tovalue(mycolor)?, json!({ "name": "Dark Salmon", "value": 0x00E9967A_u32, }), ); ```

Features

• rand enables out-of-the-box compatability with the [rand] crate.
• serde enables serialization and deserialization with the [serde] crate.
• std enables std::error::Error on ParseHexColorError. Otherwise, it's needed with rand for HexColor::random_rgb, HexColor::random_rgba, and, of course, rand::random.

Note: Only the std feature is enabled by default.

License

Licensed under either of

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

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.