GNU Info

(elisp)Explicit Encoding

---

Next: Terminal I/O Encoding Prev: Specifying Coding Systems Up: Coding Systems

---

Enter node , (file) or (file)node

Explicit Encoding and Decoding
------------------------------

   All the operations that transfer text in and out of Emacs have the
ability to use a coding system to encode or decode the text.  You can
also explicitly encode and decode text using the functions in this
section.

   The result of encoding, and the input to decoding, are not ordinary
text.  They logically consist of a series of byte values; that is, a
series of characters whose codes are in the range 0 through 255.  In a
multibyte buffer or string, character codes 128 through 159 are
represented by multibyte sequences, but this is invisible to Lisp
programs.

   The usual way to read a file into a buffer as a sequence of bytes, so
you can decode the contents explicitly, is with
`insert-file-contents-literally' (Note: Reading from Files);
alternatively, specify a non-`nil' RAWFILE argument when visiting a
file with `find-file-noselect'.  These methods result in a unibyte
buffer.

   The usual way to use the byte sequence that results from explicitly
encoding text is to copy it to a file or process--for example, to write
it with `write-region' (Note: Writing to Files), and suppress
encoding by binding `coding-system-for-write' to `no-conversion'.

   Here are the functions to perform explicit encoding or decoding.  The
decoding functions produce sequences of bytes; the encoding functions
are meant to operate on sequences of bytes.  All of these functions
discard text properties.

 - Function: encode-coding-region start end coding-system
     This function encodes the text from START to END according to
     coding system CODING-SYSTEM.  The encoded text replaces the
     original text in the buffer.  The result of encoding is logically a
     sequence of bytes, but the buffer remains multibyte if it was
     multibyte before.

 - Function: encode-coding-string string coding-system
     This function encodes the text in STRING according to coding
     system CODING-SYSTEM.  It returns a new string containing the
     encoded text.  The result of encoding is a unibyte string.

 - Function: decode-coding-region start end coding-system
     This function decodes the text from START to END according to
     coding system CODING-SYSTEM.  The decoded text replaces the
     original text in the buffer.  To make explicit decoding useful,
     the text before decoding ought to be a sequence of byte values,
     but both multibyte and unibyte buffers are acceptable.

 - Function: decode-coding-string string coding-system
     This function decodes the text in STRING according to coding
     system CODING-SYSTEM.  It returns a new string containing the
     decoded text.  To make explicit decoding useful, the contents of
     STRING ought to be a sequence of byte values, but a multibyte
     string is acceptable.