Forem: Raeisi

Converting enums to and from integers in Rust, implementing the rustls solution

Raeisi — Mon, 17 Mar 2025 18:06:13 +0000

Rust has some cool features, especially its enum types. They’re like a super-powered way to store different types of data. You can use them to store simple numbers or even complex structures, depending on what you need. Enums also have their own little language, which can be a bit tricky for beginners, but I’ve got some ideas on how to make it easier.

See full code example at Rust Online Playground

This document outlines my plan for enum_builder! macro in rustls crate.

Why Enum Conversion?

Enum conversion is a crucial step when you’re dealing with objects that need to be packed or sent over the wire. It usually involves changing enums into integers, which happens in places like databases, APIs, and even raw data.

What is the problem?

In Rust, it is not possible to convert enums to integers.

pub enum Season {
    Spring,
    Summer,
    Autumn,
    Winter,
}
fn main() {
    let season_id: u8 = Season::Autumn;
    println!("season id: {season_id}");
}

error[E0308]: mismatched types
 --> src/main.rs:8:25
  |
8 |     let season_id: u8 = Season::Autumn;
  |                    --   ^^^^^^^^^^^^^^ expected `u8`, found `Season`
  |                    |
  |                    expected due to this

One potential solution involves employing the #[repr(u8)] macro.

#[repr(u8)]
pub enum Season {
    Spring = 0,
    Summer = 1,
    Autumn = 2,
    Winter = 4,
}
fn main() {
    let season_id: u8 = Season::Autumn as _;
    println!("season id: {season_id}"); // ok

    // fails
    let session: Season = season_id as _;
}

Although this is a one-way solution, it does not address the reciprocal issue. Let’s propose implementing a macro to mitigate this problem.

Why macro?

Rust enums, which are great for type safety, don’t automatically convert to integers. But there’s a cool macro called enum_builder! that can help you out. It automatically generates into() and from() functions for your enum. This macro takes the name of your enum and a list of its variant-integer pairs. It then creates match expressions inside the impl block for conversion, using the From trait. This way, you don’t have to write out the conversion logic yourself. It saves you time, makes your code shorter, and reduces errors. Plus, it’s easier to maintain because all the conversion logic is in one place. The example uses u8, but the macro can be used for other integer types too. So, if you need to convert enums to integers in Rust, this macro is your friend!

The final main function is as follows:

enum_builder! {
    #[repr(u8)]
    #[derive(Copy, Clone, Debug)]
    pub enum Season {
        Spring => 0,
        Summer => 1,
        Autumn => 2,
        Winter => 4,
    }
}
fn main() {
    let season_id: u8 = Season::Autumn.into();
    // let season_id = u8::from(Season::Autumn); // or this syntax
    println!("season id: {season_id}");

    let season: Season = season_id.try_into().unwrap();
    //let season = Season::try_from(season_id)().unwrap(); // or this syntax
    println!("season: {season:?}");
}

Let's implement the enum_builder macro.

macro_rules! enum_builder {
    (
        // the target type to convert from/to. It must become at first before other meta tags
        #[repr($typ:ty)]

        // extra optional meta like #[derive(Debug)]
        $( #[$meta:meta] )*

        // accessor like pub or pub(crate)
        $access:vis enum $name:ident {
            // catch arms and assigned values like Sprint => 3
            // that is: $arm = Spring and $val = 3
            // I used literal not expr for later match expression.
            // If expr is used, you need to implement if/else instead of match.
            $( $arm:ident => $val:literal ),* $(,)?
        }
    ) => {
        // create the enum with specified arms without literal and values
        $( #[$meta] )*
        $access enum $name {
            $($arm,)*
        }

        // implement conversion from the target type to the enum.
        // Since the target type has a bigger domain, the conversion is fallible.
        // I mean, if target type be u8, there are 256 value for the type while or enum has much lesser arms, so
        // convesion from u8 to our enum may does not happen. 
        impl TryFrom<$typ> for $name {
            type Error = ();
            fn try_from(x: $typ) -> Result<Self, Self::Error> {
                match x {
                    $( $val => Ok($name::$arm),)*
                    _ => Err(()),
                }
            }
        }

        // implement convesion into target type. It always happens since the enum's arms are much lesser in count.
        impl From<$name> for $typ {
            fn from(enm: $name) -> Self {
                match enm {
                    $($name::$arm => $val ,)*
                }
            }
        }
    };
}

Online playground

This macro is a customized version of the original macro implemented in the rustls crate. The unknown arm is removed, and conversion from the target type is fallible here.

Conclusion:

Although there is no straightforward native solution to convert enums to and from integer values, we can utilize macros to implement a performant solution.

Human readable time in Rust

Raeisi — Tue, 17 Sep 2024 07:09:55 +0000

When it comes to formatting time into the human-readable format in Rust, there could be various possible solutions including doing some math or using Instance. However, I demonstrate the millisecond crate, the dedicated and specialized crate for the purpose. This crate converts nanoseconds, microseconds, milliseconds, seconds, etc into short and long formats; suitable for human eyes.

Imagine we have a variable containing a milliseconds value like 33023448000, computed somewhere in our code, and we want to show users the tangible equivalent result like 1 year 17 days 5 hours 10 minutes 48 seconds or a compact version 1y 17d 5h 10m 48s. Here the millisecond crate plays its role.

Project setup

First, ensure you have installed Rust and Cargo on your system and they are available in Terminal (CMD on Windows).

1. Create project

Run the following command to initialize an empty binary project:

cargo init my-millisecond --bin && cd my-millisecond

2. Install `millisecond` crate

At the moment, the latest version of the crates is 0.3.

cargo add millisecond@0.3

3. Use the crate

Open src/main.rs and write the following code:

use millisecond::Millisecond;

fn main() {
    let computed_millis = 33023448000;
    let ms = Millisecond::from_millis(computed_millis);
    println!("{ms}"); // results in: 1y 17d 5h 10m 48s
}

4. Run the project

cargo run

output:

~/my-millisecond$ cargo run
   Compiling my-millisecond v0.1.0 (~/my-millisecond)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.19s
     Running `target/debug/my-millisecond`
1y 17d 5h 10m 48s

I used the default formatting function (Display) in the example. You can use the strict method of ms.to_short_string() instead, or use ms.to_long_string() to print the long version of the output.

use millisecond::Millisecond;

fn main() {
    let computed_millis = 33023448000;
    let ms = Millisecond::from_millis(computed_millis);
    println!("default: {ms}"); // 1y 17d 5h 10m 48s
    println!("  short: {}", ms.to_short_string()); // 1y 17d 5h 10m 48s
    println!("   long: {}", ms.to_long_string()); // 1 year 17 days 5 hours 10 minutes 48 seconds
}

Conclusion

Converting time into a human-readable format can be challenging in Rust. The millisecond crate provides a better way to overcome the situation. It is easy to use, has zero dependencies, is suitable for embedded environments, and is built up with the no_std attribute. The crate follows the MIT license and is inspired by pretty-ms the NPM package.

References

Repository: https://crates.io/crates/millisecond
The source code at Github: https://github.com/raeisimv/millisecond

Find Window Handle (HWND) using Rust

Raeisi — Tue, 06 Aug 2024 08:41:16 +0000

In this paper, I will explain how to find a specific handle (HWND) for an application running on Windows using Rust programming language.

In the Windows API term, an HWND (window handle) uniquely identifies a window, serving as an abstract data type representing a window object. One of the first steps for developing applications around Windows Desktop is to find the target app's HWND.

This is what I am going to achieve:

fn main() {
    let Some(app_hwn) = find_app_hwnd() else {
        eprintln!("target app handle is not found. make sure the app is running");
        return;
    };
    assert_ne!(app_hwn, HWND::default(), "app handle must not be empty");
}

Working with Windows API has never been as easy as these days. The official windows-sys and windows crates are here to address the issue. The former contains low-level API call codes while the latter is a wrapper around it simplifying the usage.

Prepare Project

Create a new cargo binary application using:

$ cargo new find_hwnd --bin

Then modify its cargo.toml file to include the windows crate dependency with minimum required features:

# cargo.toml
[package]
name = "find_hwnd"
version = "0.1.0"
edition = "2021"

# Windows sys-call interface
[dependencies.windows]
version = "0.58"
features = [
    "Win32_Foundation",
    "Win32_UI_WindowsAndMessaging",
]

What is the plan?

First, get the current desktop handle using GetDesktopWindow sys-call. Windows, like other operating systems, can be configured for multiple desktop environments and each desktop may contain many apps. Here the focus is on the current desktop.

Second, iterate over all child apps in the corresponding desktop and filter them by name. The EnumChildWindows sys-call accepts a callback function, which gets called for each application in the given desktop HWND.

Full code

The following code will find the Task Manager app (TaskManagerWindow).

// main.rs
use std::sync::{Arc, Mutex};
use windows::Win32::Foundation::{BOOL, HWND, LPARAM};
use windows::Win32::UI::WindowsAndMessaging::{EnumChildWindows, GetDesktopWindow, RealGetWindowClassA};

type GetTargetType = Arc<Mutex<Option<HWND>>>;
const TARGET_APP_TITLE: &str = "TaskManagerWindow";

fn main() {
    let Some(app_hwn) = find_app_hwnd() else {
        eprintln!("target app handle is not found. make sure the app is running");
        return;
    };

    assert_ne!(app_hwn, HWND::default(), "app handle must not be empty");
    println!("handle for '{}' is {:?}", TARGET_APP_TITLE, app_hwn);
}

fn find_app_hwnd() -> Option<HWND> {
    let storage: GetTargetType = Arc::new(Mutex::new(None));
    let l_param = LPARAM(&storage as *const GetTargetType as isize);

    unsafe {
        let desktop_hwnd = GetDesktopWindow();
        let _ = EnumChildWindows(desktop_hwnd, Some(find_target_process), l_param);
    }

    let state = storage.lock().unwrap();
    *state
}

unsafe extern "system" fn find_target_process(hwnd: HWND, l_param: LPARAM) -> BOOL {
    let mut buffer = [0_u8; 128];
    let read_len = RealGetWindowClassA(hwnd, &mut buffer);
    let proc_name = String::from_utf8_lossy(&buffer[..read_len as usize]);

    if proc_name != TARGET_APP_TITLE {
        return BOOL(1);
    }

    let storage = &*(l_param.0 as *const GetTargetType);
    let mut storage = storage.lock().unwrap();
    (*storage).replace(hwnd);

    BOOL(1)
}

NOTE: Make sure Task Manager is running before execute.

Sample output would be something like this with a different HWND value:

handle for 'TaskManagerWindow' is HWND(0x609ba)

Code explanation:

The find_app_hwnd function finds the current desktop HWND and then pushes the system to call find_target_process for each app. The latter function will get called for each app running. It will call the RealGetWindowClassA sys-call obtaining the title of the received HWND and doing the filtration.

What about LPARAM?

Most Windows APIs accept an extra parameter called LPARAM with the type of isize. It was used here to pass the reference of local storage; when the target app is filtered and found, the storage will be recovered from LPARAM and updated. Alternatively to LPARAM, a mutable global static variable can be used.

Reference

You can find the full project code at: https://github.com/raeisimv/rust-practice/tree/main/windows_syscall/x00_find_hwnd