Module: FFI::Locale

Extended by:
Library
Defined in:
lib/ffi-locale.rb,
lib/ffi-locale/version.rb

Overview

FFI adapter for the C-library functions setlocale and localeconv.

FFI is the Ruby Foreign Function Interface library. See github.com/ffi/ffi/wiki for more details.

For example:

if RUBY_VERSION < '1.9.0'
  # 1.8.x doesn't set the locale - use this to handle UTF-8 input correctly
  FFI::Locale.setlocale(FFI::Locale::LC_ALL, "")
end

This call is in fact the reason for the existence of this library. MRI Ruby 1.8.x does not set this so C extensions and FFI adapters that call C library functions that deal with multi-byte or widechars will not function correctly unless this call has been made.

The definitions used here come from Ubuntu 11.04, /usr/include/locale.h and /usr/include/bits/locale.h.

Author:

  • Sean O’Halpin

Defined Under Namespace

Classes: LocaleConv, LocaleConvStruct

Constant Summary collapse

LC_CTYPE = 
0
LC_NUMERIC = 
1
LC_TIME = 
2
LC_COLLATE = 
3
LC_MONETARY = 
4
LC_MESSAGES = 
5
LC_ALL = 
6
LC_PAPER = 
7
LC_NAME = 
8
LC_ADDRESS = 
9
LC_TELEPHONE = 
10
LC_MEASUREMENT = 
11
LC_IDENTIFICATION = 
12
NAME = 
"ffi-locale"
VERSION = 
"1.0.1"

Class Method Summary collapse

Class Method Details

.localeconv ⇒ FFI::Locale::LocaleConv

Returns a LocaleConv containing the locale information as understood by the underlying C library.

The attributes returned are documented in LocaleConv.

See man localeconv and man 7 locale for more details.

Returns:



256
257
258
259
260
 
# File 'lib/ffi-locale.rb', line 256

def localeconv
  ptr = FFI::Locale._localeconv
  lcs = FFI::Locale::LocaleConvStruct.new(ptr)
  FFI::Locale::LocaleConv.new(lcs)
end

.setlocale(category, locale) ⇒ String

On startup, you can specify that your program will use the locale as specified in the user’s environment by calling:

FFI::Locale.setlocale(FFI::Locale::LC_ALL, "")

This enables the underlying C library to use multi-byte and wide character functions correctly. This call is in fact the reason for the existence of this library. MRI Ruby 1.8.x does not set this so C extensions and FFI adapters that call C library functions that deal with multi-byte or widechars will not function correctly unless this call has been made.

If the locale is not "", it should be a well-known constant such as “C” or “da_DK” or the value returned from a prior call to #setlocale.

The locale "C" or "POSIX" is a portable locale; its LC_CTYPE part corresponds to the 7-bit ASCII character set.

If locale is not nil, the program’s current locale is modified according to the arguments. The argument category determines which parts of the program’s current locale should be modified:

LC_ALL

for all of the locale.

LC_COLLATE

for regular expression matching (it determines the meaning of range expressions and equivalence classes) and string collation.

LC_CTYPE

for regular expression matching, character classification, conversion, case-sensitive comparison, and wide character functions.

LC_MESSAGES

for localizable natural-language messages.

LC_MONETARY

for monetary formatting.

LC_NUMERIC

for number formatting (such as the decimal point and the thousands separator).

LC_TIME

for time and date formatting.

See man setlocale for more details.

Examples:

Use locale set in environment

FFI::Locale.setlocale(FFI::Locale::LC_ALL, "")

Use UK UTF-8 locale for character sets only

FFI::Locale.setlocale(FFI::Locale::LC_CTYPE, "en_GB.UTF-8")

Parameters:

  • locale (String) —

    name of locale to switch to, e.g. “en_GB.UTF-8”.

Returns:

  • (String) —

    locale name of locale or nil if request could not be satisfied.



316
317
318
 
# File 'lib/ffi-locale.rb', line 316

def setlocale(category, locale)
  FFI::Locale._setlocale(category, locale)
end