From 746ac28f94457f26746f1c54fbd17441d88adaca Mon Sep 17 00:00:00 2001
From: Faisal Salman <f@faisalman.com>
Date: Sun, 19 Feb 2023 16:11:07 +0700
Subject: [PATCH] Readme: update is() & toString() methods explanation

---
 readme.md | 68 +++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 61 insertions(+), 7 deletions(-)

diff --git a/readme.md b/readme.md
index 514e949..cfc05c4 100644
--- a/readme.md
+++ b/readme.md
@@ -163,6 +163,32 @@ Ubuntu, Unix, VectorLinux, Viera, WebOS, Windows [Phone/Mobile], Zenwalk, ...
 #### * is() utility `since@1.1`
 
 ```js
+// Is just a shorthand to check whether one of the specified properties has equal value
+// so that instead of write it using `==` operator like this:
+
+let ua = UAParser();
+let device = ua.device;
+let os = ua.os;
+
+if (device.type == "mobile" && os.name != "iOS") {}
+if (device.type == "smarttv" || device.vendor == "Samsung") {}
+
+// we can also write the comparison above into as follow:
+
+if (device.is("mobile") && !os.is("iOS")) {}
+if (device.is("smarttv") || device.is("Samsung")) {}
+
+/*
+    Properties will be checked in this particular order:
+    * browser : name
+    * cpu : architecture 
+    * device : type, model, vendor
+    * engine : name 
+    * os : name
+*/
+
+// Another examples:
+
 let uap = new UAParser('Mozilla/5.0 (Mobile; Windows Phone 8.1; Android 4.0; ARM; Trident/7.0; Touch; rv:11.0; IEMobile/11.0; NOKIA; Lumia 635) like iPhone OS 7_0_3 Mac OS X AppleWebKit/537 (KHTML, like Gecko) Mobile Safari/537');
 
 uap.getBrowser().name;              // "IEMobile"
@@ -183,20 +209,43 @@ uap.getResult().device.is("Nokia"); // true
 uap.getResult().device.model;       // "Lumia 635"
 
 uap.setUA("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/28.0.1500.95 Safari/537.36");
-uap.getBrowser().is("IEMobile");    // false 
-uap.getBrowser().is("Chrome");      // true
+
+let browser = uap.getBrowser();
+browser.is("IEMobile");             // false 
+browser.is("Chrome");               // true
+
 uap.getResult().browser.is("Edge"); // false
+uap.getResult().os.name             // "Mac OS"
 uap.getResult().os.is("Mac OS");    // true
 uap.getResult().os.version;         // "10.6.8"
-uap.getEngine().is("Blink");        // true
+
+let engine = uap.getEngine();
+engine.is("Blink");                 // true
 ```
 
 #### * toString() utility `since@1.1`
 
 ```js
+// Retrieve full-name values as a string
+
+/*
+    Values will be concatenated following this pattern:
+    * browser : name + version
+    * cpu : architecture 
+    * device : vendor + model
+    * engine : name + version
+    * os : name + version
+*/
+
+// Usage examples
+
 let uap = new UAParser('Mozilla/5.0 (Mobile; Windows Phone 8.1; Android 4.0; ARM; Trident/7.0; Touch; rv:11.0; IEMobile/11.0; NOKIA; Lumia 635) like iPhone OS 7_0_3 Mac OS X AppleWebKit/537 (KHTML, like Gecko) Mobile Safari/537');
 
-uap.getDevice();                    // { vendor: "Nokia", model: "Lumia 635", type: "mobile" }
+uap.getDevice();                    // { 
+                                    //    vendor: "Nokia", 
+                                    //    model: "Lumia 635", 
+                                    //    type: "mobile"
+                                    // }
 uap.getDevice().toString();         // "Nokia Lumia 635"
 
 uap.getResult().os.name;            // "Windows Phone"
@@ -204,10 +253,15 @@ uap.getResult().os.version;         // "8.1"
 uap.getResult().os.toString();      // "Windows Phone 8.1"
 
 uap.setUA("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/28.0.1500.95 Safari/537.36");
-uap.getBrowser().name;              // Chrome 
-uap.getBrowser().version;           // 28.0.1500.95 
-uap.getBrowser().major;             // 28 
+uap.getBrowser().name;              // "Chrome"
+uap.getBrowser().version;           // "28.0.1500.95"
+uap.getBrowser().major;             // "28"
 uap.getBrowser().toString();        // "Chrome 28.0.1500.95"
+
+let engine = uap.getEngine();
+engine.name;                        // "Blink"
+engine.version;                     // "28.0.1500.95"
+engine.toString();                  // "Blink 28.0.1500.95"
 ```
 
 ## Extending Regex