From a48c9db964e458335d33238c97fa93a4185adb72 Mon Sep 17 00:00:00 2001 From: Eric Myhre Date: Sun, 23 Feb 2020 11:48:47 +0100 Subject: [PATCH] Addntl comments on PathSegment equality. --- pathSegment.go | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/pathSegment.go b/pathSegment.go index 2d8493e1..fd0238c7 100644 --- a/pathSegment.go +++ b/pathSegment.go @@ -27,6 +27,15 @@ import ( // PathSegment in a Path produced by ParsePath generally have all strings internally, // because there is no distinction possible when parsing a Path string // (and attempting to pre-parse all strings into ints "just in case" would waste time in almost all cases). +// +// Be cautious of attempting to use PathSegment as a map key! +// Due to the implementation detail of internal storage, it's possible for +// PathSegment values which are "equal" per PathSegment.Equal's definition +// to still be unequal in the eyes of golang's native maps. +// You should probably use the string values of the PathSegment as map keys. +// (This has the additional bonus of hitting a special fastpath that the golang +// built-in maps have specifically for plain string keys.) +// type PathSegment struct { /* A quick implementation note about the Go compiler and "union" semantics: @@ -111,9 +120,14 @@ func (ps PathSegment) Index() (int, error) { } // Equals checks if two PathSegment values are equal. -// This is equivalent to checking if their strings are equal -- -// if one of the PathSegment values is backed by an int and the other is a string, -// they may still be "equal". +// +// Because PathSegment is "stringly typed", this comparison does not +// regard if one of the segments is stored as a string and one is stored as an int; +// if string values of two segments are equal, they are "equal" overall. +// In other words, `PathSegmentOfInt(2).Equals(PathSegmentOfString("2")) == true`! +// (You should still typically prefer this method over converting two segments +// to string and comparing those, because even though that may be functionally +// correct, this method will be faster if they're both ints internally.) func (x PathSegment) Equals(o PathSegment) bool { if !x.containsString() && !o.containsString() { return x.i == o.i