Guides.rubyonrails.org

Chapters

1. 如何加载核心扩展
   • 独立的 Active Support
   • 在 Rails 应用中使用 Active Support
2. 所有对象皆可使用的扩展
   • blank? 和 present?
   • presence
   • duplicable?
   • deep_dup
   • try
   • class_eval(*args, &block)
   • acts_like?(duck)
   • to_param
   • to_query
   • with_options
   • 对 JSON 的支持
   • 实例变量
   • 静默警告和异常
   • in?
3. Module 的扩展
   • alias_method_chain
   • 属性
   • 父级
   • 可达性
   • 匿名
   • 方法委托
   • 重新定义方法
4. Class 的扩展
   • 类属性
   • 子类和后代
5. String 的扩展
   • 输出的安全性
   • remove
   • squish
   • truncate
   • truncate_words
   • inquiry
   • starts_with? 和 ends_with?
   • strip_heredoc
   • indent
   • 访问
   • 词形变化
   • 转换
6. Numeric 的扩展
   • 字节
   • 时间
   • 格式化
7. Integer 的扩展
   • multiple_of?
   • ordinal
   • ordinalize
8. BigDecimal 的扩展
   • to_s
9. Enumerable 的扩展
   • sum
   • index_by
   • many?
   • exclude?
   • without
   • pluck
10. Array 的扩展
    • 访问
    • 添加元素
    • 选项提取
    • 转换
    • 包装
    • 复制
    • 分组
11. Hash 的扩展
    • 转换
    • 合并
    • 深度复制
    • 处理键
    • 处理值
    • 切片
    • 提取
    • 无差别访问
    • 压缩
12. Regexp 的扩展
    • multiline?
13. Range 的扩展
    • to_s
    • include?
    • overlaps?
14. Date 的扩展
    • 计算
15. DateTime 的扩展
    • 计算
16. Time 的扩展
    • 计算
    • 时间构造方法
17. File 的扩展
    • atomic_write
18. Marshal 的扩展
    • load
19. NameError 的扩展
20. LoadError 的扩展

1 如何加载核心扩展

1.1 独立的 Active Support

为了减轻应用的负担，默认情况下 Active Support 不会加载任何功能。Active Support 中的各部分功能是相对独立的，可以只加载需要的功能，也可以方便地加载相互联系的功能，或者加载全部功能。

因此，只编写下面这个 require 语句，对象甚至无法响应 blank? 方法：

我们来看一下到底应该如何加载。

1.1.1 按需加载

获取 blank? 方法最轻便的做法是按需加载其定义所在的文件。

本文为核心扩展中的每个方法都做了说明，告知是在哪个文件中定义的。对 blank? 方法而言，说明如下：

因此 blank? 方法要这么加载：

Active Support 的设计方式精良，确保按需加载时真的只加载所需的扩展。

1.1.2 成组加载核心扩展

下一层级是加载 Object 对象的所有扩展。一般来说，对 SomeClass 的扩展都保存在 active_support/core_ext/some_class 文件夹中。

因此，加载 Object 对象的所有扩展（包括 balnk? 方法）可以这么做：

1.1.3 加载所有扩展

如果想加载所有核心扩展，可以这么做：

1.1.4 加载 Active Support 提供的所有功能

最后，如果想使用 Active Support 提供的所有功能，可以这么做：

其实，这么做并不会把整个 Active Support 载入内存，有些功能通过 autoload 加载，所以真正使用时才会加载。

1.2 在 Rails 应用中使用 Active Support

除非把 config.active_support.bare 设为 true，否则 Rails 应用不会加载 Active Support 提供的所有功能。即便全部加载，应用也会根据框架的设置按需加载所需功能，而且应用开发者还可以根据需要做更细化的选择，方法如前文所述。

2 所有对象皆可使用的扩展

2.1 blank? 和 present?

在 Rails 应用中，下面这些值表示空值：

• nil 和 false；

• 只有空白的字符串（注意下面的说明）；

• 空数组和空散列；

• 其他能响应 empty? 方法，而且返回值为 true 的对象；

例如，ActionController::HttpAuthentication::Token::ControllerMethods 定义的这个方法使用 blank? 检查是否有令牌：

present? 方法等价于 !blank?。下面这个方法摘自 ActionDispatch::Http::Cache::Response：

2.2 presence

如果 present? 方法返回 true，presence 方法的返回值为调用对象，否则返回 nil。惯用法如下：

2.3 duplicable?

Ruby 中很多基本的对象是单例。例如，在应用的整个生命周期内，整数 1 始终表示同一个实例：

因此，这些对象无法通过 dup 或 clone 方法复制：

有些数字虽然不是单例，但也不能复制：

Active Support 提供的 duplicable? 方法用于查询对象是否可以复制：

按照定义，除了 nil、false、true、符号、数字、类、模块和方法对象之外，其他对象都可以复制。

2.4 deep_dup

deep_dup 方法深拷贝指定的对象。一般情况下，复制包含其他对象的对象时，Ruby 不会复制内部对象，这叫做浅拷贝。假如有一个由字符串组成的数组，浅拷贝的行为如下：

如上所示，复制数组后得到了一个新对象，修改新对象后原对象没有变化。但对数组中的元素来说情况就不一样了。因为 dup 方法不是深拷贝，所以数组中的字符串是同一个对象。

如果想深拷贝一个对象，应该使用 deep_dup 方法。举个例子：

如果对象不可复制，deep_dup 方法直接返回对象本身：

2.5 try

如果只想当对象不为 nil 时在其上调用方法，最简单的方式是使用条件语句，但这么做把代码变复杂了。你可以使用 try 方法。try 方法和 Object#send 方法类似，但如果在 nil 上调用，返回值为 nil。

举个例子：

下面这个例子摘自 ActiveRecord::ConnectionAdapters::AbstractAdapter，实例变量 @logger 有可能为 nil。可以看出，使用 try 方法可以避免不必要的检查。

try 方法也可接受代码块，仅当对象不为 nil 时才会执行其中的代码：

注意，try 会吞没没有方法错误，返回 nil。如果想避免此类问题，应该使用 try!：

2.6 class_eval(*args, &block)

使用 class_eval 方法可以在对象的单例类上下文中执行代码：

2.7 acts_like?(duck)

acts_like? 方法检查一个类的行为是否与另一个类相似。比较是基于一个简单的约定：如果在某个类中定义了下面这个方法，就说明其接口与字符串一样。

这个方法只是一个标记，其定义体和返回值不影响效果。开发者可使用下面这种方式判断两个类的表现是否类似：

Rails 使用这种约定定义了行为与 Date 和 Time 相似的类。

2.8 to_param

Rails 中的所有对象都能响应 to_param 方法。to_param 方法的返回值表示查询字符串的值，或者 URL 片段。

默认情况下，to_param 方法直接调用 to_s 方法：

to_param 方法的返回值不应该转义：

Rails 中的很多类都覆盖了这个方法。

例如，nil、true 和 false 返回自身。Array#to_param 在各个元素上调用 to_param 方法，然后使用 "/" 合并：

注意，Rails 的路由系统在模型上调用 to_param 方法获取占位符 :id 的值。ActiveRecord::Base#to_param 返回模型的 id，不过可以在模型中重新定义。例如，按照下面的方式重新定义：

效果如下：

2.9 to_query

除散列之外，传入未转义的 key，to_query 方法把 to_param 方法的返回值赋值给 key，组成查询字符串。例如，重新定义了 to_param 方法：

效果如下：

to_query 方法会根据需要转义键和值：

因此得到的值可以作为查询字符串使用。

Array#to_query 方法在各个元素上调用 to_query 方法，键为 _key_[]，然后使用 "&" 合并：

散列也响应 to_query 方法，但处理方式不一样。如果不传入参数，先在各个元素上调用 to_query(key)，得到一系列键值对赋值字符串，然后按照键的顺序排列，再使用 "&" 合并：

Hash#to_query 方法还有一个可选参数，用于指定键的命名空间：

2.10 with_options

with_options 方法把一系列方法调用中的通用选项提取出来。

使用散列指定通用选项后，with_options 方法会把一个代理对象拽入代码块。在代码块中，代理对象调用的方法会转发给调用者，并合并选项。例如，如下的代码

其中的重复可以使用 with_options 方法去除：

这种用法还可形成一种分组方式。假如想根据用户使用的语言发送不同的电子报，在邮件发送程序中可以根据用户的区域设置分组：

2.11 对 JSON 的支持

Active Support 实现的 to_json 方法比 json gem 更好用，这是因为 Hash、OrderedHash 和 Process::Status 等类转换成 JSON 时要做特别处理。

2.12 实例变量

Active Support 提供了很多便于访问实例变量的方法。

2.12.1 instance_values

instance_values 方法返回一个散列，把实例变量的名称（不含前面的 @ 符号）映射到其值上，键是字符串：

2.12.2 instance_variable_names

instance_variable_names 方法返回一个数组，实例变量的名称前面包含 @ 符号。

2.13 静默警告和异常

silence_warnings 和 enable_warnings 方法修改各自代码块的 $VERBOSE 全局变量，代码块结束后恢复原值：

异常消息也可静默，使用 suppress 方法即可。suppress 方法可接受任意个异常类。如果执行代码块的过程中抛出异常，而且异常属于（kind_of?）参数指定的类，suppress 方法会静默该异常类的消息，否则抛出异常：

2.14 in?

in? 方法测试某个对象是否在另一个对象中。如果传入的对象不能响应 include? 方法，抛出 ArgumentError 异常。

in? 方法使用举例：

3 Module 的扩展

3.1 alias_method_chain

在 Ruby 中，可以把方法包装成其他方法，这叫别名链（alias chain）。

例如，想在功能测试中把参数看做字符串，就像在真正的请求中一样，但希望保留赋值数字等值的便利，可以在文件 test/test_helper.rb 中包装 ActionDispatch::IntegrationTest#process 方法：

get、post 等方法就是委托这个方法实现的。

这种技术有个问题，:original_process 方法可能已经存在了。为了避免方法重名，人们者发明了一种链状结构：

alias_method_chain 方法可以简化上述过程：

3.2 属性

3.2.1 alias_attribute

模型的属性有读值方法、设值方法和判断方法。alias_attribute 方法可以一次性为这三种方法创建别名。和其他创建别名的方法一样，alias_attribute 方法的第一个参数是新属性名，第二个参数是旧属性名（我是这样记的，参数的顺序和赋值语句一样）：

3.2.2 内部属性

如果在父类中定义属性，有可能会出现命名冲突。代码库一定要注意这个问题。

Active Support 提供了 attr_internal_reader、attr_internal_writer 和 attr_internal_accessor 三个方法，其行为与 Ruby 内置的 attr_* 方法类似，但使用其他方式命名实例变量，从而减少重名的几率。

attr_internal 方法是 attr_internal_accessor 方法的别名：

在上面的例子中，:log_level 可能不属于代码库的公开接口，只在开发过程中使用。开发者并不知道潜在的重名风险，创建了子类，并在子类中定义了 :log_level。幸好用了 attr_internal 方法才不会出现命名冲突。

默认情况下，内部变量的名字前面有个下划线，上例中的内部变量名为 @_log_level。不过可使用 Module.attr_internal_naming_format 重新设置，可以传入任何 sprintf 方法能理解的格式，开头加上 @ 符号，并在某处放入 %s（代表原变量名）。默认的设置为 "@_%s"。

Rails 的代码很多地方都用到了内部属性，例如，在视图相关的代码中有如下代码：

3.2.3 模块属性

方法 mattr_reader、mattr_writer 和 mattr_accessor 类似于为类定义的 cattr_* 方法。其实 cattr_* 方法就是 mattr_* 方法的别名。参见 类属性。

例如，依赖机制就用到了这些方法：

3.3 父级

3.3.1 parent

在嵌套的具名模块上调用 parent 方法，返回包含对应常量的模块：

如果是匿名模块或者位于顶层，parent 方法返回 Object。

3.3.2 parent_name

在嵌套的具名模块上调用 parent_name 方法，返回包含对应常量的完全限定模块名：

如果是匿名模块或者位于顶层，parent_name 方法返回 nil。

3.3.3 parents

parents 方法在调用者上调用 parent 方法，直至 Object 为止。返回的结果是一个数组，由底而上：

3.3.4 限定的常量名

常规的 const_defined?、const_get 和 const_set 方法接受裸常量名。Active Support 扩展了这个 API，可以传入相对限定的常量名。

新定义的方法是 qualified_const_defined?、qualified_const_get 和 qualified_const_set。它们的参数应该是相对接收者的限定常量名：

参数也可以是裸常量名：

这些方法的行为与内置的对应方法类似。不过，qualified_constant_defined? 方法接受一个可选参数（第二个），指明判断时是否检查祖先树。沿路径检查时，表达式中的每个常量都会考虑这个参数。

例如：

此时，qualified_const_defined? 的行为如下：

如上例所示，第二个参数的默认值为 true，跟 const_defined? 一样。

为了与内置方法保持连贯，只接受相对路径。完全限定常量名，如 ::Math::PI，会抛出 NameError 异常。

3.4 可达性

如果把具名模块存储在相应的常量中，模块是可达的，意即可以通过常量访问模块对象。

通常，模块都是如此。如果有名为“M”的模块，M 常量就存在，指代那个模块：

但是，常量和模块其实是解耦的，因此模块对象也许不可达：

3.5 匿名

模块可能有也可能没有名称：

可以使用 anonymous? 方法判断模块有没有名称：

注意，不可达不意味着就是匿名的：

但是按照定义，匿名模块是不可达的。

3.6 方法委托

delegate 方法提供一种便利的方法转发方式。

假设在一个应用中，用户的登录信息存储在 User 模型中，而名字和其他数据存储在 Profile 模型中：

此时，要通过个人资料获取用户的名字，即 user.profile.name。不过，若能直接访问这些信息更为便利：

delegate 方法正是为这种需求而生的：

这样写出的代码更简洁，而且意图更明显。

委托的方法在目标中必须是公开的。

delegate 方法可接受多个参数，委托多个方法：

内插到字符串中时，:to 选项的值应该能求值为方法委托的对象。通常，使用字符串或符号。这个选项的值在接收者的上下文中求值：

默认情况下，如果委托导致 NoMethodError 抛出，而且目标是 nil，这个异常会向上冒泡。可以指定 :allow_nil 选项，遇到这种情况时返回 nil：

设定 :allow_nil 选项后，如果用户没有个人资料，user.name 返回 nil。

:prefix 选项在生成的方法前面添加一个前缀。如果想起个更好的名称，就可以使用这个选项：

上述示例生成的方法是 address_street，而不是 street。

此外，还可以自定义前缀：

在这个示例中，生成的方法是 avatar_size，而不是 size。

3.7 重新定义方法

有时需要使用 define_method 定义方法，但却不知道那个方法名是否已经存在。如果存在，而且启用了警告消息，会发出警告。这没什么，但却不够利落。

redefine_method 方法能避免这种警告，如果需要，会把现有的方法删除。

4 Class 的扩展

4.1 类属性

4.1.1 class_attribute

class_attribute 方法声明一个或多个可继承的类属性，它们可以在继承树的任一层级覆盖。

例如，ActionMailer::Base 定义了：

类属性还可以通过实例访问和覆盖：

把 :instance_writer 选项设为 false，不生成设值实例方法：

模型可以使用这个选项，禁止批量赋值属性。

把 :instance_reader 选项设为 false，不生成读值实例方法：

为了方便，class_attribute 还会定义实例判断方法，对实例读值方法的返回值做双重否定。在上例中，判断方法是 x?。

如果 :instance_reader 的值是 false，实例判断方法与读值方法一样，返回 NoMethodError。

如果不想要实例判断方法，传入 instance_predicate: false，这样就不会定义了。

4.1.2 cattr_reader、cattr_writer 和 cattr_accessor

cattr_reader、cattr_writer 和 cattr_accessor 的作用与相应的 attr_* 方法类似，不过是针对类的。它们声明的类属性，初始值为 nil，除非在此之前类属性已经存在，而且会生成相应的访问方法：

为了方便，也会生成实例方法，这些实例方法只是类属性的代理。因此，实例可以修改类属性，但是不能覆盖——这与 class_attribute 不同（参见上文）。例如：

这样，我们便可以在视图中访问 field_error_proc。

此外，可以把一个块传给 cattr_* 方法，设定属性的默认值：

把 :instance_reader 设为 false，不生成实例读值方法，把 :instance_writer 设为 false，不生成实例设值方法，把 :instance_accessor 设为 false，实例读值和设置方法都不生成。此时，这三个选项的值都必须是 false，而不能是假值。

在模型中可以把 :instance_accessor 设为 false，防止批量赋值属性。

4.2 子类和后代

4.2.1 subclasses

subclasses 方法返回接收者的子类：

返回的子类没有特定顺序。

4.2.2 descendants

descendants 方法返回接收者的后代：

返回的后代没有特定顺序。

5 String 的扩展

5.1 输出的安全性

5.1.1 引子

把数据插入 HTML 模板要格外小心。例如，不能原封不动地把 @review.title 内插到 HTML 页面中。假如标题是“Flanagan & Matz rules!”，得到的输出格式就不对，因为 & 会转义成“&”。更糟的是，如果应用编写不当，这可能留下严重的安全漏洞，因为用户可以注入恶意的 HTML，设定精心编造的标题。关于这个问题的详情，请阅读 安全指南对跨站脚本的说明。

5.1.2 安全字符串

Active Support 提出了安全字符串（对 HTML 而言）这一概念。安全字符串是对字符串做的一种标记，表示可以原封不动地插入 HTML。这种字符串是可信赖的，不管会不会转义。

默认，字符串被认为是不安全的：

可以使用 html_safe 方法把指定的字符串标记为安全的：

注意，无论如何，html_safe 不会执行转义操作，它的作用只是一种断定：

你要自己确定该不该在某个字符串上调用 html_safe。

如果把字符串追加到安全字符串上，不管是就地修改，还是使用 concat/<< 或 +，结果都是一个安全字符串。不安全的字符会转义：

安全的字符直接追加：

在常规的视图中不应该使用这些方法。不安全的值会自动转义：

如果想原封不动地插入值，不能调用 html_safe，而要使用 raw 辅助方法：

或者，可以使用等效的 <%==：

raw 辅助方法已经调用 html_safe 了：

5.1.3 转换

通常，修改字符串的方法都返回不安全的字符串，前文所述的拼接除外。例如，downcase、gsub、strip、chomp、underscore，等等。

就地转换接收者，如 gsub!，其本身也变成不安全的了。

5.1.4 类型转换和强制转换

在安全字符串上调用 to_s，得到的还是安全字符串，但是使用 to_str 强制转换，得到的是不安全的字符串。

5.1.5 复制

在安全字符串上调用 dup 或 clone，得到的还是安全字符串。

5.2 remove

remove 方法删除匹配模式的所有内容：

也有破坏性版本，String#remove!。

5.3 squish

squish 方法把首尾的空白去掉，还会把多个空白压缩成一个：

也有破坏性版本，String#squish!。

注意，既能处理 ASCII 空白，也能处理 Unicode 空白。

5.4 truncate

truncate 方法在指定长度处截断接收者，返回一个副本：

省略号可以使用 :omission 选项自定义：

尤其要注意，截断长度包含省略字符串。

设置 :separator 选项，以自然的方式截断：

:separator 选项的值可以是一个正则表达式：

在上述示例中，本该在“dear”中间截断，但是 :separator 选项进行了阻止。

5.5 truncate_words

truncate_words 方法在指定个单词处截断接收者，返回一个副本：

省略号可以使用 :omission 选项自定义：

设置 :separator 选项，以自然的方式截断：

:separator 选项的值可以是一个正则表达式：

5.6 inquiry

inquiry 方法把字符串转换成 StringInquirer 对象，这样可以使用漂亮的方式检查相等性：

5.7 starts_with? 和 ends_with?

Active Support 为 String#start_with? 和 String#end_with? 定义了第三人称版本：

5.8 strip_heredoc

strip_heredoc 方法去掉 here 文档中的缩进。

例如：

用户看到的消息会靠左边对齐。

从技术层面来说，这个方法寻找整个字符串中的最小缩进量，然后删除那么多的前导空白。

5.9 indent

按指定量缩进接收者：

第二个参数，indent_string，指定使用什么字符串缩进。默认值是 nil，让这个方法根据第一个缩进行做猜测，如果第一行没有缩进，则使用空白。

indent_string 的值虽然经常设为一个空格或一个制表符，但是可以使用任何字符串。

第三个参数，indent_empty_lines，是个旗标，指明是否缩进空行。默认值是 false。

indent! 方法就地执行缩进。

5.10 访问

5.10.1 at(position)

返回字符串中 position 位置上的字符：

5.10.2 from(position)

返回子串，从 position 位置开始：

5.10.3 to(position)

返回子串，到 position 位置为止：

5.10.4 first(limit = 1)

如果 n > 0，str.first(n) 的作用与 str.to(n-1) 一样；如果 n == 0，返回一个空字符串。

5.10.5 last(limit = 1)

如果 n > 0，str.last(n) 的作用与 str.from(-n) 一样；如果 n == 0，返回一个空字符串。

5.11 词形变化

5.11.1 pluralize

pluralize 方法返回接收者的复数形式：

如上例所示，Active Support 知道如何处理不规则的复数形式和不可数名词。内置的规则可以在 config/initializers/inflections.rb 文件中扩展。那个文件是由 rails 命令生成的，里面的注释说明了该怎么做。

pluralize 还可以接受可选的 count 参数。如果 count == 1，返回单数形式。把 count 设为其他值，都会返回复数形式：

Active Record 使用这个方法计算模型对应的默认表名：

5.11.2 singularize

作用与 pluralize 相反：

关联使用这个方法计算默认的关联类：

5.11.3 camelize

camelize 方法把接收者变成驼峰式：

一般来说，你可以把这个方法的作用想象为把路径转换成 Ruby 类或模块名的方式（使用斜线分隔命名空间）：

例如，Action Pack 使用这个方法加载提供特定会话存储功能的类：

camelize 接受一个可选的参数，其值可以是 :upper（默认值）或 :lower。设为后者时，第一个字母是小写的：

为使用这种风格的语言计算方法名时可以这么设定，例如 JavaScript。

ActiveSupport::Inflector.inflections do |inflect|   inflect.acronym 'SSL' end   "SSLError".underscore.camelize # => "SSLError"

camelcase 是 camelize 的别名。

5.11.4 underscore

underscore 方法的作用相反，把驼峰式变成蛇底式：

还会把 "::" 转换成 "/"：

也能理解以小写字母开头的字符串：

不过，underscore 不接受任何参数。

Rails 自动加载类和模块的机制使用 underscore 推断可能定义缺失的常量的文件的相对路径（不带扩展名）：

5.11.5 titleize

titleize 方法把接收者中的单词首字母变成大写：

titlecase 是 titleize 的别名。

5.11.6 dasherize

dasherize 方法把接收者中的下划线替换成连字符：

模型的 XML 序列化程序使用这个方法处理节点名：

5.11.7 demodulize

demodulize 方法返回限定常量名的常量名本身，即最右边那一部分：

例如，Active Record 使用这个方法计算计数器缓存列的名称：

5.11.8 deconstantize

deconstantize 方法去掉限定常量引用表达式的最右侧部分，留下常量的容器：

例如，Active Support 在 Module#qualified_const_set 中使用了这个方法：

5.11.9 parameterize

parameterize 方法对接收者做整形，以便在精美的 URL 中使用。

如果想保留大小写，把 preserve_case 参数设为 true。这个参数的默认值是 false。

如果想使用自定义的分隔符，覆盖 separator 参数。

其实，得到的字符串包装在 ActiveSupport::Multibyte::Chars 实例中。

5.11.10 tableize

tableize 方法相当于先调用 underscore，再调用 pluralize。

一般来说，tableize 返回简单模型对应的表名。Active Record 真正的实现方式不是只使用 tableize，还会使用 demodulize，再检查一些可能影响返回结果的选项。

5.11.11 classify

classify 方法的作用与 tableize 相反，返回表名对应的类名：

这个方法能处理限定的表名：

注意，classify 方法返回的类名是字符串。你可以调用 constantize 方法，得到真正的类对象，如下一节所述。

5.11.12 constantize

constantize 方法解析接收者中的常量引用表达式：

如果结果是未知的常量，或者根本不是有效的常量名，constantize 抛出 NameError 异常。

即便开头没有 ::，constantize 也始终从顶层的 Object 解析常量名。

因此，通常这与 Ruby 的处理方式不同，Ruby 会求值真正的常量。

邮件程序测试用例使用 constantize 方法从测试用例的名称中获取要测试的邮件程序：

5.11.13 humanize

humanize 方法对属性名做调整，以便显示给终端用户查看。

这个方法所做的转换如下：

• 根据参数做对人类友好的词形变化

• 删除前导下划线（如果有）

• 删除“_id”后缀（如果有）

• 把下划线替换成空格（如果有）

• 把所有单词变成小写，缩略词除外

• 把第一个单词的首字母变成大写

把 :capitalize 选项设为 false（默认值为 true）可以禁止把第一个单词的首字母变成大写。

如果把“SSL”定义为缩略词：

full_messages 辅助方法使用 humanize 作为一种后备机制，以便包含属性名：

5.11.14 foreign_key

foreign_key 方法根据类名计算外键列的名称。为此，它先调用 demodulize，再调用 underscore，最后加上“_id”：

如果不想添加“_id”中的下划线，传入 false 参数：

关联使用这个方法推断外键，例如 has_one 和 has_many 是这么做的：

5.12 转换

5.12.1 to_date、to_time、to_datetime

to_date、to_time 和 to_datetime 是对 Date._parse 的便利包装：

to_time 有个可选的参数，值为 :utc 或 :local，指明想使用的时区：

默认值是 :utc。

详情参见 Date._parse 的文档。

6 Numeric 的扩展

6.1 字节

所有数字都能响应下述方法：

这些方法返回相应的字节数，因子是 1024：

这些方法都有单数别名，因此可以这样用：

6.2 时间

用于计算和声明时间，例如 45.minutes + 2.hours + 4.years。

使用 from_now、ago 等精确计算日期，以及增减 Time 对象时使用 Time#advance。例如：

6.3 格式化

以各种形式格式化数字。

把数字转换成字符串表示形式，表示电话号码：

把数字转换成字符串表示形式，表示货币：

把数字转换成字符串表示形式，表示百分比：

把数字转换成字符串表示形式，以分隔符分隔：

把数字转换成字符串表示形式，以指定精度四舍五入：

把数字转换成字符串表示形式，得到人类可读的字节数：

把数字转换成字符串表示形式，得到人类可读的词：

7 Integer 的扩展

7.1 multiple_of?

multiple_of? 方法测试一个整数是不是参数的倍数：

7.2 ordinal

ordinal 方法返回整数接收者的序数词后缀（字符串）：

7.3 ordinalize

ordinalize 方法返回整数接收者的序数词（字符串）。注意，ordinal 方法只返回后缀。

8 BigDecimal 的扩展

8.1 to_s

to_s 方法把默认的说明符设为“F”。这意味着，不传入参数时，to_s 返回浮点数表示形式，而不是工程计数法。

说明符也可以使用符号：

也支持工程计数法：

9 Enumerable 的扩展

9.1 sum

sum 方法计算可枚举对象的元素之和：

只假定元素能响应 +：

空集合的元素之和默认为零，不过可以自定义：

如果提供块，sum 变成迭代器，把集合中的元素拽入块中，然后求返回值之和：

空接收者之和也可以使用这种方式自定义：

9.2 index_by

index_by 方法生成一个散列，使用某个键索引可枚举对象中的元素。

它迭代集合，把各个元素传入块中。元素使用块的返回值为键：

9.3 many?

many? 方法是 collection.size > 1 的简化：

如果提供可选的块，many? 只考虑返回 true 的元素：

9.4 exclude?

exclude? 方法测试指定对象是否不在集合中。这是内置方法 include? 的逆向判断。

9.5 without

without 从可枚举对象中删除指定的元素，然后返回副本：

9.6 pluck

pluck 方法基于指定的键返回一个数组：

10 Array 的扩展

10.1 访问

为了便于以多种方式访问数组，Active Support 增强了数组的 API。例如，若想获取到指定索引的子数组，可以这么做：

类似地，from 从指定索引一直获取到末尾。如果索引大于数组的长度，返回一个空数组。

second、third、fourth 和 fifth 分别返回对应的元素，second_to_last 和 third_to_last 也是（first 和 last 是内置的）。得益于公众智慧和积极的建设性建议，还有 forty_two 可用。

10.2 添加元素

10.2.1 prepend

这个方法是 Array#unshift 的别名。

10.2.2 append

这个方法是 Array#<< 的别名。

10.3 选项提取

如果方法调用的最后一个参数（不含 &block 参数）是散列，Ruby 允许省略花括号：

Rails 大量使用这种语法糖，以此避免编写大量位置参数，用于模仿具名参数。Rails 经常在最后一个散列选项上使用这种惯用法。

然而，如果方法期待任意个参数，在声明中使用 *，那么选项散列就会变成数组中一个元素，失去了应有的作用。

此时，可以使用 extract_options! 特殊处理选项散列。这个方法检查数组最后一个元素的类型，如果是散列，把它提取出来，并返回；否则，返回一个空散列。

下面以控制器的 caches_action 方法的定义为例：

这个方法接收任意个动作名，最后一个参数是选项散列。extract_options! 方法获取选项散列，把它从 actions 参数中删除，这样简单便利。

10.4 转换

10.4.1 to_sentence

to_sentence 方法枚举元素，把数组变成一个句子（字符串）：

这个方法接受三个选项：

• :two_words_connector：数组长度为 2 时使用什么词。默认为“ and”。

• :words_connector：数组元素数量为 3 个以上（含）时，使用什么连接除最后两个元素之外的元素。默认为“, ”。

• :last_word_connector：数组元素数量为 3 个以上（含）时，使用什么连接最后两个元素。默认为“, and”。

这些选项的默认值可以本地化，相应的键为：

选项	i18n 键
:two_words_connector	support.array.two_words_connector
:words_connector	support.array.words_connector
:last_word_connector	support.array.last_word_connector

10.4.2 to_formatted_s

默认情况下，to_formatted_s 的行为与 to_s 一样。

然而，如果数组中的元素能响应 id 方法，可以传入参数 :db。处理 Active Record 对象集合时经常如此。返回的字符串如下：

在上述示例中，整数是在元素上调用 id 得到的。

10.4.3 to_xml

to_xml 方法返回接收者的 XML 表述：

为此，它把 to_xml 分别发送给每个元素，然后收集结果，放在一个根节点中。所有元素都必须能响应 to_xml，否则抛出异常。

默认情况下，根元素的名称是第一个元素的类名的复数形式经过 underscore 和 dasherize 处理后得到的值——前提是余下的元素属于那个类型（使用 is_a? 检查），而且不是散列。在上例中，根元素是“contributors”。

只要有不属于那个类型的元素，根元素就使用“objects”：

如果接收者是由散列组成的数组，根元素默认也是“objects”：

子节点的名称默认为根节点的单数形式。在前面几个例子中，我们见到的是“contributor”和“object”。可以使用 :children 选项设定子节点的名称。

默认的 XML 构建程序是一个新的 Builder::XmlMarkup 实例。可以使用 :builder 选项指定构建程序。这个方法还接受 :dasherize 等方法，它们会被转发给构建程序。

10.5 包装

Array.wrap 方法把参数包装成一个数组，除非参数已经是数组（或与数组类似的结构）。

具体而言：

• 如果参数是 nil，返回一个空数组。

• 否则，如果参数响应 to_ary 方法，调用之；如果 to_ary 返回值不是 nil，返回之。

• 否则，把参数作为数组的唯一元素，返回之。

这个方法的作用与 Kernel#Array 类似，不过二者之间有些区别：

• 如果参数响应 to_ary，调用之。如果 to_ary 的返回值是 nil，Kernel#Array 接着调用 to_a，而 Array.wrap 把参数作为数组的唯一元素，返回之。

• 如果 to_ary 的返回值既不是 nil，也不是 Array 对象，Kernel#Array 抛出异常，而 Array.wrap 不会，它返回那个值。

• 如果参数不响应 to_ary，Array.wrap 不在参数上调用 to_a，而是把参数作为数组的唯一元素，返回之。

对某些可枚举对象来说，最后一点尤为重要：

还有一种惯用法是使用星号运算符：

在 Ruby 1.8 中，如果参数是 nil，返回 [nil]，否则调用 Array(object)。（如果你知道在 Ruby 1.9 中的行为，请联系 fxn。）

因此，参数为 nil 时二者的行为不同，前文对 Kernel#Array 的说明适用于其他对象。

10.6 复制

Array#deep_dup 方法使用 Active Support 提供的 Object#deep_dup 方法复制数组自身和里面的对象。其工作方式相当于通过 Array#map 把 deep_dup 方法发给里面的各个对象。

10.7 分组

10.7.1 in_groups_of(number, fill_with = nil)

in_groups_of 方法把数组拆分成特定长度的连续分组，返回由各分组构成的数组：

如果有块，把各分组拽入块中：

第一个示例说明 in_groups_of 会使用 nil 元素填充最后一组，得到指定大小的分组。可以使用第二个参数（可选的）修改填充值：

如果传入 false，不填充最后一组：

因此，false 不能作为填充值使用。

10.7.2 in_groups(number, fill_with = nil)

in_groups 方法把数组分成特定个分组。这个方法返回由分组构成的数组：

如果有块，把分组拽入块中：

在上述示例中，in_groups 使用 nil 填充尾部的分组。一个分组至多有一个填充值，而且是最后一个元素。有填充值的始终是最后几个分组。

可以使用第二个参数（可选的）修改填充值：

如果传入 false，不填充较短的分组：

因此，false 不能作为填充值使用。

10.7.3 split(value = nil)

split 方法在指定的分隔符处拆分数组，返回得到的片段。

如果有块，使用块中表达式返回 true 的元素作为分隔符：

否则，使用指定的参数（默认为 nil）作为分隔符：

11 Hash 的扩展

11.1 转换

11.1.1 to_xml

to_xml 方法返回接收者的 XML 表述（字符串）：

为此，这个方法迭代各个键值对，根据值构建节点。假如键值对是 key, value：

• 如果 value 是一个散列，递归调用，此时 key 作为 :root。

• 如果 value 是一个数组，递归调用，此时 key 作为 :root，key 的单数形式作为 :children。

• 如果 value 是可调用对象，必须能接受一个或两个参数。根据参数的数量，传给可调用对象的第一个参数是 options 散列，key 作为 :root，key 的单数形式作为第二个参数。它的返回值作为新节点。

• 如果 value 响应 to_xml，调用这个方法时把 key 作为 :root。

• 否则，使用 key 为标签创建一个节点，value 的字符串表示形式为文本作为节点的文本。如果 value 是 nil，添加“nil”属性，值为“true”。除非有 :skip_type 选项，而且值为 true，否则还会根据下述对应关系添加“type”属性：

  XML_TYPE_NAMES = {   "Symbol"     => "symbol",   "Integer"    => "integer",   "BigDecimal" => "decimal",   "Float"      => "float",   "TrueClass"  => "boolean",   "FalseClass" => "boolean",   "Date"       => "date",   "DateTime"   => "datetime",   "Time"       => "datetime" }

默认情况下，根节点是“hash”，不过可以通过 :root 选项配置。

默认的 XML 构建程序是一个新的 Builder::XmlMarkup 实例。可以使用 :builder 选项配置构建程序。这个方法还接受 :dasherize 等选项，它们会被转发给构建程序。

11.2 合并

Ruby 有个内置的方法，Hash#merge，用于合并两个散列：

为了方便，Active Support 定义了几个用于合并散列的方法。

11.2.1 reverse_merge 和 reverse_merge!

如果键有冲突，merge 方法的参数中的键胜出。通常利用这一点为选项散列提供默认值：

Active Support 定义了 reverse_merge 方法，以防你想使用相反的合并方式：

还有一个爆炸版本，reverse_merge!，就地执行合并：

11.2.2 reverse_update

reverse_update 方法是 reverse_merge! 的别名，作用参见前文。

11.2.3 deep_merge 和 deep_merge!

如前面的示例所示，如果两个散列中有相同的键，参数中的散列胜出。

Active Support 定义了 Hash#deep_merge 方法。在深度合并中，如果两个散列中有相同的键，而且它们的值都是散列，那么在得到的散列中，那个键的值是合并后的结果：

deep_merge! 方法就地执行深度合并。

11.3 深度复制

Hash#deep_dup 方法使用 Active Support 提供的 Object#deep_dup 方法复制散列自身及里面的键值对。其工作方式相当于通过 Enumerator#each_with_object 把 deep_dup 方法发给各个键值对。

11.4 处理键

11.4.1 except 和 except!

except 方法返回一个散列，从接收者中把参数中列出的键删除（如果有的话）：

如果接收者响应 convert_key 方法，会在各个参数上调用它。这样 except 能更好地处理不区分键类型的散列，例如：

还有爆炸版本，except!，就地从接收者中删除键。

11.4.2 transform_keys 和 transform_keys!

transform_keys 方法接受一个块，使用块中的代码处理接收者的键：

遇到冲突的键时，只会从中选择一个。选择哪个值并不确定。

这个方法可以用于构建特殊的转换方式。例如，stringify_keys 和 symbolize_keys 使用 transform_keys 转换键：

还有爆炸版本，transform_keys!，就地使用块中的代码处理接收者的键。

此外，可以使用 deep_transform_keys 和 deep_transform_keys! 把块应用到指定散列及其嵌套的散列的所有键上。例如：

11.4.3 stringify_keys 和 stringify_keys!

stringify_keys 把接收者中的键都变成字符串，然后返回一个散列。为此，它在键上调用 to_s。

遇到冲突的键时，只会从中选择一个。选择哪个值并不确定。

使用这个方法，选项既可以是符号，也可以是字符串。例如 ActionView::Helpers::FormHelper 定义的这个方法：

因为有第二行，所以用户可以传入 :type 或 "type"。

也有爆炸版本，stringify_keys!，直接把接收者的键变成字符串。

此外，可以使用 deep_stringify_keys 和 deep_stringify_keys! 把指定散列及其中嵌套的散列的键全都转换成字符串。例如：

11.4.4 symbolize_keys 和 symbolize_keys!

symbolize_keys 方法把接收者中的键尽量变成符号。为此，它在键上调用 to_sym。

遇到冲突的键时，只会从中选择一个。选择哪个值并不确定。

使用这个方法，选项既可以是符号，也可以是字符串。例如 ActionController::UrlRewriter 定义的这个方法：

因为有第二行，所以用户可以传入 :params 或 "params"。

也有爆炸版本，symbolize_keys!，直接把接收者的键变成符号。

此外，可以使用 deep_symbolize_keys 和 deep_symbolize_keys! 把指定散列及其中嵌套的散列的键全都转换成符号。例如：

11.4.5 to_options 和 to_options!

to_options 和 to_options! 分别是 symbolize_keys and symbolize_keys! 的别名。

11.4.6 assert_valid_keys

assert_valid_keys 方法的参数数量不定，检查接收者的键是否在白名单之外。如果是，抛出 ArgumentError 异常。

例如，Active Record 构建关联时不接受未知的选项。这个功能就是通过 assert_valid_keys 实现的。

11.5 处理值

11.5.1 transform_values 和 transform_values!

transform_values 的参数是一个块，使用块中的代码处理接收者中的各个值。

也有爆炸版本，transform_values!，就地处理接收者的值。

11.6 切片

Ruby 原生支持从字符串和数组中提取切片。Active Support 为散列增加了这个功能：

如果接收者响应 convert_key，会使用它对键做整形：

也有 slice!，它就地执行切片，返回被删除的键值对：

11.7 提取

extract! 方法删除并返回匹配指定键的键值对。

extract! 方法的返回值类型与接收者一样，是 Hash 或其子类。

11.8 无差别访问

with_indifferent_access 方法把接收者转换成 ActiveSupport::HashWithIndifferentAccess 实例：

11.9 压缩

compact 和 compact! 方法返回没有 nil 值的散列：

12 Regexp 的扩展

12.1 multiline?

multiline? 方法判断正则表达式有没有设定 /m 旗标，即点号是否匹配换行符。

Rails 只在一处用到了这个方法，也在路由代码中。路由的条件不允许使用多行正则表达式，这个方法简化了这一约束的实施。

13 Range 的扩展

13.1 to_s

Active Support 扩展了 Range#to_s 方法，让它接受一个可选的格式参数。目前，唯一支持的非默认格式是 :db：

如上例所示，:db 格式生成一个 BETWEEN SQL 子句。Active Record 使用它支持范围值条件。

13.2 include?

Range#include? 和 Range#=== 方法判断值是否在值域的范围内：

Active Support 扩展了这两个方法，允许参数为另一个值域。此时，测试参数指定的值域是否在接收者的范围内：

13.3 overlaps?

Range#overlaps? 方法测试两个值域是否有交集：

14 Date 的扩展

14.1 计算

14.1.1 Date.current

Active Support 定义的 Date.current 方法表示当前时区中的今天。其作用类似于 Date.today，不过会考虑用户设定的时区（如果定义了时区的话）。Active Support 还定义了 Date.yesterday 和 Date.tomorrow，以及实例判断方法 past?、today?、future?、on_weekday? 和 on_weekend?，这些方法都与 Date.current 相关。

比较日期时，如果要考虑用户设定的时区，应该使用 Date.current，而不是 Date.today。与系统的时区（Date.today 默认采用）相比，用户设定的时区可能超前，这意味着，Date.today 可能等于 Date.yesterday。

14.1.2 具名日期

14.1.2.1 prev_year、next_year

在 Ruby 1.9 中，prev_year 和 next_year 方法返回前一年和下一年中的相同月和日：

如果是润年的 2 月 29 日，得到的是 28 日：

last_year 是 prev_year 的别名。

14.1.2.2 prev_month、next_month

在 Ruby 1.9 中，prev_month 和 next_month 方法分别返回前一个月和后一个月中的相同日：

如果日不存在，返回前一月中的最后一天：

last_month 是 prev_month 的别名。

14.1.2.3 prev_quarter、next_quarter

类似于 prev_month 和 next_month，返回前一季度和下一季度中的相同日：

如果日不存在，返回前一月中的最后一天：

last_quarter 是 prev_quarter 的别名。

14.1.2.4 beginning_of_week、end_of_week

beginning_of_week 和 end_of_week 方法分别返回某一周的第一天和最后一天的日期。一周假定从周一开始，不过这是可以修改的，方法是在线程中设定 Date.beginning_of_week 或 config.beginning_of_week。

at_beginning_of_week 是 beginning_of_week 的别名，at_end_of_week 是 end_of_week 的别名。

14.1.2.5 monday、sunday

monday 和 sunday 方法分别返回前一个周一和下一个周日的日期：

14.1.2.6 prev_week、next_week

next_week 的参数是一个符号，指定周几的英文名称（默认为线程中的 Date.beginning_of_week 或 config.beginning_of_week，或者 :monday），返回那一天的日期。

prev_week 的作用类似：

last_week 是 prev_week 的别名。

设定 Date.beginning_of_week 或 config.beginning_of_week 之后，next_week 和 prev_week 能按预期工作。

14.1.2.7 beginning_of_month、end_of_month

beginning_of_month 和 end_of_month 方法分别返回某个月的第一天和最后一天的日期：

at_beginning_of_month 是 beginning_of_month 的别名，at_end_of_month 是 end_of_month 的别名。

14.1.2.8 beginning_of_quarter、end_of_quarter

beginning_of_quarter 和 end_of_quarter 分别返回接收者日历年的季度第一天和最后一天的日期：

at_beginning_of_quarter 是 beginning_of_quarter 的别名，at_end_of_quarter 是 end_of_quarter 的别名。

14.1.2.9 beginning_of_year、end_of_year

beginning_of_year 和 end_of_year 方法分别返回一年的第一天和最后一天的日期：

at_beginning_of_year 是 beginning_of_year 的别名，at_end_of_year 是 end_of_year 的别名。

14.1.3 其他日期计算方法

14.1.3.1 years_ago、years_since

years_ago 方法的参数是一个数字，返回那么多年以前同一天的日期：

years_since 方法向前移动时间：

如果那一天不存在，返回前一个月的最后一天：

14.1.3.2 months_ago、months_since

months_ago 和 months_since 方法的作用类似，不过是针对月的：

如果那一天不存在，返回前一个月的最后一天：

14.1.3.3 weeks_ago

weeks_ago 方法的作用类似，不过是针对周的：

14.1.3.4 advance

跳到另一天最普适的方法是 advance。这个方法的参数是一个散列，包含 :years、:months、:weeks、:days 键，返回移动相应量之后的日期。

如上例所示，增量可以是负数。

这个方法做计算时，先增加年，然后是月和周，最后是日。这个顺序是重要的，向一个月的末尾流动。假如我们在 2010 年 2 月的最后一天，我们想向前移动一个月和一天。

此时，advance 先向前移动一个月，然后移动一天，结果是：

如果以其他方式移动，得到的结果就不同了：

14.1.4 修改日期组成部分

change 方法在接收者的基础上修改日期，修改的值由参数指定：

这个方法无法容错不存在的日期，如果修改无效，抛出 ArgumentError 异常：

14.1.5 时间跨度

可以为日期增加或减去时间跨度：

增加跨度会调用 since 或 advance。例如，跳跃时能正确考虑历法改革：

14.1.6 时间戳

14.1.6.1 beginning_of_day、end_of_day

beginning_of_day 方法返回一天的起始时间戳（00:00:00）：

end_of_day 方法返回一天的结束时间戳（23:59:59）：

at_beginning_of_day、midnight 和 at_midnight 是 beginning_of_day 的别名，

14.1.6.2 beginning_of_hour、end_of_hour

beginning_of_hour 返回一小时的起始时间戳（hh:00:00）：

end_of_hour 方法返回一小时的结束时间戳（hh:59:59）：

at_beginning_of_hour 是 beginning_of_hour 的别名。

14.1.6.3 beginning_of_minute、end_of_minute

beginning_of_minute 方法返回一分钟的起始时间戳（hh:mm:00）：

end_of_minute 方法返回一分钟的结束时间戳（hh:mm:59）：

at_beginning_of_minute 是 beginning_of_minute 的别名。

14.1.6.4 ago、since

ago 的参数是秒数，返回自午夜起那么多秒之后的时间戳：

类似的，since 向前移动：

15 DateTime 的扩展

15.1 计算

DateTime 类是 Date 的子类，因此加载 active_support/core_ext/date/calculations.rb 时也就继承了下述方法及其别名，只不过，此时都返回 DateTime 对象：

下述方法重新实现了，因此使用它们时无需加载 active_support/core_ext/date/calculations.rb：

此外，还定义了 advance 和 change 方法，而且支持更多选项。参见下文。

下述方法只在 active_support/core_ext/date_time/calculations.rb 中实现，因为它们只对 DateTime 实例有意义：

15.1.1 具名日期时间

15.1.1.1 DateTime.current

Active Support 定义的 DateTime.current 方法类似于 Time.now.to_datetime，不过会考虑用户设定的时区（如果定义了时区的话）。Active Support 还定义了 DateTime.yesterday 和 DateTime.tomorrow，以及与 DateTime.current 相关的判断方法 past? 和 future?。

15.1.2 其他扩展

15.1.2.1 seconds_since_midnight

seconds_since_midnight 方法返回自午夜起的秒数：

15.1.2.2 utc

utc 返回的日期时间与接收者一样，不过使用 UTC 表示。

这个方法有个别名，getutc。

15.1.2.3 utc?

utc? 判断接收者的时区是不是 UTC：

15.1.2.4 advance

跳到其他日期时间最普适的方法是 advance。这个方法的参数是一个散列，包含 :years、:months、:weeks、:days、:hours、:minutes 和 :seconds 等键，返回移动相应量之后的日期时间。

这个方法计算目标日期时，把 :years、:months、:weeks 和 :days 传给 Date#advance，然后调用 since 处理时间，前进相应的秒数。这个顺序是重要的，如若不然，在某些边缘情况下可能得到不同的日期时间。讲解 Date#advance 时所举的例子在这里也适用，我们可以扩展一下，显示处理时间的顺序。

如果先移动日期部分（如前文所述，处理日期的顺序也很重要），然后再计算时间，得到的结果如下：

但是如果以其他方式计算，结果就不同了：

15.1.3 修改日期时间组成部分

change 方法在接收者的基础上修改日期时间，修改的值由选项指定，可以包括 :year、:month、:day、:hour、:min、:sec、:offset 和 :start：

如果小时归零了，分钟和秒也归零（除非指定了值）：

类似地，如果分钟归零了，秒也归零（除非指定了值）：

这个方法无法容错不存在的日期，如果修改无效，抛出 ArgumentError 异常：

15.1.4 时间跨度

可以为日期时间增加或减去时间跨度：

增加跨度会调用 since 或 advance。例如，跳跃时能正确考虑历法改革：

16 Time 的扩展

16.1 计算

Active Support 为 Time 添加了 DateTime 的很多方法：

它们的作用与之前类似。详情参见前文，不过要知道下述区别：

• change 额外接受 :usec 选项。

• Time 支持夏令时，因此能正确计算夏令时。

  Time.zone_default # => #<ActiveSupport::TimeZone:0x7f73654d4f38 @utc_offset=nil, @name="Madrid", ...>   # 因为采用夏令时，在巴塞罗那，2010/03/28 02:00 +0100 变成 2010/03/28 03:00 +0200 t = Time.local(2010, 3, 28, 1, 59, 59) # => Sun Mar 28 01:59:59 +0100 2010 t.advance(seconds: 1) # => Sun Mar 28 03:00:00 +0200 2010

• 如果 since 或 ago 的目标时间无法使用 Time 对象表示，返回一个 DateTime 对象。

16.1.1 Time.current

Active Support 定义的 Time.current 方法表示当前时区中的今天。其作用类似于 Time.now，不过会考虑用户设定的时区（如果定义了时区的话）。Active Support 还定义了与 Time.current 有关的实例判断方法 past?、today? 和 future?。

比较时间时，如果要考虑用户设定的时区，应该使用 Time.current，而不是 Time.now。与系统的时区（Time.now 默认采用）相比，用户设定的时区可能超前，这意味着，Time.now.to_date 可能等于 Date.yesterday。

16.1.2 all_day、all_week、all_month、all_quarter 和 all_year

all_day 方法返回一个值域，表示当前时间的一整天。

类似地，all_week、all_month、all_quarter 和 all_year 分别生成相应的时间值域。

16.2 时间构造方法

Active Support 定义的 Time.current 方法，在用户设定了时区时，等价于 Time.zone.now，否则回落到 Time.now：

与 DateTime 一样，判断方法 past? 和 future? 与 Time.current 相关。

如果要构造的时间超出了运行时平台对 Time 的支持范围，微秒会被丢掉，然后返回 DateTime 对象。

16.2.1 时间跨度

可以为时间增加或减去时间跨度：

增加跨度会调用 since 或 advance。例如，跳跃时能正确考虑历法改革：

17 File 的扩展

17.1 atomic_write

使用类方法 File.atomic_write 写文件时，可以避免在写到一半时读取内容。

这个方法的参数是文件名，它会产出一个文件句柄，把文件打开供写入。块执行完毕后，atomic_write 会关闭文件句柄，完成工作。

例如，Action Pack 使用这个方法写静态资源缓存文件，如 all.css：

为此，atomic_write 会创建一个临时文件。块中的代码其实是向这个临时文件写入。写完之后，重命名临时文件，这在 POSIX 系统中是原子操作。如果目标文件存在，atomic_write 将其覆盖，并且保留属主和权限。不过，有时 atomic_write 无法修改文件的归属或权限。这个错误会被捕获并跳过，从而确保需要它的进程能访问它。

临时文件在存储临时文件的标准目录中，但是可以传入第二个参数指定一个目录。

18 Marshal 的扩展

18.1 load

Active Support 为 load 增加了常量自动加载功能。

例如，文件缓存存储像这样反序列化：

如果缓存的数据指代那一刻未知的常量，自动加载机制会被触发，如果成功加载，会再次尝试反序列化。

19 NameError 的扩展

Active Support 为 NameError 增加了 missing_name? 方法，测试异常是不是由于参数的名称引起的。

参数的名称可以使用符号或字符串指定。指定符号时，使用裸常量名测试；指定字符串时，使用完全限定常量名测试。

例如，调用 ArticlesController 的动作时，Rails 会乐观地使用 ArticlesHelper。如果那个模块不存在也没关系，因此，由那个常量名引起的异常要静默。不过，可能是由于确实是未知的常量名而由 articles_helper.rb 抛出的 NameError 异常。此时，异常应该抛出。missing_name? 方法能区分这两种情况：

20 LoadError 的扩展

Active Support 为 LoadError 增加了 is_missing? 方法。

is_missing? 方法判断异常是不是由指定路径名（不含“.rb”扩展名）引起的。

例如，调用 ArticlesController 的动作时，Rails 会尝试加载 articles_helper.rb，但是那个文件可能不存在。这没关系，辅助模块不是必须的，因此 Rails 会静默加载错误。但是，有可能是辅助模块存在，而它引用的其他库不存在。此时，Rails 必须抛出异常。is_missing? 方法能区分这两种情况：

反馈

我们鼓励您帮助提高本指南的质量。

如果看到如何错字或错误，请反馈给我们。 您可以阅读我们的文档贡献指南。

您还可能会发现内容不完整或不是最新版本。 请添加缺失文档到 master 分支。请先确认 Edge Guides 是否已经修复。 关于用语约定，请查看Ruby on Rails 指南指导。

无论什么原因，如果你发现了问题但无法修补它，请创建 issue。

最后，欢迎到 rubyonrails-docs 邮件列表参与任何有关 Ruby on Rails 文档的讨论。

中文翻译反馈

贡献：https://github.com/ruby-china/guides。