api: implement nvim_buf_get_offset_for_line

Like line2byte, but works for any buffer, and uses zero-based
indexing (API conventions).

src/nvim/api/buffer.c

@@ -491,6 +491,42 @@ end:
   try_end(err);
 }
 
+/// Return the byte offset for a line.
+//
+/// This includes the end-of-line character, depending on the 'fileformat'
+/// option for the current buffer. The first line returns 0. UTF-8 encoding is
+/// used, 'fileencoding' is ignored. Sending in the index just below the last
+/// line gives the total byte count for the entire file. A final newline is
+/// included if it would be written, see 'eol'.
+///
+/// Unlike |line2byte()|, throws error for out-of-bounds indexing.
+/// Returns -1 for unloaded buffer.
+///
+/// @param buffer     Buffer handle
+/// @param index      Line index
+/// @param[out] err   Error details, if any
+/// @return Integer   Byte offset
+Integer nvim_buf_get_offset_for_line(Buffer buffer, Integer index, Error *err)
+  FUNC_API_SINCE(5)
+{
+  buf_T *buf = find_buffer_by_handle(buffer, err);
+  if (!buf) {
+    return 0;
+  }
+
+  // return sentinel value if the buffer isn't loaded
+  if (buf->b_ml.ml_mfp == NULL) {
+    return -1;
+  }
+
+  if (index < 0 || index > buf->b_ml.ml_line_count) {
+    api_set_error(err, kErrorTypeValidation, "Index out of bounds");
+    return 0;
+  }
+
+  return ml_find_line_or_offset(buf, (int)index+1, NULL);
+}
+
 /// Gets a buffer-scoped (b:) variable.
 ///
 /// @param buffer     Buffer handle

test/functional/api/buffer_spec.lua

@@ -301,6 +301,40 @@ describe('api/buf', function()
     end)
   end)
 
+  describe('get_offset_for_line', function()
+    local get_offset_for_line = curbufmeths.get_offset_for_line
+    it('works', function()
+      curbufmeths.set_lines(0,-1,true,{'Some','exa\000mple', '', 'text'})
+      eq(4, curbufmeths.line_count())
+      eq(0, get_offset_for_line(0))
+      eq(5, get_offset_for_line(1))
+      eq(14, get_offset_for_line(2))
+      eq(15, get_offset_for_line(3))
+      eq(20, get_offset_for_line(4))
+      eq({false,'Index out of bounds'}, meth_pcall(get_offset_for_line, 5))
+      eq({false,'Index out of bounds'}, meth_pcall(get_offset_for_line, -1))
+
+      curbufmeths.set_option('eol', false)
+      curbufmeths.set_option('fixeol', false)
+      eq(19, get_offset_for_line(4))
+
+      curbufmeths.set_option('fileformat', 'dos')
+      eq(0, get_offset_for_line(0))
+      eq(6, get_offset_for_line(1))
+      eq(16, get_offset_for_line(2))
+      eq(18, get_offset_for_line(3))
+      eq(22, get_offset_for_line(4))
+      curbufmeths.set_option('eol', true)
+      eq(24, get_offset_for_line(4))
+
+      command("set hidden")
+      command("enew")
+      eq(6, bufmeths.get_offset_for_line(1,1))
+      command("bunload! 1")
+      eq(-1, bufmeths.get_offset_for_line(1,1))
+    end)
+  end)
+
   describe('{get,set,del}_var', function()
     it('works', function()
       curbuf('set_var', 'lua', {1, 2, {['3'] = 1}})