43.19 Substituting for a Character Code

The following functions replace characters within a specified region based on their character codes.

Function: subst-char-in-region start end old-char new-char &optional noundo

This function replaces all occurrences of the character old-char with the character new-char in the region of the current buffer defined by start and end.

If noundo is non-nil, then subst-char-in-region does not record the change for undo and does not mark the buffer as modified. This feature is used for controlling selective display (see Selective Display).

subst-char-in-region does not move point and returns nil.

---------- Buffer: foo ----------
This is the contents of the buffer before.
---------- Buffer: foo ----------

(subst-char-in-region 1 20 ?i ?X)
     ⇒ nil

---------- Buffer: foo ----------
ThXs Xs the contents of the buffer before.
---------- Buffer: foo ----------

Function: translate-region start end table

This function applies a translation table to the characters in the buffer between positions start and end. The translation table table can be either a string, a vector, or a char-table.

If table is a string, its nth element is the mapping for the character with code n.

If table is a vector, its nth element is the mapping for character with code n. Legal mappings are characters, strings, or nil (meaning don’t replace.)

If table is a char-table, its elements describe the mapping between characters and their replacements. The char-table should be of type char or generic.

When the table is a string or vector and its length is less than the total number of characters (256 without Mule), any characters with codes larger than the length of table are not altered by the translation.

The return value of translate-region is the number of characters that were actually changed by the translation. This does not count characters that were mapped into themselves in the translation table.

NOTE: Prior to XEmacs 21.2, the table argument was allowed only to be a string. This is still the case in FSF Emacs.

The following example creates a char-table that is passed to translate-region, which translates character ‘a’ to ‘the letter a’, removes character ‘b’, and translates character ‘c’ to newline.

---------- Buffer: foo ----------
Here is a sentence in the buffer.
---------- Buffer: foo ----------

(let ((table (make-char-table 'generic)))
  (put-char-table ?a "the letter a" table)
  (put-char-table ?b "" table)
  (put-char-table ?c ?\n table)
  (translate-region (point-min) (point-max) table))
     ⇒ 3

---------- Buffer: foo ----------
Here is the letter a senten
e in the uffer.
---------- Buffer: foo ----------