Crate hex_color

A simple, lightweight library for working with RGB(A) hexadecimal 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 = "2"

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.

Modules

rgbserde

Deserialize and serialize HexColor values as RGB strings.

rgbaserde

Deserialize and serialize HexColor values as RGBA strings.

u24serde

Deserialize and serialize HexColor values as u32 values by truncating the alpha byte.

u32serde

Deserialize and serialize HexColor values as u32 values.

Structs

HexColor

An RGBA color.

Enums

ParseHexColorError

An error which can be returned when parsing a hex color.