2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-2014 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
7 @cindex position (in buffer)
8 @cindex buffer position
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
18 can also be represented as @dfn{markers}---special objects that
19 relocate automatically when text is inserted or deleted so they stay
20 with the surrounding characters. Functions that expect an argument to
21 be a position (an integer), but accept a marker as a substitute,
22 normally ignore which buffer the marker points into; they convert the
23 marker to an integer, and use that integer, exactly as if you had
24 passed the integer as the argument, even if the marker points to the
25 ``wrong'' buffer. A marker that points nowhere cannot convert to an
26 integer; using it instead of an integer causes an error.
29 See also the ``field'' feature (@pxref{Fields}), which provides
30 functions that are used by many cursor-motion commands.
33 * Point:: The special position where editing takes place.
34 * Motion:: Changing point.
35 * Excursions:: Temporary motion and buffer changes.
36 * Narrowing:: Restricting editing to a portion of the buffer.
43 @dfn{Point} is a special buffer position used by many editing
44 commands, including the self-inserting typed characters and text
45 insertion functions. Other commands move point through the text
46 to allow editing and insertion at different places.
48 Like other positions, point designates a place between two characters
49 (or before the first character, or after the last character), rather
50 than a particular character. Usually terminals display the cursor over
51 the character that immediately follows point; point is actually before
52 the character on which the cursor sits.
54 @cindex point with narrowing
55 The value of point is a number no less than 1, and no greater than the
56 buffer size plus 1. If narrowing is in effect (@pxref{Narrowing}), then
57 point is constrained to fall within the accessible portion of the buffer
58 (possibly at one end of it).
60 Each buffer has its own value of point, which is independent of the
61 value of point in other buffers. Each window also has a value of point,
62 which is independent of the value of point in other windows on the same
63 buffer. This is why point can have different values in various windows
64 that display the same buffer. When a buffer appears in only one window,
65 the buffer's point and the window's point normally have the same value,
66 so the distinction is rarely important. @xref{Window Point}, for more
70 @cindex current buffer position
71 This function returns the value of point in the current buffer,
84 This function returns the minimum accessible value of point in the
85 current buffer. This is normally 1, but if narrowing is in effect, it
86 is the position of the start of the region that you narrowed to.
91 This function returns the maximum accessible value of point in the
92 current buffer. This is @code{(1+ (buffer-size))}, unless narrowing is
93 in effect, in which case it is the position of the end of the region
94 that you narrowed to. (@xref{Narrowing}.)
97 @defun buffer-end flag
98 This function returns @code{(point-max)} if @var{flag} is greater than
99 0, @code{(point-min)} otherwise. The argument @var{flag} must be a
103 @defun buffer-size &optional buffer
104 This function returns the total number of characters in the current
105 buffer. In the absence of any narrowing (@pxref{Narrowing}),
106 @code{point-max} returns a value one larger than this.
108 If you specify a buffer, @var{buffer}, then the value is the
109 size of @var{buffer}.
125 @cindex motion by chars, words, lines, lists
127 Motion functions change the value of point, either relative to the
128 current value of point, relative to the beginning or end of the buffer,
129 or relative to the edges of the selected window. @xref{Point}.
132 * Character Motion:: Moving in terms of characters.
133 * Word Motion:: Moving in terms of words.
134 * Buffer End Motion:: Moving to the beginning or end of the buffer.
135 * Text Lines:: Moving in terms of lines of text.
136 * Screen Lines:: Moving in terms of lines as displayed.
137 * List Motion:: Moving by parsing lists and sexps.
138 * Skipping Characters:: Skipping characters belonging to a certain set.
141 @node Character Motion
142 @subsection Motion by Characters
144 These functions move point based on a count of characters.
145 @code{goto-char} is the fundamental primitive; the other functions use
148 @deffn Command goto-char position
149 This function sets point in the current buffer to the value
151 @c This behavior used to be documented until 2013/08.
153 If @var{position} is less than 1, it moves point to the beginning of
154 the buffer. If @var{position} is greater than the length of the
155 buffer, it moves point to the end.
158 If narrowing is in effect, @var{position} still counts from the
159 beginning of the buffer, but point cannot go outside the accessible
160 portion. If @var{position} is out of range, @code{goto-char} moves
161 point to the beginning or the end of the accessible portion.
163 When this function is called interactively, @var{position} is the
164 numeric prefix argument, if provided; otherwise it is read from the
167 @code{goto-char} returns @var{position}.
170 @deffn Command forward-char &optional count
171 @c @kindex beginning-of-buffer
172 @c @kindex end-of-buffer
173 This function moves point @var{count} characters forward, towards the
174 end of the buffer (or backward, towards the beginning of the buffer, if
175 @var{count} is negative). If @var{count} is @code{nil}, the default
178 If this attempts to move past the beginning or end of the buffer (or
179 the limits of the accessible portion, when narrowing is in effect), it
180 signals an error with error symbol @code{beginning-of-buffer} or
181 @code{end-of-buffer}.
183 In an interactive call, @var{count} is the numeric prefix argument.
186 @deffn Command backward-char &optional count
187 This is just like @code{forward-char} except that it moves
188 in the opposite direction.
192 @subsection Motion by Words
194 These functions for parsing words use the syntax table to decide
195 whether a given character is part of a word. @xref{Syntax Tables}.
197 @deffn Command forward-word &optional count
198 This function moves point forward @var{count} words (or backward if
199 @var{count} is negative). If @var{count} is omitted or @code{nil}, it
202 ``Moving one word'' means moving until point crosses a
203 word-constituent character and then encounters a word-separator
204 character. However, this function cannot move point past the boundary
205 of the accessible portion of the buffer, or across a field boundary
206 (@pxref{Fields}). The most common case of a field boundary is the end
207 of the prompt in the minibuffer.
209 If it is possible to move @var{count} words, without being stopped
210 prematurely by the buffer boundary or a field boundary, the value is
211 @code{t}. Otherwise, the return value is @code{nil} and point stops at
212 the buffer boundary or field boundary.
214 If @code{inhibit-field-text-motion} is non-@code{nil},
215 this function ignores field boundaries.
217 In an interactive call, @var{count} is specified by the numeric prefix
221 @deffn Command backward-word &optional count
222 This function is just like @code{forward-word}, except that it moves
223 backward until encountering the front of a word, rather than forward.
226 @defopt words-include-escapes
228 This variable affects the behavior of @code{forward-word} and everything
229 that uses it. If it is non-@code{nil}, then characters in the
230 ``escape'' and ``character quote'' syntax classes count as part of
231 words. Otherwise, they do not.
234 @defvar inhibit-field-text-motion
235 If this variable is non-@code{nil}, certain motion functions including
236 @code{forward-word}, @code{forward-sentence}, and
237 @code{forward-paragraph} ignore field boundaries.
240 @node Buffer End Motion
241 @subsection Motion to an End of the Buffer
242 @cindex move to beginning or end of buffer
244 To move point to the beginning of the buffer, write:
248 (goto-char (point-min))
253 Likewise, to move to the end of the buffer, use:
257 (goto-char (point-max))
261 Here are two commands that users use to do these things. They are
262 documented here to warn you not to use them in Lisp programs, because
263 they set the mark and display messages in the echo area.
265 @deffn Command beginning-of-buffer &optional n
266 This function moves point to the beginning of the buffer (or the limits
267 of the accessible portion, when narrowing is in effect), setting the
268 mark at the previous position (except in Transient Mark mode, if
269 the mark is already active, it does not set the mark.)
271 If @var{n} is non-@code{nil}, then it puts point @var{n} tenths of the
272 way from the beginning of the accessible portion of the buffer. In an
273 interactive call, @var{n} is the numeric prefix argument, if provided;
274 otherwise @var{n} defaults to @code{nil}.
276 @strong{Warning:} Don't use this function in Lisp programs!
279 @deffn Command end-of-buffer &optional n
280 This function moves point to the end of the buffer (or the limits of
281 the accessible portion, when narrowing is in effect), setting the mark
282 at the previous position (except in Transient Mark mode when the mark
283 is already active). If @var{n} is non-@code{nil}, then it puts point
284 @var{n} tenths of the way from the end of the accessible portion of
287 In an interactive call, @var{n} is the numeric prefix argument,
288 if provided; otherwise @var{n} defaults to @code{nil}.
290 @strong{Warning:} Don't use this function in Lisp programs!
294 @subsection Motion by Text Lines
297 Text lines are portions of the buffer delimited by newline characters,
298 which are regarded as part of the previous line. The first text line
299 begins at the beginning of the buffer, and the last text line ends at
300 the end of the buffer whether or not the last character is a newline.
301 The division of the buffer into text lines is not affected by the width
302 of the window, by line continuation in display, or by how tabs and
303 control characters are displayed.
305 @deffn Command beginning-of-line &optional count
306 This function moves point to the beginning 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 beginning of the line.
310 This function does not move point across a field boundary
311 (@pxref{Fields}) unless doing so would move beyond there to a
312 different line; therefore, if @var{count} is @code{nil} or 1, and
313 point starts at a field boundary, point does not move. To ignore
314 field boundaries, either bind @code{inhibit-field-text-motion} to
315 @code{t}, or use the @code{forward-line} function instead. For
316 instance, @code{(forward-line 0)} does the same thing as
317 @code{(beginning-of-line)}, except that it ignores field boundaries.
319 If this function reaches the end of the buffer (or of the accessible
320 portion, if narrowing is in effect), it positions point there. No error
324 @defun line-beginning-position &optional count
325 Return the position that @code{(beginning-of-line @var{count})}
329 @deffn Command end-of-line &optional count
330 This function moves point to the end of the current line. With an
331 argument @var{count} not @code{nil} or 1, it moves forward
332 @var{count}@minus{}1 lines and then to the end of the line.
334 This function does not move point across a field boundary
335 (@pxref{Fields}) unless doing so would move beyond there to a
336 different line; therefore, if @var{count} is @code{nil} or 1, and
337 point starts at a field boundary, point does not move. To ignore
338 field boundaries, bind @code{inhibit-field-text-motion} to @code{t}.
340 If this function reaches the end of the buffer (or of the accessible
341 portion, if narrowing is in effect), it positions point there. No error
345 @defun line-end-position &optional count
346 Return the position that @code{(end-of-line @var{count})}
350 @deffn Command forward-line &optional count
351 @cindex beginning of line
352 This function moves point forward @var{count} lines, to the beginning of
353 the line. If @var{count} is negative, it moves point
354 @minus{}@var{count} lines backward, to the beginning of a line. If
355 @var{count} is zero, it moves point to the beginning of the current
356 line. If @var{count} is @code{nil}, that means 1.
358 If @code{forward-line} encounters the beginning or end of the buffer (or
359 of the accessible portion) before finding that many lines, it sets point
360 there. No error is signaled.
362 @code{forward-line} returns the difference between @var{count} and the
363 number of lines actually moved. If you attempt to move down five lines
364 from the beginning of a buffer that has only three lines, point stops at
365 the end of the last line, and the value will be 2.
367 In an interactive call, @var{count} is the numeric prefix argument.
370 @defun count-lines start end
371 @cindex lines in region
372 @anchor{Definition of count-lines}
373 This function returns the number of lines between the positions
374 @var{start} and @var{end} in the current buffer. If @var{start} and
375 @var{end} are equal, then it returns 0. Otherwise it returns at least
376 1, even if @var{start} and @var{end} are on the same line. This is
377 because the text between them, considered in isolation, must contain at
378 least one line unless it is empty.
381 @deffn Command count-words start end
382 @cindex words in region
383 This function returns the number of words between the positions
384 @var{start} and @var{end} in the current buffer.
386 This function can also be called interactively. In that case, it
387 prints a message reporting the number of lines, words, and characters
388 in the buffer, or in the region if the region is active.
391 @defun line-number-at-pos &optional pos
393 This function returns the line number in the current buffer
394 corresponding to the buffer position @var{pos}. If @var{pos} is @code{nil}
395 or omitted, the current buffer position is used.
400 The @code{previous-line} and @code{next-line} commands are functions
401 that should not be used in programs. They are for users and are
402 mentioned here only for completeness.
404 @deffn Command previous-line count
406 This function moves point up @var{count} lines (down if @var{count}
407 is negative). In moving, it attempts to keep point in the ``goal column''
408 (normally the same column that it was at the beginning of the move).
410 If there is no character in the target line exactly under the current
411 column, point is positioned after the character in that line which
412 spans this column, or at the end of the line if it is not long enough.
414 If it attempts to move beyond the top or bottom of the buffer (or clipped
415 region), then point is positioned in the goal column in the top or
416 bottom line. No error is signaled.
418 In an interactive call, @var{count} will be the numeric
421 The command @code{set-goal-column} can be used to create a semipermanent
422 goal column to which this command always moves. Then it does not try to
425 If you are thinking of using this in a Lisp program, consider using
426 @code{forward-line} with a negative argument instead. It is usually easier
427 to use and more reliable (no dependence on goal column, etc.).
430 @deffn Command next-line count
431 This function moves point down @var{count} lines (up if @var{count}
432 is negative). In moving, it attempts to keep point in the ``goal column''
433 (normally the same column that it was at the beginning of the move).
435 If there is no character in the target line exactly under the current
436 column, point is positioned after the character in that line which
437 spans this column, or at the end of the line if it is not long enough.
439 If it attempts to move beyond the top or bottom of the buffer (or clipped
440 region), then point is positioned in the goal column in the top or
441 bottom line. No error is signaled.
443 In the case where the @var{count} is 1, and point is on the last
444 line of the buffer (or clipped region), a new empty line is inserted at the
445 end of the buffer (or clipped region) and point moved there.
447 In an interactive call, @var{count} will be the numeric
450 The command @code{set-goal-column} can be used to create a semipermanent
451 goal column to which this command always moves. Then it does not try to
454 If you are thinking of using this in a Lisp program, consider using
455 @code{forward-line} instead. It is usually easier
456 to use and more reliable (no dependence on goal column, etc.).
462 Also see the functions @code{bolp} and @code{eolp} in @ref{Near Point}.
463 These functions do not move point, but test whether it is already at the
464 beginning or end of a line.
467 @subsection Motion by Screen Lines
469 The line functions in the previous section count text lines, delimited
470 only by newline characters. By contrast, these functions count screen
471 lines, which are defined by the way the text appears on the screen. A
472 text line is a single screen line if it is short enough to fit the width
473 of the selected window, but otherwise it may occupy several screen
476 In some cases, text lines are truncated on the screen rather than
477 continued onto additional screen lines. In these cases,
478 @code{vertical-motion} moves point much like @code{forward-line}.
481 Because the width of a given string depends on the flags that control
482 the appearance of certain characters, @code{vertical-motion} behaves
483 differently, for a given piece of text, depending on the buffer it is
484 in, and even on the selected window (because the width, the truncation
485 flag, and display table may vary between windows). @xref{Usual
488 These functions scan text to determine where screen lines break, and
489 thus take time proportional to the distance scanned.
491 If you intend to use them heavily, Emacs provides caches which may
492 improve the performance of your code. @xref{Truncation, cache-long-scans}.
495 @defun vertical-motion count &optional window
496 This function moves point to the start of the screen line @var{count}
497 screen lines down from the screen line containing point. If @var{count}
498 is negative, it moves up instead.
500 The @var{count} argument can be a cons cell, @code{(@var{cols}
501 . @var{lines})}, instead of an integer. Then the function moves by
502 @var{lines} screen lines, and puts point @var{cols} columns from the
503 start of that screen line.
505 The return value is the number of screen lines over which point was
506 moved. The value may be less in absolute value than @var{count} if
507 the beginning or end of the buffer was reached.
509 The window @var{window} is used for obtaining parameters such as the
510 width, the horizontal scrolling, and the display table. But
511 @code{vertical-motion} always operates on the current buffer, even if
512 @var{window} currently displays some other buffer.
515 @defun count-screen-lines &optional beg end count-final-newline window
516 This function returns the number of screen lines in the text from
517 @var{beg} to @var{end}. The number of screen lines may be different
518 from the number of actual lines, due to line continuation, the display
519 table, etc. If @var{beg} and @var{end} are @code{nil} or omitted,
520 they default to the beginning and end of the accessible portion of the
523 If the region ends with a newline, that is ignored unless the optional
524 third argument @var{count-final-newline} is non-@code{nil}.
526 The optional fourth argument @var{window} specifies the window for
527 obtaining parameters such as width, horizontal scrolling, and so on.
528 The default is to use the selected window's parameters.
530 Like @code{vertical-motion}, @code{count-screen-lines} always uses the
531 current buffer, regardless of which buffer is displayed in
532 @var{window}. This makes possible to use @code{count-screen-lines} in
533 any buffer, whether or not it is currently displayed in some window.
536 @deffn Command move-to-window-line count
537 This function moves point with respect to the text currently displayed
538 in the selected window. It moves point to the beginning of the screen
539 line @var{count} screen lines from the top of the window. If
540 @var{count} is negative, that specifies a position
541 @w{@minus{}@var{count}} lines from the bottom (or the last line of the
542 buffer, if the buffer ends above the specified screen position).
544 If @var{count} is @code{nil}, then point moves to the beginning of the
545 line in the middle of the window. If the absolute value of @var{count}
546 is greater than the size of the window, then point moves to the place
547 that would appear on that screen line if the window were tall enough.
548 This will probably cause the next redisplay to scroll to bring that
549 location onto the screen.
551 In an interactive call, @var{count} is the numeric prefix argument.
553 The value returned is the window line number point has moved to, with
554 the top line in the window numbered 0.
557 @defun compute-motion from frompos to topos width offsets window
558 This function scans the current buffer, calculating screen positions.
559 It scans the buffer forward from position @var{from}, assuming that is
560 at screen coordinates @var{frompos}, to position @var{to} or coordinates
561 @var{topos}, whichever comes first. It returns the ending buffer
562 position and screen coordinates.
564 The coordinate arguments @var{frompos} and @var{topos} are cons cells of
565 the form @code{(@var{hpos} . @var{vpos})}.
567 The argument @var{width} is the number of columns available to display
568 text; this affects handling of continuation lines. @code{nil} means
569 the actual number of usable text columns in the window, which is
570 equivalent to the value returned by @code{(window-width window)}.
572 The argument @var{offsets} is either @code{nil} or a cons cell of the
573 form @code{(@var{hscroll} . @var{tab-offset})}. Here @var{hscroll} is
574 the number of columns not being displayed at the left margin; most
575 callers get this by calling @code{window-hscroll}. Meanwhile,
576 @var{tab-offset} is the offset between column numbers on the screen and
577 column numbers in the buffer. This can be nonzero in a continuation
578 line, when the previous screen lines' widths do not add up to a multiple
579 of @code{tab-width}. It is always zero in a non-continuation line.
581 The window @var{window} serves only to specify which display table to
582 use. @code{compute-motion} always operates on the current buffer,
583 regardless of what buffer is displayed in @var{window}.
585 The return value is a list of five elements:
588 (@var{pos} @var{hpos} @var{vpos} @var{prevhpos} @var{contin})
592 Here @var{pos} is the buffer position where the scan stopped, @var{vpos}
593 is the vertical screen position, and @var{hpos} is the horizontal screen
596 The result @var{prevhpos} is the horizontal position one character back
597 from @var{pos}. The result @var{contin} is @code{t} if the last line
598 was continued after (or within) the previous character.
600 For example, to find the buffer position of column @var{col} of screen line
601 @var{line} of a certain window, pass the window's display start location
602 as @var{from} and the window's upper-left coordinates as @var{frompos}.
603 Pass the buffer's @code{(point-max)} as @var{to}, to limit the scan to
604 the end of the accessible portion of the buffer, and pass @var{line} and
605 @var{col} as @var{topos}. Here's a function that does this:
608 (defun coordinates-of-position (col line)
609 (car (compute-motion (window-start)
614 (cons (window-hscroll) 0)
618 When you use @code{compute-motion} for the minibuffer, you need to use
619 @code{minibuffer-prompt-width} to get the horizontal position of the
620 beginning of the first screen line. @xref{Minibuffer Contents}.
624 @subsection Moving over Balanced Expressions
626 @cindex Lisp expression motion
628 @cindex balanced parenthesis motion
630 Here are several functions concerned with balanced-parenthesis
631 expressions (also called @dfn{sexps} in connection with moving across
632 them in Emacs). The syntax table controls how these functions interpret
633 various characters; see @ref{Syntax Tables}. @xref{Parsing
634 Expressions}, for lower-level primitives for scanning sexps or parts of
635 sexps. For user-level commands, see @ref{Parentheses,, Commands for
636 Editing with Parentheses, emacs, The GNU Emacs Manual}.
638 @deffn Command forward-list &optional arg
639 This function moves forward across @var{arg} (default 1) balanced groups of
640 parentheses. (Other syntactic entities such as words or paired string
644 @deffn Command backward-list &optional arg
645 This function moves backward across @var{arg} (default 1) balanced groups of
646 parentheses. (Other syntactic entities such as words or paired string
650 @deffn Command up-list &optional arg escape-strings no-syntax-crossing
651 This function moves forward out of @var{arg} (default 1) levels of
652 parentheses. A negative argument means move backward but still to a
653 less deep spot. If @var{escape-strings} is non-nil (as it is
654 interactively), move out of enclosing strings as well. If
655 @var{no-syntax-crossing} is non-nil (as it is interactively), prefer
656 to break out of any enclosing string instead of moving to the start of
657 a list broken across multiple strings. On error, location of point is
661 @deffn Command backward-up-list &optional arg escape-strings no-syntax-crossing
662 This function is just like @code{up-list}, but with a negated argument.
665 @deffn Command down-list &optional arg
666 This function moves forward into @var{arg} (default 1) levels of
667 parentheses. A negative argument means move backward but still go
668 deeper in parentheses (@minus{}@var{arg} levels).
671 @deffn Command forward-sexp &optional arg
672 This function moves forward across @var{arg} (default 1) balanced expressions.
673 Balanced expressions include both those delimited by parentheses and
674 other kinds, such as words and string constants.
675 @xref{Parsing Expressions}. For example,
679 ---------- Buffer: foo ----------
680 (concat@point{} "foo " (car x) y z)
681 ---------- Buffer: foo ----------
688 ---------- Buffer: foo ----------
689 (concat "foo " (car x) y@point{} z)
690 ---------- Buffer: foo ----------
695 @deffn Command backward-sexp &optional arg
696 This function moves backward across @var{arg} (default 1) balanced expressions.
699 @deffn Command beginning-of-defun &optional arg
700 This function moves back to the @var{arg}th beginning of a defun. If
701 @var{arg} is negative, this actually moves forward, but it still moves
702 to the beginning of a defun, not to the end of one. @var{arg} defaults
706 @deffn Command end-of-defun &optional arg
707 This function moves forward to the @var{arg}th end of a defun. If
708 @var{arg} is negative, this actually moves backward, but it still moves
709 to the end of a defun, not to the beginning of one. @var{arg} defaults
713 @defopt defun-prompt-regexp
714 If non-@code{nil}, this buffer-local variable holds a regular
715 expression that specifies what text can appear before the
716 open-parenthesis that starts a defun. That is to say, a defun begins
717 on a line that starts with a match for this regular expression,
718 followed by a character with open-parenthesis syntax.
721 @defopt open-paren-in-column-0-is-defun-start
722 If this variable's value is non-@code{nil}, an open parenthesis in
723 column 0 is considered to be the start of a defun. If it is
724 @code{nil}, an open parenthesis in column 0 has no special meaning.
725 The default is @code{t}.
728 @defvar beginning-of-defun-function
729 If non-@code{nil}, this variable holds a function for finding the
730 beginning of a defun. The function @code{beginning-of-defun}
731 calls this function instead of using its normal method, passing it its
732 optional argument. If the argument is non-@code{nil}, the function
733 should move back by that many functions, like
734 @code{beginning-of-defun} does.
737 @defvar end-of-defun-function
738 If non-@code{nil}, this variable holds a function for finding the end of
739 a defun. The function @code{end-of-defun} calls this function instead
740 of using its normal method.
743 @node Skipping Characters
744 @subsection Skipping Characters
745 @cindex skipping characters
747 The following two functions move point over a specified set of
748 characters. For example, they are often used to skip whitespace. For
749 related functions, see @ref{Motion and Syntax}.
751 These functions convert the set string to multibyte if the buffer is
752 multibyte, and they convert it to unibyte if the buffer is unibyte, as
753 the search functions do (@pxref{Searching and Matching}).
755 @defun skip-chars-forward character-set &optional limit
756 This function moves point in the current buffer forward, skipping over a
757 given set of characters. It examines the character following point,
758 then advances point if the character matches @var{character-set}. This
759 continues until it reaches a character that does not match. The
760 function returns the number of characters moved over.
762 The argument @var{character-set} is a string, like the inside of a
763 @samp{[@dots{}]} in a regular expression except that @samp{]} does not
764 terminate it, and @samp{\} quotes @samp{^}, @samp{-} or @samp{\}.
765 Thus, @code{"a-zA-Z"} skips over all letters, stopping before the
766 first nonletter, and @code{"^a-zA-Z"} skips nonletters stopping before
767 the first letter. See @xref{Regular Expressions}. Character classes
768 can also be used, e.g., @code{"[:alnum:]"}. See @pxref{Char Classes}.
770 If @var{limit} is supplied (it must be a number or a marker), it
771 specifies the maximum position in the buffer that point can be skipped
772 to. Point will stop at or before @var{limit}.
774 In the following example, point is initially located directly before the
775 @samp{T}. After the form is evaluated, point is located at the end of
776 that line (between the @samp{t} of @samp{hat} and the newline). The
777 function skips all letters and spaces, but not newlines.
781 ---------- Buffer: foo ----------
782 I read "@point{}The cat in the hat
784 ---------- Buffer: foo ----------
788 (skip-chars-forward "a-zA-Z ")
791 ---------- Buffer: foo ----------
792 I read "The cat in the hat@point{}
794 ---------- Buffer: foo ----------
799 @defun skip-chars-backward character-set &optional limit
800 This function moves point backward, skipping characters that match
801 @var{character-set}, until @var{limit}. It is just like
802 @code{skip-chars-forward} except for the direction of motion.
804 The return value indicates the distance traveled. It is an integer that
812 It is often useful to move point ``temporarily'' within a localized
813 portion of the program. This is called an @dfn{excursion}, and it is
814 done with the @code{save-excursion} special form. This construct
815 remembers the initial identity of the current buffer, and its values
816 of point and the mark, and restores them after the excursion
817 completes. It is the standard way to move point within one part of a
818 program and avoid affecting the rest of the program, and is used
819 thousands of times in the Lisp sources of Emacs.
821 If you only need to save and restore the identity of the current
822 buffer, use @code{save-current-buffer} or @code{with-current-buffer}
823 instead (@pxref{Current Buffer}). If you need to save or restore
824 window configurations, see the forms described in @ref{Window
825 Configurations} and in @ref{Frame Configurations}. @c frameset?
827 @defspec save-excursion body@dots{}
828 @cindex mark excursion
829 @cindex point excursion
830 This special form saves the identity of the current buffer and the
831 values of point and the mark in it, evaluates @var{body}, and finally
832 restores the buffer and its saved values of point and the mark. All
833 three saved values are restored even in case of an abnormal exit via
834 @code{throw} or error (@pxref{Nonlocal Exits}).
836 The value returned by @code{save-excursion} is the result of the last
837 form in @var{body}, or @code{nil} if no body forms were given.
840 Because @code{save-excursion} only saves point and mark for the
841 buffer that was current at the start of the excursion, any changes
842 made to point and/or mark in other buffers, during the excursion, will
843 remain in effect afterward. This frequently leads to unintended
844 consequences, so the byte compiler warns if you call @code{set-buffer}
848 Warning: Use `with-current-buffer' rather than
849 save-excursion+set-buffer
853 To avoid such problems, you should call @code{save-excursion} only
854 after setting the desired current buffer, as in the following example:
858 (defun append-string-to-buffer (string buffer)
859 "Append STRING to the end of BUFFER."
860 (with-current-buffer buffer
862 (goto-char (point-max))
867 @cindex window excursions
868 Likewise, @code{save-excursion} does not restore window-buffer
869 correspondences altered by functions such as @code{switch-to-buffer}.
871 @strong{Warning:} Ordinary insertion of text adjacent to the saved
872 point value relocates the saved value, just as it relocates all
873 markers. More precisely, the saved value is a marker with insertion
874 type @code{nil}. @xref{Marker Insertion Types}. Therefore, when the
875 saved point value is restored, it normally comes before the inserted
878 Although @code{save-excursion} saves the location of the mark, it does
879 not prevent functions which modify the buffer from setting
880 @code{deactivate-mark}, and thus causing the deactivation of the mark
881 after the command finishes. @xref{The Mark}.
886 @cindex restriction (in a buffer)
887 @cindex accessible portion (of a buffer)
889 @dfn{Narrowing} means limiting the text addressable by Emacs editing
890 commands to a limited range of characters in a buffer. The text that
891 remains addressable is called the @dfn{accessible portion} of the
894 Narrowing is specified with two buffer positions, which become the
895 beginning and end of the accessible portion. For most editing
896 commands and primitives, these positions replace the values of the
897 beginning and end of the buffer. While narrowing is in effect, no
898 text outside the accessible portion is displayed, and point cannot
899 move outside the accessible portion. Note that narrowing does not
900 alter actual buffer positions (@pxref{Point}); it only determines
901 which positions are considered the accessible portion of the buffer.
902 Most functions refuse to operate on text that is outside the
905 Commands for saving buffers are unaffected by narrowing; they save
906 the entire buffer regardless of any narrowing.
908 If you need to display in a single buffer several very different
909 types of text, consider using an alternative facility described in
912 @deffn Command narrow-to-region start end
913 This function sets the accessible portion of the current buffer to start
914 at @var{start} and end at @var{end}. Both arguments should be character
917 In an interactive call, @var{start} and @var{end} are set to the bounds
918 of the current region (point and the mark, with the smallest first).
921 @deffn Command narrow-to-page &optional move-count
922 This function sets the accessible portion of the current buffer to
923 include just the current page. An optional first argument
924 @var{move-count} non-@code{nil} means to move forward or backward by
925 @var{move-count} pages and then narrow to one page. The variable
926 @code{page-delimiter} specifies where pages start and end
927 (@pxref{Standard Regexps}).
929 In an interactive call, @var{move-count} is set to the numeric prefix
935 This function cancels any narrowing in the current buffer, so that the
936 entire contents are accessible. This is called @dfn{widening}.
937 It is equivalent to the following expression:
940 (narrow-to-region 1 (1+ (buffer-size)))
944 @defun buffer-narrowed-p
945 This function returns non-@code{nil} if the buffer is narrowed, and
946 @code{nil} otherwise.
949 @defspec save-restriction body@dots{}
950 This special form saves the current bounds of the accessible portion,
951 evaluates the @var{body} forms, and finally restores the saved bounds,
952 thus restoring the same state of narrowing (or absence thereof) formerly
953 in effect. The state of narrowing is restored even in the event of an
954 abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
955 Therefore, this construct is a clean way to narrow a buffer temporarily.
957 The value returned by @code{save-restriction} is that returned by the
958 last form in @var{body}, or @code{nil} if no body forms were given.
960 @c Wordy to avoid overfull hbox. --rjc 16mar92
961 @strong{Caution:} it is easy to make a mistake when using the
962 @code{save-restriction} construct. Read the entire description here
965 If @var{body} changes the current buffer, @code{save-restriction} still
966 restores the restrictions on the original buffer (the buffer whose
967 restrictions it saved from), but it does not restore the identity of the
970 @code{save-restriction} does @emph{not} restore point and the mark; use
971 @code{save-excursion} for that. If you use both @code{save-restriction}
972 and @code{save-excursion} together, @code{save-excursion} should come
973 first (on the outside). Otherwise, the old point value would be
974 restored with temporary narrowing still in effect. If the old point
975 value were outside the limits of the temporary narrowing, this would
976 fail to restore it accurately.
978 Here is a simple example of correct use of @code{save-restriction}:
982 ---------- Buffer: foo ----------
983 This is the contents of foo
984 This is the contents of foo
985 This is the contents of foo@point{}
986 ---------- Buffer: foo ----------
994 (narrow-to-region 1 (point))
995 (goto-char (point-min))
996 (replace-string "foo" "bar")))
998 ---------- Buffer: foo ----------
999 This is the contents of bar
1000 This is the contents of bar
1001 This is the contents of foo@point{}
1002 ---------- Buffer: foo ----------