These functions move point based on a count of characters. goto-char is the fundamental primitive; the other functions use that.

Command goto-char

This function sets point in the current buffer to the value position. If narrowing is in effect, position still counts from the beginning of the buffer, but point cannot go outside the accessible portion. If position is out of range, goto-char moves point to the beginning or the end of the accessible portion. When this function is called interactively, position is the numeric prefix argument, if provided; otherwise it is read from the minibuffer. goto-char returns position.

Command forward-char

This function moves point count characters forward, towards the end of the buffer (or backward, towards the beginning of the buffer, if count is negative). If count is nil, the default is 1. If this attempts to move past the beginning or end of the buffer (or the limits of the accessible portion, when narrowing is in effect), it signals an error with error symbol beginning-of-buffer or end-of-buffer. In an interactive call, count is the numeric prefix argument.

Command backward-char

This is just like forward-char except that it moves in the opposite direction.

The functions for parsing words described below use the syntax table and char-script-table to decide whether a given character is part of a word. Syntax Tables, and see Character Properties.

Command forward-word

This function moves point forward count words (or backward if count is negative). If count is omitted or nil, it defaults to 1. In an interactive call, count is specified by the numeric prefix argument. "Moving one word" means moving until point crosses a word-constituent character, which indicates the beginning of a word, and then continue moving until the word ends. By default, characters that begin and end words, known as word boundaries, are defined by the current buffer's syntax table (Syntax Class Table), but modes can override that by setting up a suitable find-word-boundary-function-table, described below. Characters that belong to different scripts (as defined by char-script-table), also define a word boundary (Character Properties). In any case, this function cannot move point past the boundary of the accessible portion of the buffer, or across a field boundary (Fields). The most common case of a field boundary is the end of the prompt in the minibuffer. If it is possible to move count words, without being stopped prematurely by the buffer boundary or a field boundary, the value is t. Otherwise, the return value is nil and point stops at the buffer boundary or field boundary. If inhibit-field-text-motion is non-nil, this function ignores field boundaries.

Command backward-word

This function is just like forward-word, except that it moves backward until encountering the front of a word, rather than forward.

words-include-escapes

This variable affects the behavior of forward-word and backward-word, and everything that uses them. If it is non-nil, then characters in the escape and character-quote syntax classes count as part of words. Otherwise, they do not.

inhibit-field-text-motion

If this variable is non-nil, certain motion functions including forward-word, forward-sentence, and forward-paragraph ignore field boundaries.

find-word-boundary-function-table

This variable affects the behavior of forward-word and backward-word, and everything that uses them. Its value is a char-table (Char-Tables) of functions to search for word boundaries. If a character has a non-nil entry in this table, then when a word starts or ends with that character, the corresponding function will be called with 2 arguments: pos and limit. The function should return the position of the other word boundary. Specifically, if pos is smaller than limit, then pos is at the beginning of a word, and the function should return the position after the last character of the word; otherwise, pos is at the last character of a word, and the function should return the position of that word's first character.

forward-word-strictly

This function is like forward-word, but it is not affected by find-word-boundary-function-table. Lisp programs that should not change behavior when word movement is modified by modes which set that table, such as subword-mode, should use this function instead of forward-word.

backward-word-strictly

This function is like backward-word, but it is not affected by find-word-boundary-function-table. Like with forward-word-strictly, use this function instead of backward-word when movement by words should only consider syntax tables.

To move point to the beginning of the buffer, write:

(goto-char (point-min))

Likewise, to move to the end of the buffer, use:

(goto-char (point-max))

Here are two commands that users use to do these things. They are documented here to warn you not to use them in Lisp programs, because they set the mark and display messages in the echo area.

Command beginning-of-buffer

This function moves point to the beginning of the buffer (or the limits of the accessible portion, when narrowing is in effect), setting the mark at the previous position (except in Transient Mark mode, if the mark is already active, it does not set the mark.) If n is non-nil, then it puts point n tenths of the way from the beginning of the accessible portion of the buffer. In an interactive call, n is the numeric prefix argument, if provided; otherwise n defaults to nil. Warning: Don't use this function in Lisp programs!

Command end-of-buffer

This function moves point to the end of the buffer (or the limits of the accessible portion, when narrowing is in effect), setting the mark at the previous position (except in Transient Mark mode when the mark is already active). If n is non-nil, then it puts point n tenths of the way from the end of the accessible portion of the buffer. In an interactive call, n is the numeric prefix argument, if provided; otherwise n defaults to nil. Warning: Don't use this function in Lisp programs!

Text lines are portions of the buffer delimited by newline characters, which are regarded as part of the previous line. The first text line begins at the beginning of the buffer, and the last text line ends at the end of the buffer whether or not the last character is a newline. The division of the buffer into text lines is not affected by the width of the window, by line continuation in display, or by how tabs and control characters are displayed.

Command beginning-of-line

This function moves point to the beginning of the current line. With an argument count not nil or 1, it moves forward count/−1 lines and then to the beginning of the line. This function does not move point across a field boundary (Fields) unless doing so would move beyond there to a different line; therefore, if /count is nil or 1, and point starts at a field boundary, point does not move. To ignore field boundaries, either bind inhibit-field-text-motion to t, or use the forward-line function instead. For instance, (forward-line 0) does the same thing as (beginning-of-line), except that it ignores field boundaries. If this function reaches the end of the buffer (or of the accessible portion, if narrowing is in effect), it positions point there. No error is signaled.

line-beginning-position

Return the position that (beginning-of-line COUNT) would move to.

Command end-of-line

This function moves point to the end of the current line. With an argument count not nil or 1, it moves forward count/−1 lines and then to the end of the line. This function does not move point across a field boundary (Fields) unless doing so would move beyond there to a different line; therefore, if /count is nil or 1, and point starts at a field boundary, point does not move. To ignore field boundaries, bind inhibit-field-text-motion to t. If this function reaches the end of the buffer (or of the accessible portion, if narrowing is in effect), it positions point there. No error is signaled.

line-end-position

Return the position that (end-of-line COUNT) would move to.

Command forward-line

This function moves point forward count lines, to the beginning of the line following that. If count is negative, it moves point −/count/ lines backward, to the beginning of a line preceding that. If count is zero, it moves point to the beginning of the current line. If count is nil, that means 1. If forward-line encounters the beginning or end of the buffer (or of the accessible portion) before finding that many lines, it sets point there. No error is signaled. forward-line returns the difference between count and the number of lines actually moved. If you attempt to move down five lines from the beginning of a buffer that has only three lines, point stops at the end of the last line, and the value will be 2. As an explicit exception, if the last accessible line is non-empty, but has no newline (e.g., if the buffer ends without a newline), the function sets point to the end of that line, and the value returned by the function counts that line as one line successfully moved. In an interactive call, count is the numeric prefix argument.

count-lines

This function returns the number of lines between the positions start and end in the current buffer. If start and end are equal, then it returns 0. Otherwise it returns at least 1, even if start and end are on the same line. This is because the text between them, considered in isolation, must contain at least one line unless it is empty. If the optional ignore-invisible-lines is non-nil, invisible lines will not be included in the count.

Command count-words

This function returns the number of words between the positions start and end in the current buffer. This function can also be called interactively. In that case, it prints a message reporting the number of lines, words, and characters in the buffer, or in the region if the region is active.

line-number-at-pos

This function returns the line number in the current buffer corresponding to the buffer position pos. If pos is nil or omitted, the current buffer position is used. If absolute is nil, the default, counting starts at (point-min), so the value refers to the contents of the accessible portion of the (potentially narrowed) buffer. If absolute is non-nil, ignore any narrowing and return the absolute line number.

Also see the functions bolp and eolp in Near Point. These functions do not move point, but test whether it is already at the beginning or end of a line.

The line functions in the previous section count text lines, delimited only by newline characters. By contrast, these functions count screen lines, which are defined by the way the text appears on the screen. A text line is a single screen line if it is short enough to fit the width of the selected window, but otherwise it may occupy several screen lines. In some cases, text lines are truncated on the screen rather than continued onto additional screen lines. In these cases, vertical-motion moves point much like forward-line. Truncation. Because the width of a given string depends on the flags that control the appearance of certain characters, vertical-motion behaves differently, for a given piece of text, depending on the buffer it is in, and even on the selected window (because the width, the truncation flag, and display table may vary between windows). Usual Display. These functions scan text to determine where screen lines break, and thus take time proportional to the distance scanned.

vertical-motion

This function moves point to the start of the screen line count screen lines down from the screen line containing point. If count is negative, it moves up instead. The count argument can be a cons cell, (COLS . LINES), instead of an integer. Then the function moves by lines screen lines, and puts point cols columns from the visual start of that screen line. Note that cols are counted from the visual start of the line; if the window is scrolled horizontally (Horizontal Scrolling), the column on which point will end is in addition to the number of columns by which the text is scrolled. The return value is the number of screen lines over which point was moved. The value may be less in absolute value than count if the beginning or end of the buffer was reached. The window window is used for obtaining parameters such as the width, the horizontal scrolling, and the display table. But vertical-motion always operates on the current buffer, even if window currently displays some other buffer. The optional argument cur-col specifies the current column when the function is called. This is the window-relative horizontal coordinate of point, measured in units of font width of the frame's default face. Providing it speeds up the function, especially in very long lines, because the function doesn't have to go back in the buffer in order to determine the current column. Note that cur-col is also counted from the visual start of the line.

count-screen-lines

This function returns the number of screen lines in the text from beg to end. The number of screen lines may be different from the number of actual lines, due to line continuation, the display table, etc. If beg and end are nil or omitted, they default to the beginning and end of the accessible portion of the buffer. If the region ends with a newline, that is ignored unless the optional third argument count-final-newline is non-nil. The optional fourth argument window specifies the window for obtaining parameters such as width, horizontal scrolling, and so on. The default is to use the selected window's parameters. Like vertical-motion, count-screen-lines always uses the current buffer, regardless of which buffer is displayed in window. This makes possible to use count-screen-lines in any buffer, whether or not it is currently displayed in some window.

Command move-to-window-line

This function moves point with respect to the text currently displayed in the selected window. It moves point to the beginning of the screen line count screen lines from the top of the window; zero means the topmost line. If count is negative, that specifies a position −/count/ lines from the bottom (or the last line of the buffer, if the buffer ends above the specified screen position); thus, count of −1 specifies the last fully visible screen line of the window. If count is nil, then point moves to the beginning of the line in the middle of the window. If the absolute value of count is greater than the size of the window, then point moves to the place that would appear on that screen line if the window were tall enough. This will probably cause the next redisplay to scroll to bring that location onto the screen. In an interactive call, count is the numeric prefix argument. The value returned is the screen line number point has moved to, relative to the top line of the window.

move-to-window-group-line

This function is like move-to-window-line, except that when the selected window is a part of a group of windows (Window Group), move-to-window-group-line will move to a position with respect to the entire group, not just the single window. This condition holds when the buffer local variable move-to-window-group-line-function is set to a function. In this case, move-to-window-group-line calls the function with the argument count, then returns its result.

compute-motion

This function scans the current buffer, calculating screen positions. It scans the buffer forward from position from, assuming that is at screen coordinates frompos, to position to or coordinates topos, whichever comes first. It returns the ending buffer position and screen coordinates. The coordinate arguments frompos and topos are cons cells of the form (HPOS . VPOS). The argument width is the number of columns available to display text; this affects handling of continuation lines. nil means the actual number of usable text columns in the window, which is equivalent to the value returned by (window-width window). The argument offsets is either nil or a cons cell of the form (HSCROLL . TAB-OFFSET). Here hscroll is the number of columns not being displayed at the left margin; most callers get this by calling window-hscroll. Meanwhile, tab-offset is the offset between column numbers on the screen and column numbers in the buffer. This can be nonzero in a continuation line, when the previous screen lines' widths do not add up to a multiple of tab-width. It is always zero in a non-continuation line. The window window serves only to specify which display table to use. compute-motion always operates on the current buffer, regardless of what buffer is displayed in window. The return value is a list of five elements:

(POS HPOS VPOS PREVHPOS CONTIN)

Here pos is the buffer position where the scan stopped, vpos is the vertical screen position, and hpos is the horizontal screen position. The result prevhpos is the horizontal position one character back from pos. The result contin is t if the last line was continued after (or within) the previous character. For example, to find the buffer position of column col of screen line line of a certain window, pass the window's display start location as from and the window's upper-left coordinates as frompos. Pass the buffer's (point-max) as to, to limit the scan to the end of the accessible portion of the buffer, and pass line and col as topos. Here's a function that does this:

(defun coordinates-of-position (col line)
  (car (compute-motion (window-start)
                       '(0 . 0)
                       (point-max)
                       (cons col line)
                       (window-width)
                       (cons (window-hscroll) 0)
                       (selected-window))))

When you use compute-motion for the minibuffer, you need to use minibuffer-prompt-width to get the horizontal position of the beginning of the first screen line. Minibuffer Contents.

Here are several functions concerned with balanced-parenthesis expressions (also called sexps in connection with moving across them in Emacs). The syntax table controls how these functions interpret various characters; see Syntax Tables. Parsing Expressions, for lower-level primitives for scanning sexps or parts of sexps. For user-level commands, see Commands for Editing with Parentheses.

Command forward-list

This function moves forward across arg (default 1) balanced groups of parentheses. (Other syntactic entities such as words or paired string quotes are ignored.)

Command backward-list

This function moves backward across arg (default 1) balanced groups of parentheses. (Other syntactic entities such as words or paired string quotes are ignored.)

Command up-list

This function moves forward out of arg (default 1) levels of parentheses. A negative argument means move backward but still to a less deep spot. If escape-strings is non-nil (as it is interactively), move out of enclosing strings as well. If no-syntax-crossing is non-nil (as it is interactively), prefer to break out of any enclosing string instead of moving to the start of a list broken across multiple strings. On error, location of point is unspecified.

Command backward-up-list

This function is just like up-list, but with a negated argument.

Command down-list

This function moves forward into arg (default 1) levels of parentheses. A negative argument means move backward but still go deeper in parentheses (−/arg/ levels).

Command forward-sexp

This function moves forward across arg (default 1) balanced expressions. Balanced expressions include both those delimited by parentheses and other kinds, such as words and string constants. Parsing Expressions. For example,

---------- Buffer: foo ----------
(concat⋆ "foo " (car x) y z)
---------- Buffer: foo ----------

(forward-sexp 3)
     => nil

---------- Buffer: foo ----------
(concat "foo " (car x) y⋆ z)
---------- Buffer: foo ----------

Command backward-sexp

This function moves backward across arg (default 1) balanced expressions.

Command beginning-of-defun

This function moves back to the arg/th beginning of a defun. If /arg is negative, this actually moves forward, but it still moves to the beginning of a defun, not to the end of one. arg defaults to 1.

Command end-of-defun

This function moves forward to the arg/th end of a defun. If /arg is negative, this actually moves backward, but it still moves to the end of a defun, not to the beginning of one. arg defaults to 1.

defun-prompt-regexp

If non-nil, this buffer-local variable holds a regular expression that specifies what text can appear before the open-parenthesis that starts a defun. That is to say, a defun begins on a line that starts with a match for this regular expression, followed by a character with open-parenthesis syntax.

open-paren-in-column-0-is-defun-start

If this variable's value is non-nil, an open parenthesis in column 0 is considered to be the start of a defun. If it is nil, an open parenthesis in column 0 has no special meaning. The default is t. If a string literal happens to have a parenthesis in column 0, escape it with a backslash to avoid a false positive.

beginning-of-defun-function

If non-nil, this variable holds a function for finding the beginning of a defun. The function beginning-of-defun calls this function instead of using its normal method, passing it its optional argument. If the argument is non-nil, the function should move back by that many functions, like beginning-of-defun does.

end-of-defun-function

If non-nil, this variable holds a function for finding the end of a defun. The function end-of-defun calls this function instead of using its normal method.

The following two functions move point over a specified set of characters. For example, they are often used to skip whitespace. For related functions, see Motion and Syntax. These functions convert the set string to multibyte if the buffer is multibyte, and they convert it to unibyte if the buffer is unibyte, as the search functions do (Searching and Matching).

skip-chars-forward

This function moves point in the current buffer forward, skipping over a given set of characters. It examines the character following point, then advances point if the character matches character-set. This continues until it reaches a character that does not match. The function returns the number of characters moved over. The argument character-set is a string, like the inside of a [...] in a regular expression except that ] does not terminate it, and \ quotes ^, - or \. Thus, "a-zA-Z" skips over all letters, stopping before the first nonletter, and "^a-zA-Z" skips nonletters stopping before the first letter (Regular Expressions). Character classes can also be used, e.g., "[:alnum:]" (Char Classes). If limit is supplied (it must be a number or a marker), it specifies the maximum position in the buffer that point can be skipped to. Point will stop at or before limit. In the following example, point is initially located directly before the T. After the form is evaluated, point is located at the end of that line (between the t of hat and the newline). The function skips all letters and spaces, but not newlines.

---------- Buffer: foo ----------
I read "⋆The cat in the hat
comes back" twice.
---------- Buffer: foo ----------

(skip-chars-forward "a-zA-Z ")
     => 18

---------- Buffer: foo ----------
I read "The cat in the hat⋆
comes back" twice.
---------- Buffer: foo ----------

skip-chars-backward

This function moves point backward, skipping characters that match character-set, until limit. It is just like skip-chars-forward except for the direction of motion. The return value indicates the distance traveled. It is an integer that is zero or less.