docs: static final public int makeUTF8IntFromScalar(int c) throws IOException
      {
          // TO DO: check this encoding, it is from:
          //      http://en.wikipedia.org/wiki/UTF-8
          // we probably should use some sort of Java supported
          // library for this.  this class might be of interest:
          //     CharsetDecoder(Charset cs, float averageCharsPerByte, float maxCharsPerByte)
          // in: java.nio.charset.CharsetDecoder
  
          int value = 0;
  
          // first the quick, easy and common case - ascii
          if (c < 0x80) {
              value = (0xff & c );
          }
          else if (c < 0x800) {
              // 2 bytes characters from 0x000080 to 0x0007FF
              value  = ( 0xff & (0xC0 | (c >> 6)        ) );
              value |= ( 0xff & (0x80 | (c       & 0x3F)) ) <<  8;
          }
          else if (c < 0x10000) {
              // 3 byte characters from 0x800 to 0xFFFF
              // but only 0x800...0xD7FF and 0xE000...0xFFFF are valid
              if (c > 0xD7FF && c < 0xE000) {
                  throwUTF8Exception();
              }
              value  = ( 0xff & (0xE0 |  (c >> 12)       ) );
              value |= ( 0xff & (0x80 | ((c >>  6) & 0x3F)) ) <<  8;
              value |= ( 0xff & (0x80 |  (c        & 0x3F)) ) << 16;
  
          }
          else if (c <= 0x10FFFF) {
              // 4 byte characters 0x010000 to 0x10FFFF
              // these are are valid
              value  = ( 0xff & (0xF0 |  (c >> 18)) );
              value |= ( 0xff & (0x80 | ((c >> 12) & 0x3F)) ) <<  8;
              value |= ( 0xff & (0x80 | ((c >>  6) & 0x3F)) ) << 16;
              value |= ( 0xff & (0x80 |  (c        & 0x3F)) ) << 24;
          }
          else {
              throwUTF8Exception();
          }
          return value;
      }