Class: ActiveSupport::Multibyte::Chars
- Includes:
- Comparable
- Defined in:
- lib/active_support/multibyte/chars.rb
Overview
Chars enables you to work transparently with UTF-8 encoding in the Ruby String class without having extensive knowledge about the encoding. A Chars object accepts a string upon initialization and proxies String methods in an encoding safe manner. All the normal String methods are also implemented on the proxy.
String methods are proxied through the Chars object, and can be accessed through the mb_chars
method. Methods which would normally return a String object now return a Chars object so methods can be chained.
'The Perfect String '.mb_chars.downcase.strip.normalize # => "the perfect string"
Chars objects are perfectly interchangeable with String objects as long as no explicit class checks are made. If certain methods do explicitly check the class, call to_s
before you pass chars objects to them.
bad.explicit_checking_method 'T'.mb_chars.downcase.to_s
The default Chars implementation assumes that the encoding of the string is UTF-8, if you want to handle different encodings you can write your own multibyte string handler and configure it through ActiveSupport::Multibyte.proxy_class.
class CharsForUTF32
def size
@wrapped_string.size / 4
end
def self.accepts?(string)
string.length % 4 == 0
end
end
ActiveSupport::Multibyte.proxy_class = CharsForUTF32
Instance Attribute Summary collapse
-
#wrapped_string ⇒ Object
(also: #to_s, #to_str)
readonly
Returns the value of attribute wrapped_string.
Class Method Summary collapse
-
.consumes?(string) ⇒ Boolean
Returns
true
when the proxy class can handle the string.
Instance Method Summary collapse
-
#as_json(options = nil) ⇒ Object
:nodoc:.
-
#capitalize ⇒ Object
Converts the first character to uppercase and the remainder to lowercase.
-
#compose ⇒ Object
Performs composition on all the characters.
-
#decompose ⇒ Object
Performs canonical decomposition on all the characters.
-
#downcase ⇒ Object
Converts characters in the string to lowercase.
-
#grapheme_length ⇒ Object
Returns the number of grapheme clusters in the string.
-
#initialize(string) ⇒ Chars
constructor
Creates a new Chars instance by wrapping string.
-
#limit(limit) ⇒ Object
Limits the byte size of the string to a number of bytes without breaking characters.
-
#method_missing(method, *args, &block) ⇒ Object
Forward all undefined methods to the wrapped string.
-
#normalize(form = nil) ⇒ Object
Returns the KC normalization of the string by default.
-
#respond_to_missing?(method, include_private) ⇒ Boolean
Returns
true
if obj responds to the given method. -
#reverse ⇒ Object
Reverses all characters in the string.
-
#slice!(*args) ⇒ Object
Works like
String#slice!
, but returns an instance of Chars, or nil if the string was not modified. -
#split(*args) ⇒ Object
Works just like
String#split
, with the exception that the items in the resulting list are Chars instances instead of String. -
#swapcase ⇒ Object
Converts characters in the string to the opposite case.
-
#tidy_bytes(force = false) ⇒ Object
Replaces all ISO-8859-1 or CP1252 characters by their UTF-8 equivalent resulting in a valid UTF-8 string.
-
#titleize ⇒ Object
(also: #titlecase)
Capitalizes the first letter of every word, when possible.
-
#upcase ⇒ Object
Converts characters in the string to uppercase.
Constructor Details
#initialize(string) ⇒ Chars
Creates a new Chars instance by wrapping string.
51 52 53 54 |
# File 'lib/active_support/multibyte/chars.rb', line 51 def initialize(string) @wrapped_string = string @wrapped_string.force_encoding(Encoding::UTF_8) unless @wrapped_string.frozen? end |
Dynamic Method Handling
This class handles dynamic methods through the method_missing method
#method_missing(method, *args, &block) ⇒ Object
Forward all undefined methods to the wrapped string.
57 58 59 60 61 62 63 64 |
# File 'lib/active_support/multibyte/chars.rb', line 57 def method_missing(method, *args, &block) result = @wrapped_string.__send__(method, *args, &block) if method.to_s =~ /!$/ self if result else result.kind_of?(String) ? chars(result) : result end end |
Instance Attribute Details
#wrapped_string ⇒ Object (readonly) Also known as: to_s, to_str
Returns the value of attribute wrapped_string.
44 45 46 |
# File 'lib/active_support/multibyte/chars.rb', line 44 def wrapped_string @wrapped_string end |
Class Method Details
.consumes?(string) ⇒ Boolean
Returns true
when the proxy class can handle the string. Returns false
otherwise.
75 76 77 |
# File 'lib/active_support/multibyte/chars.rb', line 75 def self.consumes?(string) string.encoding == Encoding::UTF_8 end |
Instance Method Details
#as_json(options = nil) ⇒ Object
:nodoc:
201 202 203 |
# File 'lib/active_support/multibyte/chars.rb', line 201 def as_json( = nil) #:nodoc: to_s.as_json() end |
#capitalize ⇒ Object
Converts the first character to uppercase and the remainder to lowercase.
'über'.mb_chars.capitalize.to_s # => "Über"
144 145 146 |
# File 'lib/active_support/multibyte/chars.rb', line 144 def capitalize (slice(0) || chars('')).upcase + (slice(1..-1) || chars('')).downcase end |
#compose ⇒ Object
Performs composition on all the characters.
'é'.length # => 3
'é'.mb_chars.compose.to_s.length # => 2
180 181 182 |
# File 'lib/active_support/multibyte/chars.rb', line 180 def compose chars(Unicode.compose(@wrapped_string.codepoints.to_a).pack('U*')) end |
#decompose ⇒ Object
Performs canonical decomposition on all the characters.
'é'.length # => 2
'é'.mb_chars.decompose.to_s.length # => 3
172 173 174 |
# File 'lib/active_support/multibyte/chars.rb', line 172 def decompose chars(Unicode.decompose(:canonical, @wrapped_string.codepoints.to_a).pack('U*')) end |
#downcase ⇒ Object
Converts characters in the string to lowercase.
'VĚDA A VÝZKUM'.mb_chars.downcase.to_s # => "věda a výzkum"
130 131 132 |
# File 'lib/active_support/multibyte/chars.rb', line 130 def downcase chars Unicode.downcase(@wrapped_string) end |
#grapheme_length ⇒ Object
Returns the number of grapheme clusters in the string.
'क्षि'.mb_chars.length # => 4
'क्षि'.mb_chars.grapheme_length # => 3
188 189 190 |
# File 'lib/active_support/multibyte/chars.rb', line 188 def grapheme_length Unicode.unpack_graphemes(@wrapped_string).length end |
#limit(limit) ⇒ Object
Limits the byte size of the string to a number of bytes without breaking characters. Usable when the storage for a string is limited for some reason.
'こんにちは'.mb_chars.limit(7).to_s # => "こん"
116 117 118 |
# File 'lib/active_support/multibyte/chars.rb', line 116 def limit(limit) slice(0...translate_offset(limit)) end |
#normalize(form = nil) ⇒ Object
Returns the KC normalization of the string by default. NFKC is considered the best normalization form for passing strings to databases and validations.
-
form
- The form you want to normalize in. Should be one of the following::c
,:kc
,:d
, or:kd
. Default is ActiveSupport::Multibyte::Unicode.default_normalization_form
164 165 166 |
# File 'lib/active_support/multibyte/chars.rb', line 164 def normalize(form = nil) chars(Unicode.normalize(@wrapped_string, form)) end |
#respond_to_missing?(method, include_private) ⇒ Boolean
Returns true
if obj responds to the given method. Private methods are included in the search only if the optional second parameter evaluates to true
.
69 70 71 |
# File 'lib/active_support/multibyte/chars.rb', line 69 def respond_to_missing?(method, include_private) @wrapped_string.respond_to?(method, include_private) end |
#reverse ⇒ Object
Reverses all characters in the string.
'Café'.mb_chars.reverse.to_s # => 'éfaC'
107 108 109 |
# File 'lib/active_support/multibyte/chars.rb', line 107 def reverse chars(Unicode.unpack_graphemes(@wrapped_string).reverse.flatten.pack('U*')) end |
#slice!(*args) ⇒ Object
Works like String#slice!
, but returns an instance of Chars, or nil if the string was not modified. The string will not be modified if the range given is out of bounds
string = 'Welcome'
string.mb_chars.slice!(3) # => #<ActiveSupport::Multibyte::Chars:0x000000038109b8 @wrapped_string="c">
string # => 'Welome'
string.mb_chars.slice!(0..3) # => #<ActiveSupport::Multibyte::Chars:0x00000002eb80a0 @wrapped_string="Welo">
string # => 'me'
97 98 99 100 101 102 |
# File 'lib/active_support/multibyte/chars.rb', line 97 def slice!(*args) string_sliced = @wrapped_string.slice!(*args) if string_sliced chars(string_sliced) end end |
#split(*args) ⇒ Object
Works just like String#split
, with the exception that the items in the resulting list are Chars instances instead of String. This makes chaining methods easier.
'Café périferôl'.mb_chars.split(/é/).map { |part| part.upcase.to_s } # => ["CAF", " P", "RIFERÔL"]
84 85 86 |
# File 'lib/active_support/multibyte/chars.rb', line 84 def split(*args) @wrapped_string.split(*args).map { |i| self.class.new(i) } end |
#swapcase ⇒ Object
Converts characters in the string to the opposite case.
'El Cañón".mb_chars.swapcase.to_s # => "eL cAÑÓN"
137 138 139 |
# File 'lib/active_support/multibyte/chars.rb', line 137 def swapcase chars Unicode.swapcase(@wrapped_string) end |
#tidy_bytes(force = false) ⇒ Object
Replaces all ISO-8859-1 or CP1252 characters by their UTF-8 equivalent resulting in a valid UTF-8 string.
Passing true
will forcibly tidy all bytes, assuming that the string’s encoding is entirely CP1252 or ISO-8859-1.
197 198 199 |
# File 'lib/active_support/multibyte/chars.rb', line 197 def tidy_bytes(force = false) chars(Unicode.tidy_bytes(@wrapped_string, force)) end |
#titleize ⇒ Object Also known as: titlecase
Capitalizes the first letter of every word, when possible.
"ÉL QUE SE ENTERÓ".mb_chars.titleize # => "Él Que Se Enteró"
"日本語".mb_chars.titleize # => "日本語"
152 153 154 |
# File 'lib/active_support/multibyte/chars.rb', line 152 def titleize chars(downcase.to_s.gsub(/\b('?\S)/u) { Unicode.upcase($1)}) end |