hex_color 3.0.0

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

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:

[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)]
struct Color {
    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)]
struct NumericColor {
    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

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.