Редактирование: Binary flags (раздел)

== Changing bitflags ==

We defined our variable (disabilities) as 0, which means our mob will not have any disabilities when we start. How do we add some?

We're going to use those binary operators now.

=== Setting a bitflag ===

Above we did the following:

  var/f = 255 //0b11111111
  v3 = c & f

What happened was that completely irrespective of what c was, v3 became 0b11111111, since anything OR 1 = 1.

But we don't have to have the entire row of ones. What if we just add a single 1 in there. After all 0 OR anything = anything. The 0 doesn't change the value.

So let's write a proc, where ''dis'' is the disability we want to add (DISABILITY_EYE, DISABILITY_EAR, etc):

  mob/proc/add_disability(var/dis)
    disabilities = disabilities | dis

So if disabilities were 0b0000 before we called it, and we called it with DISABILITY_EAR, which is 2, we would get the following calculation

calling M.add_disability(DISABILITY_EAR)

disabilities = 0b0000 | 0b0010

     0b0000
  OR 0b0010
   = 0b0010

So the ''disabilities'' variable now becomes 0010, which indicates it has the poor hearing disability. But what if we called the same proc again, with the same argument DISABILITY_EAR, would anything change?

calling M.add_disability(DISABILITY_EAR)

disabilities = 0b0010 | 0b0010

     0b0010
  OR 0b0010
   = 0b0010

Nope. It remains the same, as it should.

And if we want to add another leg disability (DISABILITY_LEG)?

calling M.add_disability(DISABILITY_LEG)

disabilities = 0b0010 | 0b0100

     0b0010
  OR 0b0100
   = 0b0110

The old ear disability remains untouched, and the new leg disability is added.

=== Checking bitflags ===

Okay, so now we learned how to add a flag, now to check for one. This time AND (&) will come in handy.

Above we did...

  var/f = 255 //0b11111111
  var/e = 0   //0b11111111
  v3 = c & f  // since 1 and anything = anything, v3 didn't change from c.
  v4 = c & e  // since anything and 0 = 0, v4 was set to 0.

We can use a combination of both to help us. If we want to check for the leg disability, we can do it like this:

  mob/proc/check_disability(var/dis)
    if( disabilities & dis )
      return 1
    else
      return 0

The proc above takes a parameter and checks whether the bit is set. Let's suppose we have the same situation as we left off at above, with disabilities set to 0b0110. 

If we call check_disability(DISABILITY_EAR) the proc will check:

disabilities & dis

0b0110 & 0b0010 = 0b0010

So the value is positive, which means the if check will pass and the proc will return 1 (truth), otherwise it will return 0 (false). The value of disabilities in this proc is not changed.

If we however check for the eye disability by calling check_disability(DISABILITY_EYE)

0b0110 & 0b0001 = 0b0000

The calculation yields a 0, so the if fails, and the proc returns a 0 (false)

=== Unsetting Bitflags ===

The last thing we need to cover is how to unset bitflags. I mentioned that anything & 0 = 0, so you can be sure we'll use this.

The problem however is that the values we have (disabilities as 0b0110, DISABILITY_EYE, _EAR, _ARM, _LEG) are not really sufficient, since, if we just do a simple & between the disabilities variable and the constant for the disability, it will end up resetting everything else:

disabilities = disabilities & DISABILITY_EAR

disabilities = 0b0110 & 0b0010

disabilities = 0b0010

This is not what we want. We want the disability we add in to be reset. So we'll need a 0 in place of the disability flag, and a 1 everywhere else. This is because 1 AND anything = anything; at the same time anything AND 0 = 0.

So what we have to do is invert the DISABILITY_EAR constant. We do this with the NOT operator:

  /mob/proc/remove_disability(var/dis)
    disabilities = disabilities & ~dis

So now when we call remove_disability(DISABILITY_EAR) we will get

disabilities = disabilities & ~dis

disabilities = 0b0110 & ~0b0010

disabilities = 0b0110 & 0b1101

disabilities = 0b0100

In other words, disabilities will now no longer have the DISABILITY_EAR flag set.


=== Toggling bitflags ===
Sometimes, you want to toggle a bitflag, that is, if the bit on the flag is 1, you want to set it to 0, and if the bit is 0, you want to set it to 1

You can use the XOR function to do this due to the following properties
* where the right hand side of the XOR is a 1, it will "toggle" the bits on the left hand side in the final output
* where the right hand side of the XOR is a 0, it will leave the left hand side values unchanged in the final output

If you refer back to the [[Binary_flags#Binary_Xor_.28_.5E_.29 | XOR truth table]] you can see these principles clearly

First the truth table entries that deal with a 1 on the right hand side of the XOR operation
* 0 ^ 1 = 1
* 1 ^ 1 = 0
Then the truth table entries that deal with a 0 on the right hand side of the XOR operation
* 0 ^ 0 = 0
* 1 ^ 0 = 1


To help illustrate this concept, lets do an example where the user has the DISABILITY_ARM and the DISABILITY_EAR flags set and we want to toggle the DISABILITY_ARM flag to be the opposite of whatever it was before

disabilities = disabilities ^ DISABILITY_ARM

disabilities = 0b1010 ^ 0b1000

if we run through the XOR truth table for each pair of bits horizontally
<pre>
       0b1010
XOR    0b1000
RESULT 0b0010
</pre>

Final result, the flag for DISABILITY_ARM is toggled off, but note that DISABILITY_EAR flag is unchanged, perfect!

disabilities = 0b0010

If we want to toggle the flag again, we can repeat the operation on the current value of the binary flag variable

disabilities = disabilities ^ DISABILITY_ARM

disabilities = 0b0010 ^ 0b1000 (note DISABILITY_ARM is currently set to 0)
<pre>
       0b0010
XOR    0b1000
RESULT 0b1010
</pre>
Final result, the DISABILITY_ARM flag is toggled back on, and DISABILITY_EAR remains unchanged still.

disabilities = 0b1010

XOR can be trivially used then to toggle any specific flag by simply XORING the flag holding variable with the define that represents the bitflag you want to toggle, you can even combine sets of flags to toggle multiple at once

e.g disabilities = disabilities ^ (DISABILITY_ARM | DISABILITY_LEG)