Appending two NotesDocumentCollections

This tip was submitted to the SearchDomino.com tip library by member Michael Adams. Please let others know how useful it is via the rating scale at the end of the tip. Do you have a useful Lotus Notes, Domino, Workplace or WebSphere tip or code snippet to share? Submit it to our monthly tip contest and you could win a prize.

Here is some simple LotusScript to append two NotesDocumentCollections together.

Code: Function AddCollections
(coll1 As NotesDocumentCollection, coll2 As NotesDocumentCollection) 
As NotesDocumentCollection
 Dim doc As NotesDocument
 Dim doc2 As NotesDocument
 Dim found As Boolean
 
 
 If coll1 Is Nothing And coll2 Is Nothing Then
  Exit Function
 Else
  If coll1 Is Nothing Then
   Set AddCollections = coll2
   Exit Function
  Else
   If coll2 Is Nothing Then
    Set AddCollections = coll1
    Exit Function
   End If
  End If
 End If
 
 Set doc = coll2.GetFirstDocument
 While Not doc Is Nothing
  'Need to search the collection to 
see if it already exists there
  Set doc2 = coll1.GetFirstDocument
  If Not doc2 Is Nothing Then
   Found = False
   While Not doc2 Is Nothing
    If doc2.UniversalID = doc.UniversalID Then
     found = True
    End If
    Set doc2 = coll1.GetNextDocument(doc2)
   Wend
   If Not found Then
    'New document to add
    Call coll1.AddDocument(doc)
   Else
    'Document already existed - skip
   End If
  Else
   'coll1 must be an empty collection, so just add the lot.
   Set coll1 = coll2
  End If
  Set doc = coll2.GetNextDocument(doc)
 Wend
 
 Set AddCollections = coll1
End Function

Regarding the tip about adding two notesdocument collections, in the while loop there should be a statement to leave the while-loop as soon as a document has been found. it is purely unnecessary and inefficient to keep looping through the collection while it has already been decided the document should not be added to the collection.

The code snippet states:

While Not doc2 Is Nothing
   If doc2.UniversalID = doc.UniversalID Then
    found = True
   End If
   Set doc2 = coll1.GetNextDocument(doc2)
Wend

The code snippet should state:

While Not doc2 Is Nothing
   If doc2.UniversalID = doc.UniversalID Then
    found = True 
set doc2 = Nothing
   End If
   Set doc2 = coll1.GetNextDocument(doc2)
Wend

******************************************

1. The described method is not very practical: you can use this method only for very small collections. If the first collection contains N documents and the second contains M, the described algorithm needs N*M to perform the task. Just imagine, to append two relatively small collections, N=1000, M=1000, the algorithm will perform 1000000 steps!

2. In some cases the algorithm even won't work. For instance, when col1 and col2 are results of NotesView.GetAllDocumentsByKey from the different views, AddDocument will fail.

3. The internal loop is unnecessary: in case the document is already contained by collection NotesDocumentCollection..AddDocument raises an exception. The code can trap it and continue to the next line.
—Aleksei S.