Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

strings: EqualFold doc could be clearer #33447

Closed
kevinburke opened this issue Aug 3, 2019 · 3 comments
Closed

strings: EqualFold doc could be clearer #33447

kevinburke opened this issue Aug 3, 2019 · 3 comments
Labels
Documentation FrozenDueToAge help wanted NeedsFix The path to resolution is known, but the work has not been done.
Milestone
Go1.14

Comments

@kevinburke
Copy link
Contributor

The doc for EqualFold says:

EqualFold reports whether s and t, interpreted as UTF-8 strings, are equal under Unicode case-folding.

I have been using Go for over five years now and had no idea what "Unicode case-folding" was until about three minutes ago. Previously I had implemented this by calling strings.ToLower on each side, which is slow and unnecessary. More commonly I believe the EqualFold functionality is known as "case insensitive matching." Users who are searching the strings documentation for the phrase "case insensitive" will find nothing, when they should be finding this function.

Scanning Github this seems like a common mistake:

https://github.com/sachin-varade/network/blob/5d4ab4a3757603b8c0ba9a9df7bc9e0ff92ad102/app/utils/setup/chaincode/processors/read_ledger.go#L172
https://github.com/projectriri/bot-gateway/blob/d4402bd4ac0d4478bd86e585ca83e9d3fc1c140e/converters/cqhttp-ubm-conv/cqhttp-ubm-conv.go#L79

Several Go vetters/linters have checks for this construction that suggest using EqualFold instead:

https://github.com/dominikh/go-tools/blob/1da3061645b400d55be4855f104d8a68ca0a61e5/staticcheck/testdata/src/CheckToLowerToUpperComparison/CheckToLowerToUpperComparison.go

StackOverflow answers suggesting the use of EqualFold have 35,000 views and 10,000 views, respectively.

https://stackoverflow.com/q/24836044/329700
https://stackoverflow.com/q/30196780/329700
@smasher164
Copy link
Member

I agree that this doc can be made clearer. How about adding a clause to say that it basically does a more general form of case-insensitive matching? Something like:

EqualFold reports whether s and t, interpreted as UTF-8 strings, are equal under Unicode case-folding, a generalization of case-insensitivity.

@dmitshur dmitshur added this to the Go1.14 milestone Aug 12, 2019
@dmitshur dmitshur added the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label Aug 12, 2019
@smasher164 smasher164 added NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made. and removed NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. labels Sep 7, 2019
@smasher164 smasher164 added NeedsFix The path to resolution is known, but the work has not been done. help wanted and removed NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made. labels Sep 17, 2019
@andrewmed andrewmed mentioned this issue Sep 20, 2019
Closed
@gopherbot
Copy link

Change https://golang.org/cl/196717 mentions this issue: strings, bytes: clarify usage of EqualFolds

@andrewmed
Copy link

andrewmed commented Sep 20, 2019 •
edited

I opened PR for this, fixing also docs for EqualFold() in bytes package.
Formally, better word here seems to be "caseless" (as in the section 13.3 of Unicode Standard) but I picked up more conventional "case insensitive"
This is my first PR

@golang golang locked and limited conversation to collaborators Sep 20, 2020
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
Documentation FrozenDueToAge help wanted NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Milestone
Go1.14
Development

Successfully merging a pull request may close this issue.

strings, bytes: clarify usage of EqualFolds
5 participants
@kevinburke @dmitshur @gopherbot @smasher164 @andrewmed