From 40e2d6b59becc0e252966f81a0583f44459d1451 Mon Sep 17 00:00:00 2001
From: Peter Hodge <peter.hodge84@gmail.com>
Date: Fri, 29 Jun 2018 11:43:37 +1000
Subject: API: buf_get_lines, buf_line_count handle unloaded buffers #7688

---
 src/nvim/api/buffer.c | 10 ++++++++++
 1 file changed, 10 insertions(+)

(limited to 'src')

diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c
index 8ff24b877e..3acebd6df3 100644
--- a/src/nvim/api/buffer.c
+++ b/src/nvim/api/buffer.c
@@ -45,6 +45,11 @@ Integer nvim_buf_line_count(Buffer buffer, Error *err)
     return 0;
   }
 
+  // return sentinel value if the buffer isn't loaded
+  if (buf->b_ml.ml_mfp == NULL) {
+    return 0;
+  }
+
   return buf->b_ml.ml_line_count;
 }
 
@@ -221,6 +226,11 @@ ArrayOf(String) nvim_buf_get_lines(uint64_t channel_id,
     return rv;
   }
 
+  // return sentinel value if the buffer isn't loaded
+  if (buf->b_ml.ml_mfp == NULL) {
+    return rv;
+  }
+
   bool oob = false;
   start = normalize_index(buf, start, &oob);
   end = normalize_index(buf, end, &oob);
-- 
cgit 


From 8ff0872cf75c331680748c23329cc42d4db8fee1 Mon Sep 17 00:00:00 2001
From: Peter Hodge <peter.hodge84@gmail.com>
Date: Fri, 29 Jun 2018 11:44:08 +1000
Subject: API: add nvim_buf_is_loaded() #7688

---
 src/nvim/api/buffer.c | 13 +++++++++++++
 1 file changed, 13 insertions(+)

(limited to 'src')

diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c
index 3acebd6df3..206c32073b 100644
--- a/src/nvim/api/buffer.c
+++ b/src/nvim/api/buffer.c
@@ -755,6 +755,19 @@ void nvim_buf_set_name(Buffer buffer, String name, Error *err)
   }
 }
 
+/// Checks if a buffer is valid and loaded
+///
+/// @param buffer Buffer handle
+/// @return true if the buffer is valid and loaded, false otherwise
+Boolean nvim_buf_is_loaded(Buffer buffer)
+  FUNC_API_SINCE(5)
+{
+  Error stub = ERROR_INIT;
+  buf_T *buf = find_buffer_by_handle(buffer, &stub);
+  api_clear_error(&stub);
+  return buf && buf->b_ml.ml_mfp != NULL;
+}
+
 /// Checks if a buffer is valid
 ///
 /// @param buffer Buffer handle
-- 
cgit 


From 10bb11e8d1a0762bdfe8bd6de7453bd66ed5fc92 Mon Sep 17 00:00:00 2001
From: Peter Hodge <peter.hodge84@gmail.com>
Date: Fri, 29 Jun 2018 08:03:33 +1000
Subject: API: update docs WRT behaviours/methods for unloaded buffers #7688

---
 src/nvim/api/buffer.c | 33 +++++++++++++++++++++++++++------
 1 file changed, 27 insertions(+), 6 deletions(-)

(limited to 'src')

diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c
index 206c32073b..67a4b70c9e 100644
--- a/src/nvim/api/buffer.c
+++ b/src/nvim/api/buffer.c
@@ -31,11 +31,27 @@
 # include "api/buffer.c.generated.h"
 #endif
 
+
+/// \defgroup api-buffer
+///
+/// Unloaded Buffers:~
+///
+/// Buffers may be unloaded by the |:bunload| command or the buffer's
+/// |'bufhidden'| option. When a buffer is unloaded its file contents are freed
+/// from memory and vim cannot operate on the buffer lines until it is reloaded
+/// (usually by opening the buffer again in a new window). API methods such as
+/// |nvim_buf_get_lines()| and |nvim_buf_line_count()| will be affected.
+///
+/// You can use |nvim_buf_is_loaded()| or |nvim_buf_line_count()| to check
+/// whether a buffer is loaded.
+
+
 /// Gets the buffer line count
 ///
 /// @param buffer   Buffer handle
 /// @param[out] err Error details, if any
-/// @return Line count
+/// @return Line count, or \`0` if the buffer has been unloaded (see
+///         |api-buffer|).
 Integer nvim_buf_line_count(Buffer buffer, Error *err)
   FUNC_API_SINCE(1)
 {
@@ -210,7 +226,8 @@ ArrayOf(String) buffer_get_line_slice(Buffer buffer,
 /// @param end              Last line index (exclusive)
 /// @param strict_indexing  Whether out-of-bounds should be an error.
 /// @param[out] err         Error details, if any
-/// @return Array of lines
+/// @return Array of lines. If the buffer has been unloaded then an empty array
+///                         will be returned instead. (See |api-buffer|.)
 ArrayOf(String) nvim_buf_get_lines(uint64_t channel_id,
                                    Buffer buffer,
                                    Integer start,
@@ -755,10 +772,11 @@ void nvim_buf_set_name(Buffer buffer, String name, Error *err)
   }
 }
 
-/// Checks if a buffer is valid and loaded
+/// Checks if a buffer is valid and loaded. See |api-buffer| for more info
+/// about unloaded buffers.
 ///
 /// @param buffer Buffer handle
-/// @return true if the buffer is valid and loaded, false otherwise
+/// @return true if the buffer is valid and loaded, false otherwise.
 Boolean nvim_buf_is_loaded(Buffer buffer)
   FUNC_API_SINCE(5)
 {
@@ -768,10 +786,13 @@ Boolean nvim_buf_is_loaded(Buffer buffer)
   return buf && buf->b_ml.ml_mfp != NULL;
 }
 
-/// Checks if a buffer is valid
+/// Checks if a buffer is valid.
+///
+/// @note Even if a buffer is valid it may have been unloaded. See |api-buffer|
+/// for more info about unloaded buffers.
 ///
 /// @param buffer Buffer handle
-/// @return true if the buffer is valid, false otherwise
+/// @return true if the buffer is valid, false otherwise.
 Boolean nvim_buf_is_valid(Buffer buffer)
   FUNC_API_SINCE(1)
 {
-- 
cgit