Case Mapping¶ ↑

Some string-oriented methods use case mapping.

In String:

• String#capitalize

• String#capitalize!

• String#casecmp

• String#casecmp?

• String#downcase

• String#downcase!

• String#swapcase

• String#swapcase!

• String#upcase

• String#upcase!

In Symbol:

• Symbol#capitalize

• Symbol#casecmp

• Symbol#casecmp?

• Symbol#downcase

• Symbol#swapcase

• Symbol#upcase

Default Case Mapping¶ ↑

By default, all of these methods use full Unicode case mapping, which is suitable for most languages. See Unicode Latin Case Chart.

Non-ASCII case mapping and folding are supported for UTF-8, UTF-16BE/LE, UTF-32BE/LE, and ISO-8859-1~16 Strings/Symbols.

Context-dependent case mapping as described in Table 3-17 of the Unicode standard is currently not supported.

In most cases, case conversions of a string have the same number of characters. There are exceptions (see also :fold below):

s = "\u00DF" # => "ß"
s.upcase     # => "SS"
s = "\u0149" # => "ʼn"
s.upcase     # => "ʼN"

Case mapping may also depend on locale (see also :turkic below):

s = "\u0049"        # => "I"
s.downcase          # => "i" # Dot above.
s.downcase(:turkic) # => "ı" # No dot above.

Case changes may not be reversible:

s = 'Hello World!' # => "Hello World!"
s.downcase         # => "hello world!"
s.downcase.upcase  # => "HELLO WORLD!" # Different from original s.

Case changing methods may not maintain Unicode normalization. See String#unicode_normalize).

Options for Case Mapping¶ ↑

Except for casecmp and casecmp?, each of the case-mapping methods listed above accepts optional arguments, *options.

The arguments may be:

• :ascii only.

• :fold only.

• :turkic or :lithuanian or both.

The options:

• :ascii: ASCII-only mapping: uppercase letters ('A'..'Z') are mapped to lowercase letters ('a'..'z); other characters are not changed

  s = "Foo \u00D8 \u00F8 Bar" # => "Foo Ø ø Bar"
  s.upcase                    # => "FOO Ø Ø BAR"
  s.downcase                  # => "foo ø ø bar"
  s.upcase(:ascii)            # => "FOO Ø ø BAR"
  s.downcase(:ascii)          # => "foo Ø ø bar"
  

• :turkic: Full Unicode case mapping, adapted for the Turkic languages that distinguish dotted and dotless I, for example Turkish and Azeri.

  s = 'Türkiye'       # => "Türkiye"
  s.upcase            # => "TÜRKIYE"
  s.upcase(:turkic)   # => "TÜRKİYE" # Dot above.
  
  s = 'TÜRKIYE'       # => "TÜRKIYE"
  s.downcase          # => "türkiye"
  s.downcase(:turkic) # => "türkıye" # No dot above.
  

• :lithuanian: Not yet implemented.

• :fold (available only for String#downcase, String#downcase!, and Symbol#downcase): Unicode case folding, which is more far-reaching than Unicode case mapping.

  s = "\u00DF"      # => "ß"
  s.downcase        # => "ß"
  s.downcase(:fold) # => "ss"
  s.upcase          # => "SS"
  
  s = "\uFB04"      # => "ffl"
  s.downcase        # => "ffl"
  s.upcase          # => "FFL"
  s.downcase(:fold) # => "ffl"
  

Ruby-doc.org is a service of James Britt and Neurogami, an erratic source of art, music, and technology.

Generated with Rubydoc Rdoc Generator 0.42.0.

There is an updated format of the API docs for this version here.