(Continued from Part 1.This and the other posts in this series is material I’ve written for Programming Windows Store Apps in HTML, CSS, and JavaScript, Second Edition.)

By itself, an iterator only has methods to go through the collection in one direction (IIterable.first returns an IIterator whose only methods are getMany and moveNext). A vector is a more capable variant (IVector derives from IIterable) that adds random-access methods (getAt and indexOf) and methods to modify the collection (append, clear, insertAt, removeAt, removeAtEnd, replaceAll, and setAt). A vector can also report its size. [Footnote: The IObservableVector interface in Windows.Foundations.Collections exists for other languages and is not ever seen in JavaScript.]

Because a vector is a type of iterator, you can also just treat it as a JavaScript array—a vector that you obtain from some WinRT API, that is, will have methods like forEach and splice as you’d expect. The one caveat here is that if you inspect a vector in Visual Studio’s debugger (as when you hover over a variable), you’ll only see its IVector members.

Vectors basically exist to help marshal changes to the collection between the JavaScript environment and WinRT. This is why IIterable is used as arguments to WinRT APIs (the input array is effectively read-only), whereas IVector is used as an output type, either for the return value of a synchronous API or for the results of an asynchronous API. For example, the readLinesAsync methods of the FileIO and PathIO methods in Windows.Storage provide results as a vector.

Within WinRT you’ll most often encounter vectors with a read-write collection property on some object. For example, the Windows.UI.Popups.MessageDialog object has a commands property of type IVector<IUICommand>, which translates into JavaScript simply as an array of UICommand objects. Because the collection can be modified by either the app or the WinRT API, a vector is used to marshal those changes across the boundary.

In quite a number of cases—properties and methods alike—the collection involved is read-only but still needs to support random-access characteristics. For this we have the vector view (IVectorView also derives from IIterable), which doesn’t have the vector’s modification methods. To give a few examples, a vector view of ConnectionProfile objects is what you get back from NetworkInformation.getConnectionProfiles. Similarly, StorageFolder.getFilesAsync provides a vector view of StorageFile objects. The user’s preferred languages in the Windows.System.UserProfile.GlobalizationPreferences object is a vector view of strings. And you can always get a read-only view for any given read-write vector through the latter’s getView method.

Now because a vector is just a more capable iterator, guess what? You can just treat a vector like an array. For example, the Folder enumeration sample uses StorageFolder.getFilesAsync and getItemsAsync to list the contents of in your various media libraries, using forEach to iterate the array that those APIs produce. Using that example, here’s what I meant earlier that Visual Studio only shows the IVector members—the items from getItemsAsync doesn’t show array methods but we can clearly call forEach (circled):

Vector methods

Comments are closed