procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

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

Browse source 
* doc/lispref/nonascii.texi (Text Representations): Document
'bufferpos-to-filepos' and 'filepos-to-bufferpos'.
This commit is contained in:
Eli Zaretskii 2016-01-13 20:11:52 +02:00
parent d3776e9f7c
commit c8eb45da88
2 changed files with 42 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

39
doc/lispref/nonascii.texi
View file

@ -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

3
etc/NEWS
View file

@ -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'.