We came up with a list of functions every device –no matter how distinct– must support, and we created an interface called DeviceProtocol that encompasses all these functions. Our interface will include functions like SetDeviceConnection, SetLogger, Read, Write, GetIMEI, SetUnit, Acknowledge, Reject, Handle, StoreRecord, and Disconnect.

// DeviceProtocol is a set of functions all supports protocols need to implement.
type DeviceProtocol interface {
	// SetDeviceConnection is called to hand the connection over to the device
	// protocol instance. This is the first thing that happens once a new
	// device is connected.
	SetDeviceConnection(net.Conn)

	// SetLogger keeps a copy of a provided Logger for the protocol to consume.
	SetLogger(logger.Logger)

	// Read allows the protocol to read a specified number of bytes directly
	// from the device. Refer to the ReadParameters structure to find out
	// and/or alter the capabilities of the Read function.
	Read(ReadParameters) (Buffer, error)

	// Write allows the protocol to send byte streams directly to the device.
	// If the number of bytes written does NOT comport with the number of bytes
	// in the slice passed to the function, an error is returned.
	Write([]byte) error

	// GetIMEI does what is necessary for the protocol to retrieve the IMEI from
	// the device. Failures can be expected, and tend to be more occasional, then
	// they need to be, so the caller needs to always watch out for errors. That
	// is, if `error` is anything other than nil, the proper action is to reject
	// the connection and bailout.
	GetIMEI() (int64, error)

	// Acknowledge is automatically called once an IMEI is retrieved and
	// authenticated.
	// NOTE: Units that are marked off as disabled in the database won't
	// be acknowledged.
	Acknowledge() error

	// Reject is automatically called if the device fails to send an IMEI
	// within a specified period of time, or if the IMEI is not found in
	// the database or if the database object is marked off as disabled.
	// This function is automatically called right before Disconnect is.
	Reject() error

	// SetUnit is called once a device is acknowledged. The point of this
	// call is to hand over the Unit object to the protocol so that the
	// protocol is capable of inferring the Unit identifier.
	SetUnit(ms.Unit)

	// Handle is the entry point to a device handler. Every supported protocol
	// needs to implement this function. <b>No abstraction version of this
	// function is provided</b> for the sole reason that different devices
	// come with different protocols.
	Handle() error

	// StoreRecord is responsible for processing one device Record at a time.
	// Record (defined in Record.go) is supposed to at least have a Unit
	// object (defined in ms/Unit.go) and a Position object (defined in
	// ms/Position.go). Whether the Position is valid or not is decided by
	// its own microservice later.
	StoreRecord(*Record) error

	// Disconnect is the last function called towards the end of the lifecycle
	// of a protocol instance. That is, the function is called before the
	// protocol instance is dismissed forever. Protocol lifecycle comes to an
	// end when the device has been idle (no data received from a device within a
	// designated timeframe), or if the device fails to send an IMEI or if the
	// device IMEI is not associated with any Unit objects in the database, or
	// if the Unit object is marked as disabled.
	Disconnect() error
}

Soon after a tracking device connects, we call SetDeviceConnection with our connection object, we then call GetIMEI that’ll internally compose a device identifier request and send it to the device using the Write function. The response is then retrieved with the Read function. Our GetIMEI function returns either the device unique identifier or an error (happens when the client fails to provide its IMEI within a designated timeframe, or when invalid data is provided or when the function identifies a suspicious activity).

A lot of these functions will have identical internal implementations. For instance,

• SetDeviceConnection, SetLogger and SetUnit are a common one-liner across all protocol implementations.
• Read and Write will be identical across all protocols given Read is flexible with its ReadParameters and Write blindlessly transmits a given slice of bites. No device-specific intelligence required.
• StoreRecord is a device-agnostic microservice-consuming function that doesn’t need to be reimplemented for every protocol.
• Disconnect performs some Record-related actions (device-agnostic, remember?) and closes the TCP connection generically.

The way around the issue is to have a form of abstraction that allows protocols to adopt at will and override when needed. Problem is Go isn’t an OOP language (that’s not to say OOP can’t be employed in the language), and so class abstraction isn’t a first-class construct of the language. What we do here is we create a DeviceProtocolHeader with our common functions defined and implemented, and aggregate the object in every protocol object we create:

// DeviceProtocolHeader has a set of abstract functions that device protocols tend to have
// in common. Instead of having to re-implement the same errorprocedures for every
// Protocol implementation, it is recommended to include this header and have
// the extra functionality at no cost.
type DeviceProtocolHeader struct {
	logger.Logger
	client     net.Conn
	Unit       ms.Unit
	lastRecord Record
}

// SetConnection ...
func (proto *DeviceProtocolHeader) SetDeviceConnection(client net.Conn) {
	proto.client = client

	// Set timeout to however many seconds ReadTimeout has.
	readParams := DefaultReadParameters()
	proto.client.SetReadDeadline(time.Now().Add(readParams.Timeout))
}

// SetLogger ...
func (proto *DeviceProtocolHeader) SetLogger(logger logger.Logger) {
	proto.Logger = logger
}

// Read ...
func (proto *DeviceProtocolHeader) Read(params ReadParameters) (Buffer, error) {
	buf := make([]byte, params.ByteCount)
	for i := 0; i <= params.MaxTimeoutAttempts; i++ {
		if bufLen, _ := proto.client.Read(buf); bufLen > 0 {
			return Buffer{buf[:bufLen]}, nil
		}
		time.Sleep(params.Timeout)
	}
	return Buffer{}, errors.New("Device read timeout")
}

// Write ...
func (proto *DeviceProtocolHeader) Write(data []byte) error {
	if bCount, err := proto.client.Write(data); err != nil {
		return err
	} else if bCount != len(data) {
		return fmt.Errorf("Failed to write some or all bytes. Expected count: %d, written count: %d", len(data), bCount)
	}
	return nil
}

// SetUnit ...
func (proto *DeviceProtocolHeader) SetUnit(unit ms.Unit) {
	proto.Unit = unit
}

// StoreRecord ...
func (proto *DeviceProtocolHeader) StoreRecord(record *Record) error {
	if record == nil {
		return errors.New("Expected a Record. Received nil")
	}

	record.Unit = proto.Unit

	record.SetLogger(proto.Logger)
	if err := record.Store(); err != nil {
		return err
	}

	if record.Position.Timestamp.After(proto.lastRecord.Position.Timestamp) {
		// Prepare the last possible Record.
		proto.lastRecord.Flags.Set(ms.Last)
		proto.lastRecord.Unit = record.Unit
		proto.lastRecord.Position = record.Position
		proto.lastRecord.Position.ID = 0
		proto.lastRecord.Position.Speed = 0
		// NOTE: Modifying the last Record can be done here.

		proto.Log(logger.INFO, "Last known Position timestamp: %v", proto.lastRecord.Position.Timestamp)
	}

	return nil
}

// Disconnect ...
func (proto *DeviceProtocolHeader) Disconnect() error {
	proto.client.Close()
	if proto.lastRecord.Flags.Has(ms.Last) {
		// Store last record. Whether this is a valid last trip or not
		// is left for upper layers to decide.
		if err := proto.StoreRecord(&proto.lastRecord); err != nil {
			proto.Log(logger.ERROR, "Error: %v", err)
			return err
		}
	}
	return nil
}

So, when introducing a new protocol object (say a proprietary ZGPS protocol), we do the following

type ZGPS struct {
    DeviceProtocolHeader
}

func (proto *ZGPS) GetIMEI() (int64, error) {
    // TODO: Here goes our proprietary IMEI retrieval implementation
}

// Acknowledge ...
func (proto *ZGPS) Acknowledge() error {
    // TODO: Here goes our proprietery device/request acknowledgment implementation
}

// Reject ...
func (proto *ZGPS) Reject() error {
	// TODO: Here goes our proprietery device/request rejection implementation
}

// Handle ...
func (proto *ZGPS) Handle() error {
    // TODO: Here goes our proprietary data/request processing implementation
}

What have we objectively achieved here?

1. We’ve set ourselves up for a zero-duplication code base.
2. We’ve added the ability to introduce higher-level system-wide business logic (take lastRecord for example) that future SMEs don’t even have to know about, making it easier to specialize at their own space.
3. Bug hunting is now easier given the code is modularized yet cohesive, and fixes will often be made in one place.

“Alternative” is an overstatement, since it is totally built on top of the native MongoDB driver, and it’s not an ODM like Mongoose, and it doesn’t provide any new functionality.

Then why did I write it? The answer is: “stronger types”. The native MongoDB driver has its type definitions in the DefinitelyTyped repository, can be easily installed, but I was annoyed by all the any keywords it was littered with. It’s not that the authors don’t know how to make it more strongly typed, it’s just that MongoDB native driver API has been designed in a way (for JavaScript) that makes strong typing almost impossible with some cases.

My journey in creating this library has given me an insight on how generic types can be so helpful in some cases, and after seeing some tweets criticizing TypeScript’s generic types, I’ve decided to write this post.

Throughout this post, I’ll use TypeScript as an example, because everyone with a JavaScript background can comprehend the code, and personally, it’s my language of choice.

Introduction to Generic Types

Let’s start with an example, a common pattern for JavaScript developers is to copy JSON objects using JSON.stringify and JSON.parse, like this:

function copyObject (obj) {
    const string = JSON.stringify(obj);
    const theCopy = JSON.parse(string);
    return theCopy;
}

The parameter obj in the above example can be anything, it can be a number, a string, an array, object literal …etc. So adding type definitions might be quite useless (without generic types):

function copyObject (obj: any): any {
    const string = JSON.stringify(obj);
    const theCopy = JSON.parse(string);
    return theCopy;
}

But with generic types, our function becomes as strongly typed as any function can be:

function copyObject<T>(obj: T): T {
    const string = JSON.stringify(obj);
    const theCopy = JSON.parse(string);
    return theCopy;
}

const myObject = { a: 0, b: 3 };

const theCopy = copyObject(myObject);

console.log(theCopy.a); // OK!
console.log(theCopy.b); // OK!
console.log(theCopy.c); // Compile Error!

The syntax for writing generic types is like many languages, before the parameters using the angle brackets.

Another example of how you can make use of generic types is when requesting data from a server.

function getFromServer<DataSchema>(url: string): Data {
    // make the request
    // and return the data
}

interface Employees {
    departmentA: string[];
    departmentB: string[];
};

const employees = getFromServer<Employees>("http://www.example.com/api/employees.json");

console.log(employees.departmentA); // OK!
console.log(employees.departmentB); // OK!
console.log(employees.departmentC); // Compile error!
console.log(employees.departmentA.length) // OK!
console.log(employees.departmentA + employees.departmentB);
// ^ Compile errors because they are arrays

The previous example shows how generic types are treated like additional arguments in the function. And that’s what they really are, additional arguments. In the first example, however, TypeScript was smart enough to determine the type of the passed value, and we did not need to pass any generic type values in angle brackets. Typescript can also be smart and notify you when you do something like this:

function copyObject<T>(obj: T): T {
    const string = JSON.stringify(obj);
    const theCopy = JSON.parse(string);
    return theCopy;
}

const myObject = { a: 0, b: 3 };

const theCopy = copyObject<number>(myObject);
// ^ Compile Error:
// Argument of type '{ a: number; b: number; }'
// is not assignable to parameter of type 'number'.

Now if you’re writing your server and your front end with typescript you don’t have to write the interface Employees twice, what you can do is structure your project in a way that the server (back-end) and the front-end share a directory where you keep type definitions.

So, in the types directory, you can have this file interface.employee.ts

export interface Employee {
    name: string;
    birth: number;
}

In your server:

import { Employee } from "../types/interface.employee.ts"
const employeesCollection = new myDB.collection<Employee>("employees");

And in your front end:

import { Employee } from "../types/interface.employee.ts"
const employees = getFromServer<Employee>("http://www.example.com/api/employees/ahmed.json");

And that barely scratches the surface of how powerful generic types can be.

Restricting Generic Types

You can also restrict how generic your generic types can be, for example, let’s say that we have a function that logs the length of the passed value (whatever it is):

function logLength (val) {
    console.log(val.length);
}

But there are only two built-in types in javascript that have the length property, String and Array. So what we can do is set a constraint on the generic type like this:

interface hasLength {
    length: number;
}

function logLength <T extends hasLength> (val: T) {
    console.log(val.length);
}

logLength("string"); // OK
logLength(["a","b","c"]); // OK
logLength({
    width: 300,
    length: 600
}); // Also OK because it has the length property
logLength(17); // Compile Error!

Index Types With Generic Types

A more elaborate example is a function that copies (Using JSON.stringify and JSON.parse) a property of any object that it receives.

function copyProperty<OBJ, KEY extends keyof OBJ>(obj: OBJ, key: KEY): OBJ[KEY] {
    const string = JSON.stringify(obj[key]);
    const copied = JSON.parse(string);
    return copied;
}

const car = { engine: "v8", milage: 123000, color: "red" };
const animal = { name: "Domestic Cat", species: "silvestris" };

copyProperty(car, "engine"); // OK
copyProperty(car, "color").length; // OK
copyProperty(car, "milage").length; // Compile error, because it's a number!
copyProperty(animal, "color"); // Compile error, because "color" is not a property on that object!
// so you can only pass the object's property names and
// typescript will be smart enough to determine their values

Now let’s step it up a bit, by making our copyProperty able to copy multiple properties on the same call, so the second argument, will be an array of property names that will be copied and returned as an array.

function copyProperties<OBJ, KEY extends keyof OBJ>(obj: OBJ, keys: Array<KEY>): Array<OBJ[KEY]> {
	return keys
		.map(x => JSON.stringify(obj[x]))
		.map(x => JSON.parse(x))
}

const car = { engine: "v8", milage: 123000, color: "red" };

const a: string[] = copyProperties(car, ["engine", "color"]); // OK
const b: string[] = copyProperties(car, ["engine", "milage"]);
// ^ Compile Error! because one of the array values is a number
// and that's because one of the properties
// we're copying is "milage".

Mapped Generic Types

Sometimes, we’d like to modify the values of the object while copying it. For example, we have this document object:

const document = {
    title: "New Document",
    content: "document content ...",
    createdAt: 1510680155148
};

We’d like the copy to hold a different value for the createdAt property. So we’ll write a function that copies objects and takes a second argument that will be property names and values to be edited.

// this is a generic type, it takes any type (object)
// as an argument and returns the same type
// but with every property being optional
type Partial<T> = {
	[P in keyof T]?: T[P]
}

function copyAndModify<T>(obj: T, mods:Partial<T>): T {
	const string = JSON.stringify(obj);
	const copy = JSON.parse(string);
	Object.keys(mods).forEach(key => {
		copy[key] = mods[key];
	});
	return copy;
}


const doc = {
    title: "New Document",
    content: "document content ...",
    createdAt: 1510680155148
};


copyAndModify(doc, { createdAt: new Date().getTime() }) // OK
copyAndModify(doc, { title: "New title" }) // OK
copyAndModify(doc, { content: 0 })
// Compile Error!
// Because content is a string, so we must
// put a string when modifying it


copyAndModify(doc, { author: "Some one" })
// Compile Error!
// Because we did not have the property author on the original document

So those were some of the ways that you can utilize generic types to write a more safe and expressive code.

Finally, I’d like to finish this post with one of my favorite quotes:

Well engineered solutions fail early, fail fast, fail often.

Happy coding!

Everything discussed here is a feature brought to you by the GCC compiler. If you happen to be using a different compiler, I’m not sure all or any of this would apply given the fact that these features aren’t part of the C programming language per se.

When writing programs of considerable size and complexity, we tend to modularize our code. That is, we try to think of all different components as objects that can be easily moved around and fit within existing and future code. In C, it’s common practice for developers to divide code into libraries and header files that can be included as needed. When working with someone else’s library, you’d normally rather have a getting-started document that’s as short and as concise as possible.

Let’s consider an example. You’re working with a team that’s responsible for implementing a stack data structure and is expected to hand you the five essential functions every stack should have: push(), pop(), peek(), isFull(), and isEmpty(). You’re probably already wondering “who’s going to initialize the stack? Do I have to? Will they hand me an initialized instance? Is it stack-allocated or heap-allocated? If it’s heap-allocated, do I have to worry about freeing it myself?” The stream of questions can literally be endless the more complex the library is. Wouldn’t it be better for the library to handle all the heavy lifting of having to instantiate all necessary data objects and do the housekeeping after itself when its job is finished (something of the nature of a constructor that’s called automatically once the library is included and a destructor that’s called when the library is done with)?

Constructors

Let’s assume we have a header file named ‘stack.h’:

#ifndef STACK_H
#define STACK_H

#include <stdio.h>   // printf
#include <stdlib.h>  // calloc & free
#include <stdbool.h> // true & false

#define STACK_CAP 12

int* stack;
unsigned int stack_ptr;

bool isEmpty() {
  return stack_ptr == 0;
}

bool isFull() {
  return stack_ptr == STACK_CAP;
}

bool push(int val) {
  if (!isFull()) {
    stack[stack_ptr++] = val;
    return true;
  }
  return false;
}

bool peek(int* ref) {
  if (!isEmpty()) {
    *ref = stack[stack_ptr - 1];
    return true;
  }
  return false;
}

bool pop(int* ref) {
  if (peek(ref)) {
    stack_ptr--;
    return true;
  }
  return false;
}

#endif

You’ve probably already noticed that stack and stack_ptr are left uninitialized, so if you were to blindly use push, peek, or pop, you’re going to run into a segmentation fault as stack is a NULL pointer, and stack_ptr is likely to contain some gibberish that was left behind on the stack. The proper way to use these functions would be to allocate memory for the stack pointer and free it when you’re done. An even better way to do this would be to have this task automatically preformed at the time of including this header file. This is done through a library constructor, and it’s done as follows:

/*  Library Constructor
    @Brief: This function is automatically called when
    the containing header file is included.
*/
__attribute__((constructor)) void start() {
   printf("Inside Constructor\n");
   stack_ptr = 0;
   stack = (int*)calloc(STACK_CAP, sizeof(int));
}

The function above needs to be located inside your header file and will be automatically called once you’ve included the header file somewhere in your code.

In case you didn’t know, #ifndef STACK_H, #define STACK_H and #endif are needed to prevent multiple or recursive includes that’ll cause the compiler to run into redefinition issues.

Now the following program:

#include <stdio.h>
#include "header.h"

int main() {
    printf("Inside main\n");
    return 0;
}

Will generate the following output:

Inside Constructor
Inside Main

And exit peacefully… Well not really peacefully. At least not in every sense of the word as your program has left some heap-allocated memory un-deallocated. You’re not likely going to see your program crash or anything, but you’ve still introduced a bug to your system that the OS may or may not be able to resolve depending on what OS you happen to be using. The proper way to go about programmatically solve this problem is to use a destructor in your application. A destructor is another function that gets called automatically once you’re done with the library. Read ahead to find out how this is done.

Destructors

You’re going to like this part.

We’ve used __attribute__((constructor)) to introduce a constructor into our code, so you’re probably already thinking a __attribute__((destructor)) is what we’d use to add a destructor, in which case you’d be absolutely right. Here’s our destructor function implementation for our stack library:

/*  Library Destructor
    @Brief: This function is automatically called when
    the containing header file is dismissed (normally
    at the end of the program lifecycle).
*/
__attribute__((destructor)) void finish() {
   printf("Inside Destructor\n");
   free(stack);
   stack = NULL;
}

Now if you execute the same tiny program we’ve written above, you’ll get the following output:

Inside Constructor
Inside Main
Inside Destructor

And there we’ve achieved a library implementation that takes care of all necessary memory management for us.

Remote Procedure Calls, if you’re not familiar with them, are library implementations that allow you to remotely host some code (normally in the form of classes and functions) and invoke those classes and functions as needed.

Why would you ever want to do that? I mean, what benefit do you get from having pieces of your code run on a remote server? There actually are a number of valid reasons why that would be the case, but I’m only interested in addressing two as I don’t want to run off topic. One reason is performance. Say a mobile app you’ve been writing requires high processing power availability to compute some complex mathematical equations. Most mobile devices aren’t meant to be cutting-edge processing devices that are able to scale up to any task you hand to them. In a case like this, you’d probably better off hand the calculation task to a more processing-ready device and ask for the results since that’s all you’re really interested in. Another reason is security. If you’re developing a banking solution, for instance, chances are you want to make it as hard as possible for reverse engineers to hack into your code and find out how deposits, withdraws, and transactions are made. RPCs are a viable option here.

Now onto some technical stuff…

If you’ve ever written TCP-based projects in your life, chances are you’ve serialized data at one end and deserialized it at the other end. Serialization often takes the form of a string that is supposedly safe to parse. If you’re a performance rat like myself, you’re probably seeing a problem already. String parsing is expensive and error prone. Having to parse a string on the fly means more code, more code (in most cases) means (1) slower code and (2) more possible bugs. More bugs means more time on debugging and less on productivity. You see where I’m going with this.

What I’d suggest as a better alternative is communicating through a stream of bytes that conform to a set of standards.

Say you’re building a remote controlled calculator with the most four basic operations (addition, subtraction, multiplication, and division). Now to be honest, I don’t know why you’d ever want to build this calculator. That’d be stupid. But for the sake of clarity, I couldn’t have thought of an easier example.

To properly send a request to your server, you’ll need to have an agreement on a request standard. Our request standard can be implemented as a C struct with a pre-determined number of bytes. All requests sent to the server must be fit within this number of byte count so the server will always know how many bytes to read at a time that make up a single request.

Before we implement our Request struct, let’s first decide what fields we need to include.

What we could do is always start with a conventional acknowledgment byte that helps both the server and the client decide whether the number of bytes read make up a valid request/response to be processed. This is extremely useful when debugging cases when one side of your project starts to misbehave, then you could do some debugging and make sure outgoing requests or incoming responses are valid by checking against the acknowledgment byte. We shall call this field ack for ease of writing.

Another useful field we could include is a request identifier. Identifiers are useful in cases when the client isn’t reading the responses right away and may have difficulty telling the responses apart. What we could do here is include the identifier as part of the response we send back as a server.

Our third field will be the operation field. This field tells us what function the user wants to execute.

We’ll also need two fields for the parameters.

Sounds about it!

Now, 1 field for ack, 1 for id, 1 for op and 2 for params add up to 5 bytes. Every time the server attempts to read a request, it’ll read exactly 5 bytes.

Our strcut will look like so:

typedef struct {
  char ack;
  char id;
  char op;
  char params[2];
} Request;

Characters in C are 1 byte (8-bit) integers. because byte isn’t a valid data type in C, we can type-define it as follows:

typedef char byte;

and use it as so:

typedef struct {
  byte ack;
  byte id;
  byte op;
  byte params[2];
} Request;

Our acknowledgment byte is consensual between the server and the client. We’ll make it 10 and set it as follows:

#define ACK 0xA

Our operations can be part of an OpType enum as follows:

typedef enum {
  ADD = 0,
  SUB,
  MUL,
  DIV
} OpType;

Which allows us to replace the byte type in our Request struct with OpType, except we’ll run into a problem that is enums in C are of type integer (4-bytes long), but this issue can be overcome by enabling the -fshort-enums GCC switch that reduces the size of enums to 1 byte. Now we can re-write our Request struct as follows:

typedef struct {
  byte ack;
  byte id;
  OpType op;
  byte params[2];
} Request;

Now let’s define our Response struct.

We’ll need a starting acknowledgment byte, so that’s one.

We’ll also need to include the request identifier. That’s two.

Not every request sent to the server is a valid request. The user may be requesting a functionality that has not been yet implemented or does not exist. For this, we could include a status field that helps the client decide whether the request was handled successfully.

If the request is handled successfully, we’ll need to return some data to the user. We’ll need a data field to contain the result.

That adds up to four bytes. Here’s what our Response object will look like:

typedef struct {
  byte ack;
  byte id;
  byte status;
  byte data;
} Response;

Now assume you have a server up and running waiting to process some requests. You’d declare a Request object and Response object as follows:

Request req  = {0};
Response res = {0};

The {0} is syntactic sugar that tells the compiler to set all values within the structure to zero.

You’d then be reading the request as follows:

read(comm_fd, (byte*)&req, sizeof(Request));

The (byte*)&req typecasts our Request struct into a byte pointer.

After a so number of bytes (5 in our case) has been read and converted to a Request object, we can go ahead and verify that the request is valid by checking against our consensual acknowledgment byte as follows:

if (req.ack == ACK) {
  // Request is successful. Move forward
}

The first thing we could do is prepare the ack and id fields in our Response object as follows:

res.ack = req.ack;
res.id = req.id;

Then call a handleRequest function that’s responsible for handling the request and handing back the data. This function (and its callees) are implemented as follows:

int handleAdd(const Request* req, Response* res) {
  printf("res->data = %d + %d\n", req->params[0], req->params[1]);
  res->data = req->params[0] + req->params[1];
  return true;
}

int handleSub(const Request* req, Response* res) {
  printf("res->data = %d - %d\n", req->params[0], req->params[1]);
  res->data = req->params[0] - req->params[1];
  return true;
}

int handleMul(const Request* req, Response* res) {
  printf("res->data = %d * %d\n", req->params[0], req->params[1]);
  res->data = req->params[0] * req->params[1];
  return true;
}

int handleDiv(const Request* req, Response* res) {
  printf("res->data = %d / %d\n", req->params[0], req->params[1]);
  res->data = req->params[0] / req->params[1];
  return true;
}

int handleRequest(const Request* req, Response* res) {
  switch (req->op) {
    case ADD:
      return handleAdd(req, res);
    case SUB:
      return handleSub(req, res);
    case MUL:
      return handleMul(req, res);
    case DIV:
      return handleDiv(req, res);
    default:
      return false;
  }
}

And can be called as follows:

if (handleRequest(&req, &res)) {
  res.status = true;
}
else {
  res.status = false;
}

The response can be sent to the client as follows:

write(comm_fd, (byte*)&res, sizeof(Response));

And there we have a fully functional RPC server implementation capable of performing just about anything when expanded.

The demo I referred to at the beginning of this post can be found here

fn add(op1: f32, op2: f32) -> f32 {
  op1 + op2
}

fn sub(op1: f32, op2: f32) -> f32 {
  op1 - op2
}

fn mul(op1: f32, op2: f32) -> f32 {
  op1 * op2
}

fn div(op1: f32, op2: f32) -> f32 {
  op1 / op2
}

And that’ll require the user to import his/her desired function or set of functions as needed. This is fine, but wouldn’t it be better if you could provide only one function that does all these operations? We’re going to call this function a common interface, but this procedure is called a passthrough in the professional field. A passthrough function is a multi-purpose entry point to a set of different classes or functions. In the case of our Math library, we could have our passthrough function written as follows:

fn passthrough(operation: &'static str, op1: f32, op2: f32) -> f32 {
  return match operation {
    "+" => add(op1, op2),
    "-" => sub(op1, op2),
    "*" => mul(op1, op2),
    "/" => div(op1, op2),
    _ => 0 as f32, //Return 0 if unknown operation. Near future bug alert!!!
  };
}

That allows us to do something like this:

let res = passthrough("+", 10 as f32, 12.3);

Instead of this:

let res = add(32.4, 12 as f32);

But there’s more we could do here. So, for instance, instead of specifying the operation as a string and expose our code to all sorts of correctness bugs (afterall, our passthrough() function won’t warn us about an invalid operation), we could do something like this:

enum OperationType {
    ADD,
    SUB,
    MUL,
    DIV,
}

fn passthrough(operation: OperationType, op1: f32, op2: f32) -> f32 {
  return match operation {
    OperationType::ADD => add(op1, op2),
    OperationType::SUB => sub(op1, op2),
    OperationType::MUL => mul(op1, op2),
    OperationType::DIV => div(op1, op2),
  };
}

That will at least force the user to select one of many options, and anything that’s not on the list won’t slide. But that’s not all either. There’s still more that can be done to tweak our code.

Notice how passthrough will always take two operands, no more or less parameters. What if, in the future, you decide to add an operation that requires only one operand (a square root function for example). You may be able to get away with something as easy as passthrough(OperationType::SQRT, 25, 0), but that neither looks clean nor is something a team of professional developers would approve of. Perhaps we could turn our operands into a flexible object, and for the sake of simplicity we shall call our object Request and have it implemented as follows:

enum Request {
    NoOps,
    OneOp(f32),
    TwoOps(f32, f32),
    ThreeOps(f32, f32, f32),
}

And re-implement our passthrough() function to work with a Request object as follows:

fn passthrough(operation: OperationType, req: Request) -> f32 {
  return match operation {
    OperationType::ADD => add(req),
    OperationType::SUB => sub(req),
    OperationType::MUL => mul(req),
    OperationType::DIV => div(req),
  };
}

And re-implement our arithmetic functions to use our Request object instead of straight operands:

fn add(req: Request) -> f32 {
  return match req {
    Request::NoOps => 0 as f32,
    Request::OneOp(a) => a,w
    Request::TwoOps(a, b) => a + b,
    Request::ThreeOps(a, b, c) => a + b + c,
  };
}

And the resulting code will then allow us to do something like this:

let res = passthrough(OperationType::ADD, Request::NoOps);

Or this:

let res = passthrough(OperationType::ADD, Request::TwoOps(10.1, 40.5));

Or this:

let res = passthrough(OperationType::ADD, Request::ThreeOps(10.1, 40.5));

There’s still more room for improvement, but you get the point.

So, “why should I consider a passthrough design?”, you may wonder! Here are some reasons why:

• Passthroughs allow you to completely maintain your own code when working with a team of developers. That is to say your code needs not be scattered around, nor will anyone need direct access to any of your functions; you make your inner functions private, provide a passthrough function and there you roll ^_^.

• Documentation becomes a breeze. Think about it. Instead of having to document every single function and provide snippets and use cases, you can keep all these functions private and only worry about documenting one: your passthrough() function. This can save you lots and lots of time.

  enum PersonGender {
    MALE,
    FEMALE,
    UNDISCLOSED,
  }

  struct Person {
    name: String,
    age: i8,
    gender: PersonGender,
  }

  fn main() {
    let person = Person {
      name: "Fadi Hanna Al-Kass".to_string(),
      age: 27,
      gender: PersonGender::MALE,
    };
  }

Now, what if a person so chooses to identify as something else? In that case, you could add a 4th option (Other) and attach a value of type String to it. Here’s what your end result would look like:

  enum PersonGender {
    MALE,
    FEMALE,
    UNDISCLOSED,
    OTHER(String),
  }

  struct Person {
    name: String,
    age: i8,
    gender: PersonGender,
  }

  fn main() {
    let person = Person {
      name: "Jake Smith".to_string(),
      age: 27,
      gender: PersonGender::OTHER("Agender".to_string()),
    };
  }

Of course enums don’t have to be part of a struct, and enum values don’t have to be primitives either. An enum value can point to a struct or even another enum and so on. For instance, you can write a function that returns a status that’s either PASS or FAILURE. PASS can include a string while FAILURE can contain more information about the severity of the failure. This functionality can be achieved as so:

  enum SeverityStatus {
    BENIGN(String),
    FATAL(String),
  }

  enum FunctionStatus {
    PASS(String),
    FAILURE(SeverityStatus),
  }

  fn compute_results() -> FunctionStatus {
    // Successful execution would look like the following:
    // return FunctionStatus::PASS("Everything looks good".to_string());

    // While a failure would be indicated as follows:
    return FunctionStatus::FAILURE(SeverityStatus::FATAL("Continuing beyond this point will cause more damage to the hardware".to_string()));
  }

Now onto match. One of the things I love the most about match is its ability to unstructure objects. Let’s take a second look at our last code snippet and see how we can possibly handle the response coming back to us from compute_results(). For this, I’d definitely use a set of match statements, e.g.:

  fn main() {
    let res = compute_results();
    match res {
      FunctionStatus::PASS(x) => {
        // Handling a PASS response
        println!("PASS: {}", x);
      }
      FunctionStatus::FAILURE(x) => {
        // Handling a FAILURE response
        match x {
          SeverityStatus::BENIGN(y) => {
            // Handling a BENIGN FAILURE response
            println!("BENIGN: {}", y);
          }
          SeverityStatus::FATAL(y) => {
            // Handling a FATAL FAILURE response
            println!("FATAL: {}", y);
          }
        };
      }
    };
  }

Now, if you happen to add more options to any of the two enums (say, a WARN option to FunctionStatus or UNCATEGORIZED to SeverityStatus), the compiler will refuse to compile your code until all possible cases are handled. This is definitely a plus as it forces you to think about all the paths your code could take.

However, there will be times when you really only want to handle specific cases and not the rest. For instance, we may only be interested in handling the case of failure of compute_results() and ignore all passes. For that you could use the _ case. _ in the case of a match statement or expression means “everything else”. So, to write our FunctionStatus handling functionality in a way when only failures are handled, we could do the following:

  fn main() {
    let res = compute_results();
    match res {
      FunctionStatus::FAILURE(severity) => {
        match severity {
          SeverityStatus::FATAL(message) => {
            println!("FATAL: {}", message);
          }
          SeverityStatus::BENIGN(message) => {
            println!("BENIGN: {}", message);
          }
        };
      }
      _ => {
        // Here goes the handling of "everything else", or it can be left out completely
      }
    };
  }

The same thing can be applied to SeverityStatus. If you want to ignore benign failures, you can replace that specific case with _.

The only drawback to using _ is that “everything else” will include any options you include in future instances, so I’d personally strongly advocate against the use of _. If you want to leave some cases unhandled, you could still include them and let them point to an empty block of code, e.g.:

  fn main() {
    let res = compute_results();
    match res {
      FunctionStatus::FAILURE(severity) => {
        match severity {
          SeverityStatus::FATAL(message) => {
            println!("FATAL: {}", message);
          }
          SeverityStatus::BENIGN(_) => {
            // Leaving this case unhandled
            // NOTE: you can't print _. If you change your mind and decide to
            // actually handle this case, replace `_` with a valid variable name.
          }
        };
      }
      FunctionStatus::PASS(_) => {
        // Leaving this case unhandled
      }
    };
  }

One last thing I wanted to touch on before I wrap up with this post. When using match to unstructure objects, you’ll come across projects with multiple fields, or even worse, nested object structures. Our Person structure can be used as an example here. How would we match this object? following’s how.

Say you’re interested in only unstructuring the gender and the age of a person object. You’d do this as follows:

  fn main() {
    let person = Person {
      name: "Fadi Hanna Al-Kass".to_string(),
      age: 27,
      gender: PersonGender::MALE,
    };

    match person {
      Person { age, gender, .. } => {
        println!("age: {}", age);
        match gender {
          PersonGender::MALE => {
            println!("gender is male");
          }
          PersonGender::FEMALE => {
            println!("gender is female");
          }
          PersonGender::UNDISCLOSED => {
            println!("gender Undisclosed");
          }
          PersonGender::OTHER(g) => {
            println!("gender: {}", g);
          }
        };
      }
    }
  }

That’s all I have for now. Don’t hesitate to hit me up if you have questions.

That was true until I was deep into my NLP project in late 2016. The code base was relatively large, so many modules and functions. A friend of mine, recommended TypeScript, and I tried it. I’ve been working with it for the last 4 months, and here are my thoughts.

Type checking is more important than what you think

You might ask: why would anyone spend their time and energy writing:

function add (a: number, b: number): number {
	return a + b;
}

Instead of:

function add (a, b) {
	return a + b;
}

The TL:DR; answer is:

• Reduced bugs.
• Compile time errors instead of runtime errors.
• Better tooling.
• Code completion.

As for time and energy, developers usually spend more time reading code than writing it. TypeScript is clean and well-designed (a Microsoft product by Anders Hejlsberg the author of C#, Turbo Pascal and Delphi). So while you’re going to spend a little bit extra time writing code, but with better tooling you’ll be reading less. Especially when working in a team.

As you import the module, you’ll have inline documentation, code completion and you can jump to definition. Those are limited, or sometimes, not even possible with a dynamic language such as JavaScript.

Reduced bugs and compile time errors

Take the previous example for instance:

let a = 1;
let b = "string";
add(a, b);

In javascript, the aforementioned code will act like nothing is wrong and would just return "1string", i.e. It will fail silently, not even a runtime error will be produced. Which is the last thing you would want.

A wise man once said:

Well engineered solutions fails early, fails fast, fails often.

And I can’t emphasize enough how true this statement is.

You might argue that “no one would pass a string to a function called add, that’s too obvious”. I agree, however, think of a larger code base, many functions, classes, abstractions, on multiple modules. Things can get out of hands in JavaScript pretty quickly.

Have a look at this code for instance:

function getAuthorLines(text) {
	return text.match(/^author: (.*)$/gmi);
}

function getAuthorNames(lines) {
	return lines.map((line)=>line.substr(8))
}

let text = "Paper title: TypeScript for the Win\nAuthor: Alex Corvi\nAuthor: John Doe\nAuthor: Jane Doe\n";

console.log(getAuthorNames(getAuthorLines(text)));

What do you expect the result to be? You guessed it, it’s:

[
	"Alex Corvi",
	"John Doe",
	"Jane Doe",
]

Now add the following line:

console.log(getAuthorNames(getAuthorLines(text.substr(0,30))));

Ouch! That’s a runtime error! That’s because String.match doesn’t always return an array, it might return null.

Here’s another code, can you spot what’s wrong?

var theThing = null;
var replaceThing = function () {
	var priorThing = theThing;
	var unused = function () {
		if (priorThing) {
			console.log("hi");
		}
	};
	theThing = {
		longStr: new Array(1000000).join('*'),
		someMethod: function () {
			console.log("abc");
		}
	};
};
setInterval(replaceThing, 1000);

That was a classic example of how you can cause memory leaks in JavaScript. This one leaks 1 MegaByte per second. In TypeScript, You can’t reassign the theThing variable from null to Object.

That doesn’t mean your applications will be bug-free. That’s never true, for any language. But surely, using TypeScript you can avoid a whole class of bugs.

One might argue, that being an experienced developer will help to avoid such bugs. Again, I agree, but:

• TypeScript (or static typing in general) is like a seat belt, not matter how good driver you are, you should always wear one.
• The JavaScript community, is heavily reliant on modules (node modules) and those have a huge variance in quality.

Static typing is like a seat belt, no matter how good driver you are, you should always wear one.

Better tooling and code completion

Code analysis, like abstract syntax trees, helps a lot with tooling. Code analysis is what makes code completion, linting, debugging tools, tree shaking tools possible. However, the dynamic nature of JavaScript makes it really hard for such tools to truly understand your code.

Take for example rollup, a bundling tool, have been recently integrated into Vue.js and React, that is supposed to tree-shake your bundles making them lighter by removing inaccessible and dead code. The author of which, Rich Harris, mentions:

Because static analysis in a dynamic language like JavaScript is hard, there will occasionally be false positives […] Rollup’s static analysis will improve over time, but it will never be perfect in all cases – that’s just JavaScript.

So there’s really a limit to what can be achieved in JavaScript tooling.

One of TypeScript’s goals was to remove such limits, and they sure did.

Here are my favorites:

• Great code completion, with Intellisense.
• Goto symbol and show all symbols.
• Better code reformatting.
• A bunch of features that are provided with TSLint but not in ESLint.
• Easy refactoring (e.g. renaming a symbol).

IntelliSense is the general term for a number of features: List Members, Parameter Info, Quick Info, and Complete Word. These features help you to learn more about the code you are using, keep track of the parameters you are typing, and add calls to properties and methods with only a few keystrokes. Microsoft Developer Network

The Syntax

But I like ES6…

I hope I’ve convinced you enough to try out TypeScript. The syntax shouldn’t be alien to a JavaScript programmer. Especially those who have tried ES6/ES7.

TypeScript brands itself as a “JavaScript Superset”, so all valid JavaScript (ES3, ES5, ES6, ES7 …etc) is valid TypeScript. Everything you’ve been accustomed to, from flow controls to assignments.

So instead of having a totally new syntax (like PureScript, Elm and Dart), TypeScript builds on top of JavaScript syntax. Yet, it adds it’s own flavor on top.

Enough talk, show me the code

I can easily bet that all javascript developers will be able to understand the following piece of code:

let x: number = 1;
let y: number = 500;

function getRand (min: number, max: number): number {
	return Math.floor(Math.random() * (max - min)) + min;
}

console.log(getRand(x, y));

So is this:

class House {
	address: string;
	bedrooms: number;
	area: number;
	safeNeighborhood:boolean;
	goodCondition:boolean;
	private priceCoefficient: number = 65;
	get price(): number {
		return ((this.bedrooms * this.area) +
			(this.safeNeighborhood ? 1000 : 0 ) +
			(this.goodCondition ? 1000 : 0 )) * this.priceCoefficient;
	}
}

let myHouse = new House();
myHouse.bedrooms = 4;
myHouse.area = 300;
myHouse.safeNeighborhood = true;
myHouse.goodCondition = true;

console.log(myHouse.price)

That was a major portion of what you’ll find in a TypeScript project.

Interfaces

Interfaces, simply put, is a way to declare JSON object types.

You can write your object type definition like this:

let myObj: { a: number; str: string; } = {
	a: 123,
	str: "my string"
}

Or you can declare a re-usable interface:

interface MyObj {
	a: number;
	str: string;
}

let myObj1: MyObj = {
	a: 123,
	str: "string"
}


let myObj2: MyObj = {
	a: 456,
	str: "another string"
}

Compilation

To be able to work in the browser & node, TypeScript compiles to JavaScript. Now you may have this preconceived notion of the compiled code being unreadable and uglified, but reality is exactly the opposite.

After type-checking, the compiler will emit very clean and readable code. So this:

let x: number = 1;
let y: number = 500;
function getRand (min: number, max: number): number {
	return Math.floor(Math.random() * (max - min)) + min;
}
console.log(getRand(x, y));

Will compile to this:

var x = 1;
var y = 500;
function getRand(min, max) {
	return Math.floor(Math.random() * (max - min)) + min;
}
console.log(getRand(x, y));

Have a look at the TypeScript Playground where you can compile TypeScript immediately in your browser. Yes, it’s being compiled in the browser. This is possible since the TypeScript compiler is written in TypeScript.

And while you’re at it, you’ll notice 2 things:

• TypeScript compiler is really fast!
• You can compile your ES6/ES7 code all the way down to ES3. No Babel required.

You won’t have to use Babel/buble anymore. TypeScript bridges the gap between the recent versions of JavaScript and what’s available on every modern browser, by compiling your code down to even ES3. However, you still have the option to compile to any ES version you like.

Type inference

One of the killer features of TypeScript, is a really good type inference. Meaning that sometimes you won’t even have to declare some of the types.

For example:

let a = 1; // inferred as a number
let str = "string"; // inferred as a string

// function return type will also be inferred
function add (a:number, b:number) {
	return a + b;
}

let b = add(1, 3); // type inferred as a number
let x = add(c, b); // compiler will produce an error

Another advanced example:

// Notice how we won't declare any types:
function myFunc (param) {
	return {
		n: 0,
		str: "myString",
		obj: {
			obj: {
				obj: {
					someVal: param > 5 ? "myString" : param > 4 ? {a:5} : ["myString", 14]
				}
			}
		}
	}
}
// hover over someVal
myFunc(10).obj.obj.obj.someVal

Now when hovering over someVal you’ll notice that it’s type is declared as:

string | Array<string|number> | {a: number;}

Try it

Node and TypeScript

Node.JS support was a priority when developing TypeScript. Your TypeScript code can be distributed as a node module, consumed in JavaScript just like any JavaScript module, and consumed in TypeScript with type declarations included, all while writing only once.

Authoring and distributing TypeScript Node Modules

When compiling your javascript you can tell the compiler to emit type definitions (only type definitions, no logic) in a separate file that can be discoverable by TypeScript, yet does not affect your module when consumed in a JavaScript project (unless your editor wanted to be smart about it).

All that you have to do is include the declaration:true in your tsconfig.json file:

{
	"declarations":true
}

then refer to this file in your package.json:

{
	"types":"./dist/index.d.ts"
}

Consuming JavaScript Node Modules In TypeScript

What if you wanted to consume a module that was written in JavaScript? Express for example. Your editor (e.g. VSCode) can only try to have an idea about the imported module, but as we’ve discussed above, tools are actually limited by the dynamic nature of JavaScript.

So your best bet is head to the DefinitelyTyped repository and find if a there’s a type definition for the module you’re consuming.

The good news is that the DefinitelyTyped repository have over 3000 modules. Chances are you’re going to find the module you’re about to use.

Example: Consuming Express in TypeScript

Install the types:

npm i --save-dev @types/express

// import
import { Request, Response, NextFunction } from "@types/express";
// declare
function myMiddleWare (req: Request, res: Response, next:NextFunction) {
	// middleware code
}

React and TypeScript

TypeScript, being an open-source community driven project, have added support for react in a really nice way.

Just like you’re going to rename your .js files to .ts, your .jsx files should be .tsx. And that’s it, now install React’s type declarations from the definitely typed repository, and feel how good it is to have everything in your project to be strong-typed. Yes! Even HTML! and CSS!

Dart, Flow, PureScript, Elm

• Flow: Is a facebook product. However, it’s not a language, it’s just a type-checker. TypeScript does what Flow does in addition to many other features. Also it has a larger community.
• Dart: Although very powerful, but Dart’s syntax is different from JavaScript. I think that’s the main reason why it didn’t catch up with the community as TypeScript did. TypeScript embraced the new ES6/ES7 features and built it’s foundation on top of them.
• PureScript & Elm: Are trying to achieve different thing, pure functional programming language, that compiles to JavaScript.

Closing statement

I’ve been developing with JavaScript for at least 5 years. However, After trying TypeScript for merly 4 months, working with JavaScript feels like walking on thin ice, you may make it for 10 meters or so, but you shouldn’t go any longer.

I can now understand why there are so many well-educated developers disliking the dynamic nature of JavaScript.

Resources

• The official documentation.
• Anders Hejlsberg Talks about TypeScript: 1 2 3.
• Definitely Typed.
• Editors and IDEs plugins: Sublime Text Atom Eclipse Vim.

So, JSON in Rust?

The short answer is ‘no built-in support for JSON but…’

Well, Rust has no built-in support for JSON objects, but before you let that throw you off, Rust structs are ~ 99% identical to JSON objects in their outer structure and the way they are defined and used. Let’s look at an example.

Say you want to define a Person JSON object with fields holding things like the full name, date of birth, and gender of a person. Here’s how you’d likely define your object in a language like JavaScript:

var person = {
  fullName: 'Fadi Hanna Al-Kass',
  dateOfBirth: '01-01-1990',
  gender: 'MALE'
};

Here’s how you’d write this in Rust:

// Our pseudo-JSON object skeleton
struct Person {
  full_name: String,
  date_of_birth: String,
  gender: String
}

fn main () {
  let person = Person {
    full_name: "Fadi Hanna Al-Kass".to_string(),
    date_of_birth: "01-01-1990".to_string(),
    gender: "MALE".to_string()
  };
}

You’ve probably already noticed two differences between the two code snippets:

1. We had to define a skeleton for our pseudo-JSON object.
2. We used lowerCamelCase with JavaScript and snake_case with our Rust code snippet. This is really nothing more than a naming convention that the Rust compiler will throw a bunch of warnings at you if you don’t follow, but it shouldn’t have an effect on the execution of your program if you so choose not to follow.

Now back to the first (and perhaps, more obvious) difference. Rust is a very (and I mean very) strongly typed programming language. That said, it needs to own as much information about your object types during the compilation process as possible. Of course, structs are no exception, and you can really consider two ways (or more, depending on how imaginational you are) of looking at this: it is either (1) limiting or (2) validating. I wouldn’t be putting this post together had I considered strong-typing limiting.

You can always replace a strongly typed pseudo-JSON object with a HashMap to get around the static typing issue, but I’d advice against that, and I believe I can convince you to stick to the struct approach. You may, at this point, still not think so, but wait until we get to these magical little thingies called traits and then we’ll see ;-)

Nested pseudo-JSON Objects?

Sure, forward we go

Let’s design our Person JSON object in a more modern fashion. Instead of having a field containing the full_name, we can turn full_name into a sub-struct that has two fields (first_name and last_name). Instead of storing date_of_birth as a string that we may, at some point, need to parse down to extract the day, month, and the year from, we can store this information in a struct with three separate fields. And for our gender field, we can reference an enum value.

struct FullName {
    first_name: String,
    last_name: String
}

struct DateOfBirth {
    day: i8,  // 8-bit integer variable
    month: i8,
    year: i16 // 16-bit integer variable
}

enum Gender {
    MALE,
    FEMALE,
    NotDisclosed
}

struct Person {
  full_name: FullName,
  date_of_birth: DateOfBirth,
  gender: Gender
}

fn main () {
  let person = Person {
      full_name: FullName {
          first_name: "Fadi".to_string(),
          last_name: "Hanna Al-Kass".to_string()
      },
      date_of_birth: DateOfBirth {
          day: 1,
          month: 1,
          year: 1990
      },
      gender: Gender::MALE
  };
}

Our pseudo-JSON object is now looking much cleaner and even easier to utilize. Speaking of utilization, how do we reference our fields? Well, you’ve probably guessed it already. Yes, it’s the dot operator. If you’re interested in, say, printing the full name of your Person object, here’s how you’d do that:

// The following line of code goes inside your main function right after
// your person object has been instantiated, or really anywhere after the
// object has been declared.

println!("{} {}", person.full_name.first_name, person.full_name.last_name);

and you’re probably seeing a problem here already. It would be absolutely tedious to use this approach to print out the full name of a person especially if you were to do this from multiple places in your program let alone the fact the way the print is done looks really primitive. There must be a different (perhaps, even, better) way you say. You bet there is. In fact, there not only is but are many ways you can go about handling this issue, which one of which would be the use of traits. A trait is a programmatical way of telling the compiler how to carry out specific functionalities during the build process. We’re going to use one here and learn how to write our own further below. The trait we’re about to use in a moment is called the Debug trait which basically sets out a specific printing layout for your defined enum, struct or what have you.

If you simply add #[derive(Debug)] right on top of your FullName struct definition: i.e.:

#[derive(Debug)]
struct FullName {
    first_name: String,
    last_name: String
}

and replace:

println!("{} {}", person.full_name.first_name, person.full_name.last_name);

with:

println!("{:?}", person.full_name);

You’ll end up with:

FullName { first_name: "Fadi", last_name: "Hanna Al-Kass" }

Cool, isn’t it? Well, it gets even cooler in a bit.

But hang on a second, why did I have to replace {} with {:?} in my println statement? Or an even more proper question to ask is: what is the difference between the two? Well, so Rust has two ways of printing out stuff (there might be even more ways I am yet to discover!): a (1) Display and a Debug. Display is what you’d probably want to use to allow the program to communicate some meaningful output to your user, and Debug is what you could use during the development process. These two traits can co-exist without overlapping each other. By that I mean you can allow your object to print something with {} and something entirely different with {:?}, but that’s to be covered when we get down to writing our own traits.

So is it possible to use #[derive(Debug)] to print out nested objects? Yes, it is, and following is how. Simply add #[derive(Debug)] right on top of your main object and every object that’s part of it and then print the object as a whole by passing it to a println function using the {:?} notation, i.e.:

#[derive(Debug)]
struct FullName {
    first_name: String,
    last_name: String
}

#[derive(Debug)]
struct DateOfBirth {
    day: i8,  // 8-bit integer variable
    month: i8,
    year: i16 // 16-bit integer variable
}

#[derive(Debug)]
enum Gender {
    MALE,
    FEMALE,
    NotDisclosed
}

#[derive(Debug)]
struct Person {
  full_name: FullName,
  date_of_birth: DateOfBirth,
  gender: Gender
}

fn main () {
  let person = Person {
      full_name: FullName {
          first_name: "Fadi".to_string(),
          last_name: "Hanna Al-Kass".to_string()
      },
      date_of_birth: DateOfBirth {
          day: 1,
          month: 1,
          year: 1990
      },
      gender: Gender::MALE
  };
  println!("{:?}", person);
}

And your output will look like:

Person { full_name: FullName { first_name: "Fadi", last_name: "Hanna Al-Kass" }, date_of_birth: DateOfBirth { day: 1, month: 1, year: 1990 }, gender: MALE }

Our output is looking pretty verbose already, and you may not like that. Is there a way to manipulate this output in terms of re-arranging its layout or limiting the amount of information being displayed? You bet there is, and it’s through writing our own Debug trait instead of using a derived one. I think it’s better to introduce one more thing right before we get down to business with traits, and that is Rust’s OOP-like paradigm. I call it OOP-like because Rust doesn’t consider itself an Object-Oriented Programming Language, but sure that in no way means we can’t do OOP in Rust. It just means OOP is done differently. To be more precise, OOP in Rust is done in a way Rust wouldn’t consider OOP.

Up until now, we’ve only been working with structs and enums. You’ve probably already noticed that we used them to store data, but no logic (constructors, functions, destructors, etc) was added to them. That’s because that’s not where the functions go. before I further explain this, let’s look at a tiny Python class and discuss how its alternative can be written in Rust. Say you have a Person class with a constructor that takes a first_name and a last_name and provides two separate getter functions that give you these two string values whenever you need them. You’d write your class something as follows:

class Person:
  def __init__(self, firstName, lastName):
    self.firstName = firstName
    self.lastName = lastName
  def getFirstName(self):
    return self.firstName
  def getLastName(self):
    return self.lastName

Notice how we have our fields and functions mixed together inside a single class. Rust separates the two. You’d have your fields defined inside a struct and an impl containing all relevant functions. So, when interpreted, our Python class would look in Rust as follows:

struct Person {
    first_name: String,
    last_name: String
}

impl Person {
    fn new (first_name: String, last_name: String) -> Person {
        return Person {
            first_name: first_name,
            last_name: last_name
        };
    }
    fn get_first_name (&self) -> &str {
        return &self.first_name;
    }

    fn get_last_name (&self) -> &str {
        return &self.last_name
    }
}

And to instantiate the object and access/utilize its functions, we do the following:

let person = Person::new("Fadi".to_string(), "Hanna Al-Kass".to_string());
println!("{}, {}", person.get_last_name(), person.get_first_name());

You’ve probably already looked at the code and thought to yourself “aha, Person::new() must be the constructor” to which you’d definitely be right. however, one thing you need to keep in mind is that Rust has no concept of a constructor per se. Instead, we define a static function that we use to instantiate our object. This also means new is not a keyword nor is it the required name of your entry point to your object; it can really be anything but new is the convention.

In short, your class constructor is a static function located inside an impl and turns an object of the type of the class you’re instantiating (Person in our case).

Traits

If this doesn’t turn you into a Rust fanatic, I don’t think anything will. Sad :-(

A trait is nothing but a language feature that tells the compiler about a type-specific functionality. The definition of a trait may be confusing as heck to you, but it’ll all settle for you with the first example or two.

Remember how we were talking about classes with constructors, functions, and destructors? Well, we’ve already discussed how constructors and functions are done in Rust. Let’s talk a little about destructors. A destructor is a class function that invokes itself once the class is out of scope. In some low-level programming languages like C++, a class destructor is normally used to deallocate all allocated memory and preform some house cleaning. Rust has an impl destruction functionality (trait) called Drop. Let’s look at how this trait can be implemented and invoked:

Let’s say you have a Response object you return to a HTTP validation layer that sends it to an end-client. Once this operation is complete, you have no business in maintaining this Response object, so it’ll delete itself once it’s out of scope. Let’s start by defining this structure:

struct Response {
  code: i32,
  message: String
}

fn main () {
  let res = Response {
    code: 200,
    message: "OK".to_string()
  };
}

Now let’s add a Drop trait to our object and see when Drop is invoked:

impl Drop for Response {
  fn drop (&mut self) {
    println!("I ran out of scope. I'm about to be destroyed")
  }
}

If you try to run the complete program now, i.e.:

struct Response {
  code: i32,
  message: String
}

impl Drop for Response {
  fn drop (&mut self) {
    println!("I ran out of scope. I'm about to be destroyed")
  }
}

fn main () {
  let res = Response {
    code: 200,
    message: "OK".to_string()
  };
}

You’ll see the following output right before the program finishes executing:

I ran out of scope. I'm about to be destroyed

Let’s look at another example. If you’ve ever done any scientific computation in Python, chances are you’ve overloaded some of the arithmetic operations (+, -, *, /, %, etc). A vector class with + overloaded would look something like the following:

class Vector:
  def __init__(self, a, b):
    self.a = a
    self.b = b
  def __add__(self, otherVector):
    return Vector(self.a + otherVector.a, self.b + otherVector.b)
  def __str__(self):
    return "Vector(%s, %s)" % (self.a, self.b)

And if you were to add two Vector objects together, you’d so something like the following:

v1 = Vector(1, 2)
v2 = Vector(5, 7)
v3 = v1 + v2

And print the result as follows:

print(v3)

This will print the following:

Vector(6, 9)

Hmm.. Let’s see how we could go about implementing this in Rust. First, we’d need to somehow find a way to add objects (i.e., overload the + operator). Second, we’d need to be able to give our object to println and see it print something like Vector(#, #). Lucky for us, both of these features are available as traits we can implement. Let’s chase them one at a time. We’ll start with the Add trait.

Here’s our Rust Vector object:

struct Vector {
  a: i32,
  b: i32
}

Then we add the constructor:

impl Vector {
    fn new (a: i32, b: i32) -> Vector {
        return Vector {
            a: a,
            b: b
        };
    }
}

We, then, add the + operation overloaded to our Vector struct as follows:

use std::ops::Add;

impl Add for Vector {
  type Output = Vector;
  fn add (self, other_vector: Vector) -> Vector {
    return Vector {
      a: self.a + other_vector.a,
      b: self.b + other_vector.b
    };
  }
}

At this point, we can have the following in our main function:

let v1 = Vector::new(1, 2);
let v2 = Vector::new(5, 7);
let v3 = v1 + v2;

But we can’t print quite yet. Let’s implement this:

use std::fmt::{Debug, Formatter, Result};
impl Debug for Vector {
  fn fmt(&self, f: &mut Formatter) -> Result {
    return write!(f, "Vector({}, {})", self.a, self.b);
  }
}

Now we can print v3 as follows:

println!("{:?}", v3);

And get the following output:

Vector(6, 9)

Your final program should look like the following:

struct Vector {
  a: i32,
  b: i32
}

impl Vector {
    fn new (a: i32, b: i32) -> Vector {
        return Vector {
            a: a,
            b: b
        };
    }
}

use std::ops::Add;
impl Add for Vector {
  type Output = Vector;
  fn add (self, other_vector: Vector) -> Vector {
    return Vector {
      a: self.a + other_vector.a,
      b: self.b + other_vector.b
    };
  }
}

use std::fmt::{Debug, Formatter, Result};
impl Debug for Vector {
  fn fmt(&self, f: &mut Formatter) -> Result {
    return write!(f, "Vector({}, {})", self.a, self.b);
  }
}

fn main () {
  let v1 = Vector::new(1, 2);
  let v2 = Vector::new(5, 7);
  let v3 = v1 + v2;
  println!("{:?}", v3);
}

Oh, and you know how I said {} is used to communicate output to the user while {:?} is usually used for debugging purposes? Well, it turns out you can overload the Display trail (available under std::fmt as well) to print your object using {} instead of {:?}.

So, simply replace:

use std::fmt::{Debug, Formatter, Result};

With:

use std::fmt::{Display, Formatter, Result};

And:

impl Debug for Vector {

With:

impl Display for Vector {

And:

println!("{:?}", v3);

With:

println!("{}", v3);

And voila, you’re all set.

Statements vs. Expressions?

At this point, I’m a bit tired of having to included unnecessary keywords in my code snippets, so I thought I’d introduce the concept of statement-vs-expression in Rust.

So, basically statements that don’t end with a semi-colon (;) return something and they even have a special label: expressions. Without getting into too much detail and get you all confused, let me instead throw a little snippet at you and let you sort it out in your head.

So, let’s say you have a function that takes two i32 arguments and returns the sum of the two values. You could have your function written like this:

fn sum (a: i32, b: i32) -> i32 {
  return a + b;
}

or you could have the shorthand notation of the function by using an expression instead of a statement:

fn sum (a: i32, b: i32) -> i32 {
  a + b
}

From this point on, I will be using expressions whenever possible.

Our Journey into the Specifics

We’re now going to dive into the basics of Rust.

Variable/Object Declaration

We’ve been declaring objects and variables all over the place already, but perhaps there’s more to them than what’s been covered already. If you want to declare an integer x and assign the value 2 to it, you could do so as follows:

let x = 2;

But if you were to write an operating system, a kernel module, and/or an application that runs on an embedded system, the size of your object really matters, and chances are you’ll need to control these sizes. Unless you dive into the specifics of the design of the compiler of Rust, you really have no idea how many bits are used to store your variable. There must be a better way to carry this out, and here’s how. Rust allows you to specify the type of your object with a slight edit to your statement. Instead of writing your variable declaration like this:

let x = 2;

You could write it like this:

let x: i8 = 2;

And you know for sure that your variable is stored as an 8-bit integer.

Read more about Primitive Types and Object Declaration here

Mutability

By default, objects and variables in Rust are immutable (not modifiable after they’ve been declared). Something like the following won’t work:

let x: i8 = 2;
x = 3;

To be able to change the value of x, we need to tell the compiler to mark our variable as mutable (able to change value after it’s been declared). This introduces a slight change to our declaration that’s pretty intuitive; you simply add the keyword mut on the left side of your object declaration statement like this:

let mut x: i8 = 2;

And now the following will work like a charm!

x = 3;

Type Aliases

Rust has a keyword called type used to declare aliases of other types. Say you want to use i32 across a whole class, module or even across your whole application, and for clarity’s sake you’d rather use Int instead of i32 to reference 32-bit integers. You could define your Int type as follows:

type Int = i32;

And now to use your new type, you could define your variables like this:

let var1: Int = 10;
let var2: Int = 20;

And so on.

Functions

Function declarations are pretty intuitive and straightforward. Say you want to write a greeting function that prints out the test "hello there!" over stdio. You’d write your function as follows:

fn greeting () {
    println!("hello there!");
}

What if you want to pass the string to the function instead of hard-coding a specific value? Then, you’d write it like this:

fn greeting (message: String) {
    // TODO: Implement me
}

Multiple function arguments? Sure! Here’s how:

fn greeting (name: String, message: String) {
    // TODO: Implement me
}

Functions with return values? Here’s how:

fn add (a: i32, b: i32) -> i32 {
 a + b
}

i32 is a 32-bit integer type in Rust. You can read more about Rust’s support for numeric types here.

Remember that we’re using an expression in the code snippet above. If you wanted to replace it with a statement return a + b; will do.

Closures

The easiest definition of a closure I can give is that a closure is a function with untyped arguments. If you were to write a function that multiplies two numbers together and return the product, you’d do so as follows:

fn mul (a: i32, b: i32) -> i32 {
	a * b
}

This function can be written as a closure as follows:

let mul = |a, b| a * b;

And then you can call it the exact same way you’d call a function, i.e.:

println!("{}", mul(10, 20));

If you, for whatever reason, want to strongly-type your closure arguments, you can do so by defining their types the same way you’d define function arguments, e.g.:

let mul = |a: i32, b: i32| a * b;

And you can even strongly-type your closure return type as follows:

let mul = |a: i32, b: i32| -> i32 {a * b};

But that’ll require you to wrap your closure content within two curly brackets ({ and }).

You can read more about most of the cool stuff you can do with closures here.

Function Pointers

If you’re coming from a solid background in languages like C and C++, chances are you’ve worked with function pointers a lot. You’ve probably even worked with function pointers in languages like JavaScript and Python without ever coming across the name. At its core, a function pointer is a variable holding access to a specific memory location representing the beginning of the function. In JavaScript, if you were to have the following:

function callee () {
  // TODO: Implement me
}

function caller (callback) {
  // TODO: Implement a task
  callback();
}

caller(callback);

It can be said that “caller is a function that takes an argument of type function pointer (which in this case is our callee function)”.

Rust isn’t that flexible when it comes to function pointers though. If you were to pass a function pointer to a function, the calling function needs to have a somewhat hard set on callback function specifications; your calling function needs to specify the arguments and the return type of the callee function. Let’s discuss a use case where you may want to use a function pointer.

Say you’re creating a struct called CommandInterface that will contain two fields: (1) a command string, and (2) a function pointer pointing to the function to be executed with the specified command. Let’s start by defining the outer skeleton of our interface struct:

struct CommandInterface {
	str: String,
	exec: fn() -> i8
}

Here we’re telling the compiler to expect our function pointer to have no arguments and return an 8-bit integer. Let’s now define a function according to these specifications:

fn ls () -> i8 {
	// TODO: Implement me
	return 0;
}

Our function needs not have a specific name. I’m only naming it after the command you’re about to see below to maintain a convention.

Let’s now define our function, set the function pointer, and see how we could use the function pointer in calling our function.

let cmd = CommandInterface {
	str: "ls".to_string(),
	exec: ls // points to the ls function declared above
};

(cmd.exec)();

The parenthesis (()) around cmd.exec are a syntax requirement. If you forget to add them, the compiler will throw an error at you.

But what about functions with arguments? Say we want to pass some command arguments to our function, how would we do that? Well, this is pretty easy and it’ll require very slight changes. You could replace:

exec: fn() -> i8

with:

exec: fn(arg1: String, arg2: String) -> i8

and:

fn ls (arg1: String, arg2: String) -> i8

with:

(cmd.exec)();

with something like this:

(cmd.exec)("-a".to_string(), "-l".to_string());

In a practical world, it’d be better to pass a vector of arguments but I intentionally ignored vectors just to keep things clean.

Conditionals

When it comes to code path redirection, Rust has the three keywords you’ll likely find in most programming languages out there: if, else, and else if. If you’ve worked with languages like C, C++, C#, Java, and JavaScript, then you already know how to work with conditional expressions in Rust. Here’s the trick: conditional expressions in Rust are done exactly the way they’re done in the languages I just mentioned, except without the wrapping parenthesis, e.g.:

The following JavaScript code:

if (x == 0 || x == 2) {
	// TODO: Implement me
}
else if (x == 1) {
	// TODO: Implement me
}
else {
	// TODO: Implement me
}

is written in Rust as follows:

if x == 0 || x == 2 {
	// TODO: Implement me
}
else if x == 1 {
	// TODO: Implement me
}
else {
	// TODO: Implement me
}

And that’s really all there is to it when it comes to code path redirection.

You might, however, be used to using the ? operator for quick things like “if x is even do this and if x is odd do that”, e.g.:

// The following JavaScript statement sets `res` to 'even' if `x` is an even value, and 'odd' if `x` is an odd value

var res = x % 2 == 0 ? 'even' : 'odd';

In Rust, the same can be written as follows:

let res = if x % 2 == 0 {"even"} else {"odd"};

Matching (aka pseudo-Switch-Case Statements)

Matching is your typical switch case code block plus the ability to return something. If you were to compare integer x against a number of different values, using classical if - else -- else if gets pretty tedious really quickly, so developers tend to resort to switch case statements. Referring back to our x example, the following JavaScript compares x against 5 different values (cases):

switch (x) {
  case 1:
    console.log('x is 1');
    break;
  case 2:
    console.log('x is 2');
    break;
  case 3:
    console.log('x is 3');
    break;
  case 4:
    console.log('x is 4');
    break;
  default:
    console.log('x is something else');
    break;
}

The snipper above can be written in Rust as follows:

match x {
    1 => println!("x is 1"),
    2 => println!("x is 2"),
    3 => println!("x is 3"),
    4 => println!("x is 4"),
    5 => println!("x is 5"),
    _ => println!("x is something else")
  };

_ is how you handle default cases

But things don’t end here; there’s more to match statements. Like I mentioned above, you can actually return a value or an object from a match statement. Let’s do some refactoring to our code snippet above and make it return the actual string instead of printing it to screen:

let res = match x {
    1 => "x is 1",
    2 => "x is 2",
    3 => "x is 3",
    4 => "x is 4",
    5 => "x is 5",
    _ => "x is something else"
  };
  println!("{}", res);

That will print the exact same thing except it handed you back the string instead of printing it, and you printed it.

match can work with sophisticated objects and patterns. Read more about it here.

Loops

Loops are a very interesting subject in Rust. The language currently has three approaches to any kind of iterative activity. These three approaches use three separate keywords: for, while, and loop.

The for loop is used when you’ve already decided the number of times you’d like to iterate. For example, the following will loop 9 times and print the values 0 through 9:

for i in 0..10 {
    println!("{}", i);
}

This interprets to the following Python code:

for i in range(0, 10):
    print("%d" % i)

You can also iterate over a list using a for loop as follows:

for i in &[10, 20, 30] {
    println!("{}", i);
}

This is equivalent to the following Python code:

for i in [10, 20, 30]:
    print("%d" % i)

for loops can also preform some sophisticated tasks. For instance, if you have the string "hello\nworld\nmy\nname\nis\nFadi" and you want it up split it up using the linefeed (\n) delimiter, you can use the lines() function. This function returns an enumerator containing both the substring and the line number. So something like the following:

let my_str_tokens = "hello\nworld\nmy\nname\nis\nFadi".lines();
for (line_no, term) in my_str_tokens.enumerate() {
    println!("{}: {}", line_no, term);
}

Results in this:

0: hello
1: world
2: my
3: name
4: is
5: Fadi

The above example is equivalent to the following Python code:

myStrTokens = "hello\nworld\nmy\nname\nis\nFadi".split("\n")
for i in range(0, len(myStrTokens)):
    print("%d: %s" % (i, myStrTokens[i]))

The while loop is used when you’re not sure how many times you need to loop. It works the exact same way a while loop works in languages like C, C++, C#, Java, JavaScript, and Python. Here’s a JavaScript example:

bool status = true;
while (status) {
  // add some case that can set `status` to false
}

The snippet above can be translated into Rust and look like the following:

let status: bool = true;
while status {
  // add some case that can set `status` to false
}

The loop loop is used when you want to run your loop indefinitely until a terminating statement is reached. An example of when this would come in handy is when you have a web server with request handlers each assigned a thread. In a case like this you wouldn’t want to have this:

let status: bool = true;

while true {
  // add some case that can set `status` to false
}

When you could actually have this:

loop {
  // add some case that can break out of the loop
}

“Rust’s control-flow analysis treats this construct differently than a while true, since we know that it will always loop. In general, the more information we can give to the compiler, the better it can do with safety and code generation, so you should always prefer loop when you plan to loop infinitely” - Quoted from https://doc.rust-lang.org/book/loops.html

Here’s one more thing you’d probably like about loops in Rust. Loops can have labels. Labels are extremely useful when working with nested loops. Here’s a JavaScript example:

var status1 = true;
var status2 = true;

while (status1) {
  while (status2) {
    status1 = false;
    status2 = false;
  }
}

The snippet above can be written with labels as follows:

'outer_loop: loop {
  'inner_loop: loop {
    break 'outer_loop;
  }
}

Read more about loops here.

I think I’ve covered enough in this post and will stop right here. More stuff is coming in upcoming posts though, so stay tuned.