2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 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 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, the
14 we 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 which relocate
19 automatically when text is inserted or deleted so they stay with the
20 surrounding characters. @xref{Markers}.
23 * Point:: The special position where editing takes place.
24 * Motion:: Changing point.
25 * Excursions:: Temporary motion and buffer changes.
26 * Narrowing:: Restricting editing to a portion of the buffer.
33 @dfn{Point} is a special buffer position used by many editing
34 commands, including the self-inserting typed characters and text
35 insertion functions. Other commands move point through the text
36 to allow editing and insertion at different places.
38 Like other positions, point designates a place between two characters
39 (or before the first character, or after the last character), rather
40 than a particular character. Many terminals display the cursor over the
41 character that immediately follows point; on such terminals, point is
42 actually before the character on which the cursor sits.
44 @cindex point with narrowing
45 The value of point is a number between 1 and the buffer size plus 1.
46 If narrowing is in effect (@pxref{Narrowing}), then point is constrained
47 to fall within the accessible portion of the buffer (possibly at one end
50 Each buffer has its own value of point, which is independent of the
51 value of point in other buffers. Each window also has a value of point,
52 which is independent of the value of point in other windows on the same
53 buffer. This is why point can have different values in various windows
54 that display the same buffer. When a buffer appears in only one window,
55 the buffer's point and the window's point normally have the same value,
56 so the distinction is rarely important. @xref{Window Point}, for more
60 @cindex current buffer position
61 This function returns the position of point in the current buffer,
74 This function returns the minimum accessible value of point in the
75 current buffer. This is 1, unless narrowing is in effect, in
76 which case it is the position of the start of the region that you
77 narrowed to. (@xref{Narrowing}.)
81 This function returns the maximum accessible value of point in the
82 current buffer. This is @code{(1+ (buffer-size))}, unless narrowing is
83 in effect, in which case it is the position of the end of the region
84 that you narrowed to. (@xref{Narrowing}).
87 @defun buffer-end flag
88 This function returns @code{(point-min)} if @var{flag} is less than 1,
89 @code{(point-max)} otherwise. The argument @var{flag} must be a number.
93 This function returns the total number of characters in the current
94 buffer. In the absence of any narrowing (@pxref{Narrowing}),
95 @code{point-max} returns a value one larger than this.
112 Motion functions change the value of point, either relative to the
113 current value of point, relative to the beginning or end of the buffer,
114 or relative to the edges of the selected window. @xref{Point}.
117 * Character Motion:: Moving in terms of characters.
118 * Word Motion:: Moving in terms of words.
119 * Buffer End Motion:: Moving to the beginning or end of the buffer.
120 * Text Lines:: Moving in terms of lines of text.
121 * Screen Lines:: Moving in terms of lines as displayed.
122 * Vertical Motion:: Implementation of @code{next-line} and
123 @code{previous-line}.
124 * List Motion:: Moving by parsing lists and sexps.
125 * Skipping Characters:: Skipping characters belonging to a certain set.
128 @node Character Motion
129 @subsection Motion by Characters
131 These functions move point based on a count of characters.
132 @code{goto-char} is the fundamental primitive; the functions others use
135 @deffn Command goto-char position
136 This function sets point in the current buffer to the value
137 @var{position}. If @var{position} is less than 1, it moves point to the
138 beginning of the buffer. If @var{position} is greater than the length
139 of the buffer, it moves point to the end.
141 If narrowing is in effect, @var{position} still counts from the
142 beginning of the buffer, but point cannot go outside the accessible
143 portion. If @var{position} is out of range, @code{goto-char} moves
144 point to the beginning or the end of the accessible portion.
146 When this function is called interactively, @var{position} is the
147 numeric prefix argument, if provided; otherwise it is read from the
150 @code{goto-char} returns @var{position}.
153 @deffn Command forward-char &optional count
154 @c @kindex beginning-of-buffer
155 @c @kindex end-of-buffer
156 This function moves point @var{count} characters forward, towards the
157 end of the buffer (or backward, towards the beginning of the buffer, if
158 @var{count} is negative). If the function attempts to move point past
159 the beginning or end of the buffer (or the limits of the accessible
160 portion, when narrowing is in effect), an error is signaled with error
161 code @code{beginning-of-buffer} or @code{end-of-buffer}.
163 In an interactive call, @var{count} is the numeric prefix argument.
166 @deffn Command backward-char &optional count
167 This function moves point @var{count} characters backward, towards the
168 beginning of the buffer (or forward, towards the end of the buffer, if
169 @var{count} is negative). If the function attempts to move point past
170 the beginning or end of the buffer (or the limits of the accessible
171 portion, when narrowing is in effect), an error is signaled with error
172 code @code{beginning-of-buffer} or @code{end-of-buffer}.
174 In an interactive call, @var{count} is the numeric prefix argument.
178 @subsection Motion by Words
180 These functions for parsing words use the syntax table to decide
181 whether a given character is part of a word. @xref{Syntax Tables}.
183 @deffn Command forward-word count
184 This function moves point forward @var{count} words (or backward if
185 @var{count} is negative). Normally it returns @code{t}. If this motion
186 encounters the beginning or end of the buffer, or the limits of the
187 accessible portion when narrowing is in effect, point stops there
188 and the value is @code{nil}.
190 In an interactive call, @var{count} is set to the numeric prefix
194 @deffn Command backward-word count
195 This function just like @code{forward-word}, except that it moves
196 backward until encountering the front of a word, rather than forward.
198 In an interactive call, @var{count} is set to the numeric prefix
201 This function is rarely used in programs, as it is more efficient to
202 call @code{forward-word} with negative argument.
205 @defvar words-include-escapes
207 This variable affects the behavior of @code{forward-word} and everything
208 that uses it. If it is non-@code{nil}, then characters in the
209 ``escape'' and ``character quote'' syntax classes count as part of
210 words. Otherwise, they do not.
213 @node Buffer End Motion
214 @subsection Motion to an End of the Buffer
216 To move point to the beginning of the buffer, write:
220 (goto-char (point-min))
225 Likewise, to move to the end of the buffer, use:
229 (goto-char (point-max))
233 Here are two commands which users use to do these things. They are
234 documented here to warn you not to use them in Lisp programs, because
235 they set the mark and display messages in the echo area.
237 @deffn Command beginning-of-buffer &optional n
238 This function moves point to the beginning of the buffer (or the limits
239 of the accessible portion, when narrowing is in effect), setting the
240 mark at the previous position. If @var{n} is non-@code{nil}, then it
241 puts point @var{n} tenths of the way from the beginning of the buffer.
243 In an interactive call, @var{n} is the numeric prefix argument,
244 if provided; otherwise @var{n} defaults to @code{nil}.
246 Don't use this function in Lisp programs!
249 @deffn Command end-of-buffer &optional n
250 This function moves point to the end of the buffer (or the limits of
251 the accessible portion, when narrowing is in effect), setting the mark
252 at the previous position. If @var{n} is non-@code{nil}, then it puts
253 point @var{n} tenths of the way from the end.
255 In an interactive call, @var{n} is the numeric prefix argument,
256 if provided; otherwise @var{n} defaults to @code{nil}.
258 Don't use this function in Lisp programs!
262 @subsection Motion by Text Lines
265 Text lines are portions of the buffer delimited by newline characters,
266 which are regarded as part of the previous line. The first text line
267 begins at the beginning of the buffer, and the last text line ends at
268 the end of the buffer whether or not the last character is a newline.
269 The division of the buffer into text lines is not affected by the width
270 of the window, by line continuation in display, or by how tabs and
271 control characters are displayed.
273 @deffn Command goto-line line
274 This function moves point to the front of the @var{line}th line,
275 counting from line 1 at beginning of buffer. If @var{line} is less than
276 1, it moves point to the beginning of the buffer. If @var{line} is
277 greater than the number of lines in the buffer, it moves point to the
278 @emph{end of the last line} of the buffer.
280 If narrowing is in effect, then @var{line} still counts from the
281 beginning of the buffer, but point cannot go outside the accessible
282 portion. So @code{goto-line} moves point to the beginning or end of the
283 accessible portion, if the line number specifies an inaccessible
286 The return value of @code{goto-line} is the difference between
287 @var{line} and the line number of the line to which point actually was
288 able move (in the full buffer, disregarding any narrowing). Thus, the
289 value is positive if the scan encounters the real end of the buffer.
291 In an interactive call, @var{line} is the numeric prefix argument if
292 one has been provided. Otherwise @var{line} is read in the minibuffer.
295 @deffn Command beginning-of-line &optional count
296 This function moves point to the beginning of the current line. With an
297 argument @var{count} not @code{nil} or 1, it moves forward
298 @var{count}@minus{}1 lines and then to the beginning of the line.
300 If this function reaches the end of the buffer (or of the accessible
301 portion, if narrowing is in effect), it positions point at the end of
302 the buffer. No error is signaled.
305 @deffn Command end-of-line &optional count
306 This function moves point to the end of the current line. With an
307 argument @var{count} not @code{nil} or 1, it moves forward
308 @var{count}@minus{}1 lines and then to the end of the line.
310 If this function reaches the end of the buffer (or of the accessible
311 portion, if narrowing is in effect), it positions point at the end of
312 the buffer. No error is signaled.
315 @deffn Command forward-line &optional count
316 @cindex beginning of line
317 This function moves point forward @var{count} lines, to the beginning of
318 the line. If @var{count} is negative, it moves point
319 @minus{}@var{count} lines backward, to the beginning of the line.
321 If @code{forward-line} encounters the beginning or end of the buffer (or
322 of the accessible portion) before finding that many lines, it sets point
323 there. No error is signaled.
325 @code{forward-line} returns the difference between @var{count} and the
326 number of lines actually moved. If you attempt to move down five lines
327 from the beginning of a buffer that has only three lines, point stops at
328 the end of the last line, and the value will be 2.
330 In an interactive call, @var{count} is the numeric prefix argument.
333 @defun count-lines start end
334 @cindex lines in region
335 This function returns the number of lines between the positions
336 @var{start} and @var{end} in the current buffer. If @var{start} and
337 @var{end} are equal, then it returns 0. Otherwise it returns at least
338 1, even if @var{start} and @var{end} are on the same line. This is
339 because the text between them, considered in isolation, must contain at
340 least one line unless it is empty.
342 Here is an example of using @code{count-lines}:
346 (defun current-line ()
347 "Return the vertical position of point@dots{}"
348 (+ (count-lines (window-start) (point))
349 (if (= (current-column) 0) 1 0)
357 The @code{previous-line} and @code{next-line} commands are functions
358 that should not be used in programs. They are for users and are
359 mentioned here only for completeness.
361 @deffn Command previous-line count
363 This function moves point up @var{count} lines (down if @var{count}
364 is negative). In moving, it attempts to keep point in the ``goal column''
365 (normally the same column that it was at the beginning of the move).
367 If there is no character in the target line exactly under the current
368 column, point is positioned after the character in that line which
369 spans this column, or at the end of the line if it is not long enough.
371 If it attempts to move beyond the top or bottom of the buffer (or clipped
372 region), then point is positioned in the goal column in the top or
373 bottom line. No error is signaled.
375 In an interactive call, @var{count} will be the numeric
378 The command @code{set-goal-column} can be used to create a semipermanent
379 goal column to which this command always moves. Then it does not try to
382 If you are thinking of using this in a Lisp program, consider using
383 @code{forward-line} with a negative argument instead. It is usually easier
384 to use and more reliable (no dependence on goal column, etc.).
387 @deffn Command next-line count
388 This function moves point down @var{count} lines (up if @var{count}
389 is negative). In moving, it attempts to keep point in the ``goal column''
390 (normally the same column that it was at the beginning of the move).
392 If there is no character in the target line exactly under the current
393 column, point is positioned after the character in that line which
394 spans this column, or at the end of the line if it is not long enough.
396 If it attempts to move beyond the top or bottom of the buffer (or clipped
397 region), then point is positioned in the goal column in the top or
398 bottom line. No error is signaled.
400 In the case where the @var{count} is 1, and point is on the last
401 line of the buffer (or clipped region), a new empty line is inserted at the
402 end of the buffer (or clipped region) and point moved there.
404 In an interactive call, @var{count} will be the numeric
407 The command @code{set-goal-column} can be used to create a semipermanent
408 goal column to which this command always moves. Then it does not try to
411 If you are thinking of using this in a Lisp program, consider using
412 @code{forward-line} instead. It is usually easier
413 to use and more reliable (no dependence on goal column, etc.).
419 Also see the functions @code{bolp} and @code{eolp} in @ref{Near Point}.
420 These functions do not move point, but test whether it is already at the
421 beginning or end of a line.
424 @subsection Motion by Screen Lines
426 The line functions in the previous section count text lines, delimited
427 only by newline characters. By contrast, these functions count screen
428 lines, which are defined by the way the text appears on the screen. A
429 text line is a single screen line if it is short enough to fit the width
430 of the selected window, but otherwise it may occupy several screen
433 In some cases, text lines are truncated on the screen rather than
434 continued onto additional screen lines. In these cases,
435 @code{vertical-motion} moves point much like @code{forward-line}.
438 Because the width of a given string depends on the flags which control
439 the appearance of certain characters, @code{vertical-motion} behaves
440 differently, for a given piece of text, depending on the buffer it is
441 in, and even on the selected window (because the width, the truncation
442 flag, and display table may vary between windows). @xref{Usual
445 @defun vertical-motion count &optional window
446 This function moves point to the start of the screen line @var{count}
447 screen lines down from the screen line containing point. If @var{count}
448 is negative, it moves up instead.
450 @code{vertical-motion} returns the number of lines moved. The value may
451 be less in absolute value than @var{count} if the beginning or end of
452 the buffer was reached.
454 The window @var{window} is used for obtaining parameters such as the
455 width, the horizontal scrolling, and the display table. But
456 @code{vertical-motion} always operates on the current buffer, even if
457 @var{window} currently displays some other buffer.
460 @deffn Command move-to-window-line count
461 This function moves point with respect to the text currently displayed
462 in the selected window. It moves point to the beginning of the screen
463 line @var{count} screen lines from the top of the window. If
464 @var{count} is negative, that specifies a position
465 @w{@minus{}@var{count}} lines from the bottom---or else the last line of
466 the buffer, if the buffer ends above the specified screen position.
468 If @var{count} is @code{nil}, then point moves to the beginning of the
469 line in the middle of the window. If the absolute value of @var{count}
470 is greater than the size of the window, then point moves to the place
471 which would appear on that screen line if the window were tall enough.
472 This will probably cause the next redisplay to scroll to bring that
473 location onto the screen.
475 In an interactive call, @var{count} is the numeric prefix argument.
477 The value returned is the window line number, with the top line in the
481 @defun compute-motion from frompos to topos width offsets window
482 This function scan through the current buffer, calculating screen
483 position. It scans the current buffer forward from position @var{from},
484 assuming that is at screen coordinates @var{frompos}, to position
485 @var{to} or coordinates @var{topos}, whichever comes first. It returns
486 the ending buffer position and screen coordinates.
488 The coordinate arguments @var{frompos} and @var{topos} are cons cells of
489 the form @code{(@var{hpos} . @var{vpos})}.
491 The argument @var{width} is the number of columns available to display
492 text; this affects handling of continuation lines. Use the value
493 returned by @code{window-width} for the window of your choice.
495 The argument @var{offsets} is either @code{nil} or a cons cell of the
496 form @code{(@var{hscroll} . @var{tab-offset})}. Here @var{hscroll} is
497 the number of columns not being displayed at the left margin; most
498 callers get this from @code{window-hscroll}. Meanwhile,
499 @var{tab-offset} is the offset between column numbers on the screen and
500 column numbers in the buffer. This can be nonzero in a continuation
501 line, when the previous screen lines' widths do not add up to a multiple
502 of @code{tab-width}. It is always zero in a non-continuation line.
504 The window @var{window} serves to specify which display table to use;
505 that is its only effect. @code{compute-motion} always operates on the
506 current buffer, regardless of what buffer is displayed in @var{window}.
508 The return value is a list of five elements:
511 (@var{pos} @var{vpos} @var{hpos} @var{prevhpos} @var{contin})
515 Here @var{pos} is the buffer position where the scan stopped, @var{vpos}
516 is the vertical position, and @var{hpos} is the horizontal position.
518 The result @var{prevhpos} is the horizontal position one character back
519 from @var{pos}. The result @var{contin} is @code{t} if a line was
520 continued after (or within) the previous character.
522 For example, to find the buffer position of column @var{col} of line
523 @var{line} of a certain window, pass the window's display start location
524 as @var{from} and the window's upper-left coordinates as @var{frompos}.
525 Pass the buffer's @code{(point-max)} as @var{to}, to limit the scan to
526 the end of the visible section of the buffer, and pass @var{line} and
527 @var{col} as @var{topos}. Here's a function that does this:
530 (defun coordinates-of-position (col line)
531 (car (compute-motion (window-start)
536 (cons (window-hscroll) 0))))
539 When you use @code{compute-motion} for the minibuffer, you need to use
540 @code{minibuffer-prompt-width} to get the horizontal position of the
541 beginning of the first screen line. @xref{Minibuffer Misc}.
544 @node Vertical Motion
545 @comment node-name, next, previous, up
546 @subsection The User-Level Vertical Motion Commands
548 @cindex vertical text line motion
550 @findex previous-line
552 A goal column is useful if you want to edit text such as a table in
553 which you want to move point to a certain column on each line. The goal
554 column affects the vertical text line motion commands, @code{next-line}
555 and @code{previous-line}. @xref{Basic,, Basic Editing Commands, emacs,
556 The GNU Emacs Manual}.
559 This variable holds an explicitly specified goal column for vertical
560 line motion commands. If it is an integer, it specifies a column, and
561 these commands try to move to that column on each line. If it is
562 @code{nil}, then the commands set their own goal columns. Any other
566 @defvar temporary-goal-column
567 This variable holds the temporary goal column during a sequence of
568 consecutive vertical line motion commands. It is overridden by
569 @code{goal-column} if that is non-@code{nil}. It is set each time a
570 vertical motion command is invoked, unless the previous command was also
571 a vertical motion command.
575 This variable controls how the vertical line motion commands operate
576 when starting at the end of a line. If @code{track-eol} is
577 non-@code{nil}, then vertical motion starting at the end of a line will
578 keep to the ends of lines. This means moving to the end of each line
579 moved onto. The value of @code{track-eol} has no effect if point is not
580 at the end of a line when the first vertical motion command is given.
582 @code{track-eol} has its effect by telling line motion commands to set
583 @code{temporary-goal-column} to 9999 instead of to the current column.
587 @comment node-name, next, previous, up
588 @subsection Moving over Balanced Expressions
590 @cindex Lisp expression motion
593 Here are several functions concerned with balanced-parenthesis
594 expressions (also called @dfn{sexps} in connection with moving across
595 them in Emacs). The syntax table controls how these functions interpret
596 various characters; see @ref{Syntax Tables}. @xref{Parsing
597 Expressions}, for lower-level primitives for scanning sexps or parts of
598 sexps. For user-level commands, see @ref{Lists and Sexps,,, emacs, GNU
601 @deffn Command forward-list arg
602 This function moves forward across @var{arg} balanced groups of
603 parentheses. (Other syntactic entities such as words or paired string
607 @deffn Command backward-list arg
608 This function moves backward across @var{arg} balanced groups of
609 parentheses. (Other syntactic entities such as words or paired string
613 @deffn Command up-list arg
614 This function moves forward out of @var{arg} levels of parentheses.
615 A negative argument means move backward but still to a less deep spot.
618 @deffn Command down-list arg
619 This function moves forward down @var{arg} levels of parentheses. A
620 negative argument means move backward but still go down @var{arg}
624 @deffn Command forward-sexp arg
625 This function moves forward across @var{arg} balanced expressions.
626 Balanced expressions include both those delimited by parentheses and
627 other kinds, such as words and string constants. For example,
631 ---------- Buffer: foo ----------
632 (concat@point{} "foo " (car x) y z)
633 ---------- Buffer: foo ----------
640 ---------- Buffer: foo ----------
641 (concat "foo " (car x) y@point{} z)
642 ---------- Buffer: foo ----------
647 @deffn Command backward-sexp arg
648 This function moves backward across @var{arg} balanced expressions.
651 @deffn Command beginning-of-defun arg
652 This function moves back to the @var{arg}th beginning of a defun. If
653 @var{arg} is negative, this actually moves forward, but it still moves
654 to the beginning of a defun, not to the end of one.
657 @deffn Command end-of-defun arg
658 Move forward to the @var{arg}th end of a defun. If @var{arg} is
659 negative, this actually moves backward, but it still moves to the end of
660 a defun, not to the beginning of one.
663 @defopt defun-prompt-regexp
664 If non-@code{nil}, this variable holds a regular expression that
665 specifies what text can appear before the open-parenthesis that starts a
666 defun. That is to say, the a defun begins on a line which starts
667 with a match for this regular expression, followed by a character
668 with open-parenthesis syntax.
671 @node Skipping Characters
672 @comment node-name, next, previous, up
673 @subsection Skipping Characters
674 @cindex skipping characters
676 The following two functions move point over a specified set of
677 characters. For example, they are often used to skip whitespace. For
678 related functions, see @ref{Motion and Syntax}.
680 @defun skip-chars-forward character-set &optional limit
681 This function moves point in the current buffer forward, skipping over a
682 given set of characters. It examines the character following point,
683 then advances point if the character matches @var{character-set}. This
684 continues until it reaches a character that does not match. The
685 function returns @code{nil}.
687 The argument @var{character-set} is like the inside of a
688 @samp{[@dots{}]} in a regular expression except that @samp{]} is never
689 special and @samp{\} quotes @samp{^}, @samp{-} or @samp{\}. Thus,
690 @code{"a-zA-Z"} skips over all letters, stopping before the first
691 nonletter, and @code{"^a-zA-Z}" skips nonletters stopping before the
692 first letter. @xref{Regular Expressions}.
694 If @var{limit} is supplied (it must be a number or a marker), it
695 specifies the maximum position in the buffer that point can be skipped
696 to. Point will stop at or before @var{limit}.
698 In the following example, point is initially located directly before the
699 @samp{T}. After the form is evaluated, point is located at the end of
700 that line (between the @samp{t} of @samp{hat} and the newline). The
701 function skips all letters and spaces, but not newlines.
705 ---------- Buffer: foo ----------
706 I read "@point{}The cat in the hat
708 ---------- Buffer: foo ----------
712 (skip-chars-forward "a-zA-Z ")
715 ---------- Buffer: foo ----------
716 I read "The cat in the hat@point{}
718 ---------- Buffer: foo ----------
723 @defun skip-chars-backward character-set &optional limit
724 This function moves point backward, skipping characters that match
725 @var{character-set}, until @var{limit}. It just like
726 @code{skip-chars-forward} except for the direction of motion.
733 It is often useful to move point ``temporarily'' within a localized
734 portion of the program, or to switch buffers temporarily. This is
735 called an @dfn{excursion}, and it is done with the @code{save-excursion}
736 special form. This construct saves the current buffer and its values of
737 point and the mark so they can be restored after the completion of the
740 The forms for saving and restoring the configuration of windows are
741 described elsewhere (see @ref{Window Configurations}, and @pxref{Frame
744 @defspec save-excursion forms@dots{}
745 @cindex mark excursion
746 @cindex point excursion
747 @cindex current buffer excursion
748 The @code{save-excursion} special form saves the identity of the current
749 buffer and the values of point and the mark in it, evaluates @var{forms},
750 and finally restores the buffer and its saved values of point and the mark.
751 All three saved values are restored even in case of an abnormal exit
752 via throw or error (@pxref{Nonlocal Exits}).
754 The @code{save-excursion} special form is the standard way to switch
755 buffers or move point within one part of a program and avoid affecting
756 the rest of the program. It is used more than 500 times in the Lisp
759 @code{save-excursion} does not save the values of point and the mark for
760 other buffers, so changes in other buffers remain in effect after
761 @code{save-excursion} exits.
763 @cindex window excursions
764 Likewise, @code{save-excursion} does not restore window-buffer
765 correspondences altered by functions such as @code{switch-to-buffer}.
766 One way to restore these correspondences, and the selected window, is to
767 use @code{save-window-excursion} inside @code{save-excursion}
768 (@pxref{Window Configurations}).
770 The value returned by @code{save-excursion} is the result of the last of
771 @var{forms}, or @code{nil} if no @var{forms} are given.
778 (let ((old-buf (current-buffer))
779 (old-pnt (point-marker))
780 (old-mark (copy-marker (mark-marker))))
785 (set-marker (mark-marker) old-mark)))
793 @cindex restriction (in a buffer)
794 @cindex accessible portion (of a buffer)
796 @dfn{Narrowing} means limiting the text addressable by Emacs editing
797 commands to a limited range of characters in a buffer. The text that
798 remains addressable is called the @dfn{accessible portion} of the
801 Narrowing is specified with two buffer positions which become the
802 beginning and end of the accessible portion. For most editing commands
803 and most Emacs primitives, these positions replace the values of the
804 beginning and end of the buffer. While narrowing is in effect, no text
805 outside the accessible portion is displayed, and point cannot move
806 outside the accessible portion.
808 Values such as positions or line numbers, that usually count from the
809 beginning of the buffer, do so despite narrowing, but the functions
810 which use them refuse to operate on text that is inaccessible.
812 The commands for saving buffers are unaffected by narrowing; they save
813 the entire buffer regardless of the any narrowing.
815 @deffn Command narrow-to-region start end
816 This function sets the accessible portion of the current buffer to start
817 at @var{start} and end at @var{end}. Both arguments should be character
820 In an interactive call, @var{start} and @var{end} are set to the bounds
821 of the current region (point and the mark, with the smallest first).
824 @deffn Command narrow-to-page move-count
825 This function sets the accessible portion of the current buffer to
826 include just the current page. An optional first argument
827 @var{move-count} non-@code{nil} means to move forward or backward by
828 @var{move-count} pages and then narrow. The variable
829 @code{page-delimiter} specifies where pages start and end
830 (@pxref{Standard Regexps}).
832 In an interactive call, @var{move-count} is set to the numeric prefix
838 This function cancels any narrowing in the current buffer, so that the
839 entire contents are accessible. This is called @dfn{widening}.
840 It is equivalent to the following expression:
843 (narrow-to-region 1 (1+ (buffer-size)))
847 @defspec save-restriction body@dots{}
848 This special form saves the current bounds of the accessible portion,
849 evaluates the @var{body} forms, and finally restores the saved bounds,
850 thus restoring the same state of narrowing (or absence thereof) formerly
851 in effect. The state of narrowing is restored even in the event of an
852 abnormal exit via throw or error (@pxref{Nonlocal Exits}). Therefore,
853 this construct is a clean way to narrow a buffer temporarily.
855 The value returned by @code{save-restriction} is that returned by the
856 last form in @var{body}, or @code{nil} if no body forms were given.
858 @c Wordy to avoid overfull hbox. --rjc 16mar92
859 @strong{Caution:} it is easy to make a mistake when using the
860 @code{save-restriction} construct. Read the entire description here
863 If @var{body} changes the current buffer, @code{save-restriction} still
864 restores the restrictions on the original buffer (the buffer whose
865 restructions it saved from), but it does not restore the identity of the
868 @code{save-restriction} does @emph{not} restore point and the mark; use
869 @code{save-excursion} for that. If you use both @code{save-restriction}
870 and @code{save-excursion} together, @code{save-excursion} should come
871 first (on the outside). Otherwise, the old point value would be
872 restored with temporary narrowing still in effect. If the old point
873 value were outside the limits of the temporary narrowing, this would
874 fail to restore it accurately.
876 The @code{save-restriction} special form records the values of the
877 beginning and end of the accessible portion as distances from the
878 beginning and end of the buffer. In other words, it records the amount
879 of inaccessible text before and after the accessible portion.
881 This method yields correct results if @var{body} does further narrowing.
882 However, @code{save-restriction} can become confused if the body widens
883 and then make changes outside the range of the saved narrowing. When
884 this is what you want to do, @code{save-restriction} is not the right
885 tool for the job. Here is what you must use instead:
889 (let ((beg (point-min-marker))
890 (end (point-max-marker)))
894 (set-buffer (marker-buffer beg))
895 (narrow-to-region beg end))))
899 Here is a simple example of correct use of @code{save-restriction}:
903 ---------- Buffer: foo ----------
904 This is the contents of foo
905 This is the contents of foo
906 This is the contents of foo@point{}
907 ---------- Buffer: foo ----------
915 (narrow-to-region 1 (point))
916 (goto-char (point-min))
917 (replace-string "foo" "bar")))
919 ---------- Buffer: foo ----------
920 This is the contents of bar
921 This is the contents of bar
922 This is the contents of foo@point{}
923 ---------- Buffer: foo ----------