Node:Digression into C, Next:defvar, Previous:kill-region, Up:Cutting & Storing Text

8.3 delete-and-extract-region: Digressing into C

The zap-to-char command uses the delete-and-extract-region function, which in turn uses two other functions, copy-region-as-kill and del_range_1. The copy-region-as-kill function will be described in a following section; it puts a copy of the region in the kill ring so it can be yanked back. (See copy-region-as-kill.)

The delete-and-extract-region function removes the contents of a region and you cannot get them back.

Unlike the other code discussed here, delete-and-extract-region is not written in Emacs Lisp; it is written in C and is one of the primitives of the GNU Emacs system. Since it is very simple, I will digress briefly from Lisp and describe it here.

Like many of the other Emacs primitives, delete-and-extract-region is written as an instance of a C macro, a macro being a template for code. The complete macro looks like this:

DEFUN ("delete-and-extract-region", Fdelete_and_extract_region,
       Sdelete_and_extract_region, 2, 2, 0,
  "Delete the text between START and END and return it.")
  (start, end)
     Lisp_Object start, end;
{
  validate_region (&start, &end);
  return del_range_1 (XINT (start), XINT (end), 1, 1);
}

Without going into the details of the macro writing process, let me point out that this macro starts with the word DEFUN. The word DEFUN was chosen since the code serves the same purpose as defun does in Lisp. The word DEFUN is followed by seven parts inside of parentheses:

• The first part is the name given to the function in Lisp, delete-and-extract-region.
• The second part is the name of the function in C, Fdelete_and_extract_region. By convention, it starts with F. Since C does not use hyphens in names, underscores are used instead.
• The third part is the name for the C constant structure that records information on this function for internal use. It is the name of the function in C but begins with an S instead of an F.
• The fourth and fifth parts specify the minimum and maximum number of arguments the function can have. This function demands exactly 2 arguments.
• The sixth part is nearly like the argument that follows the interactive declaration in a function written in Lisp: a letter followed, perhaps, by a prompt. The only difference from the Lisp is when the macro is called with no arguments. Then you write a 0 (which is a `null string'), as in this macro.

  If you were to specify arguments, you would place them between quotation marks. The C macro for goto-char includes "NGoto char: " in this position to indicate that the function expects a raw prefix, in this case, a numerical location in a buffer, and provides a prompt.

• The seventh part is a documentation string, just like the one for a function written in Emacs Lisp, except that every newline must be written explicitly as \n followed by a backslash and carriage return.

  Thus, the first two lines of documentation for goto-char are written like this:

    "Set point to POSITION, a number or marker.\n\
  Beginning of buffer is position (point-min), end is (point-max).
  

In a C macro, the formal parameters come next, with a statement of what kind of object they are, followed by what might be called the `body' of the macro. For delete-and-extract-region the `body' consists of the following two lines:

validate_region (&start, &end);
return del_range_1 (XINT (start), XINT (end), 1, 1);

The first function, validate_region checks whether the values passed as the beginning and end of the region are the proper type and are within range. The second function, del_range_1, actually deletes the text.

del_range_1 is a complex function we will not look into. It updates the buffer and does other things.

However, it is worth looking at the two arguments passed to del_range. These are XINT (start) and XINT (end).

As far as the C language is concerned, start and end are two integers that mark the beginning and end of the region to be deleted¹.

In early versions of Emacs, these two numbers were thirty-two bits long, but the code is slowly being generalized to handle other lengths. Three of the available bits are used to specify the type of information and a fourth bit is used for handling the computer's memory; the remaining bits are used as `content'.

XINT is a C macro that extracts the relevant number from the longer collection of bits; the four other bits are discarded.

The command in delete-and-extract-region looks like this:

del_range_1 (XINT (start), XINT (end), 1, 1);

It deletes the region between the beginning position, start, and the ending position, end.

From the point of view of the person writing Lisp, Emacs is all very simple; but hidden underneath is a great deal of complexity to make it all work.

Footnotes

1. More precisely, and requiring more expert knowledge to understand, the two integers are of type `Lisp_Object', which can also be a C union instead of an integer type.