hex_color

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

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:

[dependencies]
hex_color = "3"

Examples

Basic parsing:

use hex_color::HexColor;let cyan = HexColor::parse("#0FF")?;assert_eq!(cyan,HexColor::CYAN);let transparent_plum = HexColor::parse("#DDA0DD80")?;assert_eq!(transparent_plum,HexColor::rgba(221,160,221,128));// Strictly enforce only an RGB color through parse_rgb:let pink = HexColor::parse_rgb("#FFC0CB")?;assert_eq!(pink,HexColor::rgb(255,192,203));// Strictly enforce an alpha component through parse_rgba:let opaque_white = HexColor::parse_rgba("#FFFF")?;assert_eq!(opaque_white,HexColor::WHITE);

Flexible constructors:

use hex_color::HexColor;let violet = HexColor::rgb(238,130,238);let transparent_maroon= HexColor::rgba(128,0,0,128);let transparent_gray = HexColor::GRAY.with_a(128);let lavender = HexColor::from_u24(0x00E6_E6FA);let transparent_lavender = HexColor::from_u32(0xE6E6_FA80);let floral_white = HexColor::WHITE.with_g(250).with_b(240);

Comprehensive arithmetic:

use hex_color::HexColor;assert_eq!(HexColor::BLUE + HexColor::RED,HexColor::MAGENTA);assert_eq!(HexColor::CYAN.saturating_add(HexColor::GRAY),HexColor::rgb(128,255,255),);assert_eq!(HexColor::BLACK.wrapping_sub(HexColor::achromatic(1)),HexColor::WHITE,);

With rand

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

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:

use hex_color::HexColor;let random_rgb = HexColor::random_rgb();let random_rgba = HexColor::random_rgba();

With serde

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

use hex_color::HexColor;use serde::{Deserialize,Serialize};use serde_json::json;#[derive(Debug,PartialEq,Deserialize,Serialize)]structColor{name:String,value:HexColor,}let json_input = json!({"name":"Light Coral","value":"#F08080",});assert_eq!(
serde_json::from_value::<Color>(json_input)?,Color{
name:String::from("Light Coral"),
value:HexColor::rgb(240,128,128),},);let my_color = Color{name:String::from("Dark Salmon"),value:HexColor::rgb(233,150,122),};assert_eq!(
serde_json::to_value(my_color)?,
json!({"name":"Dark Salmon","value":"#E9967A",}),);#[derive(Debug,PartialEq,Deserialize,Serialize)]structNumericColor{name:String,#[serde(with = "hex_color::u24")]value:HexColor,}let json_input = json!({"name":"Light Coral","value":0x00F0_8080_u32,});assert_eq!(
serde_json::from_value::<NumericColor>(json_input)?,NumericColor{
name:String::from("Light Coral"),
value:HexColor::rgb(240,128,128),},);let my_color = NumericColor{name:String::from("Dark Salmon"),value:HexColor::rgb(233,150,122),};assert_eq!(
serde_json::to_value(my_color)?,
json!({"name":"Dark Salmon","value":0x00E9_967A_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.