Returns a new 2-element Array containing the minimum and maximum values from self
, either per method <=>
or per a given block:.
When no block is given, each element in self
must respond to method <=>
with an Integer; returns a new 2-element Array containing the minimum and maximum values from self
, per method <=>
:
[0, 1, 2].minmax # => [0, 2]
When a block is given, the block must return an Integer; the block is called self.size-1
times to compare elements; returns a new 2-element Array containing the minimum and maximum values from self
, per the block:
['0', '00', '000'].minmax {|a, b| a.size <=> b.size } # => ["0", "000"]
Returns a two element array which contains the minimum and the maximum value in the range.
Can be given an optional block to override the default comparison method a <=> b
.
Returns a two element array which contains the minimum and the maximum value in the enumerable. The first form assumes all objects implement <=>
; the second uses the block to return a <=> b.
a = %w(albatross dog horse) a.minmax #=> ["albatross", "horse"] a.minmax { |a, b| a.length <=> b.length } #=> ["dog", "albatross"]
Returns a two element array containing the objects in enum that correspond to the minimum and maximum values respectively from the given block.
If no block is given, an enumerator is returned instead.
a = %w(albatross dog horse) a.minmax_by { |x| x.length } #=> ["dog", "albatross"]
Sets the minimum and maximum supported protocol versions. See min_version=
and max_version=
.
Objects of class Binding
encapsulate the execution context at some particular place in the code and retain this context for future use. The variables, methods, value of self
, and possibly an iterator block that can be accessed in this context are all retained. Binding
objects can be created using Kernel#binding
, and are made available to the callback of Kernel#set_trace_func
and instances of TracePoint
.
These binding objects can be passed as the second argument of the Kernel#eval
method, establishing an environment for the evaluation.
class Demo def initialize(n) @secret = n end def get_binding binding end end k1 = Demo.new(99) b1 = k1.get_binding k2 = Demo.new(-3) b2 = k2.get_binding eval("@secret", b1) #=> 99 eval("@secret", b2) #=> -3 eval("@secret") #=> nil
Binding
objects have no class-specific methods.
Raised when attempting to convert special float values (in particular Infinity
or NaN
) to numerical classes which don’t support them.
Float::INFINITY.to_r #=> FloatDomainError: Infinity
mkmf.rb is used by Ruby C extensions to generate a Makefile which will correctly compile and link the C extension to Ruby and a third-party library.
Raised when a gem dependencies file specifies a ruby version that does not match the current version.
Holds Integer
values. You cannot add a singleton method to an Integer
object, any attempt to do so will raise a TypeError
.
A String
object holds and manipulates an arbitrary sequence of bytes, typically representing characters. String
objects may be created using String::new
or as literals.
Because of aliasing issues, users of strings should be aware of the methods that modify the contents of a String
object. Typically, methods with names ending in “!” modify their receiver, while those without a “!” return a new String
. However, there are exceptions, such as String#[]=
.
Continuation
objects are generated by Kernel#callcc
, after having +require+d continuation. They hold a return address and execution context, allowing a nonlocal return to the end of the callcc
block from anywhere within a program. Continuations are somewhat analogous to a structured version of C’s setjmp/longjmp
(although they contain more state, so you might consider them closer to threads).
For instance:
require "continuation" arr = [ "Freddie", "Herbie", "Ron", "Max", "Ringo" ] callcc{|cc| $cc = cc} puts(message = arr.shift) $cc.call unless message =~ /Max/
produces:
Freddie Herbie Ron Max
Also you can call callcc in other methods:
require "continuation" def g arr = [ "Freddie", "Herbie", "Ron", "Max", "Ringo" ] cc = callcc { |cc| cc } puts arr.shift return cc, arr.size end def f c, size = g c.call(c) if size > 1 end f
This (somewhat contrived) example allows the inner loop to abandon processing early:
require "continuation" callcc {|cont| for i in 0..4 print "#{i}: " for j in i*5...(i+1)*5 cont.call() if j == 17 printf "%3d", j end end } puts
produces:
0: 0 1 2 3 4 1: 5 6 7 8 9 2: 10 11 12 13 14 3: 15 16
An Encoding
instance represents a character encoding usable in Ruby. It is defined as a constant under the Encoding
namespace. It has a name and optionally, aliases:
Encoding::ISO_8859_1.name #=> "ISO-8859-1" Encoding::ISO_8859_1.names #=> ["ISO-8859-1", "ISO8859-1"]
Ruby methods dealing with encodings return or accept Encoding
instances as arguments (when a method accepts an Encoding
instance as an argument, it can be passed an Encoding
name or alias instead).
"some string".encoding #=> #<Encoding:UTF-8> string = "some string".encode(Encoding::ISO_8859_1) #=> "some string" string.encoding #=> #<Encoding:ISO-8859-1> "some string".encode "ISO-8859-1" #=> "some string"
Encoding::ASCII_8BIT is a special encoding that is usually used for a byte string, not a character string. But as the name insists, its characters in the range of ASCII are considered as ASCII characters. This is useful when you use ASCII-8BIT characters with other ASCII compatible characters.
The associated Encoding
of a String
can be changed in two different ways.
First, it is possible to set the Encoding
of a string to a new Encoding
without changing the internal byte representation of the string, with String#force_encoding
. This is how you can tell Ruby the correct encoding of a string.
string #=> "R\xC3\xA9sum\xC3\xA9" string.encoding #=> #<Encoding:ISO-8859-1> string.force_encoding(Encoding::UTF_8) #=> "R\u00E9sum\u00E9"
Second, it is possible to transcode a string, i.e. translate its internal byte representation to another encoding. Its associated encoding is also set to the other encoding. See String#encode
for the various forms of transcoding, and the Encoding::Converter
class for additional control over the transcoding process.
string #=> "R\u00E9sum\u00E9" string.encoding #=> #<Encoding:UTF-8> string = string.encode!(Encoding::ISO_8859_1) #=> "R\xE9sum\xE9" string.encoding #=> #<Encoding::ISO-8859-1>
All Ruby script code has an associated Encoding
which any String
literal created in the source code will be associated to.
The default script encoding is Encoding::UTF_8 after v2.0, but it can be changed by a magic comment on the first line of the source code file (or second line, if there is a shebang line on the first). The comment must contain the word coding
or encoding
, followed by a colon, space and the Encoding
name or alias:
# encoding: UTF-8 "some string".encoding #=> #<Encoding:UTF-8>
The __ENCODING__
keyword returns the script encoding of the file which the keyword is written:
# encoding: ISO-8859-1 __ENCODING__ #=> #<Encoding:ISO-8859-1>
ruby -K
will change the default locale encoding, but this is not recommended. Ruby source files should declare its script encoding by a magic comment even when they only depend on US-ASCII strings or regular expressions.
The default encoding of the environment. Usually derived from locale.
see Encoding.locale_charmap
, Encoding.find
(‘locale’)
The default encoding of strings from the filesystem of the environment. This is used for strings of file names or paths.
see Encoding.find
(‘filesystem’)
Each IO
object has an external encoding which indicates the encoding that Ruby will use to read its data. By default Ruby sets the external encoding of an IO
object to the default external encoding. The default external encoding is set by locale encoding or the interpreter -E
option. Encoding.default_external
returns the current value of the external encoding.
ENV["LANG"] #=> "UTF-8" Encoding.default_external #=> #<Encoding:UTF-8> $ ruby -E ISO-8859-1 -e "p Encoding.default_external" #<Encoding:ISO-8859-1> $ LANG=C ruby -e 'p Encoding.default_external' #<Encoding:US-ASCII>
The default external encoding may also be set through Encoding.default_external=
, but you should not do this as strings created before and after the change will have inconsistent encodings. Instead use ruby -E
to invoke ruby with the correct external encoding.
When you know that the actual encoding of the data of an IO
object is not the default external encoding, you can reset its external encoding with IO#set_encoding
or set it at IO
object creation (see IO.new
options).
To process the data of an IO
object which has an encoding different from its external encoding, you can set its internal encoding. Ruby will use this internal encoding to transcode the data when it is read from the IO
object.
Conversely, when data is written to the IO
object it is transcoded from the internal encoding to the external encoding of the IO
object.
The internal encoding of an IO
object can be set with IO#set_encoding
or at IO
object creation (see IO.new
options).
The internal encoding is optional and when not set, the Ruby default internal encoding is used. If not explicitly set this default internal encoding is nil
meaning that by default, no transcoding occurs.
The default internal encoding can be set with the interpreter option -E
. Encoding.default_internal
returns the current internal encoding.
$ ruby -e 'p Encoding.default_internal' nil $ ruby -E ISO-8859-1:UTF-8 -e "p [Encoding.default_external, \ Encoding.default_internal]" [#<Encoding:ISO-8859-1>, #<Encoding:UTF-8>]
The default internal encoding may also be set through Encoding.default_internal=
, but you should not do this as strings created before and after the change will have inconsistent encodings. Instead use ruby -E
to invoke ruby with the correct internal encoding.
IO
encoding example In the following example a UTF-8 encoded string “Ru00E9sumu00E9” is transcoded for output to ISO-8859-1 encoding, then read back in and transcoded to UTF-8:
string = "R\u00E9sum\u00E9" open("transcoded.txt", "w:ISO-8859-1") do |io| io.write(string) end puts "raw text:" p File.binread("transcoded.txt") puts open("transcoded.txt", "r:ISO-8859-1:UTF-8") do |io| puts "transcoded text:" p io.read end
While writing the file, the internal encoding is not specified as it is only necessary for reading. While reading the file both the internal and external encoding must be specified to obtain the correct result.
$ ruby t.rb raw text: "R\xE9sum\xE9" transcoded text: "R\u00E9sum\u00E9"
Raised when the interrupt signal is received, typically because the user has pressed Control-C (on most posix platforms). As such, it is a subclass of SignalException
.
begin puts "Press ctrl-C when you get bored" loop {} rescue Interrupt => e puts "Note: You will typically use Signal.trap instead." end
produces:
Press ctrl-C when you get bored
then waits until it is interrupted with Control-C and then prints:
Note: You will typically use Signal.trap instead.
Raised when the given index is invalid.
a = [:foo, :bar] a.fetch(0) #=> :foo a[4] #=> nil a.fetch(4) #=> IndexError: index 4 outside of array bounds: -2...2
Raised when encountering Ruby code with an invalid syntax.
eval("1+1=2")
raises the exception:
SyntaxError: (eval):1: syntax error, unexpected '=', expecting $end
EncodingError
is the base class for encoding errors.
BigDecimal
provides arbitrary-precision floating point decimal arithmetic.
Ruby provides built-in support for arbitrary precision integer arithmetic.
For example:
42**13 #=> 1265437718438866624512
BigDecimal
provides similar support for very large or very accurate floating point numbers.
Decimal arithmetic is also useful for general calculation, because it provides the correct answers people expect–whereas normal binary floating point arithmetic often introduces subtle errors because of the conversion between base 10 and base 2.
For example, try:
sum = 0 10_000.times do sum = sum + 0.0001 end print sum #=> 0.9999999999999062
and contrast with the output from:
require 'bigdecimal' sum = BigDecimal("0") 10_000.times do sum = sum + BigDecimal("0.0001") end print sum #=> 0.1E1
Similarly:
(BigDecimal("1.2") - BigDecimal("1.0")) == BigDecimal("0.2") #=> true (1.2 - 1.0) == 0.2 #=> false
Because BigDecimal
is more accurate than normal binary floating point arithmetic, it requires some special values.
BigDecimal
sometimes needs to return infinity, for example if you divide a value by zero.
BigDecimal("1.0") / BigDecimal("0.0") #=> Infinity BigDecimal("-1.0") / BigDecimal("0.0") #=> -Infinity
You can represent infinite numbers to BigDecimal
using the strings 'Infinity'
, '+Infinity'
and '-Infinity'
(case-sensitive)
When a computation results in an undefined value, the special value NaN
(for ‘not a number’) is returned.
Example:
BigDecimal("0.0") / BigDecimal("0.0") #=> NaN
You can also create undefined values.
NaN is never considered to be the same as any other value, even NaN itself:
n = BigDecimal('NaN') n == 0.0 #=> false n == n #=> false
If a computation results in a value which is too small to be represented as a BigDecimal
within the currently specified limits of precision, zero must be returned.
If the value which is too small to be represented is negative, a BigDecimal
value of negative zero is returned.
BigDecimal("1.0") / BigDecimal("-Infinity") #=> -0.0
If the value is positive, a value of positive zero is returned.
BigDecimal("1.0") / BigDecimal("Infinity") #=> 0.0
(See BigDecimal.mode
for how to specify limits of precision.)
Note that -0.0
and 0.0
are considered to be the same for the purposes of comparison.
Note also that in mathematics, there is no particular concept of negative or positive zero; true mathematical zero has no sign.
When you require bigdecimal/util
, the to_d
method will be available on BigDecimal
and the native Integer
, Float
, Rational
, and String
classes:
require 'bigdecimal/util' 42.to_d # => 0.42e2 0.5.to_d # => 0.5e0 (2/3r).to_d(3) # => 0.667e0 "0.5".to_d # => 0.5e0
Copyright © 2002 by Shigeo Kobayashi <shigeo@tinyforest.gr.jp>.
BigDecimal
is released under the Ruby and 2-clause BSD licenses. See LICENSE.txt for details.
Maintained by mrkn <mrkn@mrkn.jp> and ruby-core members.
Documented by zzak <zachary@zacharyscott.net>, mathew <meta@pobox.com>, and many other contributors.
Pseudo I/O on String
object, with interface corresponding to IO
.
Commonly used to simulate $stdio
or $stderr
require 'stringio' # Writing stream emulation io = StringIO.new io.puts "Hello World" io.string #=> "Hello World\n" # Reading stream emulation io = StringIO.new "first\nsecond\nlast\n" io.getc #=> "f" io.gets #=> "irst\n" io.read #=> "second\nlast\n"