+\1f
+File: internals.info, Node: Working With Character and Byte Positions, Next: Conversion to and from External Data, Prev: Character-Related Data Types, Up: Coding for Mule
+
+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);
+
projects / chise / xemacs-chise.git.1 / blobdiff