strings: "priority" and "special casing rules" in ToLowerSpecial doc unclear

[willfaught]

$ go doc strings ToLowerSpecial
func ToLowerSpecial(c unicode.SpecialCase, s string) string
    ToLowerSpecial returns a copy of the string s with all Unicode letters
    mapped to their lower case, giving priority to the special casing rules.

It's unclear to me what "priority" and "special casing rules" mean.

The package doc says "For information about UTF-8 strings in Go, see https://blog.golang.org/strings." Searching that page for "special", "case", etc. didn't seem to point to anything related to special casing or priority.

System details

go version go1.10.3 darwin/amd64
GOARCH="amd64"
GOBIN=""
GOCACHE="/Users/will/Library/Caches/go-build"
GOEXE=""
GOHOSTARCH="amd64"
GOHOSTOS="darwin"
GOOS="darwin"
GOPATH="/Users/will/Developer/go"
GORACE=""
GOROOT="/usr/local/Cellar/go/1.10.3/libexec"
GOTMPDIR=""
GOTOOLDIR="/usr/local/Cellar/go/1.10.3/libexec/pkg/tool/darwin_amd64"
GCCGO="gccgo"
CC="clang"
CXX="clang++"
CGO_ENABLED="1"
CGO_CFLAGS="-g -O2"
CGO_CPPFLAGS=""
CGO_CXXFLAGS="-g -O2"
CGO_FFLAGS="-g -O2"
CGO_LDFLAGS="-g -O2"
PKG_CONFIG="pkg-config"
GOGCCFLAGS="-fPIC -m64 -pthread -fno-caret-diagnostics -Qunused-arguments -fmessage-length=0 -fdebug-prefix-map=/var/folders/t3/p8srlt1j4473h_4ptph5r1xh0000gn/T/go-build611520741=/tmp/go-build -gno-record-gcc-switches -fno-common"
GOROOT/bin/go version: go version go1.10.3 darwin/amd64
GOROOT/bin/go tool compile -V: compile version go1.10.3
uname -v: Darwin Kernel Version 17.7.0: Thu Jun 21 22:53:14 PDT 2018; root:xnu-4570.71.2~1/RELEASE_X86_64
ProductName:	Mac OS X
ProductVersion:	10.13.6
BuildVersion:	17G65
lldb --version: lldb-902.0.79.7
  Swift-4.1

[ianlancetaylor]

The special casing rules here handled by this function are specifically those in the argument c. See https://golang.org/pkg/unicode#SpecialCase.

There is a bit of background on this at http://www.unicode.org/reports/tr44/#Casemapping.

[agnivade]

@ianlancetaylor - Does this sound okay ?

// ToUpperSpecial returns a copy of the string s with all Unicode letters mapped to their
// upper case, using the language-specific case mapping specified by c.
// You should use this function if you need to do case-insensitive string comparison
// in a specific language.

[vikramcse]

Hi, Can I take this issue as my first contribution? :)

[agnivade]

Sure :)

[ianlancetaylor]

@agnivade Thanks, I think the first sentence is fine but I would drop the second sentence. The truth is that if you want case-insensitive string comparison in a specific language you should probably be using golang.org/x/text/search.

[vikramcse]

@agnivade @ianlancetaylor I think the term special case in the go doc points to language-specific case mappings

Does this comment sounds good?

// ToUpperSpecial returns a copy of the string s with all Unicode letters mapped to their
// upper case, using the language-specific case mapping specified by c.
// Use this function if you need to do language-specific case mappings such as Turkish or Azeri.

[agnivade]

I think the second sentence just repeats the last part of the first sentence. You can send a CL with only the first sentence. Users can always click on c to see more.

[gopherbot]

Change https://golang.org/cl/127716 mentions this issue: strings: revised ToUpperSpecial and ToLowerSpecial wording

[kzisme]

@ianlancetaylor I just submitted a PR for this issue - as it is my first one let me know if anything is incorrect. I wasn't sure if anyone was still working on this since a few days had passed - my apologies if I stepped on any toes.