Update base64_encode length parameter to more sane type references #358

Also adds documentation and cleans up formatting

changelog.md

@@ -10,11 +10,14 @@ HEAD
   std::ostreams. This allows writing logging policies that do not involve the
   use of std::ostream. This does not affect anyone using the built in logging
   policies.
-- BREAKING UTILITY CHANGE: websocketpp::lib::net::htonll and
-  websocketpp::lib::net::ntohll have been prefixed with an underscore to avoid
+- BREAKING UTILITY CHANGE: `websocketpp::lib::net::htonll` and
+  `websocketpp::lib::net::ntohll` have been prefixed with an underscore to avoid
   conflicts with similarly named macros in some operating systems. If you are
   using the WebSocket++ provided 64 bit host/network byte order functions you
   will need to switch to the prefixed versions.
+- BREAKING UTILITY CHANGE: The signature of the `base64_encode` has changed from
+  `websocketpp::base64_encode(unsigned char const *, unsigned int)` to
+  `websocketpp::base64_encode(unsigned char const *, size_t)`.
 - Feature: Adds incomplete `minimal_server` and `minimal_client` configs that
   can be used to build custom configs without pulling in the dependencies of
   `core` or `core_client`. These configs will offer a stable base config to

websocketpp/base64/base64.hpp

@@ -45,6 +45,11 @@ static std::string const base64_chars =
              "abcdefghijklmnopqrstuvwxyz"
              "0123456789+/";
 
+/// Test whether a character is a valid base64 character
+/**
+ * @param c The character to test
+ * @return true if c is a valid base64 character
+ */
 static inline bool is_base64(unsigned char c) {
     return (c == 43 || // +
            (c >= 47 && c <= 57) || // /-9
@@ -52,17 +57,21 @@ static inline bool is_base64(unsigned char c) {
            (c >= 97 && c <= 122)); // a-z
 }
 
-inline std::string base64_encode(unsigned char const * bytes_to_encode, unsigned
-    int in_len)
-{
+/// Encode a char buffer into a base64 string
+/**
+ * @param input The input data
+ * @param len The length of input in bytes
+ * @return A base64 encoded string representing input
+ */
+inline std::string base64_encode(unsigned char const * input, size_t len) {
     std::string ret;
     int i = 0;
     int j = 0;
     unsigned char char_array_3[3];
     unsigned char char_array_4[4];
 
-    while (in_len--) {
-        char_array_3[i++] = *(bytes_to_encode++);
+    while (len--) {
+        char_array_3[i++] = *(input++);
         if (i == 3) {
             char_array_4[0] = (char_array_3[0] & 0xfc) >> 2;
             char_array_4[1] = ((char_array_3[0] & 0x03) << 4) +
@@ -97,25 +106,38 @@ inline std::string base64_encode(unsigned char const * bytes_to_encode, unsigned
         while((i++ < 3)) {
             ret += '=';
         }
-  }
+    }
 
-  return ret;
+    return ret;
 }
 
-inline std::string base64_encode(std::string const & data) {
-    return base64_encode(reinterpret_cast<const unsigned char *>(data.data()),data.size());
+/// Encode a string into a base64 string
+/**
+ * @param input The input data
+ * @return A base64 encoded string representing input
+ */
+inline std::string base64_encode(std::string const & input) {
+    return base64_encode(
+        reinterpret_cast<const unsigned char *>(input.data()),
+        input.size()
+    );
 }
 
-inline std::string base64_decode(std::string const & encoded_string) {
-    size_t in_len = encoded_string.size();
+/// Decode a base64 encoded string into a string of raw bytes
+/**
+ * @param input The base64 encoded input data
+ * @return A string representing the decoded raw bytes
+ */
+inline std::string base64_decode(std::string const & input) {
+    size_t in_len = input.size();
     int i = 0;
     int j = 0;
     int in_ = 0;
     unsigned char char_array_4[4], char_array_3[3];
     std::string ret;
 
-    while (in_len-- && ( encoded_string[in_] != '=') && is_base64(encoded_string[in_])) {
-        char_array_4[i++] = encoded_string[in_]; in_++;
+    while (in_len-- && ( input[in_] != '=') && is_base64(input[in_])) {
+        char_array_4[i++] = input[in_]; in_++;
         if (i ==4) {
             for (i = 0; i <4; i++) {
                 char_array_4[i] = static_cast<unsigned char>(base64_chars.find(char_array_4[i]));