strings: document difference of ToTitle, ToUpper, Title

[reiy-leo]

go version go1.12.7 darwin/amd64

Does this issue reproduce with the latest release?

func	desc in golang.org/pkg/
ToTitle	returns a copy of the string s with all Unicode letters mapped to their title case.
Title	returns a copy of the string s with all Unicode letters that begin words mapped to their title case.
ToUpper	returns a copy of the string s with all Unicode letters mapped to their upper case.

So what are the definitions of upper case and title case in golang? the description in godocs is confusing. Could you please specify the differences?

The examples used in golang.org/pkg/ speaks nothing. all of them produces the same results no matter which func is used.

What operating system and processor architecture are you using (go env)?

go env Output

$ go env
GOARCH="amd64"
GOBIN=""
GOCACHE="/Users/******/Library/Caches/go-build"
GOEXE=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="darwin"
GOOS="darwin"
GOPATH="/Users/******/go"
GOPROXY=""
GORACE=""
GOROOT="/usr/local/Cellar/go/1.12.7/libexec"
GOTMPDIR=""
GOTOOLDIR="/usr/local/Cellar/go/1.12.7/libexec/pkg/tool/darwin_amd64"
GCCGO="gccgo"
CC="clang"
CXX="clang++"
CGO_ENABLED="1"
GOMOD="/Users/******/Documents/Playground/B/Go-Programming-Cookbook-Second-Edition/chapter1/bytestrings/go.mod"
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/rf/x53btrqj55v077g8_7z4yb280000gp/T/go-build762210892=/tmp/go-build -gno-record-gcc-switches -fno-common"

[triztian]

Perhaps adding a reference to the unicode documentation on ToTitle would be sufficient?

Q: What is titlecase? How is it different from uppercase?

A: Titlecase takes its name from the case format used when forming a title, in which the initial letter in a word is capitalized and the rest are not. Titlecase is also used in forming a sentence by capitalizing the first word, and for forming proper names. The titlecase mapping in the Unicode Standard is the mapping applied to the initial character in a word.

The titlecase mapping in Unicode differs from the uppercase mapping in that a number of characters require special handling. These are chiefly ligatures and digraphs such as 'fl', 'dz', and 'lj', plus a number of polytonic Greek characters. For example, U+01C7 (LJ) maps to U+01C8 (Lj) rather than to U+01C9 (lj).

Source: https://unicode.org/faq/casemap_charprop.html

ToUpper, ToLower and ToTitle follow such specification AFAIK.

[ianlancetaylor]

I'm not sure we need to change anything here, but I think that at most we should add a link to some Unicode docs. I don't think our docs need to explain title case when it is clearly explained elsewhere.

[aqtodd]

Would something along the lines of this make sense?

func Title(s string) string

Title returns a copy of the string s with all Unicode letters that begin words mapped to their title case. As defined by: https://unicode.org/faq/casemap_charprop.html#4.

BUG(rsc): The rule Title uses for word boundaries does not handle Unicode punctuation properly.

func ToTitle(s string) string

ToTitle returns a copy of the string s with all Unicode letters mapped to their title case. As defined by: https://unicode.org/faq/casemap_charprop.html#4.

Additionally, I think it might be helpful to include an example in the strings package showing Title vs ToTitle used together as they seem easy to confuse.

Perhaps something along the lines of:

package main

import (
	"fmt"
	"strings"
)

func main() {
	fmt.Printf("ToTitle: %s, expected output: \"LOUD NOISES\"\n", strings.ToTitle("loud noises"))
	fmt.Printf("Title: %s, expected output: \"Loud Noises\"\n",  strings.Title("loud noises"))

	fmt.Printf("Title: %s, expected output: \"Хлеб\"\n", strings.Title("хлеб"))
	fmt.Printf("ToTitle: %s, expected output: \"ХЛЕБ\"\n", strings.ToTitle("хлеб"))
}

[gopherbot]

Change https://golang.org/cl/187825 mentions this issue: strings: clarify usage of Title and ToTitle