1 // Copyright 2014 The Go Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style
3 // license that can be found in the LICENSE file.
4 5 //go:generate go run gen.go gen_trieval.go
6 7 // Package cases provides general and language-specific case mappers.
8 package cases // import "golang.org/x/text/cases"
9 10 import (
11 "golang.org/x/text/language"
12 "golang.org/x/text/transform"
13 )
14 15 // References:
16 // - Unicode Reference Manual Chapter 3.13, 4.2, and 5.18.
17 // - https://www.unicode.org/reports/tr29/
18 // - https://www.unicode.org/Public/6.3.0/ucd/CaseFolding.txt
19 // - https://www.unicode.org/Public/6.3.0/ucd/SpecialCasing.txt
20 // - https://www.unicode.org/Public/6.3.0/ucd/DerivedCoreProperties.txt
21 // - https://www.unicode.org/Public/6.3.0/ucd/auxiliary/WordBreakProperty.txt
22 // - https://www.unicode.org/Public/6.3.0/ucd/auxiliary/WordBreakTest.txt
23 // - http://userguide.icu-project.org/transforms/casemappings
24 25 // TODO:
26 // - Case folding
27 // - Wide and Narrow?
28 // - Segmenter option for title casing.
29 // - ASCII fast paths
30 // - Encode Soft-Dotted property within trie somehow.
31 32 // A Caser transforms given input to a certain case. It implements
33 // transform.Transformer.
34 //
35 // A Caser may be stateful and should therefore not be shared between
36 // goroutines.
37 type Caser struct {
38 t transform.SpanningTransformer
39 }
40 41 // Bytes returns a new byte slice with the result of converting b to the case
42 // form implemented by c.
43 func (c Caser) Bytes(b []byte) []byte {
44 b, _, _ = transform.Bytes(c.t, b)
45 return b
46 }
47 48 // String returns a string with the result of transforming s to the case form
49 // implemented by c.
50 func (c Caser) String(s string) string {
51 s, _, _ = transform.String(c.t, s)
52 return s
53 }
54 55 // Reset resets the Caser to be reused for new input after a previous call to
56 // Transform.
57 func (c Caser) Reset() { c.t.Reset() }
58 59 // Transform implements the transform.Transformer interface and transforms the
60 // given input to the case form implemented by c.
61 func (c Caser) Transform(dst, src []byte, atEOF bool) (nDst, nSrc int, err error) {
62 return c.t.Transform(dst, src, atEOF)
63 }
64 65 // Span implements the transform.SpanningTransformer interface.
66 func (c Caser) Span(src []byte, atEOF bool) (n int, err error) {
67 return c.t.Span(src, atEOF)
68 }
69 70 // Upper returns a Caser for language-specific uppercasing.
71 func Upper(t language.Tag, opts ...Option) Caser {
72 return Caser{makeUpper(t, getOpts(opts...))}
73 }
74 75 // Lower returns a Caser for language-specific lowercasing.
76 func Lower(t language.Tag, opts ...Option) Caser {
77 return Caser{makeLower(t, getOpts(opts...))}
78 }
79 80 // Title returns a Caser for language-specific title casing. It uses an
81 // approximation of the default Unicode Word Break algorithm.
82 func Title(t language.Tag, opts ...Option) Caser {
83 return Caser{makeTitle(t, getOpts(opts...))}
84 }
85 86 // Fold returns a Caser that implements Unicode case folding. The returned Caser
87 // is stateless and safe to use concurrently by multiple goroutines.
88 //
89 // Case folding does not normalize the input and may not preserve a normal form.
90 // Use the collate or search package for more convenient and linguistically
91 // sound comparisons. Use golang.org/x/text/secure/precis for string comparisons
92 // where security aspects are a concern.
93 func Fold(opts ...Option) Caser {
94 return Caser{makeFold(getOpts(opts...))}
95 }
96 97 // An Option is used to modify the behavior of a Caser.
98 type Option func(o options) options
99 100 // TODO: consider these options to take a boolean as well, like FinalSigma.
101 // The advantage of using this approach is that other providers of a lower-case
102 // algorithm could set different defaults by prefixing a user-provided slice
103 // of options with their own. This is handy, for instance, for the precis
104 // package which would override the default to not handle the Greek final sigma.
105 106 var (
107 // NoLower disables the lowercasing of non-leading letters for a title
108 // caser.
109 NoLower Option = noLower
110 111 // Compact omits mappings in case folding for characters that would grow the
112 // input. (Unimplemented.)
113 Compact Option = compact
114 )
115 116 // TODO: option to preserve a normal form, if applicable?
117 118 type options struct {
119 noLower bool
120 simple bool
121 122 // TODO: segmenter, max ignorable, alternative versions, etc.
123 124 ignoreFinalSigma bool
125 }
126 127 func getOpts(o ...Option) (res options) {
128 for _, f := range o {
129 res = f(res)
130 }
131 return
132 }
133 134 func noLower(o options) options {
135 o.noLower = true
136 return o
137 }
138 139 func compact(o options) options {
140 o.simple = true
141 return o
142 }
143 144 // HandleFinalSigma specifies whether the special handling of Greek final sigma
145 // should be enabled. Unicode prescribes handling the Greek final sigma for all
146 // locales, but standards like IDNA and PRECIS override this default.
147 func HandleFinalSigma(enable bool) Option {
148 if enable {
149 return handleFinalSigma
150 }
151 return ignoreFinalSigma
152 }
153 154 func ignoreFinalSigma(o options) options {
155 o.ignoreFinalSigma = true
156 return o
157 }
158 159 func handleFinalSigma(o options) options {
160 o.ignoreFinalSigma = false
161 return o
162 }
163