disu.se

U

U extends Ruby’s Unicode support. It provides a string class called U::String with an interface that mimics that of the String class in Ruby 2.0, but that can also be used from both Ruby 1.8. This interface also has more complete Unicode support and never modifies the receiver. Thus, a U::String is an immutable value object.

U comes with complete and very accurate documentation. The documentation can realistically also be used as a reference to the Ruby String API and may actually be preferable, as it’s a lot more explicit and complete than the documentation that comes with Ruby.

Installation

Install u with

% gem install u

Usage

Usage is basically the following:

require 'u-1.0'

a = 'äbc'
a.upcase # ⇒ 'äBC'
a.u.upcase # ⇒ 'ÄBC'

That is, you require the library, then you invoke #u on a String. This’ll give you a U::String that has much better Unicode support than a normal String. It’s important to note that U only uses UTF-8, which means that #u will try to #encode the String as such. This shouldn’t be an issue in most cases, as UTF-8 is now more or less the universal encoding – and rightfully so.

As U::Strings are immutable value objects, there’s also a U::Buffer available for building U::Strings efficiently.

See the API for more complete usage information. The following sections will only cover the extensions and differences that U::String exhibit from Ruby’s built-in String class.

Unicode Properties

There are quite a few property-checking interrogators that let you check if all characters in a U::String have the given Unicode property:

Similar to these methods are

which check whether a U::String has been cased in a given manner.

There’s also a #normalized? method that checks whether a U::String has been normalized on a given form.

You can also access certain Unicode properties of the characters of a U::String:

Locale-specific Comparisons

Comparisons of U::Strings respect the current locale (and also allow you to specify a locale to use): #<=>, #casecmp, and #collation_key.

Additional Enumerators

There are a couple of additional enumerators in #each_grapheme_cluster and #each_word (along with aliases #grapheme_clusters and #words).

Unicode-aware Sub-sequence Removal

#Chomp, #chop, #lstrip, #rstrip, and #strip all look for Unicode newline and space characters, rather than only ASCII ones.

Unicode-aware Conversions

Case-shifting methods #downcase and #upcase do proper Unicode casing and the interface is further augmented by #foldcase and #titlecase. #Mirror and #normalize do conversions similar in nature to the case-shifting methods.

Width Calculations

#Width will return the number of cells on a terminal that a U::String will occupy.

#Center, #ljust, and #rjust deal in width rather than length, making them much more useful for generating terminal output. #% (and its alias #format) similarly deal in width.

Extended Type Conversions

Finally, #hex, #oct, and #to_i use Unicode alpha-numerics for their respective conversions.

News

1.0.0

Initial public release!

Financing

Currently, most of my time is spent at my day job and in my rather busy private life. Please motivate me to spend time on this piece of software by donating some of your money to this project. Yeah, I realize that requesting money to develop software is a bit, well, capitalistic of me. But please realize that I live in a capitalistic society and I need money to have other people give me the things that I need to continue living under the rules of said society. So, if you feel that this piece of software has helped you out enough to warrant a reward, please PayPal a donation to now@disu.se. Thanks! Your support won’t go unnoticed!

Reporting Bugs

Please report any bugs that you encounter to the issue tracker.

Authors

Nikolai Weibull wrote the code, the tests, the documentation, and this README.

Licensing

U is free software: you may redistribute it and/or modify it under the terms of the GNU Lesser General Public License, version 3 or later, as published by the Free Software Foundation.