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 2-element array containing the minimum and maximum value in self
, either according to comparison method <=>
or a given block.
With no block given, returns the minimum and maximum values, using <=>
for comparison:
(1..4).minmax # => [1, 4] (1...4).minmax # => [1, 3] ('a'..'d').minmax # => ["a", "d"] (-4..-1).minmax # => [-4, -1]
With a block given, the block must return an integer:
Negative if a
is smaller than b
.
Zero if a
and b
are equal.
Positive if a
is larger than b
.
The block is called self.size
times to compare elements; returns a 2-element Array
containing the minimum and maximum values from self
, per the block:
(1..4).minmax {|a, b| -(a <=> b) } # => [4, 1]
Returns [nil, nil]
if:
The begin value of the range is larger than the end value:
(4..1).minmax # => [nil, nil] (4..1).minmax {|a, b| -(a <=> b) } # => [nil, nil]
The begin value of an exclusive range is equal to the end value:
(1...1).minmax # => [nil, nil] (1...1).minmax {|a, b| -(a <=> b) } # => [nil, nil]
Raises an exception if self
is a beginless or an endless range.
Returns a 2-element array containing the minimum and maximum elements according to a given criterion. The ordering of equal elements is indeterminate and may be unstable.
With no argument and no block, returns the minimum and maximum elements, using the elements’ own method <=>
for comparison:
(1..4).minmax # => [1, 4] (-4..-1).minmax # => [-4, -1] %w[d c b a].minmax # => ["a", "d"] {foo: 0, bar: 1, baz: 2}.minmax # => [[:bar, 1], [:foo, 0]] [].minmax # => [nil, nil]
With a block given, returns the minimum and maximum elements as determined by the block:
%w[xxx x xxxx xx].minmax {|a, b| a.size <=> b.size } # => ["x", "xxxx"] h = {foo: 0, bar: 1, baz: 2} h.minmax {|pair1, pair2| pair1[1] <=> pair2[1] } # => [[:foo, 0], [:baz, 2]] [].minmax {|a, b| a <=> b } # => [nil, nil]
Returns a 2-element array containing the elements for which the block returns minimum and maximum values:
(1..4).minmax_by {|element| -element } # => [4, 1] %w[a b c d].minmax_by {|element| -element.ord } # => ["d", "a"] {foo: 0, bar: 1, baz: 2}.minmax_by {|key, value| -value } # => [[:baz, 2], [:foo, 0]] [].minmax_by {|element| -element } # => [nil, nil]
Returns an Enumerator
if no block is given.
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.
An Integer object represents an integer value.
You can create an Integer object explicitly with:
An integer literal.
You can convert certain objects to Integers with:
Method Integer.
An attempt to add a singleton method to an instance of this class causes an exception to be raised.
First, what’s elsewhere. Class Integer:
Inherits from class Numeric.
Here, class Integer provides methods for:
allbits?
Returns whether all bits in self
are set.
anybits?
Returns whether any bits in self
are set.
nobits?
Returns whether no bits in self
are set.
Returns whether self
is less than the given value.
Returns whether self
is less than or equal to the given value.
Returns a number indicating whether self
is less than, equal to, or greater than the given value.
Returns whether self
is greater than the given value.
Returns whether self
is greater than or equal to the given value.
::sqrt
Returns the integer square root of the given value.
::try_convert
Returns the given value converted to an Integer.
Returns the bitwise AND of self
and the given value.
*
Returns the product of self
and the given value.
Returns the value of self
raised to the power of the given value.
+
Returns the sum of self
and the given value.
-
Returns the difference of self
and the given value.
Returns the quotient of self
and the given value.
<<
Returns the value of self
after a leftward bit-shift.
>>
Returns the value of self
after a rightward bit-shift.
[]
Returns a slice of bits from self
.
Returns the bitwise EXCLUSIVE OR of self
and the given value.
ceil
Returns the smallest number greater than or equal to self
.
chr
Returns a 1-character string containing the character represented by the value of self
.
digits
Returns an array of integers representing the base-radix digits of self
.
div
Returns the integer result of dividing self
by the given value.
divmod
Returns a 2-element array containing the quotient and remainder results of dividing self
by the given value.
floor
Returns the greatest number smaller than or equal to self
.
pow
Returns the modular exponentiation of self
.
pred
Returns the integer predecessor of self
.
remainder
Returns the remainder after dividing self
by the given value.
round
Returns self
rounded to the nearest value with the given precision.
truncate
Returns self
truncated to the given precision.
Returns the bitwise OR of self
and the given value.
A String object has an arbitrary sequence of bytes, typically representing text or binary data. A String object may be created using String::new
or as literals.
String
objects differ from Symbol
objects in that Symbol
objects are designed to be used as identifiers, instead of text or data.
You can create a String object explicitly with:
You can convert certain objects to Strings with:
Method String.
Some String methods modify self
. Typically, a method whose name ends with !
modifies self
and returns self
; often a similarly named method (without the !
) returns a new string.
In general, if there exist both bang and non-bang version of method, the bang! mutates and the non-bang! does not. However, a method without a bang can also mutate, such as String#replace
.
These methods perform substitutions:
String#sub
: One substitution (or none); returns a new string.
String#sub!
: One substitution (or none); returns self
.
String#gsub
: Zero or more substitutions; returns a new string.
String#gsub!
: Zero or more substitutions; returns self
.
Each of these methods takes:
A first argument, pattern
(string or regexp), that specifies the substring(s) to be replaced.
Either of these:
A second argument, replacement
(string or hash), that determines the replacing string.
A block that will determine the replacing string.
The examples in this section mostly use methods String#sub
and String#gsub
; the principles illustrated apply to all four substitution methods.
Argument pattern
Argument pattern
is commonly a regular expression:
s = 'hello' s.sub(/[aeiou]/, '*') # => "h*llo" s.gsub(/[aeiou]/, '*') # => "h*ll*" s.gsub(/[aeiou]/, '') # => "hll" s.sub(/ell/, 'al') # => "halo" s.gsub(/xyzzy/, '*') # => "hello" 'THX1138'.gsub(/\d+/, '00') # => "THX00"
When pattern
is a string, all its characters are treated as ordinary characters (not as regexp special characters):
'THX1138'.gsub('\d+', '00') # => "THX1138"
String replacement
If replacement
is a string, that string will determine the replacing string that is to be substituted for the matched text.
Each of the examples above uses a simple string as the replacing string.
String replacement
may contain back-references to the pattern’s captures:
\n
(n a non-negative integer) refers to $n
.
\k<name>
refers to the named capture name
.
See regexp.rdoc for details.
Note that within the string replacement
, a character combination such as $&
is treated as ordinary text, and not as a special match variable. However, you may refer to some special match variables using these combinations:
\&
and \0
correspond to $&
, which contains the complete matched text.
\'
corresponds to $'
, which contains string after match.
\`
corresponds to $`
, which contains string before match.
+
corresponds to $+
, which contains last capture group.
See regexp.rdoc for details.
Note that \\
is interpreted as an escape, i.e., a single backslash.
Note also that a string literal consumes backslashes. See String Literals for details about string literals.
A back-reference is typically preceded by an additional backslash. For example, if you want to write a back-reference \&
in replacement
with a double-quoted string literal, you need to write "..\\&.."
.
If you want to write a non-back-reference string \&
in replacement
, you need first to escape the backslash to prevent this method from interpreting it as a back-reference, and then you need to escape the backslashes again to prevent a string literal from consuming them: "..\\\\&.."
.
You may want to use the block form to avoid a lot of backslashes.
Hash replacement
If argument replacement
is a hash, and pattern
matches one of its keys, the replacing string is the value for that key:
h = {'foo' => 'bar', 'baz' => 'bat'} 'food'.sub('foo', h) # => "bard"
Note that a symbol key does not match:
h = {foo: 'bar', baz: 'bat'} 'food'.sub('foo', h) # => "d"
Block
In the block form, the current match string is passed to the block; the block’s return value becomes the replacing string:
s = '@' '1234'.gsub(/\d/) {|match| s.succ! } # => "ABCD"
Special match variables such as $1
, $2
, $`
, $&
, and $'
are set appropriately.
First, what’s elsewhere. Class String:
Inherits from class Object.
Includes module Comparable.
Here, class String provides methods that are useful for:
::new
Returns a new string.
::try_convert
Returns a new string created from a given object.
String
Returns a string that is not frozen: self
, if not frozen; self.dup
otherwise.
Returns a string that is frozen: self
, if already frozen; self.freeze
otherwise.
freeze
Freezes self
, if not already frozen; returns self
.
Counts
empty?
Returns true
if self.length
is zero; false
otherwise.
bytesize
Returns the count of bytes.
count
Returns the count of substrings matching given strings.
Substrings
index
Returns the index of the first occurrence of a given substring; returns nil
if none found.
rindex
Returns the index of the last occurrence of a given substring; returns nil
if none found.
include?
Returns true
if the string contains a given substring; false
otherwise.
start_with?
Returns true
if the string begins with any of the given substrings.
end_with?
Returns true
if the string ends with any of the given substrings.
Encodings
unicode_normalized?
Returns true
if the string is in Unicode normalized form; false
otherwise.
valid_encoding?
Returns true
if the string contains only characters that are valid for its encoding.
ascii_only?
Returns true
if the string has only ASCII characters; false
otherwise.
Other
sum
Returns a basic checksum for the string: the sum of each byte.
hash
Returns the integer hash code.
Returns true
if a given other string has the same content as self
.
eql?
Returns true
if the content is the same as the given other string.
Returns -1, 0, or 1 as a given other string is smaller than, equal to, or larger than self
.
casecmp
Ignoring case, returns -1, 0, or 1 as a given other string is smaller than, equal to, or larger than self
.
casecmp?
Returns true
if the string is equal to a given string after Unicode case folding; false
otherwise.
Each of these methods modifies self
.
Insertion
insert
Returns self
with a given string inserted at a given offset.
<<
Returns self
concatenated with a given string or integer.
Substitution
sub!
Replaces the first substring that matches a given pattern with a given replacement string; returns self
if any changes, nil
otherwise.
gsub!
Replaces each substring that matches a given pattern with a given replacement string; returns self
if any changes, nil
otherwise.
replace
Returns self
with its entire content replaced by a given string.
reverse!
Returns self
with its characters in reverse order.
setbyte
Sets the byte at a given integer offset to a given value; returns the argument.
tr!
Replaces specified characters in self
with specified replacement characters; returns self
if any changes, nil
otherwise.
tr_s!
Replaces specified characters in self
with specified replacement characters, removing duplicates from the substrings that were modified; returns self
if any changes, nil
otherwise.
Casing
capitalize!
Upcases the initial character and downcases all others; returns self
if any changes, nil
otherwise.
downcase!
Downcases all characters; returns self
if any changes, nil
otherwise.
upcase!
Upcases all characters; returns self
if any changes, nil
otherwise.
swapcase!
Upcases each downcase character and downcases each upcase character; returns self
if any changes, nil
otherwise.
Encoding
encode!
Returns self
with all characters transcoded from one given encoding into another.
unicode_normalize!
Unicode-normalizes self
; returns self
.
scrub!
Replaces each invalid byte with a given character; returns self
.
force_encoding
Changes the encoding to a given encoding; returns self
.
Deletion
clear
Removes all content, so that self
is empty; returns self
.
squeeze!
Removes contiguous duplicate characters; returns self
.
delete!
Removes characters as determined by the intersection of substring arguments.
lstrip!
Removes leading whitespace; returns self
if any changes, nil
otherwise.
rstrip!
Removes trailing whitespace; returns self
if any changes, nil
otherwise.
strip!
Removes leading and trailing whitespace; returns self
if any changes, nil
otherwise.
chomp!
Removes trailing record separator, if found; returns self
if any changes, nil
otherwise.
chop!
Removes trailing whitespace if found, otherwise removes the last character; returns self
if any changes, nil
otherwise.
Each of these methods returns a new String based on self
, often just a modified copy of self
.
Extension
*
Returns the concatenation of multiple copies of self
,
+
Returns the concatenation of self
and a given other string.
center
Returns a copy of self
centered between pad substring.
concat
Returns the concatenation of self
with given other strings.
prepend
Returns the concatenation of a given other string with self
.
ljust
Returns a copy of self
of a given length, right-padded with a given other string.
rjust
Returns a copy of self
of a given length, left-padded with a given other string.
Encoding
b
Returns a copy of self
with ASCII-8BIT encoding.
scrub
Returns a copy of self
with each invalid byte replaced with a given character.
unicode_normalize
Returns a copy of self
with each character Unicode-normalized.
encode
Returns a copy of self
with all characters transcoded from one given encoding into another.
Substitution
dump
Returns a copy of +self with all non-printing characters replaced by xHH notation and all special characters escaped.
undump
Returns a copy of +self with all \xNN
notation replace by \uNNNN
notation and all escaped characters unescaped.
sub
Returns a copy of self
with the first substring matching a given pattern replaced with a given replacement string;.
gsub
Returns a copy of self
with each substring that matches a given pattern replaced with a given replacement string.
reverse
Returns a copy of self
with its characters in reverse order.
tr
Returns a copy of self
with specified characters replaced with specified replacement characters.
tr_s
Returns a copy of self
with specified characters replaced with specified replacement characters, removing duplicates from the substrings that were modified.
%
Returns the string resulting from formatting a given object into self
Casing
capitalize
Returns a copy of self
with the first character upcased and all other characters downcased.
downcase
Returns a copy of self
with all characters downcased.
upcase
Returns a copy of self
with all characters upcased.
swapcase
Returns a copy of self
with all upcase characters downcased and all downcase characters upcased.
Deletion
delete
Returns a copy of self
with characters removed
delete_prefix
Returns a copy of self
with a given prefix removed.
delete_suffix
Returns a copy of self
with a given suffix removed.
lstrip
Returns a copy of self
with leading whitespace removed.
rstrip
Returns a copy of self
with trailing whitespace removed.
strip
Returns a copy of self
with leading and trailing whitespace removed.
chomp
Returns a copy of self
with a trailing record separator removed, if found.
chop
Returns a copy of self
with trailing whitespace or the last character removed.
squeeze
Returns a copy of self
with contiguous duplicate characters removed.
byteslice
Returns a substring determined by a given index, start/length, or range.
chr
Returns the first character.
Duplication
to_s
, $to_str
If self
is a subclass of String, returns self
copied into a String; otherwise, returns self
.
Each of these methods converts the contents of self
to a non-String.
Characters, Bytes, and Clusters
bytes
Returns an array of the bytes in self
.
chars
Returns an array of the characters in self
.
codepoints
Returns an array of the integer ordinals in self
.
getbyte
Returns an integer byte as determined by a given index.
grapheme_clusters
Returns an array of the grapheme clusters in self
.
Splitting
lines
Returns an array of the lines in self
, as determined by a given record separator.
partition
Returns a 3-element array determined by the first substring that matches a given substring or regexp,
rpartition
Returns a 3-element array determined by the last substring that matches a given substring or regexp,
split
Returns an array of substrings determined by a given delimiter – regexp or string – or, if a block given, passes those substrings to the block.
Matching
scan
Returns an array of substrings matching a given regexp or string, or, if a block given, passes each matching substring to the block.
unpack
Returns an array of substrings extracted from self
according to a given format.
unpack1
Returns the first substring extracted from self
according to a given format.
Numerics
hex
Returns the integer value of the leading characters, interpreted as hexadecimal digits.
oct
Returns the integer value of the leading characters, interpreted as octal digits.
ord
Returns the integer ordinal of the first character in self
.
to_i
Returns the integer value of leading characters, interpreted as an integer.
to_f
Returns the floating-point value of leading characters, interpreted as a floating-point number.
Strings and Symbols
inspect
Returns copy of self
, enclosed in double-quotes, with special characters escaped.
each_byte
Calls the given block with each successive byte in self
.
each_char
Calls the given block with each successive character in self
.
each_codepoint
Calls the given block with each successive integer codepoint in self
.
each_grapheme_cluster
Calls the given block with each successive grapheme cluster in self
.
each_line
Calls the given block with each successive line in self
, as determined by a given record separator.
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
For a calculation using a BigDecimal and another value
, the precision of the result depends on the type of value
:
If value
is a Float, the precision is Float::DIG + 1.
If value
is a Rational, the precision is larger than Float::DIG + 1.
If value
is a BigDecimal, the precision is value
‘s precision in the internal representation, which is platform-dependent.
If value
is other object, the precision is determined by the result of +BigDecimal(value)+.
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.