cases.go

     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
View as plain text