TEST: going to remove some notes and clean `...send_unicode...()` up

doc/references.md

@@ -156,6 +156,20 @@
 * [Declaring and Using Bit Fields in Structures]
   (http://publib.boulder.ibm.com/infocenter/macxhelp/v6v81/index.jsp?topic=%2Fcom.ibm.vacpp6m.doc%2Flanguage%2Fref%2Fclrc03defbitf.htm)
 
+* [Bitwise shifting in C]
+  (http://stackoverflow.com/a/8422852/2360353)  
+  Shifting unsigned values is safe, left or right.  Shifting signed values is
+  not always safe.
+
+* [The signedness of `char`]
+  (http://stackoverflow.com/questions/2054939/char-is-signed-or-unsigned-by-default)  
+  Is undefined by the standard, and done differently in different compilers.
+  avr-gcc appears to treat it as signed, by default, unless `-funsigned-char`
+  is specified on the command line.  But then you have a non-default default
+  behavior... which doesn't strike me as particularly clean.  Better to use
+  `uint8_t`s when operating on things then, when possible, and to just not
+  bitshift `char`s.
+
 ### C++ Stuff
 
 * [Google C++ Style Guide]
@@ -231,6 +245,11 @@
 * [Wide characters and unicode on the AVR]
   (http://www.avrfreaks.net/index.php?name=PNphpBB2&file=printview&t=64431&start=0)
 
+* [`char` is signed, by default, in avr-gcc]
+  (http://www.avrfreaks.net/index.php?name=PNphpBB2&file=printview&t=119944&start=0)  
+  Apparently, treating `char` as signed is more common than treating it as
+  unsigned.  It can be changed to unsigned, by default, with a compiler option.
+
 
 ## Protocol Stuff
 

firmware/lib/layout/key-functions.h

@@ -31,7 +31,17 @@ void key_functions__jump_to_bootloader (void);
 // special
 void key_functions__toggle_capslock       (void);
 // --- TODO ---
-void key_functions__send_unicode_sequence (const char * string);
+void key_functions__send_unicode_sequence (const uint8_t * string);
+// TODO
+/*
+ * Implementation notes:
+ * - We use `uint8_t *` instead of `char *` because the signedness of `char` is
+ *   implementation defined (and, actually, signed by default with avr-gcc,
+ *   which is not what we want if we're going to be doing bitwise operations
+ *   and comparisons).  It appears that one can give `char *` arguments to
+ *   functions requiring `uint8_t *` ones without the compiler even giving a
+ *   warning, so this works out.
+ */
 
 
 // ----------------------------------------------------------------------------

firmware/lib/layout/key-functions/special.c

@@ -99,19 +99,13 @@ void key_functions__toggle_capslock (uint16_t ignore) {
  *                 16   1110xxxx  10xxxxxx  10xxxxxx
  *                 21   11110xxx  10xxxxxx  10xxxxxx  10xxxxxx
  *     --------------------------------------------------------
- *
- * - bit shifting (`>>` and `<<`) and then testing for equality (`==`) is
- *   weird.  need to write a note about it.
  */
-// TODO: switch to using a `const char *` and interpreting the utf-8
-// - this way we can use the `PSTR()` macro
-// TODO: stop using a manually defined wrapper... not worth it, i think
-void key_functions__send_unicode_sequence (const char * string) {
+void key_functions__send_unicode_sequence (const uint8_t * string) {
     struct _modifier_state_t state = _read_modifier_state();
     _set_modifier_state( (struct _modifier_state_t){} );
 
     // send string
-    for (uint8_t c = pgm_read_byte(string); c; c = pgm_read_byte(++string)) {
+    for (char c = pgm_read_byte(string); c; c = pgm_read_byte(++string)) {
 
         // send start sequence
 //         usb__kb__set_key(true,  KEYBOARD__LeftAlt   ); usb__kb__send_report();