Be more consistent in the documentation and variable declarations for base64 escaping vs unescaping:

* Move table documenting escaping conversions to be next to the internal escaping code that implements it. Mention it from the internal _un_escaping code (which reverses it) too.
* Centralize the two arrays which map from normal chars to escaped chars (k(WebSafe)Base64Chars), and make bidirectional documentation links between them and their reverse (unescaping) maps (kUn(WebSafe)Base64).
* Remove redundant list of escaping/unescaping methods in the public escaping.cc.

PiperOrigin-RevId: 517142667
Change-Id: I627e59a196ef855e5bf61ef7f4b509920e8d7acd

2 files changed, 24 insertions, 0 deletions

diff --git a/absl/strings/internal/escaping.cc b/absl/strings/internal/escaping.cc
index 8bd0890d..56a4cbed 100644
--- a/absl/strings/internal/escaping.cc
+++ b/absl/strings/internal/escaping.cc
@@ -21,9 +21,17 @@ namespace absl {
 ABSL_NAMESPACE_BEGIN
 namespace strings_internal {
 
+// The two strings below provide maps from normal 6-bit characters to their
+// base64-escaped equivalent.
+// For the inverse case, see kUn(WebSafe)Base64 in the external
+// escaping.cc.
 ABSL_CONST_INIT const char kBase64Chars[] =
     "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
 
+ABSL_CONST_INIT const char kWebSafeBase64Chars[] =
+    "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+
+
 size_t CalculateBase64EscapedLenInternal(size_t input_len, bool do_padding) {
   // Base64 encodes three bytes of input at a time. If the input is not
   // divisible by three, we pad as appropriate.
@@ -62,6 +70,21 @@ size_t CalculateBase64EscapedLenInternal(size_t input_len, bool do_padding) {
   return len;
 }
 
+// ----------------------------------------------------------------------
+//   Take the input in groups of 4 characters and turn each
+//   character into a code 0 to 63 thus:
+//           A-Z map to 0 to 25
+//           a-z map to 26 to 51
+//           0-9 map to 52 to 61
+//           +(- for WebSafe) maps to 62
+//           /(_ for WebSafe) maps to 63
+//   There will be four numbers, all less than 64 which can be represented
+//   by a 6 digit binary number (aaaaaa, bbbbbb, cccccc, dddddd respectively).
+//   Arrange the 6 digit binary numbers into three bytes as such:
+//   aaaaaabb bbbbcccc ccdddddd
+//   Equals signs (one or two) are used at the end of the encoded block to
+//   indicate that the text was not an integer multiple of three bytes long.
+// ----------------------------------------------------------------------
 size_t Base64EscapeInternal(const unsigned char* src, size_t szsrc, char* dest,
                             size_t szdest, const char* base64,
                             bool do_padding) {
diff --git a/absl/strings/internal/escaping.h b/absl/strings/internal/escaping.h
index b04033ff..2186f778 100644
--- a/absl/strings/internal/escaping.h
+++ b/absl/strings/internal/escaping.h
@@ -24,6 +24,7 @@ ABSL_NAMESPACE_BEGIN
 namespace strings_internal {
 
 ABSL_CONST_INIT extern const char kBase64Chars[];
+ABSL_CONST_INIT extern const char kWebSafeBase64Chars[];
 
 // Calculates the length of a Base64 encoding (RFC 4648) of a string of length
 // `input_len`, with or without padding per `do_padding`. Note that 'web-safe'