Returns an array containing the lines returned by calling Kernel#gets until the end-of-stream is reached; (see Line IO).
With only string argument sep given, returns the remaining lines as determined by line separator sep, or nil if none; see Line Separator:
# Default separator. $ cat t.txt | ruby -e "p readlines" ["First line\n", "Second line\n", "\n", "Fourth line\n", "Fifth line\n"] # Specified separator. $ cat t.txt | ruby -e "p readlines 'li'" ["First li", "ne\nSecond li", "ne\n\nFourth li", "ne\nFifth li", "ne\n"] # Get-all separator. $ cat t.txt | ruby -e "p readlines nil" ["First line\nSecond line\n\nFourth line\nFifth line\n"] # Get-paragraph separator. $ cat t.txt | ruby -e "p readlines ''" ["First line\nSecond line\n\n", "Fourth line\nFifth line\n"]
With only integer argument limit given, limits the number of bytes in the line; see Line Limit:
$cat t.txt | ruby -e "p readlines 10" ["First line", "\n", "Second lin", "e\n", "\n", "Fourth lin", "e\n", "Fifth line", "\n"] $cat t.txt | ruby -e "p readlines 11" ["First line\n", "Second line", "\n", "\n", "Fourth line", "\n", "Fifth line\n"] $cat t.txt | ruby -e "p readlines 12" ["First line\n", "Second line\n", "\n", "Fourth line\n", "Fifth line\n"]
With arguments sep and limit given, combines the two behaviors (see Line Separator and Line Limit).
Optional keyword argument chomp specifies whether line separators are to be omitted:
$ cat t.txt | ruby -e "p readlines(chomp: true)" ["First line", "Second line", "", "Fourth line", "Fifth line"]
Optional keyword arguments enc_opts specify encoding options; see Encoding options.
Returns an integer converted from object.
Tries to convert object to an integer using to_int first and to_i second; see below for exceptions.
With a non-zero base, object must be a string or convertible to a string.
With an integer argument object given, returns object:
Integer(1) # => 1 Integer(-1) # => -1
With a floating-point argument object given, returns object truncated to an integer:
Integer(1.9) # => 1 # Rounds toward zero. Integer(-1.9) # => -1 # Rounds toward zero.
With a string argument object and zero base given, returns object converted to an integer in base 10:
Integer('100') # => 100 Integer('-100') # => -100
With base zero, string object may contain leading characters to specify the actual base (radix indicator):
Integer('0100') # => 64 # Leading '0' specifies base 8. Integer('0b100') # => 4 # Leading '0b' specifies base 2. Integer('0x100') # => 256 # Leading '0x' specifies base 16.
With a positive base (in range 2..36) given, returns object converted to an integer in the given base:
Integer('100', 2) # => 4 Integer('100', 8) # => 64 Integer('-100', 16) # => -256
With a negative base (in range -36..-2) given, returns object converted to the radix indicator if it exists or base:
Integer('0x100', -2) # => 256 Integer('100', -2) # => 4 Integer('0b100', -8) # => 4 Integer('100', -8) # => 64 Integer('0o100', -10) # => 64 Integer('100', -10) # => 100
base -1 is equivalent to the -10 case.
When converting strings, surrounding whitespace and embedded underscores are allowed and ignored:
Integer(' 100 ') # => 100 Integer('-1_0_0', 16) # => -256
Examples with object of various other classes:
Integer(Rational(9, 10)) # => 0 # Rounds toward zero. Integer(Complex(2, 0)) # => 2 # Imaginary part must be zero. Integer(Time.now) # => 1650974042
With the optional keyword argument exception given as true (the default):
Raises TypeError if object does not respond to to_int or to_i.
Raises TypeError if object is nil.
Raises ArgumentError if object is an invalid string.
With exception given as false, an exception of any kind is suppressed and nil is returned.
Returns a URI object derived from the given uri, which may be a URI string or an existing URI object:
# Returns a new URI. uri = URI('http://github.com/ruby/ruby') # => #<URI::HTTP http://github.com/ruby/ruby> # Returns the given URI. URI(uri) # => #<URI::HTTP http://github.com/ruby/ruby>
Returns a URI object derived from the given uri, which may be a URI string or an existing URI object:
# Returns a new URI. uri = URI('http://github.com/ruby/ruby') # => #<URI::HTTP http://github.com/ruby/ruby> # Returns the given URI. URI(uri) # => #<URI::HTTP http://github.com/ruby/ruby>
Creates a new child process by doing one of the following in that process:
Passing string command_line to the shell.
Invoking the executable at exe_path.
This method has potential security vulnerabilities if called with untrusted input; see Command Injection.
Returns:
true if the command exits with status zero.
false if the exit status is a non-zero integer.
nil if the command could not execute.
Raises an exception (instead of returning false or nil) if keyword argument exception is set to true.
Assigns the command’s error status to $?.
The new process is created using the system system call; it may inherit some of its environment from the calling program (possibly including open file descriptors).
Argument env, if given, is a hash that affects ENV for the new process; see Execution Environment.
Argument options is a hash of options for the new process; see Execution Options.
The first required argument is one of the following:
command_line if it is a string, and if it begins with a shell reserved word or special built-in, or if it contains one or more meta characters.
exe_path otherwise.
Argument command_line
String argument command_line is a command line to be passed to a shell; it must begin with a shell reserved word, begin with a special built-in, or contain meta characters:
system('if true; then echo "Foo"; fi') # => true # Shell reserved word. system('exit') # => true # Built-in. system('date > /tmp/date.tmp') # => true # Contains meta character. system('date > /nop/date.tmp') # => false system('date > /nop/date.tmp', exception: true) # Raises RuntimeError.
Assigns the command’s error status to $?:
system('exit') # => true # Built-in. $? # => #<Process::Status: pid 640610 exit 0> system('date > /nop/date.tmp') # => false $? # => #<Process::Status: pid 640742 exit 2>
The command line may also contain arguments and options for the command:
system('echo "Foo"') # => true
Output:
Foo
See Execution Shell for details about the shell.
Raises an exception if the new process could not execute.
Argument exe_path
Argument exe_path is one of the following:
The string path to an executable to be called.
A 2-element array containing the path to an executable and the string to be used as the name of the executing process.
Example:
system('/usr/bin/date') # => true # Path to date on Unix-style system. system('foo') # => nil # Command failed.
Output:
Mon Aug 28 11:43:10 AM CDT 2023
Assigns the command’s error status to $?:
system('/usr/bin/date') # => true $? # => #<Process::Status: pid 645605 exit 0> system('foo') # => nil $? # => #<Process::Status: pid 645608 exit 127>
Ruby invokes the executable directly. This form does not use the shell; see Arguments args for caveats.
system('doesnt_exist') # => nil
If one or more args is given, each is an argument or option to be passed to the executable:
system('echo', 'C*') # => true system('echo', 'hello', 'world') # => true
Output:
C* hello world
Raises an exception if the new process could not execute.
Specifies the handling of signals. The first parameter is a signal name (a string such as “SIGALRM”, “SIGUSR1”, and so on) or a signal number. The characters “SIG” may be omitted from the signal name. The command or block specifies code to be run when the signal is raised. If the command is the string “IGNORE” or “SIG_IGN”, the signal will be ignored. If the command is “DEFAULT” or “SIG_DFL”, the Ruby’s default handler will be invoked. If the command is “EXIT”, the script will be terminated by the signal. If the command is “SYSTEM_DEFAULT”, the operating system’s default handler will be invoked. Otherwise, the given command or block will be run. The special signal name “EXIT” or signal number zero will be invoked just prior to program termination. trap returns the previous handler for the given signal.
Signal.trap(0, proc { puts "Terminating: #{$$}" }) Signal.trap("CLD") { puts "Child died" } fork && Process.wait
produces:
Terminating: 27461 Child died Terminating: 27460
Returns the first element for which the block returns a truthy value.
With a block given, calls the block with successive elements of the collection; returns the first element for which the block returns a truthy value:
(0..9).find {|element| element > 2} # => 3
If no such element is found, calls if_none_proc and returns its return value.
(0..9).find(proc {false}) {|element| element > 12} # => false {foo: 0, bar: 1, baz: 2}.find {|key, value| key.start_with?('b') } # => [:bar, 1] {foo: 0, bar: 1, baz: 2}.find(proc {[]}) {|key, value| key.start_with?('c') } # => []
With no block given, returns an Enumerator.
Returns the result of applying a reducer to an initial value and the first element of the Enumerable. It then takes the result and applies the function to it and the second element of the collection, and so on. The return value is the result returned by the final call to the function.
You can think of
[ a, b, c, d ].inject(i) { |r, v| fn(r, v) }
as being
fn(fn(fn(fn(i, a), b), c), d)
In a way the inject function injects the function between the elements of the enumerable.
inject is aliased as reduce. You use it when you want to reduce a collection to a single value.
The Calling Sequences
Let’s start with the most verbose:
enum.inject(initial_value) do |result, next_value| # do something with +result+ and +next_value+ # the value returned by the block becomes the # value passed in to the next iteration # as +result+ end
For example:
product = [ 2, 3, 4 ].inject(1) do |result, next_value| result * next_value end product #=> 24
When this runs, the block is first called with 1 (the initial value) and 2 (the first element of the array). The block returns 1*2, so on the next iteration the block is called with 2 (the previous result) and 3. The block returns 6, and is called one last time with 6 and 4. The result of the block, 24 becomes the value returned by inject. This code returns the product of the elements in the enumerable.
First Shortcut: Default Initial value
In the case of the previous example, the initial value, 1, wasn’t really necessary: the calculation of the product of a list of numbers is self-contained.
In these circumstances, you can omit the initial_value parameter. inject will then initially call the block with the first element of the collection as the result parameter and the second element as the next_value.
[ 2, 3, 4 ].inject do |result, next_value| result * next_value end
This shortcut is convenient, but can only be used when the block produces a result which can be passed back to it as a first parameter.
Here’s an example where that’s not the case: it returns a hash where the keys are words and the values are the number of occurrences of that word in the enumerable.
freqs = File.read("README.md")
.scan(/\w{2,}/)
.reduce(Hash.new(0)) do |counts, word|
counts[word] += 1
counts
end
freqs #=> {"Actions"=>4,
"Status"=>5,
"MinGW"=>3,
"https"=>27,
"github"=>10,
"com"=>15, ...
Note that the last line of the block is just the word counts. This ensures the return value of the block is the result that’s being calculated.
Second Shortcut: a Reducer function
A reducer function is a function that takes a partial result and the next value, returning the next partial result. The block that is given to inject is a reducer.
You can also write a reducer as a function and pass the name of that function (as a symbol) to inject. However, for this to work, the function
Must be defined on the type of the result value
Must accept a single parameter, the next value in the collection, and
Must return an updated result which will also implement the function.
Here’s an example that adds elements to a string. The two calls invoke the functions String#concat and String#+ on the result so far, passing it the next value.
s = [ "cat", " ", "dog" ].inject("", :concat) s #=> "cat dog" s = [ "cat", " ", "dog" ].inject("The result is:", :+) s #=> "The result is: cat dog"
Here’s a more complex example when the result object maintains state of a different type to the enumerable elements.
class Turtle def initialize @x = @y = 0 end def move(dir) case dir when "n" then @y += 1 when "s" then @y -= 1 when "e" then @x += 1 when "w" then @x -= 1 end self end end position = "nnneesw".chars.reduce(Turtle.new, :move) position #=>> #<Turtle:0x00000001052f4698 @y=2, @x=1>
Third Shortcut: Reducer With no Initial Value
If your reducer returns a value that it can accept as a parameter, then you don’t have to pass in an initial value. Here :* is the name of the times function:
product = [ 2, 3, 4 ].inject(:*) product # => 24
String concatenation again:
s = [ "cat", " ", "dog" ].inject(:+) s #=> "cat dog"
And an example that converts a hash to an array of two-element subarrays.
nested = {foo: 0, bar: 1}.inject([], :push) nested # => [[:foo, 0], [:bar, 1]]
Returns the first element or elements.
With no argument, returns the first element, or nil if there is none:
(1..4).first # => 1 %w[a b c].first # => "a" {foo: 1, bar: 1, baz: 2}.first # => [:foo, 1] [].first # => nil
With integer argument n, returns an array containing the first n elements that exist:
(1..4).first(2) # => [1, 2] %w[a b c d].first(3) # => ["a", "b", "c"] %w[a b c d].first(50) # => ["a", "b", "c", "d"] {foo: 1, bar: 1, baz: 2}.first(2) # => [[:foo, 1], [:bar, 1]] [].first(2) # => []
Returns the element with the minimum element 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 element, using the elements’ own method #<=> for comparison:
(1..4).min # => 1 (-4..-1).min # => -4 %w[d c b a].min # => "a" {foo: 0, bar: 1, baz: 2}.min # => [:bar, 1] [].min # => nil
With positive integer argument n given, and no block, returns an array containing the first n minimum elements that exist:
(1..4).min(2) # => [1, 2] (-4..-1).min(2) # => [-4, -3] %w[d c b a].min(2) # => ["a", "b"] {foo: 0, bar: 1, baz: 2}.min(2) # => [[:bar, 1], [:baz, 2]] [].min(2) # => []
With a block given, the block determines the minimum elements. The block is called with two elements a and b, and must return:
A negative integer if a < b.
Zero if a == b.
A positive integer if a > b.
With a block given and no argument, returns the minimum element as determined by the block:
%w[xxx x xxxx xx].min {|a, b| a.size <=> b.size } # => "x" h = {foo: 0, bar: 1, baz: 2} h.min {|pair1, pair2| pair1[1] <=> pair2[1] } # => [:foo, 0] [].min {|a, b| a <=> b } # => nil
With a block given and positive integer argument n given, returns an array containing the first n minimum elements that exist, as determined by the block.
%w[xxx x xxxx xx].min(2) {|a, b| a.size <=> b.size } # => ["x", "xx"] h = {foo: 0, bar: 1, baz: 2} h.min(2) {|pair1, pair2| pair1[1] <=> pair2[1] } # => [[:foo, 0], [:bar, 1]] [].min(2) {|a, b| a <=> b } # => []
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 whether for any element object == element:
(1..4).include?(2) # => true (1..4).include?(5) # => false (1..4).include?('2') # => false %w[a b c d].include?('b') # => true %w[a b c d].include?('2') # => false {foo: 0, bar: 1, baz: 2}.include?(:foo) # => true {foo: 0, bar: 1, baz: 2}.include?('foo') # => false {foo: 0, bar: 1, baz: 2}.include?(0) # => false
Returns an enumerator object generated from this enumerator and given enumerables.
e = (1..3).chain([4, 5]) e.to_a #=> [1, 2, 3, 4, 5]
Returns a list of the supported category symbols.
Enables the coverage measurement. See the documentation of Coverage class in detail. This is equivalent to Coverage.setup and Coverage.resume.
Returns the state of the coverage measurement.
Returns the short user name of the currently logged in user. Unfortunately, it is often rather easy to fool ::getlogin.
Avoid ::getlogin for security-related purposes.
If ::getlogin fails, try ::getpwuid.
See the unix manpage for getpwuid(3) for more detail.
e.g.
Etc.getlogin -> 'guest'
Returns system temporary directory; typically “/tmp”.
Returns a Digest subclass by name
require 'openssl' OpenSSL::Digest("MD5") # => OpenSSL::Digest::MD5 Digest("Foo") # => NameError: wrong constant name Foo
Returns a Digest subclass by name
require 'openssl' OpenSSL::Digest("MD5") # => OpenSSL::Digest::MD5 Digest("Foo") # => NameError: wrong constant name Foo
Decompresses string. Raises a Zlib::NeedDict exception if a preset dictionary is needed for decompression.
This method is almost equivalent to the following code:
def inflate(string) zstream = Zlib::Inflate.new buf = zstream.inflate(string) zstream.finish zstream.close buf end
See also Zlib.deflate
Return true if the named file exists.
file_name can be an IO object.
“file exists” means that stat() or fstat() system call is successful.
Returns true if the named file is writable by the effective user and group id of this process. See eaccess(3).
Note that some OS-level security features may cause this to return true even though the file is not writable by the effective user/group.