From 4e43ab01f2c905829a521a94d5f3297263e38b80 Mon Sep 17 00:00:00 2001
From: roker <roker@pep-project.org>
Date: Tue, 2 Nov 2021 08:29:38 +0100
Subject: [PATCH] add docu, add tests. next try.....

---
 src/nfc.hh                  | 16 +++++++++++-----
 src/wrapper.hh              | 12 +++++++++++-
 test/unittest_message.cc    | 10 ++++++++++
 test/unittest_stringlist.cc | 16 ++++++++++++++++
 4 files changed, 48 insertions(+), 6 deletions(-)

diff --git a/src/nfc.hh b/src/nfc.hh
index c2c0d94..f83fafb 100644
--- a/src/nfc.hh
+++ b/src/nfc.hh
@@ -13,16 +13,19 @@
 
 namespace pEp {
 
+/// Tri-sate return value of isNFC_quick_check()
 enum class IsNFC
 {
-	No=0,    // contains a character that cannot occur in NFC
-	Maybe=1, // contains a character that is only allowed in certain positions in NFC
-	Yes=2    // contains no invalid or partially valid character
+	No=0,    //!< string contains a character that cannot occur in NFC
+	Maybe=1, //!< string contains a character that is only allowed in certain positions in NFC
+	Yes=2    //!< string contains no invalid or partially valid character
 };
 
 std::ostream& operator<<(std::ostream& o, IsNFC is_nfc);
 
 
+/// Exception class thrown whenever a string is parsed that is not a valid
+/// UTF-8 or UTF-16 sequence.
 class illegal_utf : public std::runtime_error
 {
 public:
@@ -51,8 +54,9 @@ public:
 	static
 	bool is_safe_NFC_start(std::basic_string_view<CharT> s);
 
-	/// returns No or Maybe, if at least one character with NFC_Quickcheck class is "No" or "Maybe"
-	/// might throw illegal_utf exception
+	/// returns No or Maybe, if at least one character with NFC_Quickcheck class is "No" or "Maybe".
+	/// use isNFC() for a comprehensive NFC check.
+	/// Might throw illegal_utf exception
 	static
 	IsNFC isNFC_quick_check(std::basic_string_view<CharT> s);
 
@@ -129,6 +133,7 @@ public:
 		/// read-only: shares representation
 		operator const String&() const noexcept { return s; }
 		
+		/// read-only: shares representation
 		const String& get() const noexcept { return s;}
 		
 		/// read write: copy content
@@ -185,6 +190,7 @@ public:
 			return *this;
 		}
 		
+		/// more expensive, because 's' might not be in NFC.
 		nfc_string& operator+=(StringView s);
 		
 		/// optimization possible to avoid re-normalization in most cases.
diff --git a/src/wrapper.hh b/src/wrapper.hh
index c75c02f..9a8597a 100644
--- a/src/wrapper.hh
+++ b/src/wrapper.hh
@@ -10,6 +10,7 @@
 namespace pEp
 {
 
+/// A generalized wrapper around pEpEngine's datatypes.
 template<class T>
 class Wrapper
 {
@@ -104,13 +105,17 @@ public:
         return value!=b.value;
     }
     
+    // Get read-only access to the value itself
+    // Beware: 'const' is not transitive in C, so the 2nd indirect data
+    // allows r/w access!
     const T* operator->() const { return value; }
     const T* get() const { return value; }
     
-    // dangerous!
+    // Dangerous: Get R/W access to the value!
     T* operator->() { return value; }
     T* get() { return value;}
     
+    // Releases ownership of the value. Wrapper becomes valueless.
     T*  move_out()       { T* r = value; value=nullptr; return r;}
     
     // only implemented for the datatypes where necessay.
@@ -166,6 +171,8 @@ public:
         friend class ListWrapper<T*, Element>;
     };
     
+    typedef const iterator const_iterator;
+    
     
     using Base::value;
     
@@ -176,6 +183,9 @@ public:
     
     iterator begin()     { return iterator{value}; }
     iterator end() const { return iterator{}; }
+    const_iterator cbegin() const { return const_iterator{value}; }
+    const_iterator cend()   const { return const_iterator{}; }
+    
     int  size()    const;
     bool empty()   const;
     
diff --git a/test/unittest_message.cc b/test/unittest_message.cc
index f4c98a1..82d9849 100644
--- a/test/unittest_message.cc
+++ b/test/unittest_message.cc
@@ -110,6 +110,13 @@ namespace
         "--==pEp_01==--\r\n"
         "\r\n";
 
+
+    PEP_STATUS dummy_message(::message* msg)
+    {
+        msg->shortmsg = strdup("Hello World");
+        return PEP_STATUS_OK;
+    }
+
 } // end of anonymous namespace
 
 
@@ -127,4 +134,7 @@ TEST( MessageTest, Simple )
 
     ASSERT_NE(msg->from, nullptr);
     EXPECT_STREQ( msg->from->username, "Alice");
+    
+    EXPECT_EQ( dummy_message(msg.get()), PEP_STATUS_OK);
+    EXPECT_STREQ( msg->shortmsg, "Hello World");
 }
diff --git a/test/unittest_stringlist.cc b/test/unittest_stringlist.cc
index e9898e0..5234d5e 100644
--- a/test/unittest_stringlist.cc
+++ b/test/unittest_stringlist.cc
@@ -21,6 +21,22 @@ TEST( StringList, InitList )
 }
 
 
+TEST( StringList, Algorithm )
+{
+    pEp::StringList sl( {"Alice", "Bob", "Carol", "Dave", "Eve", "Frank", "George", "Harry"} );
+    
+    auto qe = std::find(sl.begin(), sl.end(), std::string("Santa Claus")); // not there!
+    EXPECT_EQ( qe, sl.end() );
+
+//  BEWARE: DOES NOT WORK, because find() uses operator== on char* pointers. :-(
+//  auto q = std::find(sl.begin(), sl.end(), "Eve");
+
+    auto q = std::find(sl.begin(), sl.end(), std::string("Eve"));
+    EXPECT_NE( q, sl.end() );
+    EXPECT_STREQ( *q, "Eve" );
+}
+
+
 TEST( StringList, Dynamic )
 {
     static const unsigned NumberOfElements = 17;