8.7.2 Working With Character and Byte Positions

Now that we have defined the basic character-related types, we can look at the macros and functions designed for work with them and for conversion between them. Most of these macros are defined in buffer.h, and we don't discuss all of them here, but only the most important ones. Examining the existing code is the best way to learn about them.

MAX_EMCHAR_LEN

This preprocessor constant is the maximum number of buffer bytes to represent an Emacs character in the variable width internal encoding. It is useful when allocating temporary strings to keep a known number of characters. For instance:

          {
            Charcount cclen;
            ...
            {
              /* Allocate place for cclen characters. */
              Bufbyte *buf = (Bufbyte *)alloca (cclen * MAX_EMCHAR_LEN);
          ...

If you followed the previous section, you can guess that, logically, multiplying a Charcount value with MAX_EMCHAR_LEN produces a Bytecount value.

In the current Mule implementation, MAX_EMCHAR_LEN equals 4. Without Mule, it is 1.

charptr_emchar

set_charptr_emchar

The charptr_emchar macro takes a Bufbyte pointer and returns the Emchar stored at that position. If it were a function, its prototype would be:

          Emchar charptr_emchar (Bufbyte *p);

set_charptr_emchar stores an Emchar to the specified byte position. It returns the number of bytes stored:

          Bytecount set_charptr_emchar (Bufbyte *p, Emchar c);

It is important to note that set_charptr_emchar is safe only for appending a character at the end of a buffer, not for overwriting a character in the middle. This is because the width of characters varies, and set_charptr_emchar cannot resize the string if it writes, say, a two-byte character where a single-byte character used to reside.

A typical use of set_charptr_emchar can be demonstrated by this example, which copies characters from buffer buf to a temporary string of Bufbytes.

          {
            Bufpos pos;
            for (pos = beg; pos < end; pos++)
              {
                Emchar c = BUF_FETCH_CHAR (buf, pos);
                p += set_charptr_emchar (buf, c);
              }
          }

Note how set_charptr_emchar is used to store the Emchar and increment the counter, at the same time.

INC_CHARPTR

DEC_CHARPTR

These two macros increment and decrement a Bufbyte pointer, respectively. They will adjust the pointer by the appropriate number of bytes according to the byte length of the character stored there. Both macros assume that the memory address is located at the beginning of a valid character.

Without Mule support, INC_CHARPTR (p) and DEC_CHARPTR (p) simply expand to p++ and p--, respectively.

bytecount_to_charcount

Given a pointer to a text string and a length in bytes, return the equivalent length in characters.

          Charcount bytecount_to_charcount (Bufbyte *p, Bytecount bc);

charcount_to_bytecount

Given a pointer to a text string and a length in characters, return the equivalent length in bytes.

          Bytecount charcount_to_bytecount (Bufbyte *p, Charcount cc);

charptr_n_addr

Return a pointer to the beginning of the character offset cc (in characters) from p.

          Bufbyte *charptr_n_addr (Bufbyte *p, Charcount cc);