path: root/data/vim/patches/8.1.0757

To: vim_dev@googlegroups.com
Subject: Patch 8.1.0757
Fcc: outbox
From: Bram Moolenaar <Bram@moolenaar.net>
Mime-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
------------

Patch 8.1.0757
Problem:    Not enough documentation for Blobs.
Solution:   Add a section about Blobs.
Files:	    runtime/doc/eval.txt


*** ../vim-8.1.0756/runtime/doc/eval.txt	2019-01-13 15:15:54.388762907 +0100
--- runtime/doc/eval.txt	2019-01-15 22:48:29.185422882 +0100
***************
*** 17,23 ****
      1.2 Function references		|Funcref|
      1.3 Lists				|Lists|
      1.4 Dictionaries			|Dictionaries|
!     1.5 More about variables		|more-variables|
  2.  Expression syntax		|expression-syntax|
  3.  Internal variable		|internal-variables|
  4.  Builtin Functions		|functions|
--- 17,24 ----
      1.2 Function references		|Funcref|
      1.3 Lists				|Lists|
      1.4 Dictionaries			|Dictionaries|
!     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|
***************
*** 53,59 ****
  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|.
  		Example: [1, 2, ['a', 'b']]
  
  Dictionary	An associative, unordered array: Each entry has a key and a
--- 54,60 ----
  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, see |List| for details.
  		Example: [1, 2, ['a', 'b']]
  
  Dictionary	An associative, unordered array: Each entry has a key and a
***************
*** 72,78 ****
  
  Channel		Used for a channel, see |ch_open()|. *Channel* *Channels*
  
! Blob		Binary Large Object. Stores any sequence of bytes. *Blob*
  		Example: 0zFF00ED015DAF
  		0z is an empty Blob.
  
--- 73,80 ----
  
  Channel		Used for a channel, see |ch_open()|. *Channel* *Channels*
  
! Blob		Binary Large Object. Stores any sequence of bytes.  See |Blob|
! 		for details
  		Example: 0zFF00ED015DAF
  		0z is an empty Blob.
  
***************
*** 621,627 ****
  	:call map(dict, '">> " . v:val')  " prepend ">> " to each item
  
  
! 1.5 More about variables ~
  							*more-variables*
  If you need to know the type of a variable or expression, use the |type()|
  function.
--- 623,744 ----
  	:call map(dict, '">> " . v:val')  " prepend ">> " to each item
  
  
! 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.
***************
*** 1156,1162 ****
  Note that "\000" and "\x00" force the end of the string.
  
  
! blob-literal				*blob-literal* *E973* *E977* *E978*
  ------------
  
  Hexadecimal starting with 0z or 0Z, with an arbitrary number of bytes.
--- 1284,1290 ----
  Note that "\000" and "\x00" force the end of the string.
  
  
! blob-literal				*blob-literal* *E973*
  ------------
  
  Hexadecimal starting with 0z or 0Z, with an arbitrary number of bytes.
***************
*** 2034,2046 ****
  
  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}
  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}
! argc( [{winid}])		Number	number of files in the argument list
  argidx()			Number	current index in the argument list
  arglistid([{winnr} [, {tabnr}]]) Number	argument list id
  argv({nr} [, {winid}])		String	{nr} entry of the argument list
--- 2164,2176 ----
  
  abs({expr})			Float or Number  absolute value of {expr}
  acos({expr})			Float	arc cosine of {expr}
! 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}
! argc([{winid}])			Number	number of files in the argument list
  argidx()			Number	current index in the argument list
  arglistid([{winnr} [, {tabnr}]]) Number	argument list id
  argv({nr} [, {winid}])		String	{nr} entry of the argument list
***************
*** 2598,2610 ****
  		{only available when compiled with the |+float| feature}
  
  
! add({list}, {expr})					*add()*
! 		Append the item {expr} to |List| {list}.  Returns the
! 		resulting |List|.  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|.
  		Use |insert()| to add an item at another position.
  
  
--- 2728,2741 ----
  		{only available when compiled with the |+float| feature}
  
  
! 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.
  
  
***************
*** 3651,3661 ****
  		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.
  		- |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.
  
  		For a long |List| this is much faster than comparing the
  		length with zero.
--- 3783,3794 ----
  		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| 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 Blob is empty when its length is zero.
  
  		For a long |List| this is much faster than comparing the
  		length with zero.
***************
*** 4320,4325 ****
--- 4461,4470 ----
  		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
*** ../vim-8.1.0756/src/version.c	2019-01-15 22:44:14.459222955 +0100
--- src/version.c	2019-01-15 22:49:42.200905658 +0100
***************
*** 797,798 ****
--- 797,800 ----
  {   /* Add new patch number below this line */
+ /**/
+     757,
  /**/

-- 
From the classified section of a city newspaper:
Dog for sale: eats anything and is fond of children.

 /// Bram Moolenaar -- Bram@Moolenaar.net -- http://www.Moolenaar.net   \\\
///        sponsor Vim, vote for features -- http://www.Vim.org/sponsor/ \\\
\\\  an exciting new programming language -- http://www.Zimbu.org        ///
 \\\            help me help AIDS victims -- http://ICCF-Holland.org    ///