📝 Update README and example

Author: Komposten

README.md

@@ -6,8 +6,16 @@
 
 public_suffix is a dart library for identifying the public suffixes (or TLDs), root domains and registrable parts of URLs.
 
+## Main features
+- Identify suffix, root domain, registrable domain (root + suffix) and subdomain from URLs.
+- Provide your own list of suffix rules to keep up to date with the rules you need.
+- Get results from matching with only ICANN/IANA rules or also include private ones.
+	- For example, a private rule can see the full `github.io` as suffix while ICANN only recognises the `io` part.
+- Parse punycode encoded URLs and get both encoded and decoded results.
+- Check if URLs are subdomains, have valid domain parts, or end with known suffixes.
+
 ## Usage
-1) Import `public_suffix`:
+1) Import public_suffix:
     - `public_suffix.dart`: If you prefer loading suffix lists on your own.
     - `public_suffix_io.dart`: For helper methods to load suffix lists from URIs using `dart:io`.
     - `public_suffix_browser.dart`:  For helper methods to load suffix lists from URIs using `dart:html`.
@@ -17,31 +25,40 @@ public_suffix is a dart library for identifying the public suffixes (or TLDs), r
 
 **Note:** Don't overload publicsuffix.org's servers by repeatedly retrieving the suffix list from them. Cache a copy somewhere instead, and update that copy only when the master copy is updated.
 
+### Short example
 ```dart
 import 'package:public_suffix/public_suffix_io.dart';
 
 main(List<String> arguments) async {
+  // Load a list of suffix rules from publicsuffix.org.
   await SuffixRulesHelper.initFromUri(
-      Uri.parse("https://publicsuffix.org/list/public_suffix_list.dat"));
-  PublicSuffix suffix =
-      PublicSuffix(Uri.parse("https://www.komposten.github.io"));
-
-  //Results when matching against ICANN/IANA and private suffixes.
-  print(suffix.suffix); // "github.io"
-  print(suffix.root); // "komposten"
-  print(suffix.domain); // "komposten.github.io"
-
-  //Results when matching against only ICANN/IANA suffixes.
-  print(suffix.icannSuffix); // "io"
-  print(suffix.icannRoot); // "github"
-  print(suffix.icannDomain); // "github.io"
-
-  //punycode decoded results.
-  suffix = PublicSuffix(Uri.parse("https://www.xn--6qq79v.cn"));
-  print(suffix.domain); // "xn--6qq79v.cn"
-  print(suffix.punyDecoded.domain); // "你好.cn"
+      Uri.parse('https://publicsuffix.org/list/public_suffix_list.dat'));
+	  
+  // Parse a URL.
+  PublicSuffix parsedUrl =
+      PublicSuffix.fromString('https://www.komposten.github.io');
+	  
+  // Obtain information using the many getters, for example:
+  print(parsedUrl.suffix);      // github.io
+  print(parsedUrl.root);        // komposten
+  print(parsedUrl.domain);      // komposten.github.io
+  print(parsedUrl.icannDomain); // github.io
+
+  // public_suffix also supports punycoded URLs.
+  parsedUrl = PublicSuffix.fromString('https://www.xn--6qq79v.cn');
+  print(parsedUrl.domain);             // xn--6qq79v.cn
+  print(parsedUrl.punyDecoded.domain); // 你好.cn
 }
 ```
 
+## Utility functions
+Several utility functions can be found in the `DomainUtils` class (imported from `public_suffix.dart`). These currently include:
+- `isSubdomainOf`: Checks if a given URL is a subdomain of another domain.
+- `isSubdomain`: Checks if a given URL has a subdomain part.
+- `isKnownSuffix`: Checks if a given suffix (e.g. `co.uk`) is listed in the suffix rule list.
+- `hasValidDomain`: Checks if a given URL contains a registrable domain part.
+
+Most of these create PublicSuffix objects internally. If you are already working with PublicSuffix objects, there are similar methods you can call directly on those to avoid creating new ones.
+
 ## License
 public_suffix is licensed under the MIT license. See [LICENSE](https://github.com/Komposten/public_suffix/blob/master/LICENSE) for the full license text.

example/main.dart

@@ -1,28 +1,28 @@
 import 'package:public_suffix/public_suffix_io.dart';
 
-main(List<String> arguments) async {
+Future<void> main() async {
   // Load a list of suffix rules from publicsuffix.org.
   await SuffixRulesHelper.initFromUri(
-      Uri.parse("https://publicsuffix.org/list/public_suffix_list.dat"));
+      Uri.parse('https://publicsuffix.org/list/public_suffix_list.dat'));
 
   // Parse a URL.
-  PublicSuffix suffix =
-      PublicSuffix(Uri.parse("https://www.komposten.github.io"));
+  PublicSuffix parsedUrl =
+      PublicSuffix.fromString('https://www.komposten.github.io');
 
-  // Results when matching against ICANN/IANA and private suffixes.
-  print(suffix.suffix); // "github.io"
-  print(suffix.root); // "komposten"
-  print(suffix.domain); // "komposten.github.io"
+  // Results when matching against both ICANN/IANA and private suffixes.
+  print(parsedUrl.suffix); // github.io
+  print(parsedUrl.root); // komposten
+  print(parsedUrl.domain); // komposten.github.io
 
   // Results when matching against only ICANN/IANA suffixes.
-  print(suffix.icannSuffix); // "io"
-  print(suffix.icannRoot); // "github"
-  print(suffix.icannDomain); // "github.io"
+  print(parsedUrl.icannSuffix); // io
+  print(parsedUrl.icannRoot); // github
+  print(parsedUrl.icannDomain); // github.io
 
-  // punycode decoded results.
-  suffix = PublicSuffix(Uri.parse("https://www.xn--6qq79v.cn"));
-  print(suffix.domain); // "xn--6qq79v.cn"
-  print(suffix.punyDecoded.domain); // "你好.cn"
+  // Punycode decoded results.
+  parsedUrl = PublicSuffix.fromString('https://www.xn--6qq79v.cn');
+  print(parsedUrl.domain); // xn--6qq79v.cn
+  print(parsedUrl.punyDecoded.domain); // 你好.cn
 
   // Dispose the list to unload it from memory if you wish.
   // This is probably not needed since the list is relatively small.