vim: runtime/doc/eval.txt comparison

comparison runtime/doc/eval.txt @ 15498:e1de20a47fa9 v8.1.0757

patch 8.1.0757: not enough documentation for Blobs commit https://github.com/vim/vim/commit/d89682477cd01ec60edd6d88093b95b12e180127 Author: Bram Moolenaar <Bram@vim.org> Date: Tue Jan 15 22:51:57 2019 +0100 patch 8.1.0757: not enough documentation for Blobs Problem: Not enough documentation for Blobs. Solution: Add a section about Blobs.

author	Bram Moolenaar <Bram@vim.org>
date	Tue, 15 Jan 2019 23:00:07 +0100
parents	f01eb1aed348
children	f0f06837a699

comparison

equal deleted inserted replaced

-:bf6ba67f1a1c
+:e1de20a47fa9
-*eval.txt*	For Vim version 8.1.  Last change: 2019 Jan 13
+*eval.txt*	For Vim version 8.1.  Last change: 2019 Jan 15
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
 1.  Variables			|variables|
 1.1 Variable types
 1.2 Function references		|Funcref|
 1.3 Lists				|Lists|
 1.4 Dictionaries			|Dictionaries|
-1.5 More about variables		|more-variables|
+1.5 Blobs				|Blobs|
+1.6 More about variables		|more-variables|
 2.  Expression syntax		|expression-syntax|
 3.  Internal variable		|internal-variables|
 4.  Builtin Functions		|functions|
 5.  Defining functions		|user-functions|
 6.  Curly braces names		|curly-braces-names|
 							*E928*
 String		A NUL terminated string of 8-bit unsigned characters (bytes).
 		|expr-string| Examples: "ab\txx\"--"  'x-z''a,c'
-List		An ordered sequence of items |List|.
+List		An ordered sequence of items, see |List| for details.
 		Example: [1, 2, ['a', 'b']]
 Dictionary	An associative, unordered array: Each entry has a key and a
 		value. |Dictionary|
 		Example: {'blue': "#0000ff", 'red': "#ff0000"}
 Job		Used for a job, see |job_start()|. *Job* *Jobs*
 Channel		Used for a channel, see |ch_open()|. *Channel* *Channels*
-Blob		Binary Large Object. Stores any sequence of bytes. *Blob*
+Blob		Binary Large Object. Stores any sequence of bytes.  See |Blob|
+		for details
 		Example: 0zFF00ED015DAF
 		0z is an empty Blob.
 The Number and String types are converted automatically, depending on how they
 are used.
 example, to add up all the numbers in a list: >
 	:exe 'let sum = ' . join(nrlist, '+')
 1.4 Dictionaries ~
-					*dict* *Dictionaries* *Dictionary*
+				*dict* *Dict* *Dictionaries* *Dictionary*
 A Dictionary is an associative array: Each entry has a key and a value.  The
 entry can be located with the key.  The entries are stored without a specific
 ordering.
 	:let xs = count(dict, 'x')	" count nr of times 'x' appears in dict
 	:let s = string(dict)		" String representation of dict
 	:call map(dict, '">> " . v:val')  " prepend ">> " to each item
-1.5 More about variables ~
+1.5 Blobs ~
+						*blob* *Blob* *Blobs* *E978*
+A Blob mostly behaves like a |List| of numbers, where the numbers have an
+8-bit value, from 0 to 255.
+Blob creation ~
+A Blob can be created with a |blob-literal|: >
+	:let b = 0zFF00ED015DAF
+A blob can be read from a file with |readfile()| passing the {type} argument
+set to "B", for example: >
+	:let b = readfile('image.png', 'B')
+A blob can be read from a channel with the |ch_readblob()| function.
+Blob index ~
+							*blob-index* *E979*
+A byte in the Blob can be accessed by putting the index in square brackets
+after the Blob.  Indexes are zero-based, thus the first byte has index zero. >
+	:let myblob = 0z00112233
+	:let byte = myblob[0]		" get the first byte: 0x00
+	:let byte = myblob[2]		" get the third byte: 0x22
+A negative index is counted from the end.  Index -1 refers to the last byte in
+the Blob, -2 to the last but one byte, etc. >
+	:let last = myblob[-1]		" get the last byte: 0x33
+To avoid an error for an invalid index use the |get()| function.  When an item
+is not available it returns -1 or the default value you specify: >
+	:echo get(myblob, idx)
+	:echo get(myblob, idx, 999)
+Blob concatenation ~
+Two blobs can be concatenated with the "+" operator: >
+	:let longblob = myblob + 0z4455
+	:let myblob += 0z6677
+To change a blob in-place see |blob-modification| below.
+Part of a blob ~
+A part of the Blob can be obtained by specifying the first and last index,
+separated by a colon in square brackets: >
+	:let myblob = 0z00112233
+	:let shortblob = myblob[2:-1]	" get 0z2233
+Omitting the first index is similar to zero.  Omitting the last index is
+similar to -1. >
+	:let endblob = myblob[2:]	" from item 2 to the end: 0z2233
+	:let shortblob = myblob[2:2]	" Blob with one byte: 0z22
+	:let otherblob = myblob[:]	" make a copy of the Blob
+If the first index is beyond the last byte of the Blob or the second byte is
+before the first byte, the result is an empty list.  There is no error
+message.
+If the second index is equal to or greater than the length of the list the
+length minus one is used: >
+	:echo myblob[2:8]		" result: 0z2233
+Blob modification ~
+							*blob-modification*
+To change a specific byte of a blob use |:let| this way: >
+	:let blob[4] = 0x44
+When the index is just one beyond the end of the Blob, it is appended. Any
+higher index is an error.
+To change a sequence of bytes the [:] notation can be used: >
+	let blob[1:3] = 0z445566
+The length of the replaced bytes much be exactly the same as the value
+provided. *E972*
+To change part of a blob you can specify the first and last byte to be
+modified.  The value must at least have the number of bytes in the range: >
+	:let blob[3:5] = [3, 4, 5]
+You can also use the functions |add()|, |remove()| and |insert()|.
+Blob identity ~
+Blobs can be compared for equality: >
+	if blob == 0z001122
+And for equal identity: >
+	if blob is otherblob
+<							*blob-identity* *E977*
+When variable "aa" is a Blob and you assign it to another variable "bb", both
+variables refer to the same Blob.  Then the "is" operator returns true.
+When making a copy using [:] or |copy()| the values are the same, but the
+identity is different: >
+	:let blob = 0z112233
+	:let blob2 = blob
+	:echo blob == blob2
+<	1 >
+	:echo blob is blob2
+<	1 >
+	:let blob3 = blob[:]
+	:echo blob == blob3
+<	1 >
+	:echo blob is blob3
+<	0
+Making a copy of a list is done with the |copy()| function.  Using [:] also
+works, as explained above.
+1.6 More about variables ~
 							*more-variables*
 If you need to know the type of a variable or expression, use the |type()|
 function.
 When the '!' flag is included in the 'viminfo' option, global variables that
 of 'encoding'.
 Note that "\000" and "\x00" force the end of the string.
-blob-literal				*blob-literal* *E973* *E977* *E978*
+blob-literal				*blob-literal* *E973*
 ------------
 Hexadecimal starting with 0z or 0Z, with an arbitrary number of bytes.
 The sequence must be an even number of hex characters.  Example: >
 	:let b = 0zFF00ED015DAF
 USAGE				RESULT	DESCRIPTION	~
 abs({expr})			Float or Number  absolute value of {expr}
 acos({expr})			Float	arc cosine of {expr}
-add({list}, {item})		List	append {item} to |List| {list}
+add({object}, {item})		List/Blob   append {item} to {object}
 and({expr}, {expr})		Number	bitwise AND
 append({lnum}, {text})		Number	append {text} below line {lnum}
 appendbufline({expr}, {lnum}, {text})
 				Number	append {text} below line {lnum}
 					in buffer {expr}
 			:echo acos(-0.5)
 <			2.094395
 		{only available when compiled with the |+float| feature}
-add({list}, {expr})					*add()*
+add({object}, {expr})					*add()*
-		Append the item {expr} to |List| {list}.  Returns the
+		Append the item {expr} to |List| or |Blob| {object}.  Returns
-		resulting |List|.  Examples: >
+		the resulting |List| or |Blob|.  Examples: >
 			:let alist = add([1, 2, 3], item)
 			:call add(mylist, "woodstock")
 <		Note that when {expr} is a |List| it is appended as a single
 		item.  Use |extend()| to concatenate |Lists|.
+		When {object} is a |Blob| then  {expr} must be a number.
 		Use |insert()| to add an item at another position.
 and({expr}, {expr})					*and()*
 		Bitwise AND on the two arguments.  The arguments are converted
 empty({expr})						*empty()*
 		Return the Number 1 if {expr} is empty, zero otherwise.
 		- A |List| or |Dictionary| is empty when it does not have any
 		  items.
-		- A String is empty when its length is zero.
+		- A |String| is empty when its length is zero.
-		- A Number and Float is empty when its value is zero.
+		- A |Number| and |Float| are empty when their value is zero.
 		- |v:false|, |v:none| and |v:null| are empty, |v:true| is not.
-		- A Job is empty when it failed to start.
+		- A |Job| is empty when it failed to start.
-		- A Channel is empty when it is closed.
+		- A |Channel| is empty when it is closed.
+		- A Blob is empty when its length is zero.
 		For a long |List| this is much faster than comparing the
 		length with zero.
 escape({string}, {chars})				*escape()*
 		|test_garbagecollect_now()|.
 get({list}, {idx} [, {default}])			*get()*
 		Get item {idx} from |List| {list}.  When this item is not
 		available return {default}.  Return zero when {default} is
+		omitted.
+get({blob}, {idx} [, {default}])
+		Get byte {idx} from |Blob| {blob}.  When this byte is not
+		available return {default}.  Return -1 when {default} is
 		omitted.
 get({dict}, {key} [, {default}])
 		Get item with key {key} from |Dictionary| {dict}.  When this
 		item is not available return {default}.  Return zero when
 		{default} is omitted.

Mercurial > vim

comparison runtime/doc/eval.txt @ 15498:e1de20a47fa9 v8.1.0757