16. Kill and Yank Functions

The commands in this chapter move information between the Calculator and other Emacs editing buffers.

In many cases Embedded Mode is an easier and more natural way to work with Calc from a regular editing buffer. See section 18. Embedded Mode.

16.1 Killing from the Stack

Kill commands are Emacs commands that insert text into the "kill ring," from which it can later be "yanked" by a C-y command. Three common kill commands in normal Emacs are C-k, which kills one line, C-w, which kills the region between mark and point, and M-w, which puts the region into the kill ring without actually deleting it. All of these commands work in the Calculator, too. Also, M-k has been provided to complete the set; it puts the current line into the kill ring without deleting anything.

The kill commands are unusual in that they pay attention to the location of the cursor in the Calculator buffer. If the cursor is on or below the bottom line, the kill commands operate on the top of the stack. Otherwise, they operate on whatever stack element the cursor is on. Calc's kill commands always operate on whole stack entries. (They act the same as their standard Emacs cousins except they "round up" the specified region to encompass full lines.) The text is copied into the kill ring exactly as it appears on the screen, including line numbers if they are enabled.

A numeric prefix argument to C-k or M-k affects the number of lines killed. A positive argument kills the current line and n-1 lines below it. A negative argument kills the -n lines above the current line. Again this mirrors the behavior of the standard Emacs C-k command. Although a whole line is always deleted, C-k with no argument copies only the number itself into the kill ring, whereas C-k with a prefix argument of 1 copies the number with its trailing newline.

16.2 Yanking into the Stack

The C-y command yanks the most recently killed text back into the Calculator. It pushes this value onto the top of the stack regardless of the cursor position. In general it re-parses the killed text as a number or formula (or a list of these separated by commas or newlines). However if the thing being yanked is something that was just killed from the Calculator itself, its full internal structure is yanked. For example, if you have set the floating-point display mode to show only four significant digits, then killing and re-yanking 3.14159 (which displays as 3.142) will yank the full 3.14159, even though yanking it into any other buffer would yank the number in its displayed form, 3.142. (Since the default display modes show all objects to their full precision, this feature normally makes no difference.)

16.3 Grabbing from Other Buffers

The M-# g (calc-grab-region) command takes the text between point and mark in the current buffer and attempts to parse it as a vector of values. Basically, it wraps the text in vector brackets `[ ]' unless the text already is enclosed in vector brackets, then reads the text as if it were an algebraic entry. The contents of the vector may be numbers, formulas, or any other Calc objects. If the M-# g command works successfully, it does an automatic M-# c to enter the Calculator buffer.

A numeric prefix argument grabs the specified number of lines around point, ignoring the mark. A positive prefix grabs from point to the nth following newline (so that M-1 M-# g grabs from point to the end of the current line); a negative prefix grabs from point back to the n+1st preceding newline. In these cases the text that is grabbed is exactly the same as the text that C-k would delete given that prefix argument.

A prefix of zero grabs the current line; point may be anywhere on the line.

A plain C-u prefix interprets the region between point and mark as a single number or formula rather than a vector. For example, M-# g on the text `2 a b' produces the vector of three values `[2, a, b]', but C-u M-# g on the same region reads a formula which is a product of three things: `2 a b'. (The text `a + b', on the other hand, will be grabbed as a vector of one element by plain M-# g because the interpretation `[a, +, b]' would be a syntax error.)

If a different language has been specified (see section 8.8 Language Modes), the grabbed text will be interpreted according to that language.

The M-# r (calc-grab-rectangle) command takes the text between point and mark and attempts to parse it as a matrix. If point and mark are both in the leftmost column, the lines in between are parsed in their entirety. Otherwise, point and mark define the corners of a rectangle whose contents are parsed.

Each line of the grabbed area becomes a row of the matrix. The result will actually be a vector of vectors, which Calc will treat as a matrix only if every row contains the same number of values.

If a line contains a portion surrounded by square brackets (or curly braces), that portion is interpreted as a vector which becomes a row of the matrix. Any text surrounding the bracketed portion on the line is ignored.

Otherwise, the entire line is interpreted as a row vector as if it were surrounded by square brackets. Leading line numbers (in the format used in the Calc stack buffer) are ignored. If you wish to force this interpretation (even if the line contains bracketed portions), give a negative numeric prefix argument to the M-# r command.

If you give a numeric prefix argument of zero or plain C-u, each line is instead interpreted as a single formula which is converted into a one-element vector. Thus the result of C-u M-# r will be a one-column matrix. For example, suppose one line of the data is the expression `2 a'. A plain M-# r will interpret this as `[2 a]', which in turn is read as a two-element vector that forms one row of the matrix. But a C-u M-# r will interpret this row as `[2*a]'.

If you give a positive numeric prefix argument n, then each line will be split up into columns of width n; each column is parsed separately as a matrix element. If a line contained `2 +/- 3 4 +/- 5', then grabbing with a prefix argument of 8 would correctly split the line into two error forms.

See section 11. Vector/Matrix Functions, to see how to pull the matrix apart into its constituent rows and columns. (If it is a 1x1 matrix, just hit v u (calc-unpack) twice.)

The M-# : (calc-grab-sum-down) command is a handy way to grab a rectangle of data and sum its columns. It is equivalent to typing M-# r, followed by V R : + (the vector reduction command that sums the columns of a matrix; see section 11.8.3 Reducing). The result of the command will be a vector of numbers, one for each column in the input data. The M-# _ (calc-grab-sum-across) command similarly grabs a rectangle and sums its rows by executing V R _ +.

As well as being more convenient, M-# : and M-# _ are also much faster because they don't actually place the grabbed vector on the stack. In a M-# r V R : + sequence, formatting the vector for display on the stack takes a large fraction of the total time (unless you have planned ahead and used v . and t . modes).

For example, suppose we have a column of numbers in a file which we wish to sum. Go to one corner of the column and press C-@ to set the mark; go to the other corner and type M-# :. Since there is only one column, the result will be a vector of one number, the sum. (You can type v u to unpack this vector into a plain number if you want to do further arithmetic with it.)

To compute the product of the column of numbers, we would have to do it "by hand" since there's no special grab-and-multiply command. Use M-# r to grab the column of numbers into the calculator in the form of a column matrix. The statistics command u * is a handy way to find the product of a vector or matrix of numbers. See section 11.7 Statistical Operations on Vectors. Another approach would be to use an explicit column reduction command, V R : *.

16.4 Yanking into Other Buffers

The plain y (calc-copy-to-buffer) command inserts the number at the top of the stack into the most recently used normal editing buffer. (More specifically, this is the most recently used buffer which is displayed in a window and whose name does not begin with `*'. If there is no such buffer, this is the most recently used buffer except for Calculator and Calc Trail buffers.) The number is inserted exactly as it appears and without a newline. (If line-numbering is enabled, the line number is normally not included.) The number is not removed from the stack.

With a prefix argument, y inserts several numbers, one per line. A positive argument inserts the specified number of values from the top of the stack. A negative argument inserts the nth value from the top of the stack. An argument of zero inserts the entire stack. Note that y with an argument of 1 is slightly different from y with no argument; the former always copies full lines, whereas the latter strips off the trailing newline.

With a lone C-u as a prefix argument, y replaces the region in the other buffer with the yanked text, then quits the Calculator, leaving you in that buffer. A typical use would be to use M-# g to read a region of data into the Calculator, operate on the data to produce a new matrix, then type C-u y to replace the original data with the new data. One might wish to alter the matrix display style (see section 11.9 Vector and Matrix Display Formats) or change the current display language (see section 8.8 Language Modes) before doing this. Also, note that this command replaces a linear region of text (as grabbed by M-# g), not a rectangle (as grabbed by M-# r).

If the editing buffer is in overwrite (as opposed to insert) mode, and the C-u prefix was not used, then the yanked number will overwrite the characters following point rather than being inserted before those characters. The usual conventions of overwrite mode are observed; for example, characters will be inserted at the end of a line rather than overflowing onto the next line. Yanking a multi-line object such as a matrix in overwrite mode overwrites the next n lines in the buffer, lengthening or shortening each line as necessary. Finally, if the thing being yanked is a simple integer or floating-point number (like `-1.2345e-3') and the characters following point also make up such a number, then Calc will replace that number with the new number, lengthening or shortening as necessary. The concept of "overwrite mode" has thus been generalized from overwriting characters to overwriting one complete number with another.

The M-# y key sequence is equivalent to y except that it can be typed anywhere, not just in Calc. This provides an easy way to guarantee that Calc knows which editing buffer you want to use!

16.5 X Cut and Paste

If you are using Emacs with the X window system, there is an easier way to move small amounts of data into and out of the calculator: Use the mouse-oriented cut and paste facilities of X.

The default bindings for a three-button mouse cause the left button to move the Emacs cursor to the given place, the right button to select the text between the cursor and the clicked location, and the middle button to yank the selection into the buffer at the clicked location. So, if you have a Calc window and an editing window on your Emacs screen, you can use left-click/right-click to select a number, vector, or formula from one window, then middle-click to paste that value into the other window. When you paste text into the Calc window, Calc interprets it as an algebraic entry. It doesn't matter where you click in the Calc window; the new value is always pushed onto the top of the stack.

The xterm program that is typically used for general-purpose shell windows in X interprets the mouse buttons in the same way. So you can use the mouse to move data between Calc and any other Unix program. One nice feature of xterm is that a double left-click selects one word, and a triple left-click selects a whole line. So you can usually transfer a single number into Calc just by double-clicking on it in the shell, then middle-clicking in the Calc window.

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.