Document 'bufferpos-to-filepos' and 'filepos-to-bufferpos'

* doc/lispref/nonascii.texi (Text Representations): Document
'bufferpos-to-filepos' and 'filepos-to-bufferpos'.

2 files changed, 42 insertions, 0 deletions

diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi
index 744351e384e..fca40238805 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
 
+@cindex convert file byte to buffer position
+@cindex 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.
+
+@defun 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
+@var{quality} specifies how accurate the result should be; it should
+be one of the following:
+
+@table @code
+@item exact
+The result must be accurate.  The function may need to encode and
+decode a large part of the buffer.
+@item approximate
+The value can be an approximation.  The function may avoid expensive
+processing and return an inexact result.
+@item 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.
+@end table
+@end defun
+
+@defun 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
+@var{quality} and @var{coding-system} have the same meaning and values
+as for @code{bufferpos-to-filepos}.
+@end 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 5a1adff0920..88d0604cedf 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'.