Functions
buffer.c File Reference
#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>
#include <limits.h>
#include "nvim/api/buffer.h"
#include "nvim/api/private/helpers.h"
#include "nvim/api/private/defs.h"
#include "nvim/vim.h"
#include "nvim/buffer.h"
#include "nvim/charset.h"
#include "nvim/cursor.h"
#include "nvim/memline.h"
#include "nvim/memory.h"
#include "nvim/misc1.h"
#include "nvim/ex_cmds.h"
#include "nvim/mark.h"
#include "nvim/fileio.h"
#include "nvim/move.h"
#include "nvim/syntax.h"
#include "nvim/window.h"
#include "nvim/undo.h"
#include "nvim/ex_docmd.h"
#include "nvim/buffer_updates.h"

Functions

Integer nvim_buf_line_count (Buffer buffer, Error *err) FUNC_API_SINCE(1)
 
String buffer_get_line (Buffer buffer, Integer index, Error *err)
 
Boolean nvim_buf_attach (uint64_t channel_id, Buffer buffer, Boolean send_buffer, Dictionary opts, Error *err) FUNC_API_SINCE(4) FUNC_API_REMOTE_ONLY
 
Boolean nvim_buf_detach (uint64_t channel_id, Buffer buffer, Error *err) FUNC_API_SINCE(4) FUNC_API_REMOTE_ONLY
 
void buffer_set_line (Buffer buffer, Integer index, String line, Error *err)
 
void buffer_del_line (Buffer buffer, Integer index, Error *err)
 
 ArrayOf (String)
 
void buffer_set_line_slice (Buffer buffer, Integer start, Integer end, Boolean include_start, Boolean include_end, ArrayOf(String) replacement, Error *err)
 
void nvim_buf_set_lines (uint64_t channel_id, Buffer buffer, Integer start, Integer end, Boolean strict_indexing, ArrayOf(String) replacement, Error *err) FUNC_API_SINCE(1)
 
Integer nvim_buf_get_offset (Buffer buffer, Integer index, Error *err) FUNC_API_SINCE(5)
 
Object nvim_buf_get_var (Buffer buffer, String name, Error *err) FUNC_API_SINCE(1)
 
Integer nvim_buf_get_changedtick (Buffer buffer, Error *err) FUNC_API_SINCE(2)
 
 ArrayOf (Dictionary)
 
Dictionary nvim_buf_get_commands (Buffer buffer, Dictionary opts, Error *err) FUNC_API_SINCE(4)
 
void nvim_buf_set_var (Buffer buffer, String name, Object value, Error *err) FUNC_API_SINCE(1)
 
void nvim_buf_del_var (Buffer buffer, String name, Error *err) FUNC_API_SINCE(1)
 
Object buffer_set_var (Buffer buffer, String name, Object value, Error *err)
 
Object buffer_del_var (Buffer buffer, String name, Error *err)
 
Object nvim_buf_get_option (Buffer buffer, String name, Error *err) FUNC_API_SINCE(1)
 
void nvim_buf_set_option (uint64_t channel_id, Buffer buffer, String name, Object value, Error *err) FUNC_API_SINCE(1)
 
Integer nvim_buf_get_number (Buffer buffer, Error *err) FUNC_API_DEPRECATED_SINCE(2)
 
String nvim_buf_get_name (Buffer buffer, Error *err) FUNC_API_SINCE(1)
 
void nvim_buf_set_name (Buffer buffer, String name, Error *err) FUNC_API_SINCE(1)
 
Boolean nvim_buf_is_loaded (Buffer buffer) FUNC_API_SINCE(5)
 
Boolean nvim_buf_is_valid (Buffer buffer) FUNC_API_SINCE(1)
 
void buffer_insert (Buffer buffer, Integer lnum, ArrayOf(String) lines, Error *err)
 
 ArrayOf (Integer, 2)
 
Integer nvim_buf_add_highlight (Buffer buffer, Integer ns_id, String hl_group, Integer line, Integer col_start, Integer col_end, Error *err) FUNC_API_SINCE(1)
 
void nvim_buf_clear_namespace (Buffer buffer, Integer ns_id, Integer line_start, Integer line_end, Error *err) FUNC_API_SINCE(5)
 
void nvim_buf_clear_highlight (Buffer buffer, Integer ns_id, Integer line_start, Integer line_end, Error *err) FUNC_API_SINCE(1)
 
Integer nvim_buf_set_virtual_text (Buffer buffer, Integer ns_id, Integer line, Array chunks, Dictionary opts, Error *err) FUNC_API_SINCE(5)
 

Function Documentation

ArrayOf ( String  )

Retrieves a line range from the buffer

Deprecated:
use nvim_buf_get_lines(buffer, newstart, newend, false) where newstart = start + int(not include_start) - int(start < 0) newend = end + int(include_end) - int(end < 0) int(bool) = 1 if bool is true else 0
Parameters
bufferBuffer handle
startFirst line index
endLast line index
include_startTrue if the slice includes the start parameter
include_endTrue if the slice includes the end parameter
[out]errError details, if any
Returns
Array of lines

Gets a line-range from the buffer.

Indexing is zero-based, end-exclusive. Negative indices are interpreted as length+1+index: -1 refers to the index past the end. So to get the last element use start=-2 and end=-1.

Out-of-bounds indices are clamped to the nearest valid value, unless strict_indexing is set.

Parameters
bufferBuffer handle
startFirst line index
endLast line index (exclusive)
strict_indexingWhether out-of-bounds should be an error.
[out]errError details, if any
Returns
Array of lines, or empty array for unloaded buffer.
ArrayOf ( Dictionary  )

Gets a list of buffer-local |mapping| definitions.

Parameters
modeMode short-name ("n", "i", "v", ...)
bufferBuffer handle
[out]errError details, if any
Returns
Array of maparg()-like dictionaries describing mappings. The "buffer" key holds the associated buffer handle.
ArrayOf ( Integer  ,
 
)

Return a tuple (row,col) representing the position of the named mark

Parameters
bufferBuffer handle
nameMark name
[out]errError details, if any
Returns
(row, col) tuple

Gets the window position in display cells. First position is zero.

Parameters
windowWindow handle
[out]errError details, if any
Returns
(row, col) tuple with the window position
void buffer_del_line ( Buffer  buffer,
Integer  index,
Error err 
)

Deletes a buffer line

Deprecated:
use nvim_buf_set_lines instead. for positive indices use "nvim_buf_set_lines(buffer, index, index+1, true, [])" for negative indices use "nvim_buf_set_lines(buffer, index-1, index, true, [])"
Parameters
bufferbuffer handle
indexline index
[out]errError details, if any
Object buffer_del_var ( Buffer  buffer,
String  name,
Error err 
)

Removes a buffer-scoped (b:) variable

Deprecated:
Parameters
bufferBuffer handle
nameVariable name
[out]errError details, if any
Returns
Old value
String buffer_get_line ( Buffer  buffer,
Integer  index,
Error err 
)

Gets a buffer line

Deprecated:
use nvim_buf_get_lines instead. for positive indices (including 0) use "nvim_buf_get_lines(buffer, index, index+1, true)" for negative indices use "nvim_buf_get_lines(buffer, index-1, index, true)"
Parameters
bufferBuffer handle
indexLine index
[out]errError details, if any
Returns
Line string
void buffer_insert ( Buffer  buffer,
Integer  lnum,
ArrayOf(String lines,
Error err 
)

Inserts a sequence of lines to a buffer at a certain index

Deprecated:
use nvim_buf_set_lines(buffer, lnum, lnum, true, lines)
Parameters
bufferBuffer handle
lnumInsert the lines after lnum. If negative, appends to the end of the buffer.
linesArray of lines
[out]errError details, if any
void buffer_set_line ( Buffer  buffer,
Integer  index,
String  line,
Error err 
)

Sets a buffer line

Deprecated:
use nvim_buf_set_lines instead. for positive indices use "nvim_buf_set_lines(buffer, index, index+1, true, [line])" for negative indices use "nvim_buf_set_lines(buffer, index-1, index, true, [line])"
Parameters
bufferBuffer handle
indexLine index
lineContents of the new line
[out]errError details, if any
void buffer_set_line_slice ( Buffer  buffer,
Integer  start,
Integer  end,
Boolean  include_start,
Boolean  include_end,
ArrayOf(String replacement,
Error err 
)

Replaces a line range on the buffer

Deprecated:
use nvim_buf_set_lines(buffer, newstart, newend, false, lines) where newstart = start + int(not include_start) + int(start < 0) newend = end + int(include_end) + int(end < 0) int(bool) = 1 if bool is true else 0
Parameters
bufferBuffer handle
startFirst line index
endLast line index
include_startTrue if the slice includes the start parameter
include_endTrue if the slice includes the end parameter
replacementArray of lines to use as replacement (0-length
[out]errError details, if any
Object buffer_set_var ( Buffer  buffer,
String  name,
Object  value,
Error err 
)

Sets a buffer-scoped (b:) variable

Deprecated:
Parameters
bufferBuffer handle
nameVariable name
valueVariable value
[out]errError details, if any
Returns
Old value or nil if there was no previous value.
    @warning It may return nil if there was no previous value
             or if previous value was `v:null`.  
Integer nvim_buf_add_highlight ( Buffer  buffer,
Integer  ns_id,
String  hl_group,
Integer  line,
Integer  col_start,
Integer  col_end,
Error err 
)

Adds a highlight to buffer.

Useful for plugins that dynamically generate highlights to a buffer (like a semantic highlighter or linter). The function adds a single highlight to a buffer. Unlike |matchaddpos()| highlights follow changes to line numbering (as lines are inserted/removed above the highlighted line), like signs and marks do.

Namespaces are used for batch deletion/updating of a set of highlights. To create a namespace, use |nvim_create_namespace| which returns a namespace id. Pass it in to this function as ns_id to add highlights to the namespace. All highlights in the same namespace can then be cleared with single call to |nvim_buf_clear_namespace|. If the highlight never will be deleted by an API call, pass ns_id = -1.

As a shorthand, ns_id = 0 can be used to create a new namespace for the highlight, the allocated id is then returned. If hl_group is the empty string no highlight is added, but a new ns_id is still returned. This is supported for backwards compatibility, new code should use |nvim_create_namespace| to create a new empty namespace.

Parameters
bufferBuffer handle
ns_idnamespace to use or -1 for ungrouped highlight
hl_groupName of the highlight group to use
lineLine to highlight (zero-indexed)
col_startStart of (byte-indexed) column range to highlight
col_endEnd of (byte-indexed) column range to highlight, or -1 to highlight to end of line
[out]errError details, if any
Returns
The ns_id that was used
Boolean nvim_buf_attach ( uint64_t  channel_id,
Buffer  buffer,
Boolean  send_buffer,
Dictionary  opts,
Error err 
)

Activate updates from this buffer to the current channel.

Parameters
bufferThe buffer handle
send_bufferSet to true if the initial notification should contain the whole buffer. If so, the first notification will be a nvim_buf_lines_event. Otherwise, the first notification will be a nvim_buf_changedtick_event
optsOptional parameters. Currently not used.
[out]errDetails of an error that may have occurred
Returns
False when updates couldn't be enabled because the buffer isn't loaded or opts contained an invalid key; otherwise True.
void nvim_buf_clear_highlight ( Buffer  buffer,
Integer  ns_id,
Integer  line_start,
Integer  line_end,
Error err 
)

Clears highlights and virtual text from namespace and range of lines

Deprecated:
use |nvim_buf_clear_namespace|.
Parameters
bufferBuffer handle
ns_idNamespace to clear, or -1 to clear all.
line_startStart of range of lines to clear
line_endEnd of range of lines to clear (exclusive) or -1 to clear to end of file.
[out]errError details, if any
void nvim_buf_clear_namespace ( Buffer  buffer,
Integer  ns_id,
Integer  line_start,
Integer  line_end,
Error err 
)

Clears namespaced objects, highlights and virtual text, from a line range

To clear the namespace in the entire buffer, pass in 0 and -1 to line_start and line_end respectively.

Parameters
bufferBuffer handle
ns_idNamespace to clear, or -1 to clear all namespaces.
line_startStart of range of lines to clear
line_endEnd of range of lines to clear (exclusive) or -1 to clear to end of buffer.
[out]errError details, if any
void nvim_buf_del_var ( Buffer  buffer,
String  name,
Error err 
)

Removes a buffer-scoped (b:) variable

Parameters
bufferBuffer handle
nameVariable name
[out]errError details, if any
Boolean nvim_buf_detach ( uint64_t  channel_id,
Buffer  buffer,
Error err 
)

Deactivate updates from this buffer to the current channel.

Parameters
bufferThe buffer handle
[out]errDetails of an error that may have occurred
Returns
False when updates couldn't be disabled because the buffer isn't loaded; otherwise True.
Integer nvim_buf_get_changedtick ( Buffer  buffer,
Error err 
)

Gets a changed tick of a buffer

Parameters
[in]bufferBuffer handle.
[out]errError details, if any
Returns
b:changedtick value.
Dictionary nvim_buf_get_commands ( Buffer  buffer,
Dictionary  opts,
Error err 
)

Gets a map of buffer-local |user-commands|.

Parameters
bufferBuffer handle.
optsOptional parameters. Currently not used.
[out]errError details, if any.
Returns
Map of maps describing commands.
String nvim_buf_get_name ( Buffer  buffer,
Error err 
)

Gets the full file name for the buffer

Parameters
bufferBuffer handle
[out]errError details, if any
Returns
Buffer name
Integer nvim_buf_get_number ( Buffer  buffer,
Error err 
)

Gets the buffer number

Deprecated:
The buffer number now is equal to the object id, so there is no need to use this function.
Parameters
bufferBuffer handle
[out]errError details, if any
Returns
Buffer number
Integer nvim_buf_get_offset ( Buffer  buffer,
Integer  index,
Error err 
)

Returns the byte offset for a line.

Line 1 (index=0) has offset 0. UTF-8 bytes are counted. EOL is one byte. 'fileformat' and 'fileencoding' are ignored. The line index just after the last line gives the total byte-count of the buffer. A final EOL byte is counted if it would be written, see 'eol'.

Unlike |line2byte()|, throws error for out-of-bounds indexing. Returns -1 for unloaded buffer.

Parameters
bufferBuffer handle
indexLine index
[out]errError details, if any
Returns
Integer byte offset, or -1 for unloaded buffer.
Object nvim_buf_get_option ( Buffer  buffer,
String  name,
Error err 
)

Gets a buffer option value

Parameters
bufferBuffer handle
nameOption name
[out]errError details, if any
Returns
Option value
Object nvim_buf_get_var ( Buffer  buffer,
String  name,
Error err 
)

Gets a buffer-scoped (b:) variable.

Parameters
bufferBuffer handle
nameVariable name
[out]errError details, if any
Returns
Variable value
Boolean nvim_buf_is_loaded ( Buffer  buffer)

Checks if a buffer is valid and loaded. See |api-buffer| for more info about unloaded buffers.

Parameters
bufferBuffer handle
Returns
true if the buffer is valid and loaded, false otherwise.
Boolean nvim_buf_is_valid ( Buffer  buffer)

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.
Parameters
bufferBuffer handle
Returns
true if the buffer is valid, false otherwise.
Integer nvim_buf_line_count ( Buffer  buffer,
Error err 
)

Gets the buffer line count

Parameters
bufferBuffer handle
[out]errError details, if any
Returns
Line count, or 0 for unloaded buffer. |api-buffer|
void nvim_buf_set_lines ( uint64_t  channel_id,
Buffer  buffer,
Integer  start,
Integer  end,
Boolean  strict_indexing,
ArrayOf(String replacement,
Error err 
)

Sets (replaces) a line-range in the buffer.

Indexing is zero-based, end-exclusive. Negative indices are interpreted as length+1+index: -1 refers to the index past the end. So to change or delete the last element use start=-2 and end=-1.

To insert lines at a given index, set start and end to the same index. To delete a range of lines, set replacement to an empty array.

Out-of-bounds indices are clamped to the nearest valid value, unless strict_indexing is set.

Parameters
bufferBuffer handle
startFirst line index
endLast line index (exclusive)
strict_indexingWhether out-of-bounds should be an error.
replacementArray of lines to use as replacement
[out]errError details, if any
void nvim_buf_set_name ( Buffer  buffer,
String  name,
Error err 
)

Sets the full file name for a buffer

Parameters
bufferBuffer handle
nameBuffer name
[out]errError details, if any
void nvim_buf_set_option ( uint64_t  channel_id,
Buffer  buffer,
String  name,
Object  value,
Error err 
)

Sets a buffer option value. Passing 'nil' as value deletes the option (only works if there's a global fallback)

Parameters
bufferBuffer handle
nameOption name
valueOption value
[out]errError details, if any
void nvim_buf_set_var ( Buffer  buffer,
String  name,
Object  value,
Error err 
)

Sets a buffer-scoped (b:) variable

Parameters
bufferBuffer handle
nameVariable name
valueVariable value
[out]errError details, if any
Integer nvim_buf_set_virtual_text ( Buffer  buffer,
Integer  ns_id,
Integer  line,
Array  chunks,
Dictionary  opts,
Error err 
)

Set the virtual text (annotation) for a buffer line.

By default (and currently the only option) the text will be placed after the buffer text. Virtual text will never cause reflow, rather virtual text will be truncated at the end of the screen line. The virtual text will begin one cell (|lcs-eol| or space) after the ordinary text.

Namespaces are used to support batch deletion/updating of virtual text. To create a namespace, use |nvim_create_namespace|. Virtual text is cleared using |nvim_buf_clear_namespace|. The same ns_id can be used for both virtual text and highlights added by |nvim_buf_add_highlight|, both can then be cleared with a single call to |nvim_buf_clear_namespace|. If the virtual text never will be cleared by an API call, pass ns_id = -1.

As a shorthand, ns_id = 0 can be used to create a new namespace for the virtual text, the allocated id is then returned.

Parameters
bufferBuffer handle
ns_idNamespace to use or 0 to create a namespace, or -1 for a ungrouped annotation
lineLine to annotate with virtual text (zero-indexed)
chunksA list of [text, hl_group] arrays, each representing a text chunk with specified highlight. hl_group element can be omitted for no highlight.
optsOptional parameters. Currently not used.
[out]errError details, if any
Returns
The ns_id that was used