Lines Matching +refs:move +refs:beginning +refs:of +refs:line
2 @c This is part of the GNU Emacs Lisp Reference Manual.
10 A @dfn{position} is the index of a character in the text of a buffer.
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
26 integer; using it instead of an integer causes an error.
36 * Narrowing:: Restricting editing to a portion of the buffer.
45 insertion functions. Other commands move point through the text
55 The value of point is a number no less than 1, and no greater than the
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
71 This function returns the value of point in the current buffer,
84 This function returns the minimum accessible value of point in the
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
93 in effect, in which case it is the position of the end of the region
104 This function returns the total number of characters in the current
105 buffer. In the absence of any narrowing (@pxref{Narrowing}),
109 size of @var{buffer}.
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.
144 These functions move point based on a count of characters.
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
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.
171 @c @kindex beginning-of-buffer
172 @c @kindex end-of-buffer
174 end of the buffer (or backward, towards the beginning of the buffer, if
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}.
196 part of a word. @xref{Syntax Tables}, and see @ref{Character
206 word-constituent character, which indicates the beginning of a word,
215 move point past the boundary of the accessible portion of the buffer,
216 or across a field boundary (@pxref{Fields}). The most common case of
217 a field boundary is the end of the prompt in the minibuffer.
219 If it is possible to move @var{count} words, without being stopped
231 backward until encountering the front of a word, rather than forward.
236 This variable affects the behavior of @code{forward-word} and
239 syntax classes count as part of words. Otherwise, they do not.
249 This variable affects the behavior of @code{forward-word} and
251 char-table (@pxref{Char-Tables}) of functions to search for word
255 The function should return the position of the other word boundary.
257 is at the beginning of a word, and the function should return the
258 position after the last character of the word; otherwise, @var{pos} is
259 at the last character of a word, and the function should return the
260 position of that word's first character.
268 instead of @code{forward-word}.
274 @code{forward-word-strictly}, use this function instead of
280 @subsection Motion to an End of the Buffer
281 @cindex move to beginning or end of buffer
283 To move point to the beginning of the buffer, write:
292 Likewise, to move to the end of the buffer, use:
304 @deffn Command beginning-of-buffer &optional n
305 This function moves point to the beginning of the buffer (or the limits
306 of the accessible portion, when narrowing is in effect), setting the
310 If @var{n} is non-@code{nil}, then it puts point @var{n} tenths of the
311 way from the beginning of the accessible portion of the buffer. In an
318 @deffn Command end-of-buffer &optional n
319 This function moves point to the end of the buffer (or the limits of
323 @var{n} tenths of the way from the end of the accessible portion of
336 Text lines are portions of the buffer delimited by newline characters,
337 which are regarded as part of the previous line. The first text line
338 begins at the beginning of the buffer, and the last text line ends at
339 the end of the buffer whether or not the last character is a newline.
340 The division of the buffer into text lines is not affected by the width
341 of the window, by line continuation in display, or by how tabs and
344 @deffn Command beginning-of-line &optional count
345 This function moves point to the beginning of the current line. With an
347 @var{count}@minus{}1 lines and then to the beginning of the line.
349 This function does not move point across a field boundary
350 (@pxref{Fields}) unless doing so would move beyond there to a
351 different line; therefore, if @var{count} is @code{nil} or 1, and
352 point starts at a field boundary, point does not move. To ignore
354 @code{t}, or use the @code{forward-line} function instead. For
355 instance, @code{(forward-line 0)} does the same thing as
356 @code{(beginning-of-line)}, except that it ignores field boundaries.
358 If this function reaches the end of the buffer (or of the accessible
363 @defun line-beginning-position &optional count
364 Return the position that @code{(beginning-of-line @var{count})}
365 would move to.
368 @deffn Command end-of-line &optional count
369 This function moves point to the end of the current line. With an
371 @var{count}@minus{}1 lines and then to the end of the line.
373 This function does not move point across a field boundary
374 (@pxref{Fields}) unless doing so would move beyond there to a
375 different line; therefore, if @var{count} is @code{nil} or 1, and
376 point starts at a field boundary, point does not move. To ignore
379 If this function reaches the end of the buffer (or of the accessible
384 @defun line-end-position &optional count
385 Return the position that @code{(end-of-line @var{count})}
386 would move to.
389 @deffn Command forward-line &optional count
390 @cindex beginning of line
391 This function moves point forward @var{count} lines, to the beginning of
392 the line following that. If @var{count} is negative, it moves point
393 @minus{}@var{count} lines backward, to the beginning of a line
395 beginning of the current line. If @var{count} is @code{nil}, that
398 If @code{forward-line} encounters the beginning or end of the buffer (or
399 of the accessible portion) before finding that many lines, it sets point
402 @code{forward-line} returns the difference between @var{count} and the
403 number of lines actually moved. If you attempt to move down five lines
404 from the beginning of a buffer that has only three lines, point stops at
405 the end of the last line, and the value will be 2. As an explicit
406 exception, if the last accessible line is non-empty, but has no
408 sets point to the end of that line, and the value returned by the
409 function counts that line as one line successfully moved.
416 @anchor{Definition of count-lines}
417 This function returns the number of lines between the positions
420 1, even if @var{start} and @var{end} are on the same line. This is
422 least one line unless it is empty.
427 This function returns the number of words between the positions
431 prints a message reporting the number of lines, words, and characters
435 @defun line-number-at-pos &optional pos absolute
436 @cindex line number
437 This function returns the line number in the current buffer
441 @code{(point-min)}, so the value refers to the contents of the
442 accessible portion of the (potentially narrowed) buffer. If
444 the absolute line number.
449 The @code{previous-line} and @code{next-line} commands are functions
453 @deffn Command previous-line count
457 (normally the same column that it was at the beginning of the move).
459 If there is no character in the target line exactly under the current
460 column, point is positioned after the character in that line which
461 spans this column, or at the end of the line if it is not long enough.
463 If it attempts to move beyond the top or bottom of the buffer (or clipped
465 bottom line. No error is signaled.
472 move vertically.
474 If you are thinking of using this in a Lisp program, consider using
475 @code{forward-line} with a negative argument instead. It is usually easier
479 @deffn Command next-line count
482 (normally the same column that it was at the beginning of the move).
484 If there is no character in the target line exactly under the current
485 column, point is positioned after the character in that line which
486 spans this column, or at the end of the line if it is not long enough.
488 If it attempts to move beyond the top or bottom of the buffer (or clipped
490 bottom line. No error is signaled.
493 line of the buffer (or clipped region), a new empty line is inserted at the
494 end of the buffer (or clipped region) and point moved there.
501 move vertically.
503 If you are thinking of using this in a Lisp program, consider using
504 @code{forward-line} instead. It is usually easier
512 These functions do not move point, but test whether it is already at the
513 beginning or end of a line.
519 The line functions in the previous section count text lines, delimited
522 text line is a single screen line if it is short enough to fit the width
523 of the selected window, but otherwise it may occupy several screen
528 @code{vertical-motion} moves point much like @code{forward-line}.
531 Because the width of a given string depends on the flags that control
532 the appearance of certain characters, @code{vertical-motion} behaves
533 differently, for a given piece of text, depending on the buffer it is
542 improve the performance of your code. @xref{Truncation, cache-long-scans}.
546 This function moves point to the start of the screen line @var{count}
547 screen lines down from the screen line containing point. If @var{count}
551 . @var{lines})}, instead of an integer. Then the function moves by
553 visual start of that screen line. Note that @var{cols} are counted
554 from the @emph{visual} start of the line; if the window is scrolled
556 will end is in addition to the number of columns by which the text is
559 The return value is the number of screen lines over which point was
561 the beginning or end of the buffer was reached.
570 coordinate of point, measured in units of font width of the frame's
574 also counted from the visual start of the line.
578 This function returns the number of screen lines in the text from
579 @var{beg} to @var{end}. The number of screen lines may be different
580 from the number of actual lines, due to line continuation, the display
582 they default to the beginning and end of the accessible portion of the
593 current buffer, regardless of which buffer is displayed in
598 @deffn Command move-to-window-line count
600 in the selected window. It moves point to the beginning of the screen
601 line @var{count} screen lines from the top of the window; zero means
602 the topmost line. If @var{count} is negative, that specifies a
604 line of the buffer, if the buffer ends above the specified screen
605 position); thus, @var{count} of @minus{}1 specifies the last fully visible
606 screen line of the window.
608 If @var{count} is @code{nil}, then point moves to the beginning of the
609 line in the middle of the window. If the absolute value of @var{count}
610 is greater than the size of the window, then point moves to the place
611 that would appear on that screen line if the window were tall enough.
617 The value returned is the screen line number point has moved to,
618 relative to the top line of the window.
621 @vindex move-to-window-group-line-function
622 @defun move-to-window-group-line count
623 This function is like @code{move-to-window-line}, except that when the
624 selected window is a part of a group of windows (@pxref{Window
625 Group}), @code{move-to-window-group-line} will move to a position with
628 @code{move-to-window-group-line-function} is set to a function. In
629 this case, @code{move-to-window-group-line} calls the function with
640 The coordinate arguments @var{frompos} and @var{topos} are cons cells of
643 The argument @var{width} is the number of columns available to display
644 text; this affects handling of continuation lines. @code{nil} means
645 the actual number of usable text columns in the window, which is
648 The argument @var{offsets} is either @code{nil} or a cons cell of the
650 the number of columns not being displayed at the left margin; most
654 line, when the previous screen lines' widths do not add up to a multiple
655 of @code{tab-width}. It is always zero in a non-continuation line.
659 regardless of what buffer is displayed in @var{window}.
661 The return value is a list of five elements:
673 from @var{pos}. The result @var{contin} is @code{t} if the last line
676 For example, to find the buffer position of column @var{col} of screen line
677 @var{line} of a certain window, pass the window's display start location
680 the end of the accessible portion of the buffer, and pass @var{line} and
684 (defun coordinates-of-position (col line)
688 (cons col line)
695 @code{minibuffer-prompt-width} to get the horizontal position of the
696 beginning of the first screen line. @xref{Minibuffer Contents}.
710 Expressions}, for lower-level primitives for scanning sexps or parts of
715 This function moves forward across @var{arg} (default 1) balanced groups of
721 This function moves backward across @var{arg} (default 1) balanced groups of
727 This function moves forward out of @var{arg} (default 1) levels of
728 parentheses. A negative argument means move backward but still to a
730 interactively), move out of enclosing strings as well. If
732 to break out of any enclosing string instead of moving to the start of
733 a list broken across multiple strings. On error, location of point is
742 This function moves forward into @var{arg} (default 1) levels of
743 parentheses. A negative argument means move backward but still go
775 @deffn Command beginning-of-defun &optional arg
776 This function moves back to the @var{arg}th beginning of a defun. If
778 to the beginning of a defun, not to the end of one. @var{arg} defaults
782 @deffn Command end-of-defun &optional arg
783 This function moves forward to the @var{arg}th end of a defun. If
785 to the end of a defun, not to the beginning of one. @var{arg} defaults
793 on a line that starts with a match for this regular expression,
800 column 0 is considered to be the start of a defun. If it is
807 @defvar beginning-of-defun-function
809 beginning of a defun. The function @code{beginning-of-defun}
810 calls this function instead of using its normal method, passing it its
812 should move back by that many functions, like
813 @code{beginning-of-defun} does.
816 @defvar end-of-defun-function
817 If non-@code{nil}, this variable holds a function for finding the end of
818 a defun. The function @code{end-of-defun} calls this function instead
819 of using its normal method.
826 The following two functions move point over a specified set of
836 given set of characters. It examines the character following point,
839 function returns the number of characters moved over.
841 The argument @var{character-set} is a string, like the inside of a
854 @samp{T}. After the form is evaluated, point is located at the end of
855 that line (between the @samp{t} of @samp{hat} and the newline). The
881 @code{skip-chars-forward} except for the direction of motion.
891 It is often useful to move point temporarily within a localized
892 portion of the program. This is called an @dfn{excursion}, and it is
894 remembers the initial identity of the current buffer, and its value
895 of point, and restores them after the excursion
896 completes. It is the standard way to move point within one part of a
897 program and avoid affecting the rest of the program, and is used
898 thousands of times in the Lisp sources of Emacs.
900 If you only need to save and restore the identity of the current
908 This special form saves the identity of the current buffer and the
909 value of point in it, evaluates @var{body}, and finally
910 restores the buffer and its saved value of point. Both saved values are
911 restored even in case of an abnormal exit via
914 The value returned by @code{save-excursion} is the result of the last
919 buffer that was current at the start of the excursion, any changes
937 "Append STRING to the end of BUFFER."
949 @strong{Warning:} Ordinary insertion of text adjacent to the saved
968 @cindex accessible portion (of a buffer)
971 commands to a limited range of characters in a buffer. The text that
972 remains addressable is called the @dfn{accessible portion} of the
976 beginning and end of the accessible portion. For most editing
977 commands and primitives, these positions replace the values of the
978 beginning and end of the buffer. While narrowing is in effect, no
980 move outside the accessible portion. Note that narrowing does not
982 which positions are considered the accessible portion of the buffer.
987 the entire buffer regardless of any narrowing.
990 types of text, consider using an alternative facility described in
994 This function sets the accessible portion of the current buffer to start
999 of the current region (point and the mark, with the smallest first).
1002 @deffn Command narrow-to-page &optional move-count
1003 This function sets the accessible portion of the current buffer to
1005 @var{move-count} non-@code{nil} means to move forward or backward by
1006 @var{move-count} pages and then narrow to one page. The variable
1010 In an interactive call, @var{move-count} is set to the numeric prefix
1031 This special form saves the current bounds of the accessible portion,
1033 thus restoring the same state of narrowing (or absence thereof) formerly
1034 in effect. The state of narrowing is restored even in the event of an
1048 restrictions it saved from), but it does not restore the identity of the
1056 value were outside the limits of the temporary narrowing, this would
1059 Here is a simple example of correct use of @code{save-restriction}:
1064 This is the contents of foo
1065 This is the contents of foo
1066 This is the contents of foo@point{}
1074 (forward-line 2)
1080 This is the contents of bar
1081 This is the contents of bar
1082 This is the contents of foo@point{}