-*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.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|
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
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.
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.
: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.
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.
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})
{only available when compiled with the |+float| feature}
-add({list}, {expr}) *add()*
- Append the item {expr} to |List| {list}. Returns the
- resulting |List|. Examples: >
+add({object}, {expr}) *add()*
+ Append the item {expr} to |List| or |Blob| {object}. Returns
+ 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.
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 Number and Float is empty when its value is zero.
+ - A |String| is empty when its length 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 Channel is empty when it is closed.
+ - A |Job| is empty when it failed to start.
+ - 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.
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
projects / vim / commitdiff