bitWrite

Looking for any information about this function, how it's used, etc., including an example or 2. I have been unsuccessful using any search engine. Arduino.cc provides very little info.

Any help is much appreciated.

Here's an example sketch that demonstrates the use of bitWrite:

void setup() {
  Serial.begin(9600);
  while (!Serial) {}  // wait for serial port to connect. Needed for native USB port only
  byte x = 0b10000000;
  bitWrite(x, 0, 1);  // write 1 to the first bit of x
  Serial.println(x, BIN); // 10000001
}

void loop() {}

Please let me know if that's helpful and if you (or anyone else) have any suggestions for how it might be improved. If it's acceptable, I'll add it to the bitWrite reference page as example code.

The bitWrite() page needs to be expanded greatly. The example ‘looks’ ok, but, not very descriptive about what it does.

but, not very descriptive about what it does.

It writes a bit into a byte. How much detail do you need to understand that?

The syntax of bitWrite(); instruction is:

bitWrite(expression, bitPositionOfExpression, bitValue);

Assume:
byte x = 0b10000000; is an 8-bit expression
The bits are designated as 0, 1, ..., 7 from right to left.
Let us say that we wish to place 1 (HIGH) at bit-0 position of x. The instruction would be:

bitWrite(x, 0, HIGH);

Please let me know if that's helpful and if you (or anyone else) have any suggestions for how it might be improved.

I think that printing the value of x before and after the bitWrite() would make the example clearer and I wonder if something could be done to emphasise the bit order. To me

 bitWrite(x, 0, 1);  // write 1 to the first bit of x

is obviously referring to the least significant bit, but "first bit" is somewhat ambiguous

The bitWrite() page needs to be expanded greatly.

Please make some suggestions as to what you would like to see.

Changes can be made to the reference page, but those of us who understand the current reference page don’t know what you or any other “newbie” might want to see added.

Description
Writes a bit of a numeric variable.

Syntax
bitWrite(x, n, b)

Parameters
x: the numeric variable to which to write

n: which bit of the number to write, starting at 0 for the least-significant (rightmost) bit

b: the value to write to the bit (0 or 1)

Returns
Nothing

It writes a bit into a byte.

Actually bitWrite will write a bit into any integer value, not just a byte.

void setup() {
Serial.begin(115200);
unsigned int value = 0xFFFF;
Serial.println(value,BIN);
bitWrite(value, 14,0);
Serial.println(value,BIN);
unsigned long value1 = 0xFFFFFFFF;
Serial.println(value1,BIN);
bitWrite(value1, 30,0);
Serial.println(value1,BIN);
}
void loop() {}

Why have bitWrite()? what is it used for? my guess is that it would be useful for controlling single output pins on a shift register, yes? if so, how?

if so, how?

By allowing you to turn them on or off.

It could be that the poster knows how and is gently suggesting that this should be an example.

Why? Is this a statement of the obvious?

It is an obvious statement for you and me, but perhaps it is not obvious to a newbie. It is sad to have to take someone by the hand and drag them through the obvious, but sometimes it is necessary despite examples being available using search terms such as "Arduino bitWrite shift register". Sigh.

UKHeliBob:
I think that printing the value of x before and after the bitWrite() would make the example clearer

OK, I will do that.

UKHeliBob:
I wonder if something could be done to emphasise the bit order. To me

 bitWrite(x, 0, 1);  // write 1 to the first bit of x

is obviously referring to the least significant bit, but "first bit" is somewhat ambiguous

Good point. I guess the comment would be better as "write 1 to the least significant bit of x". In the reference page, there is already an explanation that "least significant" means the rightmost.

Here's my updated example:

void setup() {
  Serial.begin(9600);
  while (!Serial) {}  // wait for serial port to connect. Needed for native USB port only
  byte x = 0b10000000;  // the 0b prefix indicates a binary constant
  Serial.println(x, BIN); // 10000000
  bitWrite(x, 0, 1);  // write 1 to the least significant bit of x
  Serial.println(x, BIN); // 10000001
}

void loop() {}

I went ahead and submitted a pull request with that, but I can always update it so any additional suggestions are very welcome:

Looks good to me

bitWrite(x, 1, 1); instruction stores/writes 1 at ‘bit position 1 (bit-1)’ of x. Here, two 1s may appear confusing to readers as to referring which one is ‘bit value’ and which one is ‘bit position’. Instead, how is about to write the instruction as:

bitWrite(x, 1, HIGH);  //HIGH (1) is being stored/written at bit-1 of x 
bitWrite(x, 0, LOW);            //LOW (0) is being stored/written at bit-0 of x

We have no guarantee as to the values of HIGH and LOW. If I wanted to do something like that it would look like this:

const byte pinLowValue = 0;
const byte pinHighValue = 1;

...

bitWrite(x, 1, pinHighValue);
bitWrite(x, 0, pinLowValue);

pert:
We have no guarantee as to the values of HIGH and LOW. If I wanted to do something like that it would look like

Are they not defined in various header files of C/C++? The NULL, size_t, __int24, uint16_t, true, false, and etc. are found to have defined.

HIGH and LOW are defined only in the Arduino core library. Nowhere is it guaranteed what their values will be. They are intended to be used only with the Arduino IO functions (digitalWrite, digitalRead). They could be given any arbitrary value without breaking the API.

GolamMostafa:
bitWrite(x, 1, 1); instruction stores/writes 1 at 'bit position 1 (bit-1)' of x. Here, two 1s may appear confusing to readers as to referring which one is 'bit value' and which one is 'bit position'. Instead, how is about to write the instruction as:

bitWrite(x, 1, HIGH);  //HIGH (1) is being stored/written at bit-1 of x 

bitWrite(x, 0, LOW);            //LOW (0) is being stored/written at bit-0 of x

Until you wrote that, I thought I understood bitWrite.

Now - who's on first?

pert:
HIGH and LOW are defined only in the Arduino core library. Nowhere is it guaranteed what their values will be. They are intended to be used only with the Arduino IO functions (digitalWrite, digitalRead). They could be given any arbitrary value without breaking the API.

It is an interesting information to me. So, HIGH is high relative to low of LOW. If I assign 23 to LOW, then 56 can be assigned as high to HIGH. Now, I can do the following comparison:

if(HIGH > LOW)  //the argument will stand as true for any magnitude > 0; if it is 0.05, what will happen?
{

}

So, HIGH is not necessarily 1 as I thought; LOW is not necessarily 0 as I had. When NULL is definitely -1 (0xFFFF), then is there any symbolic name in Arduino/C/C++ that is 1 (0x0001) or 0 (0x0000)?