Convert self to locale encoding
Inserts the given other_string into self; returns self.
If the Integer index is positive, inserts other_string at offset index:
'foo'.insert(1, 'bar') # => "fbaroo"
If the Integer index is negative, counts backward from the end of self and inserts other_string at offset index+1 (that is, after self[index]):
'foo'.insert(-2, 'bar') # => "fobaro"
Returns the Integer byte-based index of the last occurrence of the given substring, or nil if none found:
'foo'.byterindex('f') # => 0 'foo'.byterindex('o') # => 2 'foo'.byterindex('oo') # => 1 'foo'.byterindex('ooo') # => nil
Returns the Integer byte-based index of the last match for the given Regexp regexp, or nil if none found:
'foo'.byterindex(/f/) # => 0 'foo'.byterindex(/o/) # => 2 'foo'.byterindex(/oo/) # => 1 'foo'.byterindex(/ooo/) # => nil
The last match means starting at the possible last position, not the last of longest matches.
'foo'.byterindex(/o+/) # => 2 $~ #=> #<MatchData "o">
To get the last longest match, needs to combine with negative lookbehind.
'foo'.byterindex(/(?<!o)o+/) # => 1 $~ #=> #<MatchData "oo">
Or String#byteindex with negative lookforward.
'foo'.byteindex(/o+(?!.*o)/) # => 1 $~ #=> #<MatchData "oo">
Integer argument offset, if given and non-negative, specifies the maximum starting byte-based position in the
string to _end_ the search: 'foo'.byterindex('o', 0) # => nil 'foo'.byterindex('o', 1) # => 1 'foo'.byterindex('o', 2) # => 2 'foo'.byterindex('o', 3) # => 2
If offset is a negative Integer, the maximum starting position in the string to end the search is the sum of the string’s length and offset:
'foo'.byterindex('o', -1) # => 2 'foo'.byterindex('o', -2) # => 1 'foo'.byterindex('o', -3) # => nil 'foo'.byterindex('o', -4) # => nil
If offset does not land on character (codepoint) boundary, IndexError is raised.
Related: String#byteindex.
Returns the byte at zero-based index as an integer, or nil if index is out of range:
s = 'abcde' # => "abcde" s.getbyte(0) # => 97 s.getbyte(-1) # => 101 s.getbyte(5) # => nil
Related: String#setbyte.
Returns a new string with the characters from self in reverse order.
'stressed'.reverse # => "desserts"
Returns self with its characters reversed:
s = 'stressed' s.reverse! # => "desserts" s # => "desserts"
Returns the Symbol corresponding to str, creating the symbol if it did not previously exist. See Symbol#id2name.
"Koala".intern #=> :Koala s = 'cat'.to_sym #=> :cat s == :cat #=> true s = '@cat'.to_sym #=> :@cat s == :@cat #=> true
This can also be used to create symbols that cannot be represented using the :xxx notation.
'cat and dog'.to_sym #=> :"cat and dog"
Returns a centered copy of self.
If integer argument size is greater than the size (in characters) of self, returns a new string of length size that is a copy of self, centered and padded on both ends with pad_string:
'hello'.center(10) # => " hello " ' hello'.center(10) # => " hello " 'hello'.center(10, 'ab') # => "abhelloaba" 'тест'.center(10) # => " тест " 'こんにちは'.center(10) # => " こんにちは "
If size is not greater than the size of self, returns a copy of self:
'hello'.center(5) # => "hello" 'hello'.center(1) # => "hello"
Related: String#ljust, String#rjust.
Returns a 2-element array containing other converted to a Float and self:
f = 3.14 # => 3.14 f.coerce(2) # => [2.0, 3.14] f.coerce(2.0) # => [2.0, 3.14] f.coerce(Rational(1, 2)) # => [0.5, 3.14] f.coerce(Complex(1, 0)) # => [1.0, 3.14]
Raises an exception if a type conversion fails.
Returns self modulo other as a float.
For float f and real number r, these expressions are equivalent:
f % r f-r*(f/r).floor f.divmod(r)[1]
See Numeric#divmod.
Examples:
10.0 % 2 # => 0.0 10.0 % 3 # => 1.0 10.0 % 4 # => 2.0 10.0 % -2 # => 0.0 10.0 % -3 # => -2.0 10.0 % -4 # => -2.0 10.0 % 4.0 # => 2.0 10.0 % Rational(4, 1) # => 2.0
Returns the largest number less than or equal to self with a precision of ndigits decimal digits.
When ndigits is positive, returns a float with ndigits digits after the decimal point (as available):
f = 12345.6789 f.floor(1) # => 12345.6 f.floor(3) # => 12345.678 f = -12345.6789 f.floor(1) # => -12345.7 f.floor(3) # => -12345.679
When ndigits is non-positive, returns an integer with at least ndigits.abs trailing zeros:
f = 12345.6789 f.floor(0) # => 12345 f.floor(-3) # => 12000 f = -12345.6789 f.floor(0) # => -12346 f.floor(-3) # => -13000
Note that the limited precision of floating-point arithmetic may lead to surprising results:
(0.3 / 0.1).floor #=> 2 (!)
Related: Float#ceil.
Returns true if self is 0.0, false otherwise.
Returns the numerator. The result is machine dependent.
n = 0.3.numerator #=> 5404319552844595 d = 0.3.denominator #=> 18014398509481984 n.fdiv(d) #=> 0.3
See also Float#denominator.
Forces the fiber to be blocking for the duration of the block. Returns the result of the block.
See the “Non-blocking fibers” section in class docs for details.
Returns true if fiber is blocking and false otherwise. Fiber is non-blocking if it was created via passing blocking: false to Fiber.new, or via Fiber.schedule.
Note that, even if the method returns false, the fiber behaves differently only if Fiber.scheduler is set in the current thread.
See the “Non-blocking fibers” section in class docs for details.
Returns a copy of the storage hash for the fiber. The method can only be called on the Fiber.current.
Sets the storage hash for the fiber. This feature is experimental and may change in the future. The method can only be called on the Fiber.current.
You should be careful about using this method as you may inadvertently clear important fiber-storage state. You should mostly prefer to assign specific keys in the storage using Fiber::[]=.
You can also use Fiber.new(storage: nil) to create a fiber with an empty storage.
Example:
while request = request_queue.pop # Reset the per-request state: Fiber.current.storage = nil handle_request(request) end
Transfer control to another fiber, resuming it from where it last stopped or starting it if it was not resumed before. The calling fiber will be suspended much like in a call to Fiber.yield.
The fiber which receives the transfer call treats it much like a resume call. Arguments passed to transfer are treated like those passed to resume.
The two style of control passing to and from fiber (one is resume and Fiber::yield, another is transfer to and from fiber) can’t be freely mixed.
If the Fiber’s lifecycle had started with transfer, it will never be able to yield or be resumed control passing, only finish or transfer back. (It still can resume other fibers that are allowed to be resumed.)
If the Fiber’s lifecycle had started with resume, it can yield or transfer to another Fiber, but can receive control back only the way compatible with the way it was given away: if it had transferred, it only can be transferred back, and if it had yielded, it only can be resumed back. After that, it again can transfer or yield.
If those rules are broken FiberError is raised.
For an individual Fiber design, yield/resume is easier to use (the Fiber just gives away control, it doesn’t need to think about who the control is given to), while transfer is more flexible for complex cases, allowing to build arbitrary graphs of Fibers dependent on each other.
Example:
manager = nil # For local var to be visible inside worker block # This fiber would be started with transfer # It can't yield, and can't be resumed worker = Fiber.new { |work| puts "Worker: starts" puts "Worker: Performed #{work.inspect}, transferring back" # Fiber.yield # this would raise FiberError: attempt to yield on a not resumed fiber # manager.resume # this would raise FiberError: attempt to resume a resumed fiber (double resume) manager.transfer(work.capitalize) } # This fiber would be started with resume # It can yield or transfer, and can be transferred # back or resumed manager = Fiber.new { puts "Manager: starts" puts "Manager: transferring 'something' to worker" result = worker.transfer('something') puts "Manager: worker returned #{result.inspect}" # worker.resume # this would raise FiberError: attempt to resume a transferring fiber Fiber.yield # this is OK, the fiber transferred from and to, now it can yield puts "Manager: finished" } puts "Starting the manager" manager.resume puts "Resuming the manager" # manager.transfer # this would raise FiberError: attempt to transfer to a yielding fiber manager.resume
produces
Starting the manager Manager: starts Manager: transferring 'something' to worker Worker: starts Worker: Performed "something", transferring back Manager: worker returned "Something" Resuming the manager Manager: finished
Returns false if the current fiber is non-blocking. Fiber is non-blocking if it was created via passing blocking: false to Fiber.new, or via Fiber.schedule.
If the current Fiber is blocking, the method returns 1. Future developments may allow for situations where larger integers could be returned.
Note that, even if the method returns false, Fiber behaves differently only if Fiber.scheduler is set in the current thread.
See the “Non-blocking fibers” section in class docs for details.
Returns the Fiber scheduler, that was last set for the current thread with Fiber.set_scheduler. Returns nil if no scheduler is set (which is the default), and non-blocking fibers’ behavior is the same as blocking. (see “Non-blocking fibers” section in class docs for details about the scheduler concept).
Closes the stream in self, if it is open, and returns nil; ignored if self is already closed:
dir = Dir.new('example') dir.read # => "." dir.close # => nil dir.close # => nil dir.read # Raises IOError.
Returns the path to the current working directory:
Dir.chdir("/tmp") # => 0 Dir.pwd # => "/tmp"
Forms an array entry_names of the entry names selected by the arguments.
Argument patterns is a string pattern or an array of string patterns; note that these are not regexps; see below.
Notes for the following examples:
'*' is the pattern that matches any entry name except those that begin with '.'.
We use method Array#take to shorten returned arrays that otherwise would be very large.
With no block, returns array entry_names; example (using the simple file tree):
Dir.glob('*') # => ["config.h", "lib", "main.rb"]
With a block, calls the block with each of the entry_names and returns nil:
Dir.glob('*') {|entry_name| puts entry_name } # => nil
Output:
config.h lib main.rb
If optional keyword argument flags is given, the value modifies the matching; see below.
If optional keyword argument base is given, its value specifies the base directory. Each pattern string specifies entries relative to the base directory; the default is '.'. The base directory is not prepended to the entry names in the result:
Dir.glob(pattern, base: 'lib').take(5) # => ["abbrev.gemspec", "abbrev.rb", "base64.gemspec", "base64.rb", "benchmark.gemspec"] Dir.glob(pattern, base: 'lib/irb').take(5) # => ["cmd", "color.rb", "color_printer.rb", "completion.rb", "context.rb"]
If optional keyword sort is given, its value specifies whether the array is to be sorted; the default is true. Passing value false with that keyword disables sorting (though the underlying file system may already have sorted the array).
Patterns
Each pattern string is expanded according to certain metacharacters; examples below use the Ruby file tree:
'*': Matches any substring in an entry name, similar in meaning to regexp /.*/mx; may be restricted by other values in the pattern strings:
'*' matches all entry names:
Dir.glob('*').take(3) # => ["BSDL", "CONTRIBUTING.md", "COPYING"]
'c*' matches entry names beginning with 'c':
Dir.glob('c*').take(3) # => ["CONTRIBUTING.md", "COPYING", "COPYING.ja"]
'*c' matches entry names ending with 'c':
Dir.glob('*c').take(3) # => ["addr2line.c", "array.c", "ast.c"]
'*c*' matches entry names that contain 'c', even at the beginning or end:
Dir.glob('*c*').take(3) # => ["CONTRIBUTING.md", "COPYING", "COPYING.ja"]
Does not match Unix-like hidden entry names (“dot files”). To include those in the matched entry names, use flag IO::FNM_DOTMATCH or something like '{*,.*}'.
'**': Matches entry names recursively if followed by the slash character '/':
Dir.glob('**/').take(3) # => ["basictest/", "benchmark/", "benchmark/gc/"]
If the string pattern contains other characters or is not followed by a slash character, it is equivalent to '*'.
'?' Matches any single character; similar in meaning to regexp /./:
Dir.glob('io.?') # => ["io.c"]
'[set]': Matches any one character in the string set; behaves like a Regexp character class, including set negation ('[^a-z]'):
Dir.glob('*.[a-z][a-z]').take(3) # => ["CONTRIBUTING.md", "COPYING.ja", "KNOWNBUGS.rb"]
'{abc,xyz}': Matches either string abc or string xyz; behaves like Regexp alternation:
Dir.glob('{LEGAL,BSDL}') # => ["LEGAL", "BSDL"]
More than two alternatives may be given.
\: Escapes the following metacharacter.
Note that on Windows, the backslash character may not be used in a string pattern: Dir['c:\foo*'] will not work, use Dir['c:/foo*'] instead.
More examples (using the simple file tree):
# We're in the example directory.
File.basename(Dir.pwd) # => "example"
Dir.glob('config.?') # => ["config.h"]
Dir.glob('*.[a-z][a-z]') # => ["main.rb"]
Dir.glob('*.[^r]*') # => ["config.h"]
Dir.glob('*.{rb,h}') # => ["main.rb", "config.h"]
Dir.glob('*') # => ["config.h", "lib", "main.rb"]
Dir.glob('*', File::FNM_DOTMATCH) # => [".", "config.h", "lib", "main.rb"]
Dir.glob(["*.rb", "*.h"]) # => ["main.rb", "config.h"]
Dir.glob('**/*.rb')
=> ["lib/song/karaoke.rb", "lib/song.rb", "main.rb"]
Dir.glob('**/*.rb', base: 'lib') # => ["song/karaoke.rb", "song.rb"]
Dir.glob('**/lib') # => ["lib"]
Dir.glob('**/lib/**/*.rb') # => ["lib/song/karaoke.rb", "lib/song.rb"]
Dir.glob('**/lib/*.rb') # => ["lib/song.rb"]
Flags
If optional keyword argument flags is given (the default is zero – no flags), its value should be the bitwise OR of one or more of the constants defined in module File::Constants.
Example:
flags = File::FNM_EXTGLOB | File::FNM_DOTMATCH
Specifying flags can extend, restrict, or otherwise modify the matching.
The flags for this method (other constants in File::Constants do not apply):
File::FNM_DOTMATCH: specifies that entry names beginning with '.' should be considered for matching:
Dir.glob('*').take(5) # => ["BSDL", "CONTRIBUTING.md", "COPYING", "COPYING.ja", "GPL"] Dir.glob('*', flags: File::FNM_DOTMATCH).take(5) # => [".", ".appveyor.yml", ".cirrus.yml", ".dir-locals.el", ".document"]
File::FNM_EXTGLOB: enables the pattern extension '{a,b}', which matches pattern a and pattern b; behaves like a regexp union (e.g., '(?:a|b)'):
pattern = '{LEGAL,BSDL}' Dir.glob(pattern) # => ["LEGAL", "BSDL"]
File::FNM_NOESCAPE: specifies that escaping with the backslash character '\' is disabled; the character is not an escape character.
File::FNM_PATHNAME: specifies that metacharacters '*' and '?' do not match directory separators.
File::FNM_SHORTNAME: specifies that patterns may match short names if they exist; Windows only.
Locks or unlocks a file according to the given locking_constant, a bitwise OR of the values in the table below.
Not available on all platforms.
Returns false if File::LOCK_NB is specified and the operation would have blocked; otherwise returns 0.
| Locking Constants | ||
|---|---|---|
| Constant | Lock | Effect |
| File::LOCK_EX | Exclusive | Only one process may hold an exclusive lock for self at a time. |
| File::LOCK_NB | Non-blocking | No blocking; may be combined with other File::LOCK_SH or File::LOCK_EX using the bitwise OR operator |. |
| File::LOCK_SH | Shared | Multiple processes may each hold a shared lock for self at the same time. |
| File::LOCK_UN | Unlock | Remove an existing lock held by this process. |
Example:
# Update a counter using an exclusive lock. # Don't use File::WRONLY because it truncates the file. File.open('counter', File::RDWR | File::CREAT, 0644) do |f| f.flock(File::LOCK_EX) value = f.read.to_i + 1 f.rewind f.write("#{value}\n") f.flush f.truncate(f.pos) end # Read the counter using a shared lock. File.open('counter', 'r') do |f| f.flock(File::LOCK_SH) f.read end
Returns true if the named file exists and has a zero size.
file_name can be an IO object.