[Proposal] Clarify (the existence of) the constant empty String

cores/esp8266/AddrList.h

@@ -123,7 +123,7 @@ struct netifWrapper
 
     // common to all addresses of this interface
     String ifname () const          { return String(_netif->name[0]) + _netif->name[1]; }
-    const char* ifhostname () const { return _netif->hostname?: emptyString.c_str(); }
+    const char* ifhostname () const { return _netif->hostname?: String::empty().c_str(); }
     const char* ifmac () const      { return (const char*)_netif->hwaddr; }
     int ifnumber () const           { return _netif->num; }
 

cores/esp8266/WString.h

@@ -70,6 +70,13 @@ class String {
         explicit String(double, unsigned char decimalPlaces = 2);
         ~String(void);
 
+        // empty string singleton
+        // return the reference to the constant empty string.
+        static inline const String &empty() {
+            extern const String emptyString;
+            return emptyString;
+        }
+
         // memory management
         // return true on success, false on failure (in which case, the string
         // is left unchanged).  reserve(0), if successful, will validate an
@@ -294,7 +301,8 @@ class StringSumHelper: public String {
         }
 };
 
-extern const String emptyString;
+// only for backward compatibility
+extern const String emptyString __attribute__((deprecated("Use String::empty() instead.")));
 
 #endif  // __cplusplus
 #endif  // String_class_h

libraries/ESP8266HTTPUpdateServer/src/ESP8266HTTPUpdateServer.cpp

@@ -20,8 +20,8 @@ ESP8266HTTPUpdateServer::ESP8266HTTPUpdateServer(bool serial_debug)
 {
   _serial_output = serial_debug;
   _server = NULL;
-  _username = emptyString;
-  _password = emptyString;
+  _username = String::empty();
+  _password = String::empty();
   _authenticated = false;
 }
 
@@ -33,7 +33,7 @@ void ESP8266HTTPUpdateServer::setup(ESP8266WebServer *server, const String& path
 
     // handler for the /update form page
     _server->on(path.c_str(), HTTP_GET, [&](){
-      if(_username != emptyString && _password != emptyString && !_server->authenticate(_username.c_str(), _password.c_str()))
+      if(_username != String::empty() && _password != String::empty() && !_server->authenticate(_username.c_str(), _password.c_str()))
         return _server->requestAuthentication();
       _server->send_P(200, PSTR("text/html"), serverIndex);
     });
@@ -61,7 +61,7 @@ void ESP8266HTTPUpdateServer::setup(ESP8266WebServer *server, const String& path
         if (_serial_output)
           Serial.setDebugOutput(true);
 
-        _authenticated = (_username == emptyString || _password == emptyString || _server->authenticate(_username.c_str(), _password.c_str()));
+        _authenticated = (_username == String::empty() || _password == String::empty() || _server->authenticate(_username.c_str(), _password.c_str()));
         if(!_authenticated){
           if (_serial_output)
             Serial.printf("Unauthenticated Update\n");

libraries/ESP8266HTTPUpdateServer/src/ESP8266HTTPUpdateServer.h

@@ -10,12 +10,12 @@ class ESP8266HTTPUpdateServer
 
     void setup(ESP8266WebServer *server)
     {
-      setup(server, emptyString, emptyString);
+      setup(server, String::empty(), String::empty());
     }
 
     void setup(ESP8266WebServer *server, const String& path)
     {
-      setup(server, path, emptyString, emptyString);
+      setup(server, path, String::empty(), String::empty());
     }
 
     void setup(ESP8266WebServer *server, const String& username, const String& password)

libraries/ESP8266WebServer/src/ESP8266WebServer.cpp

@@ -108,7 +108,7 @@ void ESP8266WebServer::begin(uint16_t port) {
 String ESP8266WebServer::_extractParam(String& authReq,const String& param,const char delimit) const {
   int _begin = authReq.indexOf(param);
   if (_begin == -1)
-    return emptyString;
+    return String::empty();
   return authReq.substring(_begin+param.length(),authReq.indexOf(delimit,_begin+param.length()));
 }
 
@@ -486,7 +486,7 @@ void ESP8266WebServer::_streamFileCore(const size_t fileSize, const String & fil
       contentType != String(FPSTR(mimeTable[none].mimeType))) {
     sendHeader(F("Content-Encoding"), F("gzip"));
   }
-  send(200, contentType, emptyString);
+  send(200, contentType, String::empty());
 }
 
 
@@ -499,19 +499,19 @@ const String& ESP8266WebServer::arg(String name) const {
     if ( _currentArgs[i].key == name )
       return _currentArgs[i].value;
   }
-  return emptyString;
+  return String::empty();
 }
 
 const String& ESP8266WebServer::arg(int i) const {
   if (i >= 0 && i < _currentArgCount)
     return _currentArgs[i].value;
-  return emptyString;
+  return String::empty();
 }
 
 const String& ESP8266WebServer::argName(int i) const {
   if (i >= 0 && i < _currentArgCount)
     return _currentArgs[i].key;
-  return emptyString;
+  return String::empty();
 }
 
 int ESP8266WebServer::args() const {
@@ -536,7 +536,7 @@ const String& ESP8266WebServer::header(String name) const {
     if (_currentHeaders[i].key.equalsIgnoreCase(name))
       return _currentHeaders[i].value;
   }
-  return emptyString;
+  return String::empty();
 }
 
 void ESP8266WebServer::collectHeaders(const char* headerKeys[], const size_t headerKeysCount) {
@@ -553,13 +553,13 @@ void ESP8266WebServer::collectHeaders(const char* headerKeys[], const size_t hea
 const String& ESP8266WebServer::header(int i) const {
   if (i < _headerKeysCount)
     return _currentHeaders[i].value;
-  return emptyString;
+  return String::empty();
 }
 
 const String& ESP8266WebServer::headerName(int i) const {
   if (i < _headerKeysCount)
     return _currentHeaders[i].key;
-  return emptyString;
+  return String::empty();
 }
 
 int ESP8266WebServer::headers() const {
@@ -619,7 +619,7 @@ void ESP8266WebServer::_handleRequest() {
 
 void ESP8266WebServer::_finalizeResponse() {
   if (_chunked) {
-    sendContent(emptyString);
+    sendContent(String::empty());
   }
 }
 

libraries/ESP8266WiFi/src/ESP8266WiFiAP.h

@@ -37,7 +37,7 @@ class ESP8266WiFiAPClass {
     public:
 
         bool softAP(const char* ssid, const char* passphrase = NULL, int channel = 1, int ssid_hidden = 0, int max_connection = 4);
-        bool softAP(const String& ssid,const String& passphrase = emptyString,int channel = 1,int ssid_hidden = 0,int max_connection = 4);
+        bool softAP(const String& ssid,const String& passphrase = String::empty(),int channel = 1,int ssid_hidden = 0,int max_connection = 4);
         bool softAPConfig(IPAddress local_ip, IPAddress gateway, IPAddress subnet);
         bool softAPdisconnect(bool wifioff = false);
 

libraries/ESP8266WiFi/src/ESP8266WiFiSTA.h

@@ -38,7 +38,7 @@ class ESP8266WiFiSTAClass {
 
         wl_status_t begin(const char* ssid, const char *passphrase = NULL, int32_t channel = 0, const uint8_t* bssid = NULL, bool connect = true);
         wl_status_t begin(char* ssid, char *passphrase = NULL, int32_t channel = 0, const uint8_t* bssid = NULL, bool connect = true);
-        wl_status_t begin(const String& ssid, const String& passphrase = emptyString, int32_t channel = 0, const uint8_t* bssid = NULL, bool connect = true);
+        wl_status_t begin(const String& ssid, const String& passphrase = String::empty(), int32_t channel = 0, const uint8_t* bssid = NULL, bool connect = true);
         wl_status_t begin();
 
         //The argument order for ESP is not the same as for Arduino. However, there is compatibility code under the hood