rust enums by example

Ever since I started learning Rust about 4 years ago, I've been in love with its enums. You see, Rust's enums aren't strictly enumerations. They're closer to tagged unions or sum types, which are used to represent variants. Let's take a look at what an enum is, and a few cool use-cases for them.

About enums & A comparison to tagged unions in C

You should already be familiar with unions and traditional enums.

Rust's enums are something of a mix between the two.
You can read up on the basics in the book and/or Rust by Example.
That said, let's look at a simple enum in Rust and how it might be implemented in C.

Note that Rust's enums share the same span of memory between its constituent types, so only a small amount of memory is wasted. You can play around with their internal representations in this playground, or read more in the nomicon.

error handling with variants

Two particularly useful enums are Result and Option.

Result gives you a way to represent whether an operation is successful or not, as well as a way to access the data or error of the... result. 👀

Option gives you a way to represent whether something exists or not. This is generally used as a replacement for nullable types (which Rust does not have*).

But what really makes Rust shine is that it forces you to explicitly handle enum variants before you can access the underlying data. This is done using the match keyword. Rust also has special syntax for handling Results and Options when you raise issues from the unhappy path.

To start, let's compare how we handle a simple http endpoint with Go's gorilla/mux and Rust's Rocket.

Rust:

Go:

By having data embedded into variants, we can represent whether an operation is successful or not. Potential errors can be propagated, transformed, and handled without mucking up your happy path.

Very cool. 😎

Let's go deeper.

heap allocation and dynamic dispatch

Imagine you're writing an audio system for a game. You have a directed acyclic graph and you need a way to represent the nodes in this graph. A node can be an input (sine wave, mp3), effect (pan, mix), or output (speakers, a file, visualizer).

What all nodes have in common is one function: process(inputs, outputs). Let's call this common behaviour the AudioNode interface (or trait).

So our audio graph looks something like Graph<AudioNode>.
In practice then, each node in the graph is dynamically sized and must be heap allocated. To perform that heap allocation in Rust, our nodes must be wrapped in a smart pointer: Box<dyn AudioNode>.

Then the process(..) function needs to be dynamically dispatched.

All this results in significant overhead with multiple vtable accesses, and more importantly: indirection which prevents compiler optimization.

Keep in mind process(..) is called multiple thousands of times per second.


But we can improve that with enums:

In my project I'm getting up to 10% better performance. Not at all laughable in audio programming. You can remove a lot of boilerplate here with the impl-enum or enum_dispatch crates (see enum_dispatch benchmarks).

Very, very cool. 😎

message passing

Imagine you're writing a music player. Your UI has controls for play/pause, seek, skip, etc. These inputs can come from different places - like dbus, hotkeys, or simple UI interactions.

We've just run into an ideal use-case for MPSC (multi-producer/single-consumer) channels! An MPSC channel is simply an atomic queue that can only be accessed through its producers and consumers.

Whenever one of the aforementioned controls are triggered, we can send a message through an MPSC channel to control playback. With that out of the way, we need to determine what data to send.

Let's look at some potential Java-esque solutions. Normal enums won't work because some of our controls like Seek(timestamp) have associated data. Maybe a class with an enum field, plus fields for each type of associated data would work? Or a string?

It's an oddly gnarly problem to solve.

Fortunately for us, Rust's enums make this easy. This is part of what makes multithreading so nice in Rust.

closing thoughts

The last pattern using enums that I'd like to shine some light on is the finite state machine. Plenty of others have written about state machines in Rust before, so I won't reiterate on that.

Hopefully you've learned something new about rust's enums - whether you've never seen Rust before, or you're a Rust veteran. If you have any questions, feedback, or flattery, you can find my contact info on my résumé.


Speaking of résumés, I'm looking for work right now!

I'm a generalist software developer with a specialization in backend / web architecture. I've spent the last nine years honing the craft in my free time, and I'd really like to get my foot in the door professionally. Send me an email if you know of any internships, contract positions, or full-time employment that I might be a good fit for!

- Devin

staring into the void

Long ago I went to a 48 hour game jam at Becker University. It was the global game jam and the theme was what do we do now? At the time I had already been working on a 2D game project on top of a javafx canvas, so I copied the text rendering code and said let's make a text adventure!

It was a fun little project, but little did we know the dangers of such a thing. You see, we were in ye olde java 7 times[1], fresh out of our second year of computer science in high school. We had even struggled to represent branching trees of text that could loop back upon themselves. Perhaps better known as directed graphs.

Our solution was to write a big ol' switch statement. Teehee 😇 what's a stack overflow?

Text was represented as strings with special tokens to change how fast text was printed. For example, "\^" meant the following text should print quickly, and "\#" meant that text should print slow. This has made many people very angry and has been widely regarded as a bad move.

A few years later, I tried to run the game out on Linux, and, surprise! 🎉
Audio doesn't play, the logic thread crashes and burns, and you're left with an unresponsive window. Write once, run anywhere, eh?[2]

So 6 years after that, I finally resolved to finish that game the right way. The core idea of void is to have text that is engaging. Sometimes you want text to wiggle, or type-write slowly, or any other of the infinite possibilities to add character to text. Which makes any markup language a natural choice for text representation.

And with that I've started using xml to represent my game text. This required parsing my xml and turning it into data structures stored in bincode files for later use. The last part to navigate then, is branching storylines. I initially decided that this would also be done in xml, so long as the logic isn't much more complicated than checking booleans - but part of me is thinking that maybe these logic checks should be done in Rust.

Anyway, that's all for today! Hopefully I won't get too distracted with other projects in the near future


  1. Technically java 8 had just come out the year before, but we were inexperienced - we didn't even know what a lambda was, let alone how to use it. Frankly, I even thought writing code in a legacy style was considered good practice because it was backwards compatible 🤦
  2. As long as you're not on linux. And while we're at it, even if you successfully create a cross-platform abstraction layer, you'd need to pack all the abstractions into one distributable. Or create multiple distributables.

autopilot

i've fallen into a pattern of metaphorically losing my mind, regaining it again, and then forgetting - returning to a state of mere existence for months at a time.

you go from thought - and i mean real, genuine thought - ...
you go from genuine thought, and you become just a process.
you may still problem solve, interact with others, et cetera, et al,
but you live on autopilot.

ask yourself: how often do you think about what you're actually doing?

where do you want to go?
how are you going to get there?
what are you actually doing?


we live on some dumb rock flying through space.
we're humans.
we live because we fuck.
--- stop and acknowledge that. ---
yet at least half of our waking lives (at work, university),
procreation is unspeakable.

...

and that's funny. maybe a little sad.
but that's not the point.
the point is that you have to put on a facade, day in and day out.
whether your facade is in regards to sex
or you're embarrassed about your immense plant collection.
you exist almost independent from your true self.
you think differently, you behave differently,
you live on autopilot.

but sometimes, for a little while, you break out.


i had a friend once
who told me that the worst mistake that you can make
is to think that you are alive...

when really, you're asleep in life's waiting room.
ukelele guy in waking life

this is a reminder to wake up.
smell the flowers.
get back to doing what you want to do.
take that trip.
get that project done.
tell her how you really feel.
take off that facade.

don't let the world pass you by.

lightboard follow-up (aka lightboard v2)

Nearly five years ago I finished a lightboard project consisting of a WS2812 LED strip, a sheet of plexiglas, and an adafruit trinket. I never did write a blog post about it, but now is as good a time as ever.

Originally, the 48"x24"x1/8" acrylic sheet was mounted with a 1/4" wide plastic J channel screwed into drywall. The top of the sheet was kept in place with a nail at each corner, allowing the acrylic to slide out easily for maintenance. This mounting solution was not quite good enough, and daily use wore down the drywall until the board could no longer stand.

A few years later, I resolved to make a better lightboard, an advanced lightboard! I built plywood shelves for an unrelated project, and used that to mount the next revision of the lightboard. The new revision uses side-mounted WS2812 LEDs, which can fit perfectly in a 1/8" aluminum J channel.

With the mounting hardware set up, it was time to work on the electronics. I had spent a good chunk of my free time in the past year writing firmware in Rust for the teensy 3.2. I hoped I could use this firmware to build the lightboard's interface, so I added SPI functionality to the teensy, and... it wasn't fast enough! Turns out, assembly is essential for firmware development. And I really did not feel like learning assembly at the time.

So, I resigned myself to learning C++ and writing the software in that with the help of Arduino libraries.

(holy heck, this is a long post, sorry)

Onto the interface! The plan is to use three rotary encoders and a small OLED screen. Then I'll plop these into a 3D printed enclosure (which I'll figure out later). For now, I've mounted the prototype to some cardboard!~

The three rotary encoders will control things like the "mode" of the lightboard - on, off, rainbow cycle, etc - parameters of different modes, and resets for those parameters. I haven't perfectly defined the interface yet, but I have plenty of options. Right now I'm thinking each mode will have three parameters, and the mode can be changed by depressing the first knob while turning.

I'm going to end this post here and leave the software for another post.

But first... A celebration!

I've recently graduated with an A.S. in Computer Information Systems, and I've been accepted into UMass Amherst for a B.S. in Mathematics! 🎉

I'm still not sure about what I'll do in the future, but at least I've accomplished a few things, eh?

Ciao!~

november has come

Wow. I can’t believe it’s been two years since my last blog post. I’ve learned a lot since the start of this blog. Well, here I am. I read a bunch of books on programming. I got my diploma and started working on a degree. Man, how time flies.

I’m trying to be more conscious of the world around me. I’m using Linux whenever possible, but some classes require otherwise. Luckily spinning up a VM is never too hard. I’ve tested out every desktop environment under the sea before finally settling on Gnome. I still can’t find a suitable terminal or file manager. These are two things that macOS seem to get right, but which no-one else can.

Ligatures! I love them. The mozilla foundation is a developer’s best friend. FiraMono/FiraCode. Rust. Firefox nightly. Just... Everything. They’re so great right now! I’m glad all their efforts are catching up to them :)

I’ve also learned a bit of OpenGL. I bought a domain and made a website which blew up on reddit for a minute. I started learning Rust and Kotlin.

The Pokemon project is still ongoing! It’s currently in a private github repository, and I think I’ll release it when the code is pretty enough. I’m refactoring the old code, updating it with new knowledge, and replacing Java with Kotlin as I go. Planning for battles - the largest part of development - is nearly complete. Everything else should move along pretty quickly, and progress should look much faster when that happens.

I’m sure I’m forgetting some things, but this will do for now.

research and whiteboards

I’ve been yelling at myself to write something for a while now, but I’ve been putting it off because I haven’t really figured out what to write. So I guess I’ll just wing it and this will be whatever it is.

Over the past however-long-it’s-been-since-my-last-post I haven’t been doing nothing. I mean I’ve mostly been doing nothing, but I haven’t been doing completely nothing. When I reached the point in my Pokemon remake where I had to gather all of the data for the Pokemon I got lazy. I really don’t like tedious work, so I kind of ignored it for a while. In the mean time I did a few other things to kill time.

The very first thing I made since I’ve been gone is a glowey-whiteboard. Here’s the final result:

The whole build needs a post of its own so I’ll try to do that within the next week.

After that I got back on track a bit. I downloaded a bunch of sprites from Veekun’s collection of downloads. I also wanted to get the animated sprites from Black/White, so I used HTTP GET requests to gather those from Pokemondb. It took a while and it ended up being something like 65MB total. Not terrible, but I can understand why Veekun wouldn’t want that on his server.

At around the same time I finally decided to get all of the Pokemon data up until gen 3. Basically I made a list of all the data needed for each Pokemon (Index #s, names, gender rates, color, egg types, etc.), and put it all into one convenient spreadsheet. I have some different pages for certain data like moves, evolutions, and forms - but I haven’t filled out forms and moves yet. I still have to decide how I’m going to program those in first. For forms/transformation I’ve been tossing around this data structure that seems to fit how GameFreak does it. There are three form interfaces: “In-battle Transforming” (Castform, Cherrim, Giratina), “Evolution Transforming” (Deoxys, Burmy, Rotom), “Non-Transforming” (Unown, Shellos). There’s probably some worksheet pages that I used just to paste some regex data, so you can ignore those.

I also added the particles for ledge-jumping and running through grass, and I’m in the process of adding battles right now, I just need to figure out how I’m going to implement it. Here’s a beautifully looped gif of the game in its current form.

I also painted and reorganized my room, and added some neat lights, which I’ll show sometime in the future whenever I get a chance.

That’s about it for the past. Now onto the future. My current non-Pokemon projects are making a smart mirror from an old laptop screen and some minicomputer, and making a custom aux cable. The smart mirror is fairly straightforward, but the aux cable is where it gets interesting.

I’ve always been frustrated by headphones. Especially expensive ones with hardware you can’t replace. The most notably example being the cord, as simple as it is. They always seem to break, usually right at the base of the jack, completely ruining a nice pair of headphones. The solution is usually to cut it off and solder on a new jack, which shortens the cord and usually comes out pretty ugly. Another thing that bothers me is the length of the wire. They’re either too short for anything but tying an iPod to your arm, or so long that they dangle down to your knees. I might be exaggerating a bit, but it begs the question: why aren’t headphone wires made to be retractable? Obviously not buds though.

So I’ve decided I’m going to a.) mount a female TRS jack where the wire splits, and b.) make a custom TRS/aux cable. As a personal choice I’d like to have it with a right-angle jack on one end, a straight jack on the other, and a paracord sheath. I also want it to have a retractable coil. This can all be done by Pexon, but it’s cheaper to do on my own and should offer some valuable experience.

The idea is to get some magnet wire, twist those together, wrap that in aluminum coated Mylar to prevent interference, cover that in a polyvinyl sleeve, then cover that in a Nylon paracord sheath, wrap the cable around a metal rod and bake it hot enough for heat memory, then twist it in the opposite direction of the coil to make it snappy, and put on the jacks. Pretty easy. The cable should be 10′ long total, and should compress to about 3′. Obviously I haven’t included all the details, but I’ll give the nitty-gritty when I make a full post on this. Overall it will cost about $50, and I’ll be able to make two cables, with each new one after that costing <$20. All that’s needed is more PVC, Mylar, paracord, and jacks. Much cheaper than the $70+ for a similar cord from Pexon.

I guess that’s about it. I already know what I’ll be working on when I finish all of everything, but I’m going to keep that on the hush hush until I at least finish this Pokemon game. That’s it for now so until the next time I decide to stop being a lazy bastard, goodbye and goodnight.

gifbackgroundifier

Finished my “GifBackgroundifier”! Set an animated .gif as your background on a Windows computer! I think it’s pretty rad, and if you’d like to try it just ask.


Download GifBackgroundifier.jar

If your GIF doesn’t work, try opening it in GIMP and exporting it to a new file with the highest quality. This is just the first version so I haven’t made an error popup, but you can tell if your GIF doesn’t work by if the loading bar moves or not.

Windows only, sorry.

Feel free to send me ideas, suggestions, or complaints!

Warning: This program uses a decent amount of processing power, about 12% on my laptop.

pocket progress 4

I’ve finally got grass working beautifully, and I actually discovered exactly how grass works through a funky glitch in FR/LG.

Here’s how it works: Use cut in the north-most grass in Route 1, take one step into Viridian city, then go back down to the grass. When you step on the empty tiles, the grass particle effects show and you still have a chance of wild encounters. I figured out that rather than having three separate particles for each “piece” of the animation (the stepped on floor, the fluttering grass/leaves, and the part that stays on above your character), it’s all in one particle, that looks like this:

and changes the depth during the animation. There’s just one frame in which the second image is behind the character which led me to the discovery.

The glitch isn’t listed anywhere I could find easily, which reminds me of another visual glitch in Vermilion City, which is less interesting, but showcases a glaring flaw with the layer system used in the generation 3 games.

And lastly, here’s a comparison between what my game looks like now, versus what the real game looks like. Pretty close, right? Forgive the input lag on the left screen (The real game).

pocket progress 3

Look at how far we’ve come! It’s not really that much but it’s exciting to me. Here you can see animations for running, biking, and cliff jumping in action! Cliff jumping still needs the offset for the sprite, the shadow, and the dust particles when you land, but the movement and animation frames are all in place!

This gif is a bit lower quality than the last one, even though it’s still at 15FPS, but it gets the point across. Anyway, that’s it for now.

Make sure to follow if you’re interested in this project. If you want to know what’s being done every day follow my daily updates page.

It isn’t shown in the gif, but you can no longer phase through the cliffs going upwards.

pocket progress 2

Collision and animations are looking good right now. Here’s a gif of where I’m at. It took me all day to figure out what the hell I was doing wrong with interrupting walking into walls.

Anyway, I also overhauled the movement and controls I’d put in yesterday because I realized exactly how the real games handled it.

You can see travelling through areas right in this, which is nice, and you can also see that I haven’t programmed in collision for cliffs yet. :x

I had to keep the gif at 15FPS to make sure it was under 2MB while not looking being mangled by compression, but the game does in fact run at 60FPS, just like a real Gameboy game.

That’s pretty much it for now. Make sure to check the Live Updates page on my blog for live updates of what I’ve done or am doing. Bye!

pocket progress 1

It may not look like much but this is really exciting progress for me and this project. This is a Pokemon recreation I’m making with Slick2D/Java that I’ve been working on for the past two weeks. There’s no collisions or animations quite yet but those should be done within the next two days.

This game is a recreation of FR/LG that’s expanded to several other regions in a single story line including Hoenn, Johto, and Orre. The main goal is to have a “pure” Pokemon game in which all Pokemon can be found and there are no weird Dex restrictions (For example, not being able to evolve a Crobat in FR/LG before the national dex, or having game specific Pokemon like Vulpix or Bellsprout).

The biggest problem is leveling throughout regions. I think the best solution is to have a level lock until you beat certain gyms - similar to how traded Pokemon of a high level refuse to listen.

If you have any ideas send me an email and I’ll think about it. Remember to check my live update page for more information on what exactly is being done!

the start of something

Last month I started re-playing Pokemon Fire Red on the VBA-M emulator. I went into the game with the goal of catching as many Pokemon as possible. After about two weeks I managed to catch 124 of the 151 in the game. That magic number also happened to be the maximum number of Pokemon you could get in either of the games.

I still wanted to catch all the Pokemon though. I’d never really be happy with it until I had all of them. So I moved my save to Leaf Green and caught all the LG exclusives. This brought me to a total of 138 caught, 149 seen. I would also only capture Female Pokemon and that I have one of every Pokemon in my box in numeric order, but that’s besides the point.

The only Pokemon I couldn’t get were the 4 trade-evolvers, the two other starters, the other fossil Pokemon (Omanyte), and the legendary Mew. Omastar and Mew were the only Pokemon I hadn’t seen.

And I wanted them.

What really sucks though is that trading on VBA-M is and has been broken forever on FR/LG. I thought: “Hey, I program, I should help out with this and figure out the glitch!” so I did just that. Kind of... I opened up the source code in Visual Studio and got it to compile right - Success! After a little while scouring the source I realized that I really didn’t know C++ well at all.

I gave up on that and decided I would make my own Pokemon game. That it should run on all systems, be able to use a controller, have online trades, have all the regions, and most importantly that you could catch all the Pokemon.

Five days later and here I am starting this dev blog.

But I’ve never really finished a project this big before, so I don’t want this to get popular until I finish. I don’t want to disappoint a lot of people. If you find this I beg you not to get too excited until I’ve made considerable progress.

I do want to finish this though, so if anyone stumbles upon this and notices I’m not updating the blog or working on the game, please spam my email or telephone or anything you can.

Email: dwbrite@gmail

Thanks~