From b0845eff0db7d3aa35c3dc1629d250535d704bc8 Mon Sep 17 00:00:00 2001
From: Vincent Richard <vincent@vincent-richard.net>
Date: Fri, 26 Jul 2013 14:47:30 +0200
Subject: Allow messages to be designated either by their number or their UID.

Warning: this is an API-breaking change.
---
 doc/book/net.tex | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

(limited to 'doc/book/net.tex')

diff --git a/doc/book/net.tex b/doc/book/net.tex
index 19a6ccb9..7359c3e3 100644
--- a/doc/book/net.tex
+++ b/doc/book/net.tex
@@ -555,7 +555,9 @@ The following code shows how to list all the messages in a folder, and
 retrieve basic information to show them to the user:
 
 \begin{lstlisting}[caption={Fetching information about multiple messages}]
-std::vector <ref <vmime::net::message> > allMessages = folder->getMessages();
+std::vector <ref <vmime::net::message> > allMessages =
+   folder->getMessages(vmime::net::messageSet::byNumber(1, -1));
+      // -1 is a special value to mean "the number of the last message in the folder"
 
 folder->fetchMessages(allMessages,
    vmime::net::folder::FETCH_FLAGS |
@@ -628,17 +630,17 @@ store.
 \begin{lstlisting}[caption={Deleting messages}]
 vmime::ref <vmime::net::folder> folder = store->getDefaultFolder();
 
-folder->deleteMessage(3);
-folder->deleteMessage(2);
+folder->deleteMessages(vmime::net::messageSet::byNumber(/* from */ 2, /* to */ 3));
 
 // This is equivalent
 std::vector <int> nums;
 nums.push_back(2);
 nums.push_back(3);
-folder->deleteMessages(nums);
+folder->deleteMessages(vmime::net::messageSet::byNumber(nums));
 
-// This is also equivalent
-folder->deleteMessages(/* from */ 2, /* to */ 3);
+// This is also equivalent (but will require 2 roundtrips to server)
+folder->deleteMessages(vmime::net::messageSet::byNumber(2));
+folder->deleteMessages(vmime::net::messageSet::byNumber(2)); // renumbered, 3 becomes 2
 \end{lstlisting}
 
 \subsection{Events} % --------------------------------------------------------
-- 
cgit v1.2.3