2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @setfilename ../info/positions
6 @node Positions, Markers, Frames, Top
8 @cindex position (in buffer)
10 A @dfn{position} is the index of a character in the text of a buffer.
11 More precisely, a position identifies the place between two characters
12 (or before the first character, or after the last character), so we can
13 speak of the character before or after a given position. However, we
14 often speak of the character ``at'' a position, meaning the character
17 Positions are usually represented as integers starting from 1, but can
18 also be represented as @dfn{markers}---special objects that relocate
19 automatically when text is inserted or deleted so they stay with the
20 surrounding characters. @xref{Markers}.
22 See also the ``field'' feature (@pxref{Fields}), which provides
23 functions that are used by many cursur-motion commands.
26 * Point:: The special position where editing takes place.
27 * Motion:: Changing point.
28 * Excursions:: Temporary motion and buffer changes.
29 * Narrowing:: Restricting editing to a portion of the buffer.
36 @dfn{Point} is a special buffer position used by many editing
37 commands, including the self-inserting typed characters and text
38 insertion functions. Other commands move point through the text
39 to allow editing and insertion at different places.
41 Like other positions, point designates a place between two characters
42 (or before the first character, or after the last character), rather
43 than a particular character. Usually terminals display the cursor over
44 the character that immediately follows point; point is actually before
45 the character on which the cursor sits.
47 @cindex point with narrowing
48 The value of point is a number no less than 1, and no greater than the
49 buffer size plus 1. If narrowing is in effect (@pxref{Narrowing}), then
50 point is constrained to fall within the accessible portion of the buffer
51 (possibly at one end of it).
53 Each buffer has its own value of point, which is independent of the
54 value of point in other buffers. Each window also has a value of point,
55 which is independent of the value of point in other windows on the same
56 buffer. This is why point can have different values in various windows
57 that display the same buffer. When a buffer appears in only one window,
58 the buffer's point and the window's point normally have the same value,
59 so the distinction is rarely important. @xref{Window Point}, for more
63 @cindex current buffer position
64 This function returns the value of point in the current buffer,
77 This function returns the minimum accessible value of point in the
78 current buffer. This is normally 1, but if narrowing is in effect, it
79 is the position of the start of the region that you narrowed to.
84 This function returns the maximum accessible value of point in the
85 current buffer. This is @code{(1+ (buffer-size))}, unless narrowing is
86 in effect, in which case it is the position of the end of the region
87 that you narrowed to. (@xref{Narrowing}.)
90 @defun buffer-end flag
91 This function returns @code{(point-min)} if @var{flag} is less than 1,
92 @code{(point-max)} otherwise. The argument @var{flag} must be a number.
95 @defun buffer-size &optional buffer
96 This function returns the total number of characters in the current
97 buffer. In the absence of any narrowing (@pxref{Narrowing}),
98 @code{point-max} returns a value one larger than this.
100 If you specify a buffer, @var{buffer}, then the value is the
101 size of @var{buffer}.
118 Motion functions change the value of point, either relative to the
119 current value of point, relative to the beginning or end of the buffer,
120 or relative to the edges of the selected window. @xref{Point}.
123 * Character Motion:: Moving in terms of characters.
124 * Word Motion:: Moving in terms of words.
125 * Buffer End Motion:: Moving to the beginning or end of the buffer.
126 * Text Lines:: Moving in terms of lines of text.
127 * Screen Lines:: Moving in terms of lines as displayed.
128 * List Motion:: Moving by parsing lists and sexps.
129 * Skipping Characters:: Skipping characters belonging to a certain set.
132 @node Character Motion
133 @subsection Motion by Characters
135 These functions move point based on a count of characters.
136 @code{goto-char} is the fundamental primitive; the other functions use
139 @deffn Command goto-char position
140 This function sets point in the current buffer to the value
141 @var{position}. If @var{position} is less than 1, it moves point to the
142 beginning of the buffer. If @var{position} is greater than the length
143 of the buffer, it moves point to the end.
145 If narrowing is in effect, @var{position} still counts from the
146 beginning of the buffer, but point cannot go outside the accessible
147 portion. If @var{position} is out of range, @code{goto-char} moves
148 point to the beginning or the end of the accessible portion.
150 When this function is called interactively, @var{position} is the
151 numeric prefix argument, if provided; otherwise it is read from the
154 @code{goto-char} returns @var{position}.
157 @deffn Command forward-char &optional count
158 @c @kindex beginning-of-buffer
159 @c @kindex end-of-buffer
160 This function moves point @var{count} characters forward, towards the
161 end of the buffer (or backward, towards the beginning of the buffer, if
162 @var{count} is negative). If the function attempts to move point past
163 the beginning or end of the buffer (or the limits of the accessible
164 portion, when narrowing is in effect), an error is signaled with error
165 code @code{beginning-of-buffer} or @code{end-of-buffer}.
167 In an interactive call, @var{count} is the numeric prefix argument.
170 @deffn Command backward-char &optional count
171 This function moves point @var{count} characters backward, towards the
172 beginning of the buffer (or forward, towards the end of the buffer, if
173 @var{count} is negative). If the function attempts to move point past
174 the beginning or end of the buffer (or the limits of the accessible
175 portion, when narrowing is in effect), an error is signaled with error
176 code @code{beginning-of-buffer} or @code{end-of-buffer}.
178 In an interactive call, @var{count} is the numeric prefix argument.
182 @subsection Motion by Words
184 These functions for parsing words use the syntax table to decide
185 whether a given character is part of a word. @xref{Syntax Tables}.
187 @deffn Command forward-word count
188 This function moves point forward @var{count} words (or backward if
189 @var{count} is negative). ``Moving one word'' means moving until point
190 crosses a word-constituent character and then encounters a
191 word-separator character. However, this function cannot move point past
192 the boundary of the accessible part of the buffer, or across a field
193 boundary (@pxref{Fields}). The most common case of a field boundary is
194 the end of the prompt in the minibuffer.
196 If it is possible to move @var{count} words, without being stopped
197 prematurely by the buffer boundary or a field boundary, the value is
198 @code{t}. Otherwise, the return value is @code{nil} and point stops at
199 the buffer boundary or field boundary.
201 In an interactive call, @var{count} is specified by the numeric prefix
205 @deffn Command backward-word count
206 This function is just like @code{forward-word}, except that it moves
207 backward until encountering the front of a word, rather than forward.
209 In an interactive call, @var{count} is set to the numeric prefix
212 This function is rarely used in programs, as it is more efficient to
213 call @code{forward-word} with a negative argument.
216 @defvar words-include-escapes
218 This variable affects the behavior of @code{forward-word} and everything
219 that uses it. If it is non-@code{nil}, then characters in the
220 ``escape'' and ``character quote'' syntax classes count as part of
221 words. Otherwise, they do not.
224 @node Buffer End Motion
225 @subsection Motion to an End of the Buffer
227 To move point to the beginning of the buffer, write:
231 (goto-char (point-min))
236 Likewise, to move to the end of the buffer, use:
240 (goto-char (point-max))
244 Here are two commands that users use to do these things. They are
245 documented here to warn you not to use them in Lisp programs, because
246 they set the mark and display messages in the echo area.
248 @deffn Command beginning-of-buffer &optional n
249 This function moves point to the beginning of the buffer (or the limits
250 of the accessible portion, when narrowing is in effect), setting the
251 mark at the previous position. If @var{n} is non-@code{nil}, then it
252 puts point @var{n} tenths of the way from the beginning of the
253 accessible portion of the buffer.
255 In an interactive call, @var{n} is the numeric prefix argument,
256 if provided; otherwise @var{n} defaults to @code{nil}.
258 @strong{Warning:} Don't use this function in Lisp programs!
261 @deffn Command end-of-buffer &optional n
262 This function moves point to the end of the buffer (or the limits of the
263 accessible portion, when narrowing is in effect), setting the mark at
264 the previous position. If @var{n} is non-@code{nil}, then it puts point
265 @var{n} tenths of the way from the end of the accessible portion of the
268 In an interactive call, @var{n} is the numeric prefix argument,
269 if provided; otherwise @var{n} defaults to @code{nil}.
271 @strong{Warning:} Don't use this function in Lisp programs!
275 @subsection Motion by Text Lines
278 Text lines are portions of the buffer delimited by newline characters,
279 which are regarded as part of the previous line. The first text line
280 begins at the beginning of the buffer, and the last text line ends at
281 the end of the buffer whether or not the last character is a newline.
282 The division of the buffer into text lines is not affected by the width
283 of the window, by line continuation in display, or by how tabs and
284 control characters are displayed.
286 @deffn Command goto-line line
287 This function moves point to the front of the @var{line}th line,
288 counting from line 1 at beginning of the buffer. If @var{line} is less
289 than 1, it moves point to the beginning of the buffer. If @var{line} is
290 greater than the number of lines in the buffer, it moves point to the
291 end of the buffer---that is, the @emph{end of the last line} of the
292 buffer. This is the only case in which @code{goto-line} does not
293 necessarily move to the beginning of a line.
295 If narrowing is in effect, then @var{line} still counts from the
296 beginning of the buffer, but point cannot go outside the accessible
297 portion. So @code{goto-line} moves point to the beginning or end of the
298 accessible portion, if the line number specifies an inaccessible
301 The return value of @code{goto-line} is the difference between
302 @var{line} and the line number of the line to which point actually was
303 able to move (in the full buffer, before taking account of narrowing).
304 Thus, the value is positive if the scan encounters the real end of the
305 buffer before finding the specified line. The value is zero if scan
306 encounters the end of the accessible portion but not the real end of the
309 In an interactive call, @var{line} is the numeric prefix argument if
310 one has been provided. Otherwise @var{line} is read in the minibuffer.
313 @deffn Command beginning-of-line &optional count
314 This function moves point to the beginning of the current line. With an
315 argument @var{count} not @code{nil} or 1, it moves forward
316 @var{count}@minus{}1 lines and then to the beginning of the line.
318 If this function reaches the end of the buffer (or of the accessible
319 portion, if narrowing is in effect), it positions point there. No error
322 This function does not move across a field boundary (@pxref{Fields}),
323 unless it moves to another line beyond the one that contains the field
324 boundary. If @var{count} is zero, and point starts at a field boundary,
325 then point does not move.
328 @defun line-beginning-position &optional count
329 @tindex line-beginning-position
330 Return the position that @code{(beginning-of-line @var{count})}
334 @deffn Command end-of-line &optional count
335 This function moves point to the end of the current line. With an
336 argument @var{count} not @code{nil} or 1, it moves forward
337 @var{count}@minus{}1 lines and then to the end of the line.
339 If this function reaches the end of the buffer (or of the accessible
340 portion, if narrowing is in effect), it positions point there. No error
343 This function does not move across a field boundary, unless it moves to
344 another line beyond the one that contains the field boundary. If
345 @var{count} is zero, and point starts at a field boundary, then point
349 @defun line-end-position &optional count
350 @tindex line-end-position
351 Return the position that @code{(end-of-line @var{count})}
355 @deffn Command forward-line &optional count
356 @cindex beginning of line
357 This function moves point forward @var{count} lines, to the beginning of
358 the line. If @var{count} is negative, it moves point
359 @minus{}@var{count} lines backward, to the beginning of a line. If
360 @var{count} is zero, it moves point to the beginning of the current
363 If @code{forward-line} encounters the beginning or end of the buffer (or
364 of the accessible portion) before finding that many lines, it sets point
365 there. No error is signaled.
367 @code{forward-line} returns the difference between @var{count} and the
368 number of lines actually moved. If you attempt to move down five lines
369 from the beginning of a buffer that has only three lines, point stops at
370 the end of the last line, and the value will be 2.
372 In an interactive call, @var{count} is the numeric prefix argument.
375 @defun count-lines start end
376 @cindex lines in region
377 This function returns the number of lines between the positions
378 @var{start} and @var{end} in the current buffer. If @var{start} and
379 @var{end} are equal, then it returns 0. Otherwise it returns at least
380 1, even if @var{start} and @var{end} are on the same line. This is
381 because the text between them, considered in isolation, must contain at
382 least one line unless it is empty.
384 Here is an example of using @code{count-lines}:
388 (defun current-line ()
389 "Return the vertical position of point@dots{}"
390 (+ (count-lines (window-start) (point))
391 (if (= (current-column) 0) 1 0)
399 The @code{previous-line} and @code{next-line} commands are functions
400 that should not be used in programs. They are for users and are
401 mentioned here only for completeness.
403 @deffn Command previous-line count
405 This function moves point up @var{count} lines (down if @var{count}
406 is negative). In moving, it attempts to keep point in the ``goal column''
407 (normally the same column that it was at the beginning of the move).
409 If there is no character in the target line exactly under the current
410 column, point is positioned after the character in that line which
411 spans this column, or at the end of the line if it is not long enough.
413 If it attempts to move beyond the top or bottom of the buffer (or clipped
414 region), then point is positioned in the goal column in the top or
415 bottom line. No error is signaled.
417 In an interactive call, @var{count} will be the numeric
420 The command @code{set-goal-column} can be used to create a semipermanent
421 goal column to which this command always moves. Then it does not try to
424 If you are thinking of using this in a Lisp program, consider using
425 @code{forward-line} with a negative argument instead. It is usually easier
426 to use and more reliable (no dependence on goal column, etc.).
429 @deffn Command next-line count
430 This function moves point down @var{count} lines (up if @var{count}
431 is negative). In moving, it attempts to keep point in the ``goal column''
432 (normally the same column that it was at the beginning of the move).
434 If there is no character in the target line exactly under the current
435 column, point is positioned after the character in that line which
436 spans this column, or at the end of the line if it is not long enough.
438 If it attempts to move beyond the top or bottom of the buffer (or clipped
439 region), then point is positioned in the goal column in the top or
440 bottom line. No error is signaled.
442 In the case where the @var{count} is 1, and point is on the last
443 line of the buffer (or clipped region), a new empty line is inserted at the
444 end of the buffer (or clipped region) and point moved there.
446 In an interactive call, @var{count} will be the numeric
449 The command @code{set-goal-column} can be used to create a semipermanent
450 goal column to which this command always moves. Then it does not try to
453 If you are thinking of using this in a Lisp program, consider using
454 @code{forward-line} instead. It is usually easier
455 to use and more reliable (no dependence on goal column, etc.).
461 Also see the functions @code{bolp} and @code{eolp} in @ref{Near Point}.
462 These functions do not move point, but test whether it is already at the
463 beginning or end of a line.
466 @subsection Motion by Screen Lines
468 The line functions in the previous section count text lines, delimited
469 only by newline characters. By contrast, these functions count screen
470 lines, which are defined by the way the text appears on the screen. A
471 text line is a single screen line if it is short enough to fit the width
472 of the selected window, but otherwise it may occupy several screen
475 In some cases, text lines are truncated on the screen rather than
476 continued onto additional screen lines. In these cases,
477 @code{vertical-motion} moves point much like @code{forward-line}.
480 Because the width of a given string depends on the flags that control
481 the appearance of certain characters, @code{vertical-motion} behaves
482 differently, for a given piece of text, depending on the buffer it is
483 in, and even on the selected window (because the width, the truncation
484 flag, and display table may vary between windows). @xref{Usual
487 These functions scan text to determine where screen lines break, and
488 thus take time proportional to the distance scanned. If you intend to
489 use them heavily, Emacs provides caches which may improve the
490 performance of your code. @xref{Truncation, cache-long-line-scans}.
493 @defun vertical-motion count &optional window
494 This function moves point to the start of the screen line @var{count}
495 screen lines down from the screen line containing point. If @var{count}
496 is negative, it moves up instead.
498 @code{vertical-motion} returns the number of screen lines over which it
499 moved point. The value may be less in absolute value than @var{count}
500 if the beginning or end of the buffer was reached.
502 The window @var{window} is used for obtaining parameters such as the
503 width, the horizontal scrolling, and the display table. But
504 @code{vertical-motion} always operates on the current buffer, even if
505 @var{window} currently displays some other buffer.
508 @deffn Command move-to-window-line count
509 This function moves point with respect to the text currently displayed
510 in the selected window. It moves point to the beginning of the screen
511 line @var{count} screen lines from the top of the window. If
512 @var{count} is negative, that specifies a position
513 @w{@minus{}@var{count}} lines from the bottom (or the last line of the
514 buffer, if the buffer ends above the specified screen position).
516 If @var{count} is @code{nil}, then point moves to the beginning of the
517 line in the middle of the window. If the absolute value of @var{count}
518 is greater than the size of the window, then point moves to the place
519 that would appear on that screen line if the window were tall enough.
520 This will probably cause the next redisplay to scroll to bring that
521 location onto the screen.
523 In an interactive call, @var{count} is the numeric prefix argument.
525 The value returned is the window line number point has moved to, with
526 the top line in the window numbered 0.
529 @defun compute-motion from frompos to topos width offsets window
530 This function scans the current buffer, calculating screen positions.
531 It scans the buffer forward from position @var{from}, assuming that is
532 at screen coordinates @var{frompos}, to position @var{to} or coordinates
533 @var{topos}, whichever comes first. It returns the ending buffer
534 position and screen coordinates.
536 The coordinate arguments @var{frompos} and @var{topos} are cons cells of
537 the form @code{(@var{hpos} . @var{vpos})}.
539 The argument @var{width} is the number of columns available to display
540 text; this affects handling of continuation lines. Use the value
541 returned by @code{window-width} for the window of your choice;
542 normally, use @code{(window-width @var{window})}.
544 The argument @var{offsets} is either @code{nil} or a cons cell of the
545 form @code{(@var{hscroll} . @var{tab-offset})}. Here @var{hscroll} is
546 the number of columns not being displayed at the left margin; most
547 callers get this by calling @code{window-hscroll}. Meanwhile,
548 @var{tab-offset} is the offset between column numbers on the screen and
549 column numbers in the buffer. This can be nonzero in a continuation
550 line, when the previous screen lines' widths do not add up to a multiple
551 of @code{tab-width}. It is always zero in a non-continuation line.
553 The window @var{window} serves only to specify which display table to
554 use. @code{compute-motion} always operates on the current buffer,
555 regardless of what buffer is displayed in @var{window}.
557 The return value is a list of five elements:
560 (@var{pos} @var{vpos} @var{hpos} @var{prevhpos} @var{contin})
564 Here @var{pos} is the buffer position where the scan stopped, @var{vpos}
565 is the vertical screen position, and @var{hpos} is the horizontal screen
568 The result @var{prevhpos} is the horizontal position one character back
569 from @var{pos}. The result @var{contin} is @code{t} if the last line
570 was continued after (or within) the previous character.
572 For example, to find the buffer position of column @var{col} of screen line
573 @var{line} of a certain window, pass the window's display start location
574 as @var{from} and the window's upper-left coordinates as @var{frompos}.
575 Pass the buffer's @code{(point-max)} as @var{to}, to limit the scan to
576 the end of the accessible portion of the buffer, and pass @var{line} and
577 @var{col} as @var{topos}. Here's a function that does this:
580 (defun coordinates-of-position (col line)
581 (car (compute-motion (window-start)
586 (cons (window-hscroll) 0)
590 When you use @code{compute-motion} for the minibuffer, you need to use
591 @code{minibuffer-prompt-width} to get the horizontal position of the
592 beginning of the first screen line. @xref{Minibuffer Misc}.
596 @comment node-name, next, previous, up
597 @subsection Moving over Balanced Expressions
599 @cindex Lisp expression motion
602 Here are several functions concerned with balanced-parenthesis
603 expressions (also called @dfn{sexps} in connection with moving across
604 them in Emacs). The syntax table controls how these functions interpret
605 various characters; see @ref{Syntax Tables}. @xref{Parsing
606 Expressions}, for lower-level primitives for scanning sexps or parts of
607 sexps. For user-level commands, see @ref{Lists Commands,,, emacs, The GNU
610 @deffn Command forward-list arg
611 This function moves forward across @var{arg} balanced groups of
612 parentheses. (Other syntactic entities such as words or paired string
616 @deffn Command backward-list arg
617 This function moves backward across @var{arg} balanced groups of
618 parentheses. (Other syntactic entities such as words or paired string
622 @deffn Command up-list arg
623 This function moves forward out of @var{arg} levels of parentheses.
624 A negative argument means move backward but still to a less deep spot.
627 @deffn Command down-list arg
628 This function moves forward into @var{arg} levels of parentheses. A
629 negative argument means move backward but still go
630 deeper in parentheses (@minus{}@var{arg} levels).
633 @deffn Command forward-sexp arg
634 This function moves forward across @var{arg} balanced expressions.
635 Balanced expressions include both those delimited by parentheses and
636 other kinds, such as words and string constants. For example,
640 ---------- Buffer: foo ----------
641 (concat@point{} "foo " (car x) y z)
642 ---------- Buffer: foo ----------
649 ---------- Buffer: foo ----------
650 (concat "foo " (car x) y@point{} z)
651 ---------- Buffer: foo ----------
656 @deffn Command backward-sexp arg
657 This function moves backward across @var{arg} balanced expressions.
660 @deffn Command beginning-of-defun arg
661 This function moves back to the @var{arg}th beginning of a defun. If
662 @var{arg} is negative, this actually moves forward, but it still moves
663 to the beginning of a defun, not to the end of one.
666 @deffn Command end-of-defun arg
667 This function moves forward to the @var{arg}th end of a defun. If
668 @var{arg} is negative, this actually moves backward, but it still moves
669 to the end of a defun, not to the beginning of one.
672 @defopt defun-prompt-regexp
673 If non-@code{nil}, this variable holds a regular expression that
674 specifies what text can appear before the open-parenthesis that starts a
675 defun. That is to say, a defun begins on a line that starts with a
676 match for this regular expression, followed by a character with
677 open-parenthesis syntax.
680 @node Skipping Characters
681 @comment node-name, next, previous, up
682 @subsection Skipping Characters
683 @cindex skipping characters
685 The following two functions move point over a specified set of
686 characters. For example, they are often used to skip whitespace. For
687 related functions, see @ref{Motion and Syntax}.
689 @defun skip-chars-forward character-set &optional limit
690 This function moves point in the current buffer forward, skipping over a
691 given set of characters. It examines the character following point,
692 then advances point if the character matches @var{character-set}. This
693 continues until it reaches a character that does not match. The
694 function returns the number of characters moved over.
696 The argument @var{character-set} is like the inside of a
697 @samp{[@dots{}]} in a regular expression except that @samp{]} is never
698 special and @samp{\} quotes @samp{^}, @samp{-} or @samp{\}. Thus,
699 @code{"a-zA-Z"} skips over all letters, stopping before the first
700 nonletter, and @code{"^a-zA-Z"} skips nonletters stopping before the
701 first letter. @xref{Regular Expressions}.
703 If @var{limit} is supplied (it must be a number or a marker), it
704 specifies the maximum position in the buffer that point can be skipped
705 to. Point will stop at or before @var{limit}.
707 In the following example, point is initially located directly before the
708 @samp{T}. After the form is evaluated, point is located at the end of
709 that line (between the @samp{t} of @samp{hat} and the newline). The
710 function skips all letters and spaces, but not newlines.
714 ---------- Buffer: foo ----------
715 I read "@point{}The cat in the hat
717 ---------- Buffer: foo ----------
721 (skip-chars-forward "a-zA-Z ")
724 ---------- Buffer: foo ----------
725 I read "The cat in the hat@point{}
727 ---------- Buffer: foo ----------
732 @defun skip-chars-backward character-set &optional limit
733 This function moves point backward, skipping characters that match
734 @var{character-set}, until @var{limit}. It is just like
735 @code{skip-chars-forward} except for the direction of motion.
737 The return value indicates the distance traveled. It is an integer that
745 It is often useful to move point ``temporarily'' within a localized
746 portion of the program, or to switch buffers temporarily. This is
747 called an @dfn{excursion}, and it is done with the @code{save-excursion}
748 special form. This construct initially remembers the identity of the
749 current buffer, and its values of point and the mark, and restores them
750 after the completion of the excursion.
752 The forms for saving and restoring the configuration of windows are
753 described elsewhere (see @ref{Window Configurations}, and @pxref{Frame
756 @defspec save-excursion forms@dots{}
757 @cindex mark excursion
758 @cindex point excursion
759 @cindex current buffer excursion
760 The @code{save-excursion} special form saves the identity of the current
761 buffer and the values of point and the mark in it, evaluates
762 @var{forms}, and finally restores the buffer and its saved values of
763 point and the mark. All three saved values are restored even in case of
764 an abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
766 The @code{save-excursion} special form is the standard way to switch
767 buffers or move point within one part of a program and avoid affecting
768 the rest of the program. It is used more than 4000 times in the Lisp
771 @code{save-excursion} does not save the values of point and the mark for
772 other buffers, so changes in other buffers remain in effect after
773 @code{save-excursion} exits.
775 @cindex window excursions
776 Likewise, @code{save-excursion} does not restore window-buffer
777 correspondences altered by functions such as @code{switch-to-buffer}.
778 One way to restore these correspondences, and the selected window, is to
779 use @code{save-window-excursion} inside @code{save-excursion}
780 (@pxref{Window Configurations}).
782 The value returned by @code{save-excursion} is the result of the last of
783 @var{forms}, or @code{nil} if no @var{forms} are given.
787 (save-excursion @var{forms})
789 (let ((old-buf (current-buffer))
790 (old-pnt (point-marker))
792 (old-mark (copy-marker (mark-marker))))
798 (set-marker (mark-marker) old-mark)))
803 @strong{Warning:} Ordinary insertion of text adjacent to the saved
804 point value relocates the saved value, just as it relocates all markers.
805 Therefore, when the saved point value is restored, it normally comes
806 before the inserted text.
808 Although @code{save-excursion} saves the location of the mark, it does
809 not prevent functions which modify the buffer from setting
810 @code{deactivate-mark}, and thus causing the deactivation of the mark
811 after the command finishes. @xref{The Mark}.
816 @cindex restriction (in a buffer)
817 @cindex accessible portion (of a buffer)
819 @dfn{Narrowing} means limiting the text addressable by Emacs editing
820 commands to a limited range of characters in a buffer. The text that
821 remains addressable is called the @dfn{accessible portion} of the
824 Narrowing is specified with two buffer positions which become the
825 beginning and end of the accessible portion. For most editing commands
826 and most Emacs primitives, these positions replace the values of the
827 beginning and end of the buffer. While narrowing is in effect, no text
828 outside the accessible portion is displayed, and point cannot move
829 outside the accessible portion.
831 Values such as positions or line numbers, which usually count from the
832 beginning of the buffer, do so despite narrowing, but the functions
833 which use them refuse to operate on text that is inaccessible.
835 The commands for saving buffers are unaffected by narrowing; they save
836 the entire buffer regardless of any narrowing.
838 @deffn Command narrow-to-region start end
839 This function sets the accessible portion of the current buffer to start
840 at @var{start} and end at @var{end}. Both arguments should be character
843 In an interactive call, @var{start} and @var{end} are set to the bounds
844 of the current region (point and the mark, with the smallest first).
847 @deffn Command narrow-to-page move-count
848 This function sets the accessible portion of the current buffer to
849 include just the current page. An optional first argument
850 @var{move-count} non-@code{nil} means to move forward or backward by
851 @var{move-count} pages and then narrow to one page. The variable
852 @code{page-delimiter} specifies where pages start and end
853 (@pxref{Standard Regexps}).
855 In an interactive call, @var{move-count} is set to the numeric prefix
861 This function cancels any narrowing in the current buffer, so that the
862 entire contents are accessible. This is called @dfn{widening}.
863 It is equivalent to the following expression:
866 (narrow-to-region 1 (1+ (buffer-size)))
870 @defspec save-restriction body@dots{}
871 This special form saves the current bounds of the accessible portion,
872 evaluates the @var{body} forms, and finally restores the saved bounds,
873 thus restoring the same state of narrowing (or absence thereof) formerly
874 in effect. The state of narrowing is restored even in the event of an
875 abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
876 Therefore, this construct is a clean way to narrow a buffer temporarily.
878 The value returned by @code{save-restriction} is that returned by the
879 last form in @var{body}, or @code{nil} if no body forms were given.
881 @c Wordy to avoid overfull hbox. --rjc 16mar92
882 @strong{Caution:} it is easy to make a mistake when using the
883 @code{save-restriction} construct. Read the entire description here
886 If @var{body} changes the current buffer, @code{save-restriction} still
887 restores the restrictions on the original buffer (the buffer whose
888 restrictions it saved from), but it does not restore the identity of the
891 @code{save-restriction} does @emph{not} restore point and the mark; use
892 @code{save-excursion} for that. If you use both @code{save-restriction}
893 and @code{save-excursion} together, @code{save-excursion} should come
894 first (on the outside). Otherwise, the old point value would be
895 restored with temporary narrowing still in effect. If the old point
896 value were outside the limits of the temporary narrowing, this would
897 fail to restore it accurately.
899 The @code{save-restriction} special form records the values of the
900 beginning and end of the accessible portion as distances from the
901 beginning and end of the buffer. In other words, it records the amount
902 of inaccessible text before and after the accessible portion.
904 This method yields correct results if @var{body} does further narrowing.
905 However, @code{save-restriction} can become confused if the body widens
906 and then makes changes outside the range of the saved narrowing. When
907 this is what you want to do, @code{save-restriction} is not the right
908 tool for the job. Here is what you must use instead:
912 (let ((beg (point-min-marker))
913 (end (point-max-marker)))
917 (set-buffer (marker-buffer beg))
918 (narrow-to-region beg end))))
922 Here is a simple example of correct use of @code{save-restriction}:
926 ---------- Buffer: foo ----------
927 This is the contents of foo
928 This is the contents of foo
929 This is the contents of foo@point{}
930 ---------- Buffer: foo ----------
938 (narrow-to-region 1 (point))
939 (goto-char (point-min))
940 (replace-string "foo" "bar")))
942 ---------- Buffer: foo ----------
943 This is the contents of bar
944 This is the contents of bar
945 This is the contents of foo@point{}
946 ---------- Buffer: foo ----------