sponsor Vim development Vim logo Vim Book Ad

multvals.vim : Array library that uses patterns as separators

 script karma  Rating 102/38, Downloaded by 24500  Comments, bugs, improvements  Vim wiki

created by
Hari Krishna Dara
script type
The new version requires Vim 6.3.

This is an array library useful for script developers.

I started off from the lightWeightArray.vim script as a basis and created this
more complete script to call it an array. You can now manipulate the Vim's
multi-valued variables or create your own using this script. This makes it easy
for you to support variables having multiple values and familiar for the users
of your script.

See file header for function prototypes.

- An array is nothing but a string of multiple values separated by a
  pattern.  The simplest example being Vim's multi-value variables such as
  tags. You can use the MvAddElement() function to create an array.
  However, there is nothing special about this function, you can as well
  make up the string by simply concatinating elements with the chosen
  pattern as a separator.
- The separator can be any regular expression (which means that if you
  want to use regex metacharacters in a non-regex pattern, then you need
  to protect the metacharacters with backslashes). However, if a regular
  expression is used as a separtor, you need to pass in a second separator,
  which is a plain string that guarantees to match the separator regular
  expression, as an additional argument (which was not the case with
  earlier versions). When the array needs to be modified (which is
  internally done by some of the reader functions also) this sample
  separator is used to preserve the integrity of the array.
- If you for example want to go over the words in a sentence, then an easy
  way would be to treat the sentence as an array with '\s\+' as a
  separator pattern. Be sure not to have zero-width expressions in the
  pattern as these would otherwise confuse the plugin.
- Suggested usage to go over the elements is to use the iterater functions
  as shows in the below example
  Ex Usage:
    " The below pattern avoids protected comma's from getting treated as
    "   separators.
    call MvIterCreate(&tags, '\\\@<!\(\\\\\)*\zs,', 'Tags', ',')
    while MvIterHasNext('Tags')
      call input('Next element: ' . MvIterNext('Tags'))
    call MvIterDestroy('Tags')
All element-indexes start from 0 (like in C++ or Java).
All string-indexes start from 0 (as it is for Vim built-in functions).

Please let me know of any bugs and problems that you face.

Search_key_words: array arrays multvals sort multiple values multivals Hari Krishna Dara
install details
Source it from your .vimrc or just drop it in your plugin directory.
Since version 2.1.1, you require Vim 6.0, for older versions you require Vim 5.6.

Sort functionality from version 2.4 requires genutils.vim: vimscript #197

rate this script Life Changing Helpful Unfulfilling 
script versions (upload new version)

Click on the package to download.

package script version date Vim version user release notes
multvals.vim 3.10 2004-10-28 6.0 Hari Krishna Dara - New MvBISortElements() that uses the faster BinInsertSort2() function
  from genutils.vim plugin.
multvals.vim 3.9 2004-10-20 6.0 Hari Krishna Dara - MvIterPeek made public. This was left private by accident.
multvals.vim 3.8 2004-09-24 6.0 Hari Krishna Dara Fixed bugs in the *StrIndex* functions, such that when the element is
not found, they always return the contracted -1 (instead of any -ve
value). This will fix problems with a number of other functions that
depend on them (such as MvPushToFront reported by Thomas Link).
multvals.vim 3.6 2004-06-18 6.0 Hari Krishna Dara Maintenance release.
- Work-around for a bug in MvNumberOfElements().
- New utility function MvCrUnProtectedCharsPattern()
multvals.vim 3.5 2004-03-22 6.0 Hari Krishna Dara CAUTION: This version potentially introduces an incompatibility with that of
older versions because of the below change. If your plugin depended on this
undocumented behavior you will have to update your plugin immediately to work
with the new plugin. Even if you didn't know about behavior, it is still better
to check if your plugin accidentally depended on this. If you need further
clarifications, please email me with your questions and I will try to answer.

- Now the plugin ignores the 'ignorecase' and 'smartcase' settings, so the
  results are more consistent. This I think is the right thing to do for a
- Also added a new function MvIterPeek.
multvals.vim 3.4 2003-12-17 6.0 Hari Krishna Dara - The plugin was not working correctly when there are *'s in the array.
- New function MvRemovePatternAll
- g:loaded_multvals now contains the version number for dependency cheking.
  (see ":help v:version" for format)
- Added prototypes for the functions in the header as per the suggestion
  of Naveen Chandra.
multvals.vim 3.3 2003-08-25 6.0 Hari Krishna Dara Minor changes, added a new function MvElementLike and improved MvPromptForElement by adding a new companion function MvGetSelectedIndex, to be used when the array can contain empty elements.
multvals.vim 3.2 2003-06-11 6.0 Hari Krishna Dara New function MvNumSearchNext. See the function header for details.
multvals.vim 3.1 2003-03-28 6.0 Hari Krishna Dara Minor changes. Now the MvCreateIter() also accepts sample separator as the last argument when a regular expression is used as a separator. This is consistent with the rest of the functions and makes it easy to iterate over settings like 'tags'.

call MvIterCreate(&tags, "\\\@<!\(\\\\\)*\zs,", "Tags", ',')

multvals.vim 3.0 2002-12-26 6.0 Hari Krishna Dara - All functions can now be used with regular expressions as separators. Most of the functions now accept an optional extra argument as the last argument, which needs to be a plain separator as a sample that matches the regular expression of the separator. If the separator is not a regular expressions, this can be ignored, making it backwardly compatible change.
- Added new functions MvRemovePattern, MvStrIndexOfPattern, MvStrIndexAfterPattern, MvIndexOfPattern, MvContainsPattern.
- Fixed a bug in the new implementation of MvPromptForElement. This function now accepts only element index as selection. This makes it cleaner to implement and also makes it possible to have even numbers as values in the array.
multvals.vim 2.5 2002-12-05 6.0 Hari Krishna Dara Just removed some debug echomsg which I forgot to remove. Sorry about it. I also added some more information on how to use MvQSortElements() method.
multvals.vim 2.4 2002-11-26 6.0 Hari Krishna Dara - New functions MvQSortElements() and MvSwapElementsAt(). Requires genutils.vim
  for sorting support.
- Worked-around a bug in vim that effects MvElementAt() for last element in a
  large array.
- A variant of MvPromptForElement to specify the number of columns that you
  want the elements to be formatted in. The formatting is very nice now.
multvals.vim 2.3 2002-06-21 6.0 Hari Krishna Dara GPL'ed it mainly for the use by Creme project (http://cream.sf.net). Added MvRemoveElementAll and MvReplaceElementAt, contributed by Steve Hall <digitect at mindspring.com>
multvals.vim 2.1.2 2002-02-25 6.0 Hari Krishna Dara More robust iterator, now checks for maximum count. Reimplemented it to use the ElementAt() function and removed NextElement and NextIndex() functions that are not needed.
multvals.vim 2.1.1 2002-02-10 6.0 Hari Krishna Dara New functions MvRotateLeftAt() and MvRotateRight() to be used by the PushPop.vim script.
multvals.vim 2.1.1 2002-02-08 6.0 Hari Krishna Dara Enhanced the script to accept any regular expression as a separator pattern, but it works only for read-only operations. Now you can treat the following as an array:


and access a, b, c, d and e as array elements.

Now the element is escaped before using in the matches, so you shouldn't have any problem using any random strings to store in to the array.

Also the script is now made as a plugin, so it works only 6.0
multvals.vim 2.0.5 2002-02-01 6.0 Hari Krishna Dara Fixed bugs in MvStrIndexOfElement(), MvIterHasNext() and MvCmpByPosition(). Now I have been using the script for quite some time and fixed all the bugs that I discovered. It should be quite robust and usable now. I have used the functions from here in selectbuf.vim for implementing MRU listing and also in the remcmd.vim for list selection, so check these scripts for a good usage. Also see the end of the script for test code that gives example usage of the script.
multvals.vim 2.0.4 2002-01-11 6.0 Hari Krishna Dara Lots of new functions are added and they are documented well. Now the script has functions to access the elements by element index, just like a real array. Much more usable as an array than previously it was.

However, it is incompatible with the previous version for the following reasons:
   - Prefixed all the global functions with "Mv" to avoid global name
   - The order of arguments for MvIterCreate has been changed for the sake of

Here is a list of all the functions:
multvals.vim 2.0.2 2002-01-02 5.7 Hari Krishna Dara Initial upload
ip used for rating:

If you have questions or remarks about this site, visit the vimonline development pages. Please use this site responsibly.
Questions about Vim should go to the maillist. Help Bram help Uganda.