Part of the Gears work I've been doing involved generating a random string to use as a "Sync ID" for a device. The server then knows where data has been taken offline to. It can then decide whether to allow it be either taken down to or sent back from a device with a different Sync ID.

This worked well and I was happy that the Sync ID format I'd come up with was suitably random. Then I happened to read Google's advice on the matter and noticed they recommend using GUIDs. This got me interested, so I read more on Wikipedia, where they say of their uniqueness:

... consider the observable universe, which contains about 5x10²² stars; every star could then have 6.8x10¹⁵ unique GUIDs.

That's the kind of geeky over-the-topness I love. Not just that it was over the top but also that they look so much more professional than some random string. Where the Sync IDs used to look something like this:

7y*e435ua^t$!q7G

Now they look like:

02D5FA82-42C1-42B7-8F9E-D188EE51F93F

Makes no difference to anybody but me really, but I like to be happy with the work I've done, no matter if other people will every appreciate the details or not.

Generating a UUID

Generating a GUID (a variant of a UUID) was easy.  I just did a quick Google and and soon found this simple bit of JavaScript. Once pasted in to my JavaScript file it worked straight away. Job done.

What niggled me was that I didn't understand what the code was doing and I don't like to just paste in any old code off the Google without really knowing what it's doing.

The logic of the code was simple -- perform a loop 36 times and build a string of random "hex" characters (0 to 9 and A to F), with a dash ("-") here and there. What had me perplexed was the following line which chose the character to insert:

In particular it was the single pipe (|) and single ampersand (&) that through me. Not to mention the odd-looking 0xf and stuff.

I've been coding in JavaScript for 10 years or more now and am used to using || and && in my code, but I'd never seen a pipe or a ampersand used in anything other than a pair.

After reaching for my copy of O'Reilly's JavaScript Pocket Guide, I soon found out that their singular use was as an a "bitwise operator" and after reading this Mozilla Developer Center page (a couple of times) it all started to make some kind of sense.

If like me of last week you don't just don't get it, then it's probably worth me writing a quick layman's guide.

A Quick Guide To Binary Counting

Here's a table with the numbers 1 to 9 in binary form:

Given any binary string you can convert it to a real number by working from the right-most "bit" (a 1 or a 0) and working towards the left. If the first bit is a 1 then you add one (to zero at this point, so you have 1). If the bit to the left of the first bit is a 1 you add 2 (now you have 3). If the bit to the left of that bit is 1 then you add 4 (now you have 7). This carries on. Notice each time you move one bit to the left the number you add doubles.

Bitwise Operations

Doing bitwise operations simply means you put the binary form of two numbers next to each other and compare the bits in each position of each binary string. For example, let's take the bitwise operation (5 | 2). This is a "bitwise or" and means we compare the bits in each number and if either of them are a 1 then we put a 1 in the same position in the resulting binary number. Otherwise we use a 0 in that position.

Here's an example of a bitwise Or operation.

Now let's look at a "Bitwise And" comparison of two numbers. In this case the resulting binary only has a 1 in each position where both the binary numbers we're inspecting also have a 1.

For example:

So, 5 | 2 = 7 whereas 5 & 2 = 0. Hope that makes sense?

Back to the JavaScript

Let's look again at the JavaScript that had me perplexed:

uuid[i] = chars[(i == 19) ? (r & 0x3) | 0x8 : r & 0xf];

The other thing which threw me was the hex number format. Although it looked familiar it took a while to work out that 0x3 is just another way (hex notation) of writing the number 3. Same goes for 0x8 being 8. While 0xf is 15, which is 00001111 in binary (8+4+2+1).  

With this knowledge I was ready to port the code.

Porting to LotusScript

Reproducing the logic of the ifs and for loops from JavaScript to LotusScript didn't take long. What took me some time was working out how to represent hex numbers in LotusScript. After a while I worked it out and this line of code of JavaScript:

uuid[i] = chars[(i == 19) ? (r & 0x3) | 0x8 : r & 0xf];

Became this LotusScript:

If i=20 Then
 uuid(i) = chars( ( r And &H3 ) Or &H8 )
Else
 uuid(i) = chars( r And &HF )
End If

The LotusScript works well and you can see a demo of it in use here. If you want a copy of the code before I make a new version of DEXT available then here's a LotusScript file with it.

Happy Now?

Although I had now ported the code and felt happier that I understood what it was doing I still had no idea why it was doing it!

Even with my new-found knowledge of Bitwise operators I still didn't know why it was comparing with 3 and then 9 for the 20th character in the string. Even after a glance at the spec it made no sense. That's the point where I decided I didn't need to go to that level and stopped worrying about it. Although, if anybody can enlighten me...

Something else I didn't get was why the author of the JavaScript was doing a Bitwise And comparison with 15 (1111) as, from what I could see, any hex number less than 16 when compared with 15 is always just itself! e.g: 7 & 15 = 15.

The other part of the JavaScript I didn't get was why it did a "bitwise or" of the random number generated with 0, like so:

r = 0 | rnd()*16;

A "bitwise or" with 0 always just returns the number being compared with it. I can only guess that it acts like a Round() function and removes the decimal part, which can't exist in the resulting binary number. Anybody?

Summary

Whether you need to use GUIDs in your LotusScript or not or even if you ever need to use other random strings of any length, hopefully, like me, you'll have learnt something if you've read this far? Even if all you've learnt it that Jake doesn't know the first thing about Computer Science...