Function: forward-line

forward-line is an interactive function defined in cmds.c.

Signature

(forward-line &optional N)

Documentation

Move N lines forward (backward if N is negative).

Precisely, if point is on line I, move to the start of line I + N
("start of line" in the logical order).
If there isn't room, go as far as possible (no error). Interactively, N is the numeric prefix argument and defaults to 1.

Returns the count of lines left to move. If moving forward, that is N minus number of lines moved; if backward, N plus number moved.

Exception: With positive N, a non-empty line at the end of the buffer, or of its accessible portion, counts as one line successfully moved (for the return value). This means that the function will move point to the end of such a line and will count it as a line moved across, even though there is no next line to go to its beginning.

Other relevant functions are documented in the buffer group.

View in manual

Key Bindings

Shortdoc

;; buffer
(forward-line 1)
    e.g. => 0
  (forward-line -2)
    e.g. => 0

Source Code

// Defined in /usr/src/emacs/src/cmds.c
{
  ptrdiff_t opoint = PT, pos, pos_byte, count;
  bool excessive = false;

  if (NILP (n))
    count = 1;
  else
    {
      CHECK_INTEGER (n);
      if (FIXNUMP (n)
	  && -BUF_BYTES_MAX <= XFIXNUM (n) && XFIXNUM (n) <= BUF_BYTES_MAX)
	count = XFIXNUM (n);
      else
	{
	  count = !NILP (Fnatnump (n)) ? BUF_BYTES_MAX : -BUF_BYTES_MAX;
	  excessive = true;
	}
    }

  ptrdiff_t counted = scan_newline_from_point (count, &pos, &pos_byte);

  SET_PT_BOTH (pos, pos_byte);

  ptrdiff_t shortage = count - (count <= 0) - counted;
  if (shortage != 0)
    shortage -= (count <= 0 ? -1
		  : (BEGV < ZV && PT != opoint
		     && FETCH_BYTE (PT_BYTE - 1) != '\n'));
  return (excessive
	  ? CALLN (Fplus, make_fixnum (shortage - count), n)
	  : make_fixnum (shortage));
}