[Emacs-diffs] emacs-25 c8eb45d: Document 'bufferpos-to-filepos' and 'filepos-to-bufferpos'

[Eli Zaretskii]

branch: emacs-25
commit c8eb45da88e05453e78440fedf09a143c832d5a0
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    Document 'bufferpos-to-filepos' and 'filepos-to-bufferpos'
    
    * doc/lispref/nonascii.texi (Text Representations): Document
    'bufferpos-to-filepos' and 'filepos-to-bufferpos'.
---
 doc/lispref/nonascii.texi |   39 +++++++++++++++++++++++++++++++++++++++
 etc/NEWS                  |    3 +++
 2 files changed, 42 insertions(+), 0 deletions(-)

diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi
index 744351e..fca4023 100644
--- a/doc/lispref/nonascii.texi
+++ b/doc/lispref/nonascii.texi
@@ -123,6 +123,45 @@ In other words, the value does not change for all byte 
positions that
 belong to the same character.
 @end defun
 
address@hidden convert file byte to buffer position
address@hidden convert buffer position to file byte
+  The following two functions are useful when a Lisp program needs to
+map buffer positions to byte offsets in a file visited by the buffer.
+
address@hidden bufferpos-to-filepos position &optional quality coding-system
+This function is similar to @code{position-bytes}, but instead of byte
+position in the current buffer it returns the offset from the
+beginning of the current buffer's file of the byte that corresponds to
+the given character @var{position} in the buffer.  The conversion
+requires to know how the text is encoded in the buffer's file; this is
+what the @var{coding-system} argument is for, defaulting to the value
+of @code{buffer-file-coding-system}.  The optional argument
address@hidden specifies how accurate the result should be; it should
+be one of the following:
+
address@hidden @code
address@hidden exact
+The result must be accurate.  The function may need to encode and
+decode a large part of the buffer.
address@hidden approximate
+The value can be an approximation.  The function may avoid expensive
+processing and return an inexact result.
address@hidden nil
+If the exact result needs expensive processing, the function will
+return @code{nil} rather than an approximation.  This is the default
+if the argument is omitted.
address@hidden table
address@hidden defun
+
address@hidden filepos-to-bufferpos byte &optional quality coding-system
+This function returns the buffer position corresponding to a file
+position specified by @var{byte}, a zero-base byte offset from the
+file's beginning.  The function performs the conversion opposite to
+what @code{bufferpos-to-filepos} does.  Optional arguments
address@hidden and @var{coding-system} have the same meaning and values
+as for @code{bufferpos-to-filepos}.
address@hidden defun
+
 @defun multibyte-string-p string
 Return @code{t} if @var{string} is a multibyte string, @code{nil}
 otherwise.  This function also returns @code{nil} if @var{string} is
diff --git a/etc/NEWS b/etc/NEWS
index 5a1adff..88d0604 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1340,7 +1340,10 @@ parsing functions like `forward-sexp'.
 `prefix-command-preserve-state-hook' allow the definition of prefix
 commands other than the predefined `C-u'.
 
++++
 ** New functions `filepos-to-bufferpos' and `bufferpos-to-filepos'.
+These allow to convert between buffer positions and the corresponding
+file byte offsets, given the file's encoding.
 
 ** The default value of `load-read-function' is now `read'.