From c56bc9f2420621a8b6bce99bb5e0840817af8f7b Mon Sep 17 00:00:00 2001
From: Min Huang <70873102+min0625@users.noreply.github.com>
Date: Tue, 23 Jun 2026 05:37:02 +0000
Subject: [PATCH] docs: update README and add examples for Equal, LoadString,
 and LoadTimeZone errors

Clarifies that == is unreliable for loaded TimeZone values (pointer
semantics) and Equal should be used instead. Adds runnable examples
for ExampleLoadTimeZone_errors, ExampleTimeZone_LoadString, and
expands the main README snippet to demonstrate Equal.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 README.md                 |  8 ++++++--
 README.zh-TW.md           |  8 ++++++--
 time_zone_example_test.go | 34 ++++++++++++++++++++++++++++++++++
 3 files changed, 46 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index b0856e7..dd1ef89 100644
--- a/README.md
+++ b/README.md
@@ -12,7 +12,7 @@ A small Go library providing a `TimeZone` type backed by the IANA time zone data
 - **Zero value is UTC** — `TimeZone{}` represents UTC; loading `"UTC"` or `""` always yields the zero value.
 - **IANA names** — accepts any [IANA time zone database](https://www.iana.org/time-zones) name (e.g. `"America/New_York"`).
 - **No `"Local"`** — the `"Local"` time zone is always rejected with an error.
-- **Comparable** — `TimeZone` is a plain struct; use `==` for equality checks.
+- **Equality** — compare values with the `Equal` method; `==` is only reliable against the zero value, since a `TimeZone` holds a `*time.Location` pointer.
 - **Rich interface support** — implements `fmt.Stringer`, `sql.Scanner`, `driver.Valuer`, `encoding.TextMarshaler/Unmarshaler`, and `json.Marshaler/Unmarshaler`.
 - **No dependencies** — built entirely on the standard library.
 
@@ -49,7 +49,11 @@ func main() {
 	fmt.Println(z)                                      // America/New_York
 	fmt.Println(time.Now().In(z.Location()).Location()) // America/New_York
 
-	// UTC is the zero value
+	// Compare with Equal; == is unreliable for loaded zones.
+	other := tz.MustLoadTimeZone("America/New_York")
+	fmt.Println(z.Equal(other)) // true
+
+	// UTC is the zero value.
 	utc, _ := tz.LoadTimeZone("UTC")
 	fmt.Println(utc == tz.TimeZone{}) // true
 }
diff --git a/README.zh-TW.md b/README.zh-TW.md
index a410e9d..a5c0f8f 100644
--- a/README.zh-TW.md
+++ b/README.zh-TW.md
@@ -12,7 +12,7 @@
 - **零值即 UTC** — `TimeZone{}` 代表 UTC；載入 `"UTC"` 或 `""` 必定回傳零值。
 - **IANA 名稱** — 接受任何 [IANA 時區資料庫](https://www.iana.org/time-zones) 名稱（例如 `"America/New_York"`）。
 - **不支援 `"Local"`** — `"Local"` 時區一律以錯誤拒絕。
-- **可比較** — `TimeZone` 為一般結構體；可直接使用 `==` 進行相等判斷。
+- **相等判斷** — 請使用 `Equal` 方法進行比較；由於 `TimeZone` 內含 `*time.Location` 指標，`==` 僅適用於與零值比較。
 - **豐富的介面支援** — 實作 `fmt.Stringer`、`sql.Scanner`、`driver.Valuer`、`encoding.TextMarshaler/Unmarshaler` 及 `json.Marshaler/Unmarshaler`。
 - **零相依** — 完全建構於標準函式庫之上。
 
@@ -49,7 +49,11 @@ func main() {
 	fmt.Println(z)                                      // America/New_York
 	fmt.Println(time.Now().In(z.Location()).Location()) // America/New_York
 
-	// UTC 為零值
+	// 請使用 Equal 進行比較；對已載入的時區而言 == 並不可靠。
+	other := tz.MustLoadTimeZone("America/New_York")
+	fmt.Println(z.Equal(other)) // true
+
+	// UTC 為零值。
 	utc, _ := tz.LoadTimeZone("UTC")
 	fmt.Println(utc == tz.TimeZone{}) // true
 }
diff --git a/time_zone_example_test.go b/time_zone_example_test.go
index ffebbe1..05a5977 100644
--- a/time_zone_example_test.go
+++ b/time_zone_example_test.go
@@ -57,6 +57,20 @@ func ExampleTimeZone_Equal() {
 	// true
 }
 
+func ExampleLoadTimeZone_errors() {
+	// "Local" is always rejected.
+	_, err := tz.LoadTimeZone("Local")
+	fmt.Println(err != nil)
+
+	// An unknown name is rejected too.
+	_, err = tz.LoadTimeZone("Not/A_Zone")
+	fmt.Println(err != nil)
+
+	// Output:
+	// true
+	// true
+}
+
 func ExampleMustLoadTimeZone() {
 	z := tz.MustLoadTimeZone("America/New_York")
 	fmt.Println(z.String())
@@ -65,6 +79,26 @@ func ExampleMustLoadTimeZone() {
 	// America/New_York
 }
 
+func ExampleTimeZone_LoadString() {
+	var z tz.TimeZone
+	if err := z.LoadString("Asia/Tokyo"); err != nil {
+		panic(err)
+	}
+
+	fmt.Println(z)
+
+	// Loading "UTC" (or an empty string) resets z to the zero value.
+	if err := z.LoadString("UTC"); err != nil {
+		panic(err)
+	}
+
+	fmt.Println(z == tz.TimeZone{})
+
+	// Output:
+	// Asia/Tokyo
+	// true
+}
+
 func ExampleTimeZone_Scan() {
 	var z tz.TimeZone
 	if err := z.Scan("America/New_York"); err != nil {