ruby 2.2.4 core api reference api referenceruby 2.2.4 core api reference api reference this is the...

Ruby2.2.4CoreAPIReferenceAPIReferenceThisistheAPIdocumentationfor'Ruby2.2.4CoreAPIReferenceAPIReference'.

Classes/ModulesIO

IO::EAGAINWaitReadable

IO::EAGAINWaitWritable

IO::EINPROGRESSWaitReadable

IO::EINPROGRESSWaitWritable

IO::EWOULDBLOCKWaitReadable

IO::EWOULDBLOCKWaitWritable

IO::WaitReadable

IO::WaitWritable

Encoding

Encoding::CompatibilityError

Encoding::Converter

Encoding::ConverterNotFoundError

Encoding::InvalidByteSequenceError

Encoding::UndefinedConversionError

Process

Process::GID

Process::Status

Process::Sys

Process::UID

Process::Waiter

Enumerator

Enumerator::Generator

Enumerator::Lazy

Enumerator::Yielder

File::Constants

File::Stat

RubyVM

RubyVM::Env

RubyVM::InstructionSequence

Complex

Complex::compatible

GC::Profiler

Math::DomainError

ObjectSpace

ObjectSpace::WeakMap

Rational

Rational::compatible

ArgumentError

BasicObject

Bignum

Binding

Comparable

Continuation

EOFError

EncodingError

Enumerable

Exception

FalseClass

FiberError

FileTest

Fixnum

FloatDomainError

IOError

IndexError

Integer

Interrupt

Kernel

KeyError

LoadError

LocalJumpError

Marshal

MatchData

Method

Module

NameError

NilClass

NoMemoryError

NoMethodError

NotImplementedError

Numeric

Object

Random

RangeError

Regexp

RegexpError

Ripper

RuntimeError

ScriptError

SecurityError

Signal

SignalException

StandardError

StopIteration

String

Struct

Symbol

SyntaxError

SystemCallError

SystemExit

SystemStackError

Thread

ThreadError

ThreadGroup

TracePoint

TrueClass

TypeError

UnboundMethod

UncaughtThrowError

ZeroDivisionError

GeneratedbyRDoc3.12.2.GeneratedwiththeDarkfishRdocGenerator3.

classArgumentErrorRaisedwhentheargumentsarewrongandthereisn'tamorespecificExceptionclass.

Ex:passingthewrongnumberofarguments

[1,2,3].first(4,5)

raisestheexception:

ArgumentError:wrongnumberofarguments(2for1)

Ex:passinganargumentthatisnotacceptable:

[1,2,3].first(-4)

raisestheexception:

ArgumentError:negativearraysize

InFileserror.c

ParentStandardError

classArrayArraysareordered,integer-indexedcollectionsofanyobject.

Arrayindexingstartsat0,asinCorJava.Anegativeindexisassumedtoberelativetotheendofthearray—thatis,anindexof-1indicatesthelastelementofthearray,-2isthenexttolastelementinthearray,andsoon.

CreatingArrays

Anewarraycanbecreatedbyusingtheliteralconstructor[].Arrayscancontaindifferenttypesofobjects.Forexample,thearraybelowcontainsanInteger,aStringandaFloat:

ary=[1,"two",3.0]#=>[1,"two",3.0]

Anarraycanalsobecreatedbyexplicitlycalling::newwithzero,one(theinitialsizeoftheArray)ortwoarguments(theinitialsizeandadefaultobject).

ary=Array.new#=>[]

Array.new(3)#=>[nil,nil,nil]

Array.new(3,true)#=>[true,true,true]

Notethatthesecondargumentpopulatesthearraywithreferencestothesameobject.Therefore,itisonlyrecommendedincaseswhenyouneedtoinstantiatearrayswithnativelyimmutableobjectssuchasSymbols,numbers,trueorfalse.

Tocreateanarraywithseparateobjectsablockcanbepassedinstead.Thismethodissafetousewithmutableobjectssuchashashes,stringsorotherarrays:

Array.new(4){Hash.new}#=>[{},{},{},{}]

Thisisalsoaquickwaytobuildupmulti-dimensionalarrays:

empty_table=Array.new(3){Array.new(3)}

#=>[[nil,nil,nil],[nil,nil,nil],[nil,nil,nil]]

AnarraycanalsobecreatedbyusingtheArray()method,providedbyKernel,whichtriestocallto_ary,thento_aonitsargument.

Array({:a=>"a",:b=>"b"})#=>[[:a,"a"],[:b,"b"]]

ExampleUsage

InadditiontothemethodsitmixesinthroughtheEnumerablemodule,theArrayclasshasproprietarymethodsforaccessing,searchingandotherwisemanipulatingarrays.

Someofthemorecommononesareillustratedbelow.

AccessingElements

ElementsinanarraycanberetrievedusingtheArray#[]method.Itcantakeasingleintegerargument(anumericindex),apairofarguments(startandlength)orarange.Negativeindicesstartcountingfromtheend,with-1beingthelastelement.

arr=[1,2,3,4,5,6]

arr[2]#=>3

arr[100]#=>nil

arr[-3]#=>4

arr[2,3]#=>[3,4,5]

arr[1..4]#=>[2,3,4,5]

arr[1..-3]#=>[2,3,4]

Anotherwaytoaccessaparticulararrayelementisbyusingtheatmethod

arr.at(0)#=>1

TheslicemethodworksinanidenticalmannertoArray#[].

Toraiseanerrorforindicesoutsideofthearrayboundsorelsetoprovideadefaultvaluewhenthathappens,youcanusefetch.

arr=['a','b','c','d','e','f']

arr.fetch(100)#=>IndexError:index100outsideofarraybounds:-6...6

arr.fetch(100,"oops")#=>"oops"

Thespecialmethodsfirstandlastwillreturnthefirstandlastelementsofanarray,respectively.

arr.first#=>1

arr.last#=>6

Toreturnthefirstnelementsofanarray,usetake

arr.take(3)#=>[1,2,3]

dropdoestheoppositeoftake,byreturningtheelementsafternelementshavebeendropped:

arr.drop(3)#=>[4,5,6]

ObtainingInformationaboutanArray

Arrayskeeptrackoftheirownlengthatalltimes.Toqueryanarrayaboutthenumberofelementsitcontains,uselength,countorsize.

browsers=['Chrome','Firefox','Safari','Opera'

browsers.length#=>5

browsers.count#=>5

Tocheckwhetheranarraycontainsanyelementsatall

browsers.empty?#=>false

Tocheckwhetheraparticularitemisincludedinthearray

browsers.include?('Konqueror')#=>false

AddingItemstoArrays

Itemscanbeaddedtotheendofanarraybyusingeitherpushor#<<

arr=[1,2,3,4]

arr.push(5)#=>[1,2,3,4,5]

arr<<6#=>[1,2,3,4,5,6]

unshiftwilladdanewitemtothebeginningofanarray.

arr.unshift(0)#=>[0,1,2,3,4,5,6]

Withinsertyoucanaddanewelementtoanarrayatanyposition.

arr.insert(3,'apple')#=>[0,1,2,'apple',3,4,5,6]

Usingtheinsertmethod,youcanalsoinsertmultiplevaluesatonce:

arr.insert(3,'orange','pear','grapefruit')

#=>[0,1,2,"orange","pear","grapefruit","apple",3,4,5,6]

RemovingItemsfromanArray

Themethodpopremovesthelastelementinanarrayandreturnsit:

arr=[1,2,3,4,5,6]

arr.pop#=>6

arr#=>[1,2,3,4,5]

Toretrieveandatthesametimeremovethefirstitem,useshift:

arr.shift#=>1

arr#=>[2,3,4,5]

Todeleteanelementataparticularindex:

arr.delete_at(2)#=>4

arr#=>[2,3,5]

Todeleteaparticularelementanywhereinanarray,usedelete:

arr=[1,2,2,3]

arr.delete(2)#=>2

arr#=>[1,3]

Ausefulmethodifyouneedtoremovenilvaluesfromanarrayiscompact:

arr=['foo',0,nil,'bar',7,'baz',nil]

arr.compact#=>['foo',0,'bar',7,'baz']

arr#=>['foo',0,nil,'bar',7,'baz',nil]

arr.compact!#=>['foo',0,'bar',7,'baz']

arr#=>['foo',0,'bar',7,'baz']

Anothercommonneedistoremoveduplicateelementsfromanarray.

Ithasthenon-destructiveuniq,anddestructivemethoduniq!

arr=[2,5,6,556,6,6,8,9,0,123,556]

arr.uniq#=>[2,5,6,556,8,9,0,123]

IteratingoverArrays

LikeallclassesthatincludetheEnumerablemodule,Arrayhasaneachmethod,whichdefineswhatelementsshouldbeiteratedoverandhow.IncaseofArray'seach,allelementsintheArrayinstanceareyieldedtothesuppliedblockinsequence.

Notethatthisoperationleavesthearrayunchanged.

arr=[1,2,3,4,5]

arr.each{|a|printa-=10,""}

#prints:-9-8-7-6-5

#=>[1,2,3,4,5]

Anothersometimesusefuliteratorisreverse_eachwhichwilliterateovertheelementsinthearrayinreverseorder.

words=%w[firstsecondthirdfourthfifthsixth]

str=""

words.reverse_each{|word|str+="#{word}"}

pstr#=>"sixthfifthfourththirdsecondfirst"

Themapmethodcanbeusedtocreateanewarraybasedontheoriginalarray,butwiththevaluesmodifiedbythesuppliedblock:

arr.map{|a|2*a}#=>[2,4,6,8,10]

arr#=>[1,2,3,4,5]

arr.map!{|a|a**2}#=>[1,4,9,16,25]

arr#=>[1,4,9,16,25]

SelectingItemsfromanArray

Elementscanbeselectedfromanarrayaccordingtocriteriadefinedinablock.Theselectioncanhappeninadestructiveoranon-destructivemanner.Whilethedestructiveoperationswillmodifythearraytheywerecalledon,thenon-destructivemethodsusuallyreturnanewarraywiththeselectedelements,butleavetheoriginalarrayunchanged.

Non-destructiveSelectionarr=[1,2,3,4,5,6]

arr.select{|a|a>3}#=>[4,5,6]

arr.reject{|a|a<3}#=>[3,4,5,6]

arr.drop_while{|a|a<4}#=>[4,5,6]

arr#=>[1,2,3,4,5,6]

DestructiveSelection

select!andreject!arethecorrespondingdestructivemethodstoselectandreject

Similartoselectvs.reject,delete_ifandkeep_ifhavetheexactoppositeresultwhensuppliedwiththesameblock:

arr.delete_if{|a|a<4}#=>[4,5,6]

arr#=>[4,5,6]

arr=[1,2,3,4,5,6]

arr.keep_if{|a|a<4}#=>[1,2,3]

arr#=>[1,2,3]

InFilesarray.cpack.c

ParentObject

IncludedModulesEnumerable

PublicClassMethods

Returnsanewarraypopulatedwiththegivenobjects.

Array.[](1,'a',/^A/)#=>[1,"a",/^A/]

Array[1,'a',/^A/]#=>[1,"a",/^A/]

[1,'a',/^A/]#=>[1,"a",/^A/]

Returnsanewarray.

Inthefirstform,ifnoargumentsaresent,thenewarraywillbeempty.Whenasizeandanoptionaldefaultaresent,anarrayiscreatedwithsizecopies

[](*args)

new(size=0,default=nil)new(array)new(size){|index|block}

ofdefault.Takenoticethatallelementswillreferencethesameobjectdefault.

Thesecondformcreatesacopyofthearraypassedasaparameter(thearrayisgeneratedbycalling#to_aryontheparameter).

first_array=["Matz","Guido"]

second_array=Array.new(first_array)#=>["Matz","Guido"]

first_array.equal?second_array#=>false

Inthelastform,anarrayofthegivensizeiscreated.Eachelementinthisarrayiscreatedbypassingtheelement'sindextothegivenblockandstoringthereturnvalue.

Array.new(3){|index|index**2}

#=>[0,1,4]

Whensendingthesecondparameter,thesameobjectwillbeusedasthevalueforallthearrayelements:

a=Array.new(2,Hash.new)

#=>[{},{}]

a[0]['cat']='feline'

a#=>[{"cat"=>"feline"},{"cat"=>"feline"}]

a[1]['cat']='Felix'

a#=>[{"cat"=>"Felix"},{"cat"=>"Felix"}]

SincealltheArrayelementsstorethesamehash,changestooneofthemwillaffectthemall.

Ifmultiplecopiesarewhatyouwant,youshouldusetheblockversionwhichusestheresultofthatblockeachtimeanelementofthearrayneedstobeinitialized:

a=Array.new(2){Hash.new}

a[0]['cat']='feline'

a#=>[{"cat"=>"feline"},{}]

Triestoconvertobjintoanarray,usingto_arymethod.Returnstheconvertedarrayornilifobjcannotbeconvertedforanyreason.Thismethodcanbeusedtocheckifanargumentisanarray.

Array.try_convert([1])#=>[1]

Array.try_convert("1")#=>nil

iftmp=Array.try_convert(arg)

Commongotchas

try_convert(obj)→arrayornil

#theargumentisanarray

elsiftmp=String.try_convert(arg)

#theargumentisastring

PublicInstanceMethods

SetIntersection—Returnsanewarraycontainingelementscommontothetwoarrays,excludinganyduplicates.Theorderispreservedfromtheoriginalarray.

Itcompareselementsusingtheirhashandeql?methodsforefficiency.

[1,1,3,5]&[1,2,3]#=>[1,3]

['a','b','b','z']&['a','b','c']#=>['a','b']

Seealso#uniq.

Repetition—WithaStringargument,equivalenttoary.join(str).

Otherwise,returnsanewarraybuiltbyconcatenatingtheintcopiesofself.

[1,2,3]*3#=>[1,2,3,1,2,3,1,2,3]

[1,2,3]*","#=>"1,2,3"

Concatenation—Returnsanewarraybuiltby

ary&other_ary→new_ary

ary*int→new_aryary*str→new_string

ary+other_ary→new_ary

concatenatingthetwoarraystogethertoproduceathirdarray.

[1,2,3]+[4,5]#=>[1,2,3,4,5]

a=["a","b","c"]

c=a+["d","e","f"]

c#=>["a","b","c","d","e","f"]

a#=>["a","b","c"]

Notethat

isthesameas

Thismeansthatitproducesanewarray.Asaconsequence,repeateduseof+=onarrayscanbequiteinefficient.

Seealso#concat.

ArrayDifference

Returnsanewarraythatisacopyoftheoriginalarray,removinganyitemsthatalsoappearinother_ary.Theorderispreservedfromtheoriginalarray.

[1,1,2,2,3,3,4,5]-[1,2,4]#=>[3,3,5]

Ifyouneedset-likebehavior,seethelibraryclassSet.

ary-other_ary→new_ary

Append—Pushesthegivenobjectontotheendofthisarray.Thisexpressionreturnsthearrayitself,soseveralappendsmaybechainedtogether.

[1,2]<<"c"<<"d"<<[3,4]

#=>[1,2,"c","d",[3,4]]

Comparison—Returnsaninteger(-1,0,or+1)ifthisarrayislessthan,equalto,orgreaterthanother_ary.

Eachobjectineacharrayiscompared(usingthe<=>operator).

Arraysarecomparedinan“element-wise”manner;thefirstelementofaryiscomparedwiththefirstoneofother_aryusingthe<=>operator,theneachofthesecondelements,etc…Assoonastheresultofanysuchcomparisonisnonzero(i.e.thetwocorrespondingelementsarenotequal),thatresultisreturnedforthewholearraycomparison.

Ifalltheelementsareequal,thentheresultisbasedonacomparisonofthearraylengths.Thus,twoarraysare“equal”accordingtoArray#<=>if,andonlyif,theyhavethesamelengthandthevalueofeachelementisequaltothevalueofthecorrespondingelementintheotherarray.

nilisreturnediftheother_aryisnotanarrayorifthecomparisonoftwoelementsreturnednil.

["a","a","c"]<=>["a","b","c"]#=>-1

[1,2,3,4,5,6]<=>[1,2]#=>+1

[1,2]<=>[1,:two]#=>nil

ary<<obj→ary

ary<=>other_ary→-1,0,+1ornil

Equality—Twoarraysareequaliftheycontainthesamenumberofelementsandifeachelementisequalto(accordingtoObject#==)thecorrespondingelementinother_ary.

["a","c"]==["a","c",7]#=>false

["a","c",7]==["a","c",7]#=>true

["a","c",7]==["a","d","f"]#=>false

ElementReference—Returnstheelementatindex,orreturnsasubarraystartingatthestartindexandcontinuingforlengthelements,orreturnsasubarrayspecifiedbyrangeofindices.

Negativeindicescountbackwardfromtheendofthearray(-1isthelastelement).Forstartandrangecasesthestartingindexisjustbeforeanelement.Additionally,anemptyarrayisreturnedwhenthestartingindexforanelementrangeisattheendofthearray.

Returnsniliftheindex(orstartingindex)areoutofrange.

a=["a","b","c","d","e"]

a[2]+a[0]+a[1]#=>"cab"

a[6]#=>nil

a[1,2]#=>["b","c"]

a[1..3]#=>["b","c","d"]

ary==other_ary→bool

ary[index]→objornilary[start,length]→new_aryornilary[range]→new_aryornilslice(index)→objornilslice(start,length)→new_aryornilslice(range)→new_aryornil

a[4..7]#=>["e"]

a[6..10]#=>nil

a[-3,3]#=>["c","d","e"]

#specialcases

a[5]#=>nil

a[6,1]#=>nil

a[5,1]#=>[]

a[5..10]#=>[]

ElementAssignment—Setstheelementatindex,orreplacesasubarrayfromthestartindexforlengthelements,orreplacesasubarrayspecifiedbytherangeofindices.

Ifindicesaregreaterthanthecurrentcapacityofthearray,thearraygrowsautomatically.Elementsareinsertedintothearrayatstartiflengthiszero.

Negativeindiceswillcountbackwardfromtheendofthearray.Forstartandrangecasesthestartingindexisjustbeforeanelement.

AnIndexErrorisraisedifanegativeindexpointspastthebeginningofthearray.

Seealso#push,and#unshift.

a=Array.new

a[4]="4";#=>[nil,nil,nil,nil,"4"]

a[0,3]=['a','b','c']#=>["a","b","c",nil,"4"]

a[1..2]=[1,2]#=>["a",1,2,nil,"4"]

a[0,2]="?"#=>["?",2,nil,"4"]

a[0..2]="A"#=>["A","4"]

a[-1]="Z"#=>["A","Z"]

a[1..-1]=nil#=>["A",nil]

a[1..-1]=[]#=>["A"]

ary[index]=obj→objary[start,length]=objorother_aryornil→objorother_aryornilary[range]=objorother_aryornil→objorother_aryornil

a[0,0]=[1,2]#=>[1,2,"A"]

a[3,0]="B"#=>[1,2,"A","B"]

SeealsoEnumerable#any?

Searchesthroughanarraywhoseelementsarealsoarrayscomparingobjwiththefirstelementofeachcontainedarrayusingobj.==.

Returnsthefirstcontainedarraythatmatches(thatis,thefirstassociatedarray),ornilifnomatchisfound.

Seealso#rassoc

s1=["colors","red","blue","green"]

s2=["letters","a","b","c"]

s3="foo"

a=[s1,s2,s3]

a.assoc("letters")#=>["letters","a","b","c"]

a.assoc("foo")#=>nil

Returnstheelementatindex.Anegativeindexcountsfromtheendofself.Returnsniliftheindexisoutofrange.SeealsoArray#[].

a=["a","b","c","d","e"]

a.at(0)#=>"a"

a.at(-1)#=>"e"

Byusingbinarysearch,findsavaluefromthisarray

any?[{|obj|block}]→trueorfalse

assoc(obj)→new_aryornil

at(index)→objornil

bsearch{|x|block}→elem

whichmeetsthegivenconditioninO(logn)wherenisthesizeofthearray.

Youcanusethismethodintwousecases:afind-minimummodeandafind-anymode.Ineithercase,theelementsofthearraymustbemonotone(orsorted)withrespecttotheblock.

Infind-minimummode(thisisagoodchoicefortypicalusecase),theblockmustreturntrueorfalse,andtheremustbeanindexi(0<=i<=ary.size)sothat:

theblockreturnsfalseforanyelementwhoseindexislessthani,and

theblockreturnstrueforanyelementwhoseindexisgreaterthanorequaltoi.

Thismethodreturnsthei-thelement.Ifiisequaltoary.size,itreturnsnil.

ary=[0,4,7,10,12]

ary.bsearch{|x|x>=4}#=>4

ary.bsearch{|x|x>=6}#=>7

ary.bsearch{|x|x>=-1}#=>0

ary.bsearch{|x|x>=100}#=>nil

Infind-anymode(thisbehaveslikelibc'sbsearch(3)),theblockmustreturnanumber,andtheremustbetwoindicesiandj(0<=i<=j<=ary.size)sothat:

theblockreturnsapositivenumberforaryif0<=k<i,

theblockreturnszeroforaryifi<=k<j,and

theblockreturnsanegativenumberforaryifj<=k<ary.size.

Underthiscondition,thismethodreturnsanyelementwhoseindexiswithini…j.Ifiisequaltoj(i.e.,thereisnoelementthatsatisfiestheblock),thismethodreturnsnil.

ary=[0,4,7,10,12]

#trytofindvsuchthat4<=v<8

ary.bsearch{|x|1-x/4}#=>4or7

#trytofindvsuchthat8<=v<10

ary.bsearch{|x|4-x/2}#=>nil

Youmustnotmixthetwomodesatatime;theblockmustalwaysreturneithertrue/false,oralwaysreturnanumber.Itisundefinedwhichvalueisactuallypickedupateachiteration.

Removesallelementsfromself.

a=["a","b","c","d","e"]

a.clear#=>[]

Invokesthegivenblockonceforeachelementofself.

Createsanewarraycontainingthevaluesreturnedbytheblock.

SeealsoEnumerable#collect.

Ifnoblockisgiven,anEnumeratorisreturnedinstead.

a=["a","b","c","d"]

a.collect{|x|x+"!"}#=>["a!","b!","c!","d!"]

a.map.with_index{|x,i|x*i}#=>["","b","cc","ddd"]

a#=>["a","b","c","d"]

clear→ary

collect{|item|block}→new_arymap{|item|block}→new_arycollect→Enumeratormap→Enumerator

Invokesthegivenblockonceforeachelementofself,replacingtheelementwiththevaluereturnedbytheblock.

a=["a","b","c","d"]

a.map!{|x|x+"!"}

a#=>["a!","b!","c!","d!"]

a.collect!.with_index{|x,i|x[0...i]}

a#=>["","b","c!","d!"]

Wheninvokedwithablock,yieldsallcombinationsoflengthnofelementsfromthearrayandthenreturnsthearrayitself.

Theimplementationmakesnoguaranteesabouttheorderinwhichthecombinationsareyielded.

Examples:

a=[1,2,3,4]

a.combination(1).to_a#=>[[1],[2],[3],[4]]

a.combination(2).to_a#=>[[1,2],[1,3],[1,4],[2,3],[2,4],[3,4]]

a.combination(3).to_a#=>[[1,2,3],[1,2,4],[1,3,4],[2,3,4]]

a.combination(4).to_a#=>[[1,2,3,4]]

a.combination(0).to_a#=>[[]]#onecombinationoflength0

a.combination(5).to_a#=>[]#nocombinationsoflength5

collect!{|item|block}→arymap!{|item|block}→arycollect!→Enumeratormap!→Enumerator

combination(n){|c|block}→arycombination(n)→Enumerator

Returnsacopyofselfwithallnilelementsremoved.

["a",nil,"b",nil,"c",nil].compact

#=>["a","b","c"]

Removesnilelementsfromthearray.

Returnsnilifnochangesweremade,otherwisereturnsthearray.

["a",nil,"b",nil,"c"].compact!#=>["a","b","c"]

["a","b","c"].compact!#=>nil

Appendstheelementsofother_arytoself.

["a","b"].concat(["c","d"])#=>["a","b","c","d"]

a=[1,2,3]

a.concat([4,5])

a#=>[1,2,3,4,5]

SeealsoArray#+.

Returnsthenumberofelements.

Ifanargumentisgiven,countsthenumberofelementswhichequalobjusing==.

compact→new_ary

compact!→aryornil

concat(other_ary)→ary

count→intcount(obj)→intcount{|item|block}→int

Ifablockisgiven,countsthenumberofelementsforwhichtheblockreturnsatruevalue.

ary=[1,2,4,2]

ary.count#=>4

ary.count(2)#=>2

ary.count{|x|x%2==0}#=>3

Callsthegivenblockforeachelementntimesorforeverifnilisgiven.

Doesnothingifanon-positivenumberisgivenorthearrayisempty.

Returnsniliftheloophasfinishedwithoutgettinginterrupted.

a=["a","b","c"]

a.cycle{|x|putsx}#print,a,b,c,a,b,c,..forever.

a.cycle(2){|x|putsx}#print,a,b,c,a,b,c.

Deletesallitemsfromselfthatareequaltoobj.

Returnsthelastdeleteditem,ornilifnomatchingitemisfound.

Iftheoptionalcodeblockisgiven,theresultoftheblockisreturnediftheitemisnotfound.(Toremovenilelementsandgetaninformativereturnvalue,use#compact!)

cycle(n=nil){|obj|block}→nilcycle(n=nil)→Enumerator

delete(obj)→itemornildelete(obj){block}→itemorresultofblock

a=["a","b","b","b","c"]

a.delete("b")#=>"b"

a#=>["a","c"]

a.delete("z")#=>nil

a.delete("z"){"notfound"}#=>"notfound"

Deletestheelementatthespecifiedindex,returningthatelement,orniliftheindexisoutofrange.

Seealso#slice!

a=["ant","bat","cat","dog"]

a.delete_at(2)#=>"cat"

a#=>["ant","bat","dog"]

a.delete_at(99)#=>nil

Deleteseveryelementofselfforwhichblockevaluatestotrue.

Thearrayischangedinstantlyeverytimetheblockiscalled,notaftertheiterationisover.

Seealso#reject!

scores=[97,42,75]

scores.delete_if{|score|score<80}#=>[97]

Dropsfirstnelementsfromaryandreturnstherestoftheelementsinanarray.

delete_at(index)→objornil

delete_if{|item|block}→arydelete_if→Enumerator

drop(n)→new_ary

Ifanegativenumberisgiven,raisesanArgumentError.

Seealso#take

a=[1,2,3,4,5,0]

a.drop(3)#=>[4,5,0]

Dropselementsupto,butnotincluding,thefirstelementforwhichtheblockreturnsnilorfalseandreturnsanarraycontainingtheremainingelements.

Seealso#take_while

a=[1,2,3,4,5,0]

a.drop_while{|i|i<3}#=>[3,4,5,0]

Callsthegivenblockonceforeachelementinself,passingthatelementasaparameter.

AnEnumeratorisreturnedifnoblockisgiven.

a=["a","b","c"]

a.each{|x|printx,"--"}

produces:

a--b--c--

drop_while{|arr|block}→new_arydrop_while→Enumerator

each{|item|block}→aryeach→Enumerator

each_index{|index|block}→aryeach_index→Enumerator

Sameas#each,butpassestheindexoftheelementinsteadoftheelementitself.

a=["a","b","c"]

a.each_index{|x|printx,"--"}

produces:

0--1--2--

Returnstrueifselfcontainsnoelements.

[].empty?#=>true

Returnstrueifselfandotherarethesameobject,orarebotharrayswiththesamecontent(accordingtoObject#eql?).

Triestoreturntheelementatpositionindex,butthrowsanIndexErrorexceptionifthereferencedindexliesoutsideofthearraybounds.Thiserrorcanbepreventedbysupplyingasecondargument,whichwillactasadefaultvalue.

Alternatively,ifablockisgivenitwillonlybeexecutedwhenaninvalidindexisreferenced.Negativevaluesofindexcountfromtheendofthearray.

empty?→trueorfalse

eql?(other)→trueorfalse

fetch(index)→objfetch(index,default)→objfetch(index){|index|block}→obj

a=[11,22,33,44]

a.fetch(1)#=>22

a.fetch(-1)#=>44

a.fetch(4,'cat')#=>"cat"

a.fetch(100){|i|puts"#{i}isoutofbounds"}

#=>"100isoutofbounds"

Thefirstthreeformssettheselectedelementsofself(whichmaybetheentirearray)toobj.

Astartofnilisequivalenttozero.

Alengthofnilisequivalenttothelengthofthearray.

Thelastthreeformsfillthearraywiththevalueofthegivenblock,whichispassedtheabsoluteindexofeachelementtobefilled.

Negativevaluesofstartcountfromtheendofthearray,where-1isthelastelement.

a=["a","b","c","d"]

a.fill("x")#=>["x","x","x","x"]

a.fill("z",2,2)#=>["x","x","z","z"]

a.fill("y",0..1)#=>["y","y","z","z"]

a.fill{|i|i*i}#=>[0,1,4,9]

a.fill(-2){|i|i*i*i}#=>[0,1,8,27]

fill(obj)→aryfill(obj,start[,length])→aryfill(obj,range)→aryfill{|index|block}→aryfill(start[,length]){|index|block}→aryfill(range){|index|block}→ary

find_index(obj)→intornilfind_index{|item|block}→intornil

Returnstheindexofthefirstobjectinarysuchthattheobjectis==toobj.

Ifablockisgiveninsteadofanargument,returnstheindexofthefirstobjectforwhichtheblockreturnstrue.Returnsnilifnomatchisfound.

Seealso#rindex.

AnEnumeratorisreturnedifneitherablocknorargumentisgiven.

a=["a","b","c"]

a.index("b")#=>1

a.index("z")#=>nil

a.index{|x|x=="b"}#=>1

Returnsthefirstelement,orthefirstnelements,ofthearray.Ifthearrayisempty,thefirstformreturnsnil,andthesecondformreturnsanemptyarray.Seealso#lastfortheoppositeeffect.

a=["q","r","s","t"]

a.first#=>"q"

a.first(2)#=>["q","r"]

Returnsanewarraythatisaone-dimensionalflatteningofself(recursively).

find_index→Enumeratorindex(obj)→intornilindex{|item|block}→intornilindex→Enumerator

first→objornilfirst(n)→new_ary

flatten→new_aryflatten(level)→new_ary

Thatis,foreveryelementthatisanarray,extractitselementsintothenewarray.

Theoptionallevelargumentdeterminesthelevelofrecursiontoflatten.

s=[1,2,3]#=>[1,2,3]

t=[4,5,6,[7,8]]#=>[4,5,6,[7,8]]

a=[s,t,9,10]#=>[[1,2,3],[4,5,6,[7,8]],9,10]

a.flatten#=>[1,2,3,4,5,6,7,8,9,10]

a=[1,2,[3,[4,5]]]

a.flatten(1)#=>[1,2,3,[4,5]]

Flattensselfinplace.

Returnsnilifnomodificationsweremade(i.e.,thearraycontainsnosubarrays.)

Theoptionallevelargumentdeterminesthelevelofrecursiontoflatten.

a=[1,2,[3,[4,5]]]

a.flatten!#=>[1,2,3,4,5]

a.flatten!#=>nil

a#=>[1,2,3,4,5]

a=[1,2,[3,[4,5]]]

a.flatten!(1)#=>[1,2,3,[4,5]]

Returntrueifthisarrayisfrozen(ortemporarilyfrozenwhilebeingsorted).SeealsoObject#frozen?

Computeahash-codeforthisarray.

Twoarrayswiththesamecontentwillhavethesame

flatten!→aryornilflatten!(level)→aryornil

frozen?→trueorfalse

hash→fixnum

hashcode(andwillcompareusingeql?).

SeealsoObject#hash.

Returnstrueifthegivenobjectispresentinself(thatis,ifanyelement==object),otherwisereturnsfalse.

a=["a","b","c"]

a.include?("b")#=>true

a.include?("z")#=>false

Returnstheindexofthefirstobjectinarysuchthattheobjectis==toobj.

Ifablockisgiveninsteadofanargument,returnstheindexofthefirstobjectforwhichtheblockreturnstrue.Returnsnilifnomatchisfound.

Seealso#rindex.

AnEnumeratorisreturnedifneitherablocknorargumentisgiven.

a=["a","b","c"]

a.index("b")#=>1

a.index("z")#=>nil

a.index{|x|x=="b"}#=>1

include?(object)→trueorfalse

find_index(obj)→intornilfind_index{|item|block}→intornilfind_index→Enumeratorindex(obj)→intornilindex{|item|block}→intornilindex→Enumerator

Replacesthecontentsofselfwiththecontentsofother_ary,truncatingorexpandingifnecessary.

a=["a","b","c","d","e"]

a.replace(["x","y","z"])#=>["x","y","z"]

a#=>["x","y","z"]

Insertsthegivenvaluesbeforetheelementwiththegivenindex.

Negativeindicescountbackwardsfromtheendofthearray,where-1isthelastelement.Ifanegativeindexisused,thegivenvalueswillbeinsertedafterthatelement,sousinganindexof-1willinsertthevaluesattheendofthearray.

a=%w{abcd}

a.insert(2,99)#=>["a","b",99,"c","d"]

a.insert(-2,1,2,3)#=>["a","b",99,"c",1,2,3,"d"]

Createsastringrepresentationofself.

["a","b","c"].to_s#=>"[\"a\",\"b\",\"c\"]"

Alsoaliasedas:to_s

Returnsastringcreatedbyconvertingeachelement

replace(other_ary)→aryinitialize_copy(other_ary)→ary

insert(index,obj...)→ary

inspect→stringto_s→string

join(separator=$,)→str

ofthearraytoastring,separatedbythegivenseparator.Iftheseparatorisnil,itusescurrent$,.Ifboththeseparatorand$,arenil,itusesemptystring.

["a","b","c"].join#=>"abc"

["a","b","c"].join("-")#=>"a-b-c"

Deleteseveryelementofselfforwhichthegivenblockevaluatestofalse.

Seealso#select!

a=%w{abcdef}

a.keep_if{|v|v=~/[aeiou]/}#=>["a","e"]

Returnsthelastelement(s)ofself.Ifthearrayisempty,thefirstformreturnsnil.

Seealso#firstfortheoppositeeffect.

a=["w","x","y","z"]

a.last#=>"z"

a.last(2)#=>["y","z"]

Returnsthenumberofelementsinself.Maybezero.

[1,2,3,4,5].length#=>5

keep_if{|item|block}→arykeep_if→Enumerator

last→objornillast(n)→new_ary

length→int

[].length#=>0

Alsoaliasedas:size

Invokesthegivenblockonceforeachelementofself.

Createsanewarraycontainingthevaluesreturnedbytheblock.

a=["a","b","c","d"]

a.collect{|x|x+"!"}#=>["a!","b!","c!","d!"]

a.map.with_index{|x,i|x*i}#=>["","b","cc","ddd"]

a#=>["a","b","c","d"]

Invokesthegivenblockonceforeachelementofself,replacingtheelementwiththevaluereturnedbytheblock.

a=["a","b","c","d"]

collect{|item|block}→new_arymap{|item|block}→new_arycollect→Enumeratormap→Enumerator

collect!{|item|block}→arymap!{|item|block}→arycollect!→Enumeratormap!→Enumerator

a.map!{|x|x+"!"}

a#=>["a!","b!","c!","d!"]

a.collect!.with_index{|x,i|x[0...i]}

a#=>["","b","c!","d!"]

PacksthecontentsofarrintoabinarysequenceaccordingtothedirectivesinaTemplateString(seethetablebelow)Directives“A,''“a,''and“Z''maybefollowedbyacount,whichgivesthewidthoftheresultingfield.Theremainingdirectivesalsomaytakeacount,indicatingthenumberofarrayelementstoconvert.Ifthecountisanasterisk(“*''),allremainingarrayelementswillbeconverted.Anyofthedirectives“sSiIlL''maybefollowedbyanunderscore(“_'')orexclamationmark(“!'')tousetheunderlyingplatform'snativesizeforthespecifiedtype;otherwise,theyuseaplatform-independentsize.Spacesareignoredinthetemplatestring.SeealsoString#unpack.

a=["a","b","c"]

n=[65,66,67]

a.pack("A3A3A3")#=>"abc"

a.pack("a3a3a3")#=>"a\000\000b\000\000c\000\000"

n.pack("ccc")#=>"ABC"

Directivesforpack.

Integer|Array|

Directive|Element|Meaning

---------------------------------------------------------------------------

C|Integer|8-bitunsigned(unsignedchar)

S|Integer|16-bitunsigned,nativeendian(uint16_t)

L|Integer|32-bitunsigned,nativeendian(uint32_t)

Q|Integer|64-bitunsigned,nativeendian(uint64_t)

c|Integer|8-bitsigned(signedchar)

s|Integer|16-bitsigned,nativeendian(int16_t)

pack(aTemplateString)→aBinaryString

l|Integer|32-bitsigned,nativeendian(int32_t)

q|Integer|64-bitsigned,nativeendian(int64_t)

S_,S!|Integer|unsignedshort,nativeendian

I,I_,I!|Integer|unsignedint,nativeendian

L_,L!|Integer|unsignedlong,nativeendian

Q_,Q!|Integer|unsignedlonglong,nativeendian(ArgumentError

||iftheplatformhasnolonglongtype.)

||(Q_andQ!isavailablesinceRuby2.1.)

s_,s!|Integer|signedshort,nativeendian

i,i_,i!|Integer|signedint,nativeendian

l_,l!|Integer|signedlong,nativeendian

q_,q!|Integer|signedlonglong,nativeendian(ArgumentError

||(q_andq!isavailablesinceRuby2.1.)

S>L>Q>|Integer|sameasthedirectiveswithout">"except

s>l>q>||bigendian

S!>I!>||(availablesinceRuby1.9.3)

L!>Q!>||"S>"issameas"n"

s!>i!>||"L>"issameas"N"

l!>q!>||

S<L<Q<|Integer|sameasthedirectiveswithout"<"except

s<l<q<||littleendian

S!<I!<||(availablesinceRuby1.9.3)

L!<Q!<||"S<"issameas"v"

s!<i!<||"L<"issameas"V"

l!<q!<||

n|Integer|16-bitunsigned,network(big-endian)byteorder

N|Integer|32-bitunsigned,network(big-endian)byteorder

v|Integer|16-bitunsigned,VAX(little-endian)byteorder

V|Integer|32-bitunsigned,VAX(little-endian)byteorder

U|Integer|UTF-8character

w|Integer|BER-compressedinteger

Float||

Directive||Meaning

---------------------------------------------------------------------------

D,d|Float|double-precision,nativeformat

F,f|Float|single-precision,nativeformat

E|Float|double-precision,little-endianbyteorder

e|Float|single-precision,little-endianbyteorder

G|Float|double-precision,network(big-endian)byteorder

g|Float|single-precision,network(big-endian)byteorder

String||

Directive||Meaning

---------------------------------------------------------------------------

A|String|arbitrarybinarystring(spacepadded,countiswidth)

a|String|arbitrarybinarystring(nullpadded,countiswidth)

Z|String|sameas``a'',exceptthatnullisaddedwith*

B|String|bitstring(MSBfirst)

b|String|bitstring(LSBfirst)

H|String|hexstring(highnibblefirst)

h|String|hexstring(lownibblefirst)

u|String|UU-encodedstring

M|String|quotedprintable,MIMEencoding(seeRFC2045)

m|String|base64encodedstring(seeRFC2045,countiswidth)

||(ifcountis0,nolinefeedareadded,seeRFC4648)

P|String|pointertoastructure(fixed-lengthstring)

p|String|pointertoanull-terminatedstring

Misc.||

Directive||Meaning

---------------------------------------------------------------------------

@|---|movestoabsoluteposition

X|---|backupabyte

x|---|nullbyte

Wheninvokedwithablock,yieldallpermutationsoflengthnoftheelementsofthearray,thenreturnthearrayitself.

Ifnisnotspecified,yieldallpermutationsofallelements.

Theimplementationmakesnoguaranteesabouttheorderinwhichthepermutationsareyielded.

Ifnoblockisgiven,anEnumeratorisreturned

permutation{|p|block}→arypermutation→Enumeratorpermutation(n){|p|block}→arypermutation(n)→Enumerator

instead.

Examples:

a=[1,2,3]

a.permutation.to_a#=>[[1,2,3],[1,3,2],[2,1,3],[2,3,1],[3,1,2],[3,2,1]]

a.permutation(1).to_a#=>[[1],[2],[3]]

a.permutation(2).to_a#=>[[1,2],[1,3],[2,1],[2,3],[3,1],[3,2]]

a.permutation(3).to_a#=>[[1,2,3],[1,3,2],[2,1,3],[2,3,1],[3,1,2],[3,2,1]]

a.permutation(0).to_a#=>[[]]#onepermutationoflength0

a.permutation(4).to_a#=>[]#nopermutationsoflength4

Removesthelastelementfromselfandreturnsit,ornilifthearrayisempty.

Ifanumbernisgiven,returnsanarrayofthelastnelements(orless)justlikearray.slice!(-n,n)does.Seealso#pushfortheoppositeeffect.

a=["a","b","c","d"]

a.pop#=>"d"

a.pop(2)#=>["b","c"]

a#=>["a"]

Returnsanarrayofallcombinationsofelementsfromallarrays.

Thelengthofthereturnedarrayistheproductofthelengthofselfandtheargumentarrays.

Ifgivenablock,productwillyieldallcombinationsandreturnselfinstead.

[1,2,3].product([4,5])#=>[[1,4],[1,5],[2,4],[2,5],[3,4],[3,5]]

[1,2].product([1,2])#=>[[1,1],[1,2],[2,1],[2,2]]

pop→objornilpop(n)→new_ary

product(other_ary,...)→new_aryproduct(other_ary,...){|p|block}→ary

[1,2].product([3,4],[5,6])#=>[[1,3,5],[1,3,6],[1,4,5],[1,4,6],

#[2,3,5],[2,3,6],[2,4,5],[2,4,6]]

[1,2].product()#=>[[1],[2]]

[1,2].product([])#=>[]

Append—Pushesthegivenobject(s)ontotheendofthisarray.Thisexpressionreturnsthearrayitself,soseveralappendsmaybechainedtogether.Seealso#popfortheoppositeeffect.

a=["a","b","c"]

a.push("d","e","f")

#=>["a","b","c","d","e","f"]

[1,2,3,].push(4).push(5)

#=>[1,2,3,4,5]

Searchesthroughthearraywhoseelementsarealsoarrays.

Comparesobjwiththesecondelementofeachcontainedarrayusingobj.==.

Returnsthefirstcontainedarraythatmatchesobj.

Seealso#assoc.

a=[[1,"one"],[2,"two"],[3,"three"],["ii","two"

a.rassoc("two")#=>[2,"two"]

a.rassoc("four")#=>nil

Returnsanewarraycontainingtheitemsinselfforwhichthegivenblockisnottrue.

push(obj,...)→ary

rassoc(obj)→new_aryornil

reject{|item|block}→new_aryreject→Enumerator

Seealso#delete_if

Equivalentto#delete_if,deletingelementsfromselfforwhichtheblockevaluatestotrue,butreturnsnilifnochangesweremade.

Thearrayischangedinstantlyeverytimetheblockiscalled,notaftertheiterationisover.

SeealsoEnumerable#rejectand#delete_if.

Wheninvokedwithablock,yieldsallrepeatedcombinationsoflengthnofelementsfromthearrayandthenreturnsthearrayitself.

Theimplementationmakesnoguaranteesabouttheorderinwhichtherepeatedcombinationsareyielded.

Examples:

a=[1,2,3]

a.repeated_combination(1).to_a#=>[[1],[2],[3]]

a.repeated_combination(2).to_a#=>[[1,1],[1,2],[1,3],[2,2],[2,3],[3,3]]

a.repeated_combination(3).to_a#=>[[1,1,1],[1,1,2],[1,1,3],[1,2,2],[1,2,3],

#[1,3,3],[2,2,2],[2,2,3],[2,3,3],[3,3,3]]

a.repeated_combination(4).to_a#=>[[1,1,1,1],[1,1,1,2],[1,1,1,3],[1,1,2,2],[1,1,2,3],

#[1,1,3,3],[1,2,2,2],[1,2,2,3],[1,2,3,3],[1,3,3,3],

reject!{|item|block}→aryornilreject!→Enumerator

repeated_combination(n){|c|block}→aryrepeated_combination(n)→Enumerator

#[2,2,2,2],[2,2,2,3],[2,2,3,3],[2,3,3,3],[3,3,3,3]]

a.repeated_combination(0).to_a#=>[[]]#onecombinationoflength0

Wheninvokedwithablock,yieldallrepeatedpermutationsoflengthnoftheelementsofthearray,thenreturnthearrayitself.

Theimplementationmakesnoguaranteesabouttheorderinwhichtherepeatedpermutationsareyielded.

Examples:

a=[1,2]

a.repeated_permutation(1).to_a#=>[[1],[2]]

a.repeated_permutation(2).to_a#=>[[1,1],[1,2],[2,1],[2,2]]

a.repeated_permutation(3).to_a#=>[[1,1,1],[1,1,2],[1,2,1],[1,2,2],

#[2,1,1],[2,1,2],[2,2,1],[2,2,2]]

a.repeated_permutation(0).to_a#=>[[]]#onepermutationoflength0

Replacesthecontentsofselfwiththecontentsofother_ary,truncatingorexpandingifnecessary.

a=["a","b","c","d","e"]

a.replace(["x","y","z"])#=>["x","y","z"]

a#=>["x","y","z"]

Returnsanewarraycontainingself'selementsin

repeated_permutation(n){|p|block}→aryrepeated_permutation(n)→Enumerator

replace(other_ary)→aryinitialize_copy(other_ary)→ary

reverse→new_ary

reverseorder.

["a","b","c"].reverse#=>["c","b","a"]

[1].reverse#=>[1]

Reversesselfinplace.

a=["a","b","c"]

a.reverse!#=>["c","b","a"]

a#=>["c","b","a"]

Sameas#each,buttraversesselfinreverseorder.

a=["a","b","c"]

a.reverse_each{|x|printx,""}

produces:

Returnstheindexofthelastobjectinself==toobj.

Ifablockisgiveninsteadofanargument,returnstheindexofthefirstobjectforwhichtheblockreturnstrue,startingfromthelastobject.

Returnsnilifnomatchisfound.

Seealso#index.

Ifneitherblocknorargumentisgiven,anEnumerator

reverse!→ary

reverse_each{|item|block}→aryreverse_each→Enumerator

rindex(obj)→intornilrindex{|item|block}→intornilrindex→Enumerator

isreturnedinstead.

a=["a","b","b","b","c"]

a.rindex("b")#=>3

a.rindex("z")#=>nil

a.rindex{|x|x=="b"}#=>3

Returnsanewarraybyrotatingselfsothattheelementatcountisthefirstelementofthenewarray.

Ifcountisnegativethenitrotatesintheoppositedirection,startingfromtheendofselfwhere-1isthelastelement.

a=["a","b","c","d"]

a.rotate#=>["b","c","d","a"]

a#=>["a","b","c","d"]

a.rotate(2)#=>["c","d","a","b"]

a.rotate(-3)#=>["b","c","d","a"]

Rotatesselfinplacesothattheelementatcountcomesfirst,andreturnsself.

Ifcountisnegativethenitrotatesintheoppositedirection,startingfromtheendofthearraywhere-1isthelastelement.

a=["a","b","c","d"]

a.rotate!#=>["b","c","d","a"]

a#=>["b","c","d","a"]

a.rotate!(2)#=>["d","a","b","c"]

a.rotate!(-3)#=>["a","b","c","d"]

rotate(count=1)→new_ary

rotate!(count=1)→ary

sample→objsample(random:rng)→obj

Choosearandomelementornrandomelementsfromthearray.

Theelementsarechosenbyusingrandomanduniqueindicesintothearrayinordertoensurethatanelementdoesn'trepeatitselfunlessthearrayalreadycontainedduplicateelements.

Ifthearrayisemptythefirstformreturnsnilandthesecondformreturnsanemptyarray.

Theoptionalrngargumentwillbeusedastherandomnumbergenerator.

a=[1,2,3,4,5,6,7,8,9,10]

a.sample#=>7

a.sample(4)#=>[6,4,2,5]

Returnsanewarraycontainingallelementsofaryforwhichthegivenblockreturnsatruevalue.

[1,2,3,4,5].select{|num|num.even?}#=>[2,4]

a=%w{abcdef}

a.select{|v|v=~/[aeiou]/}#=>["a","e"]

SeealsoEnumerable#select.

sample(n)→new_arysample(n,random:rng)→new_ary

select{|item|block}→new_aryselect→Enumerator

select!{|item|block}→aryornilselect!→Enumerator

Invokesthegivenblockpassinginsuccessiveelementsfromself,deletingelementsforwhichtheblockreturnsafalsevalue.

Ifchangesweremade,itwillreturnself,otherwiseitreturnsnil.

Seealso#keep_if

Removesthefirstelementofselfandreturnsit(shiftingallotherelementsdownbyone).Returnsnilifthearrayisempty.

Ifanumbernisgiven,returnsanarrayofthefirstnelements(orless)justlikearray.slice!(0,n)does.Witharycontainingonlytheremainderelements,notincludingwhatwasshiftedtonew_ary.Seealso#unshiftfortheoppositeeffect.

args=["-m","-q","filename"]

args.shift#=>"-m"

args#=>["-q","filename"]

args=["-m","-q","filename"]

args.shift(2)#=>["-m","-q"]

args#=>["filename"]

Returnsanewarraywithelementsofselfshuffled.

a=[1,2,3]#=>[1,2,3]

a.shuffle#=>[2,3,1]

shift→objornilshift(n)→new_ary

shuffle→new_aryshuffle(random:rng)→new_ary

a#=>[1,2,3]

a.shuffle(random:Random.new(1))#=>[1,3,2]

Shuffleselementsinselfinplace.

a=[1,2,3]#=>[1,2,3]

a.shuffle!#=>[2,3,1]

a#=>[2,3,1]

a.shuffle!(random:Random.new(1))#=>[1,3,2]

Aliasfor:length

ElementReference—Returnstheelementatindex,orreturnsasubarraystartingatthestartindexandcontinuingforlengthelements,orreturnsasubarrayspecifiedbyrangeofindices.

shuffle!→aryshuffle!(random:rng)→ary

size()

ary[index]→objornilary[start,length]→new_aryornilary[range]→new_aryornilslice(index)→objornilslice(start,length)→new_aryornilslice(range)→new_aryornil

Negativeindicescountbackwardfromtheendofthearray(-1isthelastelement).Forstartandrangecasesthestartingindexisjustbeforeanelement.Additionally,anemptyarrayisreturnedwhenthestartingindexforanelementrangeisattheendofthearray.

Returnsniliftheindex(orstartingindex)areoutofrange.

a=["a","b","c","d","e"]

a[2]+a[0]+a[1]#=>"cab"

a[6]#=>nil

a[1,2]#=>["b","c"]

a[1..3]#=>["b","c","d"]

a[4..7]#=>["e"]

a[6..10]#=>nil

a[-3,3]#=>["c","d","e"]

#specialcases

a[5]#=>nil

a[6,1]#=>nil

a[5,1]#=>[]

a[5..10]#=>[]

Deletestheelement(s)givenbyanindex(optionallyuptolengthelements)orbyarange.

Returnsthedeletedobject(orobjects),orniliftheindexisoutofrange.

a=["a","b","c"]

a.slice!(1)#=>"b"

a#=>["a","c"]

a.slice!(-1)#=>"c"

a#=>["a"]

a.slice!(100)#=>nil

a#=>["a"]

slice!(index)→objornilslice!(start,length)→new_aryornilslice!(range)→new_aryornil

Returnsanewarraycreatedbysortingself.

Comparisonsforthesortwillbedoneusingthe<=>operatororusinganoptionalcodeblock.

Theblockmustimplementacomparisonbetweenaandb,andreturn-1,whenafollowsb,0whenaandbareequivalent,or+1ifbfollowsa.

SeealsoEnumerable#sort_by.

a=["d","a","e","c","b"]

a.sort#=>["a","b","c","d","e"]

a.sort{|x,y|y<=>x}#=>["e","d","c","b","a"]

Sortsselfinplace.

Comparisonsforthesortwillbedoneusingthe<=>operatororusinganoptionalcodeblock.

Theblockmustimplementacomparisonbetweenaandb,andreturn-1,whenafollowsb,0whenaandbareequivalent,or+1ifbfollowsa.

SeealsoEnumerable#sort_by.

a=["d","a","e","c","b"]

a.sort!#=>["a","b","c","d","e"]

a.sort!{|x,y|y<=>x}#=>["e","d","c","b","a"]

sort→new_arysort{|a,b|block}→new_ary

sort!→arysort!{|a,b|block}→ary

sort_by!{|obj|block}→ary

Sortsselfinplaceusingasetofkeysgeneratedbymappingthevaluesinselfthroughthegivenblock.

Returnsfirstnelementsfromthearray.

Ifanegativenumberisgiven,raisesanArgumentError.

Seealso#drop

a=[1,2,3,4,5,0]

a.take(3)#=>[1,2,3]

Passeselementstotheblockuntiltheblockreturnsnilorfalse,thenstopsiteratingandreturnsanarrayofallpriorelements.

Seealso#drop_while

a=[1,2,3,4,5,0]

a.take_while{|i|i<3}#=>[1,2]

Returnsself.

IfcalledonasubclassofArray,convertsthereceivertoanArrayobject.

sort_by!→Enumerator

take(n)→new_ary

take_while{|arr|block}→new_arytake_while→Enumerator

to_a→ary

Returnsself.

Returnstheresultofinterpretingaryasanarrayof[key,value]pairs.

[[:foo,:bar],[1,2]].to_h

#=>{:foo=>:bar,1=>2}

Aliasfor:inspect

Assumesthatselfisanarrayofarraysandtransposestherowsandcolumns.

a=[[1,2],[3,4],[5,6]]

a.transpose#=>[[1,3,5],[2,4,6]]

Ifthelengthofthesubarraysdon'tmatch,anIndexErrorisraised.

Returnsanewarraybyremovingduplicatevaluesinself.

Ifablockisgiven,itwillusethereturnvalueoftheblockforcomparison.

Itcomparesvaluesusingtheirhashandeql?methodsforefficiency.

a=["a","a","b","b","c"]

to_ary→ary

to_h→hash

to_s()

transpose→new_ary

uniq→new_aryuniq{|item|...}→new_ary

a.uniq#=>["a","b","c"]

b=[["student","sam"],["student","george"],["teacher"

b.uniq{|s|s.first}#=>[["student","sam"],["teacher","matz"]]

Removesduplicateelementsfromself.

Ifablockisgiven,itwillusethereturnvalueoftheblockforcomparison.

Itcomparesvaluesusingtheirhashandeql?methodsforefficiency.

Returnsnilifnochangesaremade(thatis,noduplicatesarefound).

a=["a","a","b","b","c"]

a.uniq!#=>["a","b","c"]

b=["a","b","c"]

b.uniq!#=>nil

c=[["student","sam"],["student","george"],["teacher"

c.uniq!{|s|s.first}#=>[["student","sam"],["teacher","matz"]]

Prependsobjectstothefrontofself,movingotherelementsupwards.Seealso#shiftfortheoppositeeffect.

a=["b","c","d"]

a.unshift("a")#=>["a","b","c","d"]

a.unshift(1,2)#=>[1,2,"a","b","c","d"]

uniq!→aryorniluniq!{|item|...}→aryornil

unshift(obj,...)→ary

Returnsanarraycontainingtheelementsinselfcorrespondingtothegivenselector(s).

Theselectorsmaybeeitherintegerindicesorranges.

Seealso#select.

a=%w{abcdef}

a.values_at(1,3,5)#=>["b","d","f"]

a.values_at(1,3,5,7)#=>["b","d","f",nil]

a.values_at(-1,-2,-2,-7)#=>["f","e","e",nil]

a.values_at(4..6,3...6)#=>["e","f",nil,"d","e","f"]

Convertsanyargumentstoarrays,thenmergeselementsofselfwithcorrespondingelementsfromeachargument.

Thisgeneratesasequenceofary.sizen-elementarrays,wherenisonemorethanthecountofarguments.

Ifthesizeofanyargumentislessthanthesizeoftheinitialarray,nilvaluesaresupplied.

Ifablockisgiven,itisinvokedforeachoutputarray,otherwiseanarrayofarraysisreturned.

a=[4,5,6]

b=[7,8,9]

[1,2,3].zip(a,b)#=>[[1,4,7],[2,5,8],[3,6,9]]

[1,2].zip(a,b)#=>[[1,4,7],[2,5,8]]

a.zip([1,2],[8])#=>[[4,1,8],[5,2,nil],[6,nil,nil]]

values_at(selector,...)→new_ary

zip(arg,...)→new_aryzip(arg,...){|arr|block}→nil

SetUnion—Returnsanewarraybyjoiningarywithother_ary,excludinganyduplicatesandpreservingtheorderfromtheoriginalarray.

["a","b","c"]|["c","d","a"]#=>["a","b","c","d"]

Seealso#uniq.

ary|other_ary→new_ary

classBasicObjectBasicObjectistheparentclassofallclassesinRuby.It'sanexplicitblankclass.

BasicObjectcanbeusedforcreatingobjecthierarchiesindependentofRuby'sobjecthierarchy,proxyobjectsliketheDelegatorclass,orotheruseswherenamespacepollutionfromRuby'smethodsandclassesmustbeavoided.

ToavoidpollutingBasicObjectforotherusersanappropriatelynamedsubclassofBasicObjectshouldbecreatedinsteadofdirectlymodifyingBasicObject:

classMyObjectSystem<BasicObject

BasicObjectdoesnotincludeKernel(formethodslikeputs)andBasicObjectisoutsideofthenamespaceofthestandardlibrarysocommonclasseswillnotbefoundwithoutusingafullclasspath.

AvarietyofstrategiescanbeusedtoprovideusefulportionsofthestandardlibrarytosubclassesofBasicObject.AsubclasscouldincludeKerneltoobtainputs,exit,etc.AcustomKernel-likemodulecouldbecreatedandincludedordelegationcanbeusedvia

method_missing:

DELEGATE=[:puts,:p]

defmethod_missing(name,*args,&block)

superunlessDELEGATE.include?name

::Kernel.send(name,*args,&block)

defrespond_to_missing?(name,include_private=

DELEGATE.include?(name)orsuper

AccesstoclassesandmodulesfromtheRubystandardlibrarycanbeobtainedinaBasicObjectsubclassbyreferencingthedesiredconstantfromtherootlike::Fileor::Enumerator.Likemethod_missing,const_missingcanbeusedtodelegateconstantlookuptoObject:

defself.const_missing(name)

::Object.const_get(name)

InFilesclass.cgc.cobject.cvm_eval.c

Parent

PublicClassMethods

Notdocumented

Booleannegate.

Returnstrueiftwoobjectsarenot-equal,otherwisefalse.

Equality—AttheObjectlevel,==returnstrueonlyifobjandotherarethesameobject.Typically,thismethodisoverriddenindescendantclassestoprovideclass-specificmeaning.

Unlike==,theequal?methodshouldneverbeoverriddenbysubclassesasitisusedtodetermineobjectidentity(thatis,a.equal?(b)ifandonlyifaisthesameobjectasb):

obj="a"

other=obj.dup

!obj→trueorfalse

obj!=other→trueorfalse

obj==other→trueorfalseequal?(other)→trueorfalseeql?(other)→trueorfalse

obj==other#=>true

obj.equal?other#=>false

obj.equal?obj#=>true

Theeql?methodreturnstrueifobjandotherrefertothesamehashkey.ThisisusedbyHashtotestmembersforequality.ForobjectsofclassObject,eql?issynonymouswith==.Subclassesnormallycontinuethistraditionbyaliasingeql?totheiroverridden==method,butthereareexceptions.Numerictypes,forexample,performtypeconversionacross==,butnotacrosseql?,so:

1==1.0#=>true

1.eql?1.0#=>false

Returnsanintegeridentifierforobj.

Thesamenumberwillbereturnedonallcallstoobject_idforagivenobject,andnotwoactiveobjectswillshareanid.

Note:thatsomeobjectsofbuiltinclassesarereusedforoptimization.Thisisthecaseforimmediatevaluesandfrozenstringliterals.

Immediatevaluesarenotpassedbyreferencebutarepassedbyvalue:nil,true,false,Fixnums,Symbols,andsomeFloats.

Object.new.object_id==Object.new.object_id#=>false

(21*2).object_id==(21*2).object_id#=>true

"hello".object_id=="hello".object_id#=>false

"hi".freeze.object_id=="hi".freeze.object_id#=>true

__id__→integerobject_id→integer

Invokesthemethodidentifiedbysymbol,passingitanyargumentsspecified.Youcanuse__send__ifthenamesendclasheswithanexistingmethodinobj.Whenthemethodisidentifiedbyastring,thestringisconvertedtoasymbol.

classKlass

defhello(*args)

"Hello"+args.join('')

k=Klass.new

k.send:hello,"gentle","readers"#=>"Hellogentlereaders"

obj="a"

other=obj.dup

obj==other#=>true

send(symbol[,args...])→obj__send__(symbol[,args...])→objsend(string[,args...])→obj__send__(string[,args...])→obj

1==1.0#=>true

1.eql?1.0#=>false

EvaluatesastringcontainingRubysourcecode,orthegivenblock,withinthecontextofthereceiver(obj).Inordertosetthecontext,thevariableselfissettoobjwhilethecodeisexecuting,givingthecodeaccesstoobj'sinstancevariablesandprivatemethods.

Wheninstance_evalisgivenablock,objisalsopassedinastheblock'sonlyargument.

Wheninstance_evalisgivenaString,theoptionalsecondandthirdparameterssupplyafilenameandstartinglinenumberthatareusedwhenreportingcompilationerrors.

classKlassWithSecret

definitialize

@secret=99

private

defthe_secret

"Ssssh!Thesecretis#{@secret}."

instance_eval(string[,filename[,lineno]])→objinstance_eval{|obj|block}→obj

k=KlassWithSecret.new

k.instance_eval{@secret}#=>99

k.instance_eval{the_secret}#=>"Ssssh!Thesecretis99."

k.instance_eval{|obj|obj==self}#=>true

Executesthegivenblockwithinthecontextofthereceiver(obj).Inordertosetthecontext,thevariableselfissettoobjwhilethecodeisexecuting,givingthecodeaccesstoobj'sinstancevariables.Argumentsarepassedasblockparameters.

classKlassWithSecret

definitialize

@secret=99

k=KlassWithSecret.new

k.instance_exec(5){|x|@secret+x}#=>104

instance_exec(arg...){|var...|block}→obj

classBignumBignumobjectsholdintegersoutsidetherangeofFixnum.BignumobjectsarecreatedautomaticallywhenintegercalculationswouldotherwiseoverflowaFixnum.WhenacalculationinvolvingBignumobjectsreturnsaresultthatwillfitinaFixnum,theresultisautomaticallyconverted.

Forthepurposesofthebitwiseoperationsand[],aBignumistreatedasifitwereaninfinite-lengthbitstringwith2'scomplementrepresentation.

WhileFixnumvaluesareimmediate,Bignumobjectsarenot—assignmentandparameterpassingworkwithreferencestoobjects,nottheobjectsthemselves.

InFilesbignum.c

ParentInteger

Constants

GMP_VERSION

TheversionofloadedGMP.

Returnsbigmoduloother.SeeNumeric#divmodformoreinformation.

Performsbitwiseandbetweenbigandnumeric.

Multipliesbigandother,returningtheresult.

Raisesbigtotheexponentpower(whichmaybeaninteger,float,oranythingthatwillcoercetoanumber).TheresultmaybeaFixnum,Bignum,orFloat

123456789**2#=>15241578750190521

123456789**1.2#=>5126464716.09932

123456789**-2#=>6.5610001194102e-17

Addsbigandother,returningtheresult.

big%other→Numericmodulo(other)→Numeric

big&numeric→integer

big*other→Numeric

big**exponent→numeric

big+other→Numeric

big-other→Numeric

Subtractsotherfrombig,returningtheresult.

Unaryminus(returnsanintegerwhosevalueis0-big)

Performsdivision:theclassoftheresultingobjectdependsontheclassofnumericandonthemagnitudeoftheresult.

Returnstrueifthevalueofbigislessthanthatofreal.

Shiftsbigleftnumericpositions(rightifnumericisnegative).

Returnstrueifthevalueofbigislessthanorequaltothatofreal.

Comparison—Returns-1,0,or+1dependingonwhetherbigislessthan,equalto,orgreaterthannumeric.ThisisthebasisforthetestsinComparable.

nilisreturnedifthetwovaluesareincomparable.

-big→integer

big/other→Numeric

big<real→trueorfalse

big<<numeric→integer

big<=real→trueorfalse

big<=>numeric→-1,0,+1ornil

big==obj→trueorfalse

Returnstrueonlyifobjhasthesamevalueasbig.ContrastthiswithBignum#eql?,whichrequiresobjtobeaBignum.

68719476736==68719476736.0#=>true

Returnstrueonlyifobjhasthesamevalueasbig.ContrastthiswithBignum#eql?,whichrequiresobjtobeaBignum.

68719476736==68719476736.0#=>true

Returnstrueifthevalueofbigisgreaterthanthatofreal.

Returnstrueifthevalueofbigisgreaterthanorequaltothatofreal.

Shiftsbigrightnumericpositions(leftifnumericisnegative).

BitReference—Returnsthenthbitinthe(assumed)binaryrepresentationofbig,wherebigistheleastsignificantbit.

a=9**15

50.downto(0)do|n|

big==obj→trueorfalse

big>real→trueorfalse

big>=real→trueorfalse

big>>numeric→integer

big[n]→0,1

printa[n]

produces:

000101110110100000111000011110010100111100010111001

Performsbitwise+exclusiveor+betweenbigandnumeric.

Returnstheabsolutevalueofbig.

-1234567890987654321.abs#=>1234567890987654321

Returnsthenumberofbitsofthevalueofint.

“thenumberofbits”meansthatthebitpositionofthehighestbitwhichisdifferenttothesignbit.(Thebitpositionofthebit2**nisn+1.)Ifthereisnosuchbit(zeroorminusone),zeroisreturned.

I.e.Thismethodreturnsceil(log2(int<0?-int:int+1)).

(-2**10000-1).bit_length#=>10001

(-2**10000).bit_length#=>10000

(-2**10000+1).bit_length#=>10000

(-2**1000-1).bit_length#=>1001

(-2**1000).bit_length#=>1000

(-2**1000+1).bit_length#=>1000

(2**1000-1).bit_length#=>1000

big^numeric→integer

abs→aBignummagnitude→aBignum

bit_length→integer

(2**1000).bit_length#=>1001

(2**1000+1).bit_length#=>1001

(2**10000-1).bit_length#=>10000

(2**10000).bit_length#=>10001

(2**10000+1).bit_length#=>10001

ThismethodcanbeusedtodetectoverflowinArray#packasfollows.

ifn.bit_length<32

[n].pack("l")#nooverflow

raise"overflow"

ReturnsanarraywithbothanumericandabigrepresentedasBignumobjects.

ThisisachievedbyconvertingnumerictoaBignum.

ATypeErrorisraisedifthenumericisnotaFixnumorBignumtype.

(0x3FFFFFFFFFFFFFFF+1).coerce(42)#=>[42,4611686018427387904]

Performsintegerdivision:returnsintegervalue.

SeeNumeric#divmod.

ReturnstrueonlyifobjisaBignumwiththesamevalueasbig.ContrastthiswithBignum#==,which

coerce(numeric)→array

div(other)→integer

divmod(numeric)→array

eql?(obj)→trueorfalse

performstypeconversions.

68719476736.eql?(68719476736.0)#=>false

Returnstrueifbigisanevennumber.

Returnsthefloatingpointresultofdividingbigbynumeric.

-1234567890987654321.fdiv(13731)#=>-89910996357705.5

-1234567890987654321.fdiv(13731.24)#=>-89909424858035.7

Computeahashbasedonthevalueofbig.

SeealsoObject#hash.

Aliasfor:to_s

Returnstheabsolutevalueofbig.

-1234567890987654321.abs#=>1234567890987654321

Returnsbigmoduloother.SeeNumeric#divmodfor

even?→trueorfalse

fdiv(numeric)→float

hash→fixnum

inspect(p1=v1)

abs→aBignummagnitude→aBignum

big%other→Numericmodulo(other)→Numeric

moreinformation.

Returnstrueifbigisanoddnumber.

Returnstheremainderafterdividingbigbynumeric.

-1234567890987654321.remainder(13731)#=>-6966

-1234567890987654321.remainder(13731.24)#=>-9906.22531493148

Returnsthenumberofbytesinthemachinerepresentationofbig.

(256**10-1).size#=>12

(256**20-1).size#=>20

(256**40-1).size#=>40

ConvertsbigtoaFloat.Ifbigdoesn'tfitinaFloat,theresultisinfinity.

Returnsastringcontainingtherepresentationofbigradixbase(2through36).

12345654321.to_s#=>"12345654321"

12345654321.to_s(2)#=>"1011011111110110111011110000110001"

12345654321.to_s(8)#=>"133766736061"

12345654321.to_s(16)#=>"2dfdbbc31"

78546939656932.to_s(36)#=>"rubyrules"

odd?→trueorfalse

remainder(numeric)→number

size→integer

to_f→float

to_s(base=10)→string

Alsoaliasedas:inspect

Performsbitwiseorbetweenbigandnumeric.

Invertsthebitsinbig.AsBignumsareconceptuallyinfinitelength,theresultactsasifithadaninfinitenumberofonebitstotheleft.Inhexrepresentations,thisisdisplayedastwoperiodstotheleftofthedigits.

sprintf("%X",~0x1122334455)#=>"..FEEDDCCBBAA"

big|numeric→integer

~big→integer

classBindingObjectsofclassBindingencapsulatetheexecutioncontextatsomeparticularplaceinthecodeandretainthiscontextforfutureuse.Thevariables,methods,valueofself,andpossiblyaniteratorblockthatcanbeaccessedinthiscontextareallretained.BindingobjectscanbecreatedusingKernel#binding,andaremadeavailabletothecallbackofKernel#set_trace_func.

ThesebindingobjectscanbepassedasthesecondargumentoftheKernel#evalmethod,establishinganenvironmentfortheevaluation.

classDemo

definitialize(n)

@secret=n

defget_binding

returnbinding()

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

Bindingobjectshavenoclass-specificmethods.

InFilesproc.c

ParentObject

EvaluatestheRubyexpression(s)instring,inthebinding'scontext.Iftheoptionalfilenameandlinenoparametersarepresent,theywillbeusedwhenreportingsyntaxerrors.

defget_binding(param)

returnbinding

b=get_binding("hello")

b.eval("param")#=>"hello"

Returnsatrueifalocalvariablesymbolexists.

deffoo

binding.local_variable_defined?(:a)#=>true

binding.local_variable_defined?(:b)#=>false

Thismethodisshortversionofthefollowingcode.

binding.eval("defined?(#{symbol})=='local-variable'")

eval(string[,filename[,lineno]])→obj

local_variable_defined?(symbol)→obj

Returnsavalueoflocalvariablesymbol.

deffoo

binding.local_variable_get(:a)#=>1

binding.local_variable_get(:b)#=>NameError

binding.eval("#{symbol}")

Setlocalvariablenamedsymbolasobj.

deffoo

b=binding

b.local_variable_set(:a,2)#setexistinglocalvariable`a'

b.local_variable_set(:b,3)#createnewlocalvariable`b'

#`b'existsonlyinbinding.

b.local_variable_get(:a)#=>2

b.local_variable_get(:b)#=>3

pa#=>2

pb#=>NameError

Thismethodisasimilarbehaviorofthefollowingcode

binding.eval("#{symbol}=#{obj}")

ifobjcanbedumpedinRubycode.

Returnsthesymbolnamesofthebinding'slocal

local_variable_get(symbol)→obj

local_variable_set(symbol,obj)→obj

local_variables→Array

variables

deffoo

2.timesdo|n|

binding.local_variables#=>[:a,:n]

binding.eval("local_variables")

Returnstheboundreceiverofthebindingobject.

receiver→object

classClassClassesinRubyarefirst-classobjects—eachisaninstanceofclassClass.

Typically,youcreateanewclassbyusing:

className

#somecodedescribingtheclassbehavior

Whenanewclassiscreated,anobjectoftypeClassisinitializedandassignedtoaglobalconstant(Nameinthiscase).

WhenName.newiscalledtocreateanewobject,thenewmethodinClassisrunbydefault.ThiscanbedemonstratedbyoverridingnewinClass:

classClass

aliasold_newnew

defnew(*args)

print"Creatinganew",self.name,"\n"

old_new(*args)

className

n=Name.new

produces:

CreatinganewName

Classes,modules,andobjectsareinterrelated.Inthediagramthatfollows,theverticalarrowsrepresentinheritance,andtheparenthesesmetaclasses.Allmetaclassesareinstancesoftheclass`Class'.

+---------++-...

BasicObject-----|-->(BasicObject)-------|-...

Object---------|----->(Object)---------|-...

+-------+|+--------+|

||||||

|Module-|---------|--->(Module)-|-...

|^||^|

||||||

|Class-|---------|---->(Class)-|-...

|^||^|

|+---+|+----+

obj--->OtherClass---------->(OtherClass)-----------...

InFilesclass.cobject.c

ParentModule

PublicClassMethods

Createsanewanonymous(unnamed)classwiththegivensuperclass(orObjectifnoparameterisgiven).Youcangiveaclassanamebyassigningtheclassobjecttoaconstant.

Ifablockisgiven,itispassedtheclassobject,andtheblockisevaluatedinthecontextofthisclassusingclass_eval.

fred=Class.newdo

defmeth1

"hello"

defmeth2

a=fred.new#=>#<#<Class:0x100381890>:0x100376b98>

a.meth1#=>"hello"

a.meth2#=>"bye"

Assigntheclasstoaconstant(namestartinguppercase)ifyouwanttotreatitlikearegularclass.

Allocatesspaceforanewobjectofclass'sclassanddoesnotcallinitializeonthenewinstance.Thereturnedobjectmustbeaninstanceofclass.

new(super_class=Object)→a_classnew(super_class=Object){|mod|...}→a_class

allocate()→obj

klass=Class.newdo

definitialize(*args)

@initialized=true

definitialized?

@initialized||false

klass.allocate.initialized?#=>false

Callsallocatetocreateanewobjectofclass'sclass,theninvokesthatobject'sinitializemethod,passingitargs.Thisisthemethodthatendsupgettingcalledwheneveranobjectisconstructedusing.new.

Returnsthesuperclassofclass,ornil.

File.superclass#=>IO

IO.superclass#=>Object

Object.superclass#=>BasicObject

classFoo;end

classBar<Foo;end

Bar.superclass#=>Foo

Returnsnilwhenthegivenclassdoesnothaveaparentclass:

BasicObject.superclass#=>nil

new(args,...)→obj

superclass→a_super_classornil

moduleComparableTheComparablemixinisusedbyclasseswhoseobjectsmaybeordered.Theclassmustdefinethe<=>operator,whichcomparesthereceiveragainstanotherobject,returning-1,0,or+1dependingonwhetherthereceiverislessthan,equalto,orgreaterthantheotherobject.Iftheotherobjectisnotcomparablethenthe<=>operatorshouldreturnnil.Comparableuses<=>toimplementtheconventionalcomparisonoperators(<,<=,==,>=,and>)andthemethodbetween?.

classSizeMatters

includeComparable

attr:str

def<=>(anOther)

str.size<=>anOther.str.size

definitialize(str)

@str=str

definspect

s1=SizeMatters.new("Z")

s2=SizeMatters.new("YY")

s3=SizeMatters.new("XXX")

s4=SizeMatters.new("WWWW")

s5=SizeMatters.new("VVVVV")

s1<s2#=>true

s4.between?(s1,s3)#=>false

s4.between?(s3,s5)#=>true

[s3,s2,s5,s4,s1].sort#=>[Z,YY,XXX,WWWW,VVVVV]

InFilescompar.c

Comparestwoobjectsbasedonthereceiver's<=>method,returningtrueifitreturns-1.

Comparestwoobjectsbasedonthereceiver's<=>method,returningtrueifitreturns-1or0.

Comparestwoobjectsbasedonthereceiver's<=>method,returningtrueifitreturns0.Alsoreturnstrueifobjandotherarethesameobject.

Evenifobj<=>otherraisedanexception,theexceptionisignoredandreturnsfalse.

Comparestwoobjectsbasedonthereceiver's<=>method,returningtrueifitreturns1.

obj<other→trueorfalse

obj<=other→trueorfalse

obj==other→trueorfalse

obj>other→trueorfalse

Comparestwoobjectsbasedonthereceiver's<=>method,returningtrueifitreturns0or1.

Returnsfalseifobj<=>minislessthanzeroorifanObject<=>maxisgreaterthanzero,trueotherwise.

3.between?(1,5)#=>true

6.between?(1,5)#=>false

'cat'.between?('ant','dog')#=>true

'gnu'.between?('ant','dog')#=>false

obj>=other→trueorfalse

between?(min,max)→trueorfalse

classComplexAcomplexnumbercanberepresentedasapairedrealnumberwithimaginaryunit;a+bi.Whereaisrealpart,bisimaginarypartandiisimaginaryunit.Realaequalscomplexa+0imathematically.

Inruby,youcancreatecomplexobjectwithComplex,::rect,::polaror#to_cmethod.

Complex(1)#=>(1+0i)

Complex(2,3)#=>(2+3i)

Complex.polar(2,3)#=>(-1.9799849932008908+0.2822400161197344i)

3.to_c#=>(3+0i)

Youcanalsocreatecomplexobjectfromfloating-pointnumbersorstrings.

Complex(0.3)#=>(0.3+0i)

Complex('0.3-0.5i')#=>(0.3-0.5i)

Complex('2/3+3/4i')#=>((2/3)+(3/4)*i)

Complex('1@2')#=>(-0.4161468365471424+0.9092974268256817i)

0.3.to_c#=>(0.3+0i)

'0.3-0.5i'.to_c#=>(0.3-0.5i)

'2/3+3/4i'.to_c#=>((2/3)+(3/4)*i)

'1@2'.to_c#=>(-0.4161468365471424+0.9092974268256817i)

Acomplexobjectiseitheranexactoraninexactnumber.

Complex(1,1)/2#=>((1/2)+(1/2)*i)

Complex(1,1)/2.0#=>(0.5+0.5i)

InFilescomplex.c

ParentNumeric

Constants

Theimaginaryunit.

PublicClassMethods

Returnsacomplexobjectwhichdenotesthegivenpolarform.

Complex.polar(3,0)#=>(3.0+0.0i)

Complex.polar(3,Math::PI/2)#=>(1.836909530733566e-16+3.0i)

Complex.polar(3,Math::PI)#=>(-3.0+3.673819061467132e-16i)

Complex.polar(3,-Math::PI/2)#=>(1.836909530733566e-16-3.0i)

Returnsacomplexobjectwhichdenotesthegiven

polar(abs[,arg])→complex

rect(real[,imag])→complexrectangular(real[,imag])→complex

rectangularform.

Complex.rectangular(1,2)#=>(1+2i)

Returnsacomplexobjectwhichdenotesthegivenrectangularform.

Complex.rectangular(1,2)#=>(1+2i)

Performsmultiplication.

Complex(2,3)*Complex(2,3)#=>(-5+12i)

Complex(900)*Complex(1)#=>(900+0i)

Complex(-2,9)*Complex(-9,2)#=>(0-85i)

Complex(9,8)*4#=>(36+32i)

Complex(20,9)*9.8#=>(196.0+88.2i)

Performsexponentiation.

Complex('i')**2#=>(-1+0i)

Complex(-8)**Rational(1,3)#=>(1.0000000000000002+1.7320508075688772i)

Performsaddition.

Complex(2,3)+Complex(2,3)#=>(4+6i)

Complex(900)+Complex(1)#=>(901+0i)

rect(real[,imag])→complexrectangular(real[,imag])→complex

cmp*numeric→complex

cmp**numeric→complex

cmp+numeric→complex

Complex(-2,9)+Complex(-9,2)#=>(-11+11i)

Complex(9,8)+4#=>(13+8i)

Complex(20,9)+9.8#=>(29.8+9i)

Performssubtraction.

Complex(2,3)-Complex(2,3)#=>(0+0i)

Complex(900)-Complex(1)#=>(899+0i)

Complex(-2,9)-Complex(-9,2)#=>(7+7i)

Complex(9,8)-4#=>(5+8i)

Complex(20,9)-9.8#=>(10.2+9i)

Returnsnegationofthevalue.

-Complex(1,2)#=>(-1-2i)

Performsdivision.

Complex(2,3)/Complex(2,3)#=>((1/1)+(0/1)*i)

Complex(900)/Complex(1)#=>((900/1)+(0/1)*i)

Complex(-2,9)/Complex(-9,2)#=>((36/85)-(77/85)*i)

Complex(9,8)/4#=>((9/4)+(2/1)*i)

Complex(20,9)/9.8#=>(2.0408163265306123+0.9183673469387754i)

Returnstrueifcmpequalsobjectnumerically.

Complex(2,3)==Complex(2,3)#=>true

Complex(5)==5#=>true

Complex(0)==0.0#=>true

Complex('1/3')==0.33#=>false

Complex('1/2')=='1/2'#=>false

cmp-numeric→complex

-cmp→complex

cmp/numeric→complexquo(numeric)→complex

cmp==object→trueorfalse

Returnstheabsolutepartofitspolarform.

Complex(-1).abs#=>1

Complex(3.0,-4.0).abs#=>5.0

Returnssquareoftheabsolutevalue.

Complex(-1).abs2#=>1

Complex(3.0,-4.0).abs2#=>25.0

Returnstheanglepartofitspolarform.

Complex.polar(3,Math::PI/2).arg#=>1.5707963267948966

Returnsthecomplexconjugate.

abs→realmagnitude→real

abs2→real

arg→floatangle→floatphase→float

conj→complexconjugate→complex

Complex(1,2).conjugate#=>(1-2i)

Returnsthedenominator(lcmofbothdenominator-realandimag).

Seenumerator.

Performsdivisionaseachpartisafloat,neverreturnsafloat.

Complex(11,22).fdiv(3)#=>(3.6666666666666665+7.333333333333333i)

Returnstheimaginarypart.

Complex(7).imaginary#=>0

Complex(9,-4).imaginary#=>-4

Returnstheimaginarypart.

Complex(7).imaginary#=>0

Complex(9,-4).imaginary#=>-4

denominator→integer

fdiv(numeric)→complex

imag→realimaginary→real

Returnsthevalueasastringforinspection.

Complex(2).inspect#=>"(2+0i)"

Complex('-8/6').inspect#=>"((-4/3)+0i)"

Complex('1/2i').inspect#=>"(0+(1/2)*i)"

Complex(0,Float::INFINITY).inspect#=>"(0+Infinity*i)"

Complex(Float::NAN,Float::NAN).inspect#=>"(NaN+NaN*i)"

Returnstheabsolutepartofitspolarform.

Complex(-1).abs#=>1

Complex(3.0,-4.0).abs#=>5.0

Returnsthenumerator.

123+4i<-numerator

-+-i->----

236<-denominator

c=Complex('1/2+2/3i')#=>((1/2)+(2/3)*i)

n=c.numerator#=>(3+4i)

d=c.denominator#=>6

n/d#=>((1/2)+(2/3)*i)

Complex(Rational(n.real,d),Rational(n.imag,d))

#=>((1/2)+(2/3)*i)

Seedenominator.

inspect→string

abs→realmagnitude→real

numerator→numeric

arg→floatangle→float

Returnsanarray;[cmp.abs,cmp.arg].

Complex(1,2).polar#=>[2.23606797749979,1.1071487177940904]

Performsdivision.

Complex(2,3)/Complex(2,3)#=>((1/1)+(0/1)*i)

Complex(900)/Complex(1)#=>((900/1)+(0/1)*i)

Complex(-2,9)/Complex(-9,2)#=>((36/85)-(77/85)*i)

Complex(9,8)/4#=>((9/4)+(2/1)*i)

Complex(20,9)/9.8#=>(2.0408163265306123+0.9183673469387754i)

Returnsthevalueasarationalifpossible(theimaginarypartshouldbeexactlyzero).

Complex(1.0/3,0).rationalize#=>(1/3)

Complex(1,0.0).rationalize#RangeError

Complex(1,2).rationalize#RangeError

Seeto_r.

Returnstherealpart.

Complex(7).real#=>7

phase→float

polar→array

cmp/numeric→complexquo(numeric)→complex

rationalize([eps])→rational

real→real

Complex(9,-4).real#=>9

Returnsfalse.

Returnsanarray;[cmp.real,cmp.imag].

Complex(1,2).rectangular#=>[1,2]

Returnsanarray;[cmp.real,cmp.imag].

Complex(1,2).rectangular#=>[1,2]

Returnsself.

Complex(2).to_c#=>(2+0i)

Complex(-8,6).to_c#=>(-8+6i)

Returnsthevalueasafloatifpossible(theimaginarypartshouldbeexactlyzero).

Complex(1,0).to_f#=>1.0

Complex(1,0.0).to_f#RangeError

Complex(1,2).to_f#RangeError

real?→false

rect→arrayrectangular→array

to_c→self

to_f→float

to_i→integer

Returnsthevalueasanintegerifpossible(theimaginarypartshouldbeexactlyzero).

Complex(1,0).to_i#=>1

Complex(1,0.0).to_i#RangeError

Complex(1,2).to_i#RangeError

Returnsthevalueasarationalifpossible(theimaginarypartshouldbeexactlyzero).

Complex(1,0).to_r#=>(1/1)

Complex(1,0.0).to_r#RangeError

Complex(1,2).to_r#RangeError

Seerationalize.

Returnsthevalueasastring.

Complex(2).to_s#=>"2+0i"

Complex('-8/6').to_s#=>"-4/3+0i"

Complex('1/2i').to_s#=>"0+1/2i"

Complex(0,Float::INFINITY).to_s#=>"0+Infinity*i"

Complex(Float::NAN,Float::NAN).to_s#=>"NaN+NaN*i"

to_r→rational

to_s→string

classComplex::compatible

InFilescomplex.c

ParentObject

classContinuationContinuationobjectsaregeneratedbyKernel#callcc,afterhaving+require+dcontinuation.Theyholdareturnaddressandexecutioncontext,allowinganonlocalreturntotheendofthecallccblockfromanywherewithinaprogram.ContinuationsaresomewhatanalogoustoastructuredversionofC'ssetjmp/longjmp(althoughtheycontainmorestate,soyoumightconsiderthemclosertothreads).

Forinstance:

require"continuation"

arr=["Freddie","Herbie","Ron","Max","Ringo"

callcc{|cc|$cc=cc}

puts(message=arr.shift)

$cc.callunlessmessage=~/Max/

produces:

Freddie

Herbie

This(somewhatcontrived)exampleallowstheinnerlooptoabandonprocessingearly:

require"continuation"

callcc{|cont|

foriin0..4

print"\n#{i}:"

forjini*5...(i+1)*5

cont.call()ifj==17

printf"%3d",j

produces:

0:01234

1:56789

2:1011121314

3:1516

InFilescont.c

ParentObject

Invokesthecontinuation.Theprogramcontinuesfromtheendofthecallccblock.Ifnoargumentsaregiven,theoriginalcallccreturnsnil.Ifoneargument

call(args,...)cont[args,...]

isgiven,callccreturnsit.Otherwise,anarraycontainingargsisreturned.

callcc{|cont|cont.call}#=>nil

callcc{|cont|cont.call1}#=>1

callcc{|cont|cont.call1,2,3}#=>[1,2,3]

Invokesthecontinuation.Theprogramcontinuesfromtheendofthecallccblock.Ifnoargumentsaregiven,theoriginalcallccreturnsnil.Ifoneargumentisgiven,callccreturnsit.Otherwise,anarraycontainingargsisreturned.

callcc{|cont|cont.call}#=>nil

callcc{|cont|cont.call1}#=>1

callcc{|cont|cont.call1,2,3}#=>[1,2,3]

call(args,...)cont[args,...]

classDataThisisarecommendedbaseclassforCextensionsusingData_Make_StructorData_Wrap_Struct,seeREADME.EXTfordetails.

InFilesobject.c

ParentObject

classDirObjectsofclassDiraredirectorystreamsrepresentingdirectoriesintheunderlyingfilesystem.Theyprovideavarietyofwaystolistdirectoriesandtheircontents.SeealsoFile.

Thedirectoryusedintheseexamplescontainsthetworegularfiles(config.handmain.rb),theparentdirectory(..),andthedirectoryitself(.).

InFilesdir.c

ParentObject

PublicClassMethods

EquivalenttocallingDir.glob([string,...],0).Dir[string[,string...]]→array

chdir([string])→0

Changesthecurrentworkingdirectoryoftheprocesstothegivenstring.Whencalledwithoutanargument,changesthedirectorytothevalueoftheenvironmentvariableHOME,orLOGDIR.SystemCallError(probablyErrno::ENOENT)ifthetargetdirectorydoesnotexist.

Ifablockisgiven,itispassedthenameofthenewcurrentdirectory,andtheblockisexecutedwiththatasthecurrentdirectory.Theoriginalworkingdirectoryisrestoredwhentheblockexits.Thereturnvalueofchdiristhevalueoftheblock.chdirblockscanbenested,butinamulti-threadedprogramanerrorwillberaisedifathreadattemptstoopenachdirblockwhileanotherthreadhasoneopen.

Dir.chdir("/var/spool/mail")

putsDir.pwd

Dir.chdir("/tmp")do

putsDir.pwd

Dir.chdir("/usr")do

putsDir.pwd

produces:

/var/spool/mail

Changesthisprocess'sideaofthefilesystemroot.Onlyaprivilegedprocessmaymakethiscall.Notavailableonallplatforms.OnUnixsystems,see

chdir([string]){|path|block}→anObject

chroot(string)→0

chroot(2)formoreinformation.

Deletesthenameddirectory.RaisesasubclassofSystemCallErrorifthedirectoryisn'tempty.

Returnsanarraycontainingallofthefilenamesinthegivendirectory.WillraiseaSystemCallErrorifthenameddirectorydoesn'texist.

Theoptionalencargumentspecifiestheencodingofthedirectory.Ifnotspecified,thefilesystemencodingisused.

Dir.entries("testdir")#=>[".","..","config.h","main.rb"]

Returnstrueifthenamedfileisadirectory,falseotherwise.

Deprecatedmethod.Don'tuse.

delete(string)→0rmdir(string)→0unlink(string)→0

entries(dirname)→arrayentries(dirname,encoding:enc)→array

exist?(file_name)→trueorfalse

exists?(file_name)→trueorfalse

foreach(dirname){|filename|block}→nilforeach(dirname,encoding:enc){|filename|block}→nilforeach(dirname)→an_enumerator

Callstheblockonceforeachentryinthenameddirectory,passingthefilenameofeachentryasaparametertotheblock.

Ifnoblockisgiven,anenumeratorisreturnedinstead.

Dir.foreach("testdir"){|x|puts"Got#{x}"}

produces:

Gotconfig.h

Gotmain.rb

Returnsthepathtothecurrentworkingdirectoryofthisprocessasastring.

Dir.chdir("/tmp")#=>0

Dir.getwd#=>"/tmp"

Dir.pwd#=>"/tmp"

Expandspattern,whichisanArrayofpatternsorapatternString,andreturnstheresultsasmatchesorasargumentsgiventotheblock.

Notethatthispatternisnotaregexp,it'sclosertoashellglob.SeeFile.fnmatchforthemeaningoftheflagsparameter.Notethatcasesensitivitydepends

foreach(dirname,encoding:enc)→an_enumerator

getwd→stringpwd→string

glob(pattern,[flags])→matchesglob(pattern,[flags]){|filename|block}→nil

onyoursystem(soFile::FNM_CASEFOLDisignored),asdoestheorderinwhichtheresultsarereturned.*

Matchesanyfile.Canberestrictedbyothervaluesintheglob.Equivalentto/.*/xinregexp.*

Matchesallfiles

Matchesallfilesbeginningwithc

Matchesallfilesendingwithc

Matchallfilesthathavecinthem(includingatthebeginningorend).

Note,thiswillnotmatchUnix-likehiddenfiles(dotfiles).Inordertoincludethoseinthematchresults,youmustusetheFile::FNM_DOTMATCHflagorsomethinglike"{*,.*}".

Matchesdirectoriesrecursively.

Matchesanyonecharacter.Equivalentto/.{1}/inregexp.

Matchesanyonecharacterinset.BehavesexactlylikecharactersetsinRegexp,includingsetnegation([^a-z]).

Matcheseitherliteralporliteralq.Equivalenttopatternalternationinregexp.

Matchingliteralsmaybemorethanonecharacter

inlength.Morethantwoliteralsmaybespecified.

Escapesthenextmetacharacter.

Notethatthismeansyoucannotusebackslashonwindowsaspartofaglob,i.e.Dir["c:\foo*"]willnotwork,useDir["c:/foo*"]instead.

Examples:

Dir["config.?"]#=>["config.h"]

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","main.rb"]

Dir.glob("*",File::FNM_DOTMATCH)#=>[".","..","config.h","main.rb"]

rbfiles=File.join("**","*.rb")

Dir.glob(rbfiles)#=>["main.rb",

#"lib/song.rb",

#"lib/song/karaoke.rb"]

libdirs=File.join("**","lib")

Dir.glob(libdirs)#=>["lib"]

librbfiles=File.join("**","lib","**","*.rb")

Dir.glob(librbfiles)#=>["lib/song.rb",

#"lib/song/karaoke.rb"]

librbfiles=File.join("**","lib","*.rb")

Dir.glob(librbfiles)#=>["lib/song.rb"]

Returnsthehomedirectoryofthecurrentuserorthenameduserifgiven.

Makesanewdirectorynamedbystring,with

home()→"/home/me"home("root")→"/root"

mkdir(string[,integer])→0

permissionsspecifiedbytheoptionalparameteranInteger.ThepermissionsmaybemodifiedbythevalueofFile::umask,andareignoredonNT.RaisesaSystemCallErrorifthedirectorycannotbecreated.SeealsothediscussionofpermissionsintheclassdocumentationforFile.

Dir.mkdir(File.join(Dir.home,".foo"),0700)#=>0

Returnsanewdirectoryobjectforthenameddirectory.

Theoptionalencargumentspecifiestheencodingofthedirectory.Ifnotspecified,thefilesystemencodingisused.

Withnoblock,openisasynonymforDir::new.Ifablockispresent,itispassedaDirasaparameter.Thedirectoryisclosedattheendoftheblock,andDir::openreturnsthevalueoftheblock.

new(string)→aDirnew(string,encoding:enc)→aDir

open(string)→aDiropen(string,encoding:enc)→aDiropen(string){|aDir|block}→anObjectopen(string,encoding:enc){|aDir|block}→anObject

getwd→string

Returnsthepathtothecurrentworkingdirectoryofthisprocessasastring.

Dir.chdir("/tmp")#=>0

Dir.getwd#=>"/tmp"

Dir.pwd#=>"/tmp"

Deletesthenameddirectory.RaisesasubclassofSystemCallErrorifthedirectoryisn'tempty.

Closesthedirectorystream.AnyfurtherattemptstoaccessdirwillraiseanIOError.

d=Dir.new("testdir")

d.close#=>nil

Callstheblockonceforeachentryinthisdirectory,

pwd→string

delete(string)→0rmdir(string)→0unlink(string)→0

close→nil

each{|filename|block}→direach→an_enumerator

passingthefilenameofeachentryasaparametertotheblock.

d.each{|x|puts"Got#{x}"}

produces:

Gotconfig.h

Gotmain.rb

Returnsthefiledescriptorusedindir.

d=Dir.new("..")

d.fileno#=>8

Thismethodusesdirfd()functiondefinedbyPOSIX2008.NotImplementedErrorisraisedonotherplatforms,suchasWindows,whichdoesn'tprovidethefunction.

ReturnastringdescribingthisDirobject.

Returnsthepathparameterpassedtodir'sconstructor.

d=Dir.new("..")

d.path#=>".."

fileno→integer

inspect→string

path→stringornilto_path→stringornil

Returnsthecurrentpositionindir.SeealsoDir#seek.

d.tell#=>0

d.read#=>"."

d.tell#=>12

SynonymforDir#seek,butreturnsthepositionparameter.

d=Dir.new("testdir")#=>#<Dir:0x401b3c40>

d.read#=>"."

i=d.pos#=>12

d.read#=>".."

d.pos=i#=>12

d.read#=>".."

Readsthenextentryfromdirandreturnsitasastring.Returnsnilattheendofthestream.

d.read#=>"."

d.read#=>".."

d.read#=>"config.h"

Repositionsdirtothefirstentry.

d.read#=>"."

d.rewind#=>#<Dir:0x401b3fb0>

d.read#=>"."

pos→integertell→integer

pos=integer→integer

read→stringornil

rewind→dir

Seekstoaparticularlocationindir.integermustbeavaluereturnedbyDir#tell.

d=Dir.new("testdir")#=>#<Dir:0x401b3c40>

d.read#=>"."

i=d.tell#=>12

d.read#=>".."

d.seek(i)#=>#<Dir:0x401b3c40>

d.read#=>".."

Returnsthecurrentpositionindir.SeealsoDir#seek.

d.tell#=>0

d.read#=>"."

d.tell#=>12

Returnsthepathparameterpassedtodir'sconstructor.

d=Dir.new("..")

d.path#=>".."

seek(integer)→dir

path→stringornilto_path→stringornil

classENVENVisahash-likeaccessorforenvironmentvariables.

InFileshash.c

ParentObject

PublicClassMethods

RetrievesthevalueforenvironmentvariablenameasaString.Returnsnilifthenamedvariabledoesnotexist.

Setstheenvironmentvariablenametovalue.Ifthevaluegivenisniltheenvironmentvariableisdeleted.

ReturnsanArrayofthenameandvalueofthe

ENV[name]→value

ENV[name]=valuestore(name,value)→value

assoc(name)→Arrayornil

environmentvariablewithnameornilifthenamecannotbefound.

Removeseveryenvironmentvariable.

Deletestheenvironmentvariablewithnameandreturnsthevalueofthevariable.Ifablockisgivenitwillbecalledwhenthenamedenvironmentdoesnotexist.

Deleteseveryenvironmentvariableforwhichtheblockevaluatestotrue.

Ifnoblockisgivenanenumeratorisreturnedinstead.

Yieldseachenvironmentvariablenameandvalue.

IfnoblockisgivenanEnumeratorisreturned.

Yieldseachenvironmentvariablename.

delete(name)→valuedelete(name){|name|}→value

delete_if{|name,value|}→Hashdelete_if→Enumerator

each{|name,value|}→Hasheach→Enumeratoreach_pair{|name,value|}→Hasheach_pair→Enumerator

each_key{|name|}→Hasheach_key→Enumerator

Yieldseachenvironmentvariablenameandvalue.

IfnoblockisgivenanEnumeratorisreturned.

Yieldseachenvironmentvariablevalue.

AnEnumeratorisreturnedifnoblockwasgiven.

Returnstruewhentherearenoenvironmentvariables

Retrievestheenvironmentvariablename.

IfthegivennamedoesnotexistandneitherdefaultnorablockaprovidedanIndexErrorisraised.Ifablockisgivenitiscalledwiththemissingnametoprovideavalue.Ifadefaultvalueisgivenitwillbereturnedwhennoblockisgiven.

each{|name,value|}→Hasheach→Enumeratoreach_pair{|name,value|}→Hasheach_pair→Enumerator

each_value{|value|}→Hasheach_value→Enumerator

fetch(name)→valuefetch(name,default)→valuefetch(name){|missing_name|...}→value

key?(name)→trueorfalse

Returnstrueifthereisanenvironmentvariablewiththegivenname.

Returnstrueifthereisanenvironmentvariablewiththegivenvalue.

Deprecatedmethodthatisequivalentto::key

ReturnsthecontentsoftheenvironmentasaString.

Returnsanewhashcreatedbyusingenvironmentvariablenamesasvaluesandvaluesasnames.

include?(name)→trueorfalsehas_key?(name)→trueorfalsemember?(name)→trueorfalse

value?(value)→trueorfalsehas_value?(value)→trueorfalse

key?(name)→trueorfalseinclude?(name)→trueorfalsehas_key?(name)→trueorfalsemember?(name)→trueorfalse

index(value)→key

inspect→string

invert→Hash

keep_if{|name,value|}→Hash

Deleteseveryenvironmentvariablewheretheblockevaluatestofalse.

Returnsanenumeratorifnoblockwasgiven.

Returnsthenameoftheenvironmentvariablewithvalue.Ifthevalueisnotfoundnilisreturned.

ReturnseveryenvironmentvariablenameinanArray

Returnsthenumberofenvironmentvariables.

keep_if→Enumerator

key(value)→name

keys→Array

lengthsize

ReturnsanArrayofthenameandvalueoftheenvironmentvariablewithvalueornilifthevaluecannotbefound.

Re-hashingtheenvironmentvariablesdoesnothing.ItisprovidedforcompatibilitywithHash.

SameasENV#delete_if,butworkson(andreturns)acopyoftheenvironment.

EquivalenttoENV#delete_ifbutreturnsnilifnochangesweremade.

ReturnsanEnumeratorifnoblockwasgiven.

Replacesthecontentsoftheenvironmentvariableswiththecontentsofhash.

Returnsacopyoftheenvironmentforentrieswheretheblockreturnstrue.

ReturnsanEnumeratorifnoblockwasgiven.

rassoc(value)

rehash

reject{|name,value|}→Hashreject→Enumerator

reject!{|name,value|}→ENVornilreject!→Enumerator

replace(hash)→env

select{|name,value|}→Hashselect→Enumerator

EquivalenttoENV#keep_ifbutreturnsnilifnochangesweremade.

Removesanenvironmentvariablename-valuepairfromENVandreturnsitasanArray.Returnsnilifwhentheenvironmentisempty.

Returnsthenumberofenvironmentvariables.

Setstheenvironmentvariablenametovalue.Ifthevaluegivenisniltheenvironmentvariableisdeleted.

Convertstheenvironmentvariablesintoanarrayofnamesandvaluearrays.

ENV.to_a#=>[["TERM","xterm-color"],["SHELL","/bin/bash"],...]

Createsahashwithacopyoftheenvironmentvariables.

select!{|name,value|}→ENVornilselect!→Enumerator

shift→Arrayornil

lengthsize

ENV[name]=valuestore(name,value)→value

to_a→Array

to_hash→hashto_h→hash

Createsahashwithacopyoftheenvironmentvariables.

Returns“ENV”

Addsthecontentsofhashtotheenvironmentvariables.Ifnoblockisspecifiedentrieswithduplicatekeysareoverwritten,otherwisethevalueofeachduplicatenameisdeterminedbycallingtheblockwiththekey,itsvaluefromtheenvironmentanditsvaluefromthehash.

Returnstrueifthereisanenvironmentvariablewiththegivenvalue.

ReturnseveryenvironmentvariablevalueasanArray

Returnsanarraycontainingtheenvironmentvariablevaluesassociatedwiththegivennames.Seealso::select.

to_hash→hashto_h→hash

to_s→"ENV"

update(hash)→Hashupdate(hash){|name,old_value,new_value|}→Hash

value?(value)→trueorfalsehas_value?(value)→trueorfalse

values→Array

values_at(name,...)→Array

classEOFErrorRaisedbysomeIOoperationswhenreachingtheendoffile.ManyIOmethodsexistintwoforms,

onethatreturnsnilwhentheendoffileisreached,theotherraisesEOFErrorEOFError.

EOFErrorisasubclassofIOError.

file=File.open("/etc/hosts")

file.read

file.gets#=>nil

file.readline#=>EOFError:endoffilereached

InFilesio.c

ParentIOError

classEncodingAnEncodinginstancerepresentsacharacterencodingusableinRuby.ItisdefinedasaconstantundertheEncodingnamespace.Ithasanameandoptionally,aliases:

Encoding::ISO_8859_1.name

#=>#<Encoding:ISO-8859-1>

Encoding::ISO_8859_1.names

#=>["ISO-8859-1","ISO8859-1"]

RubymethodsdealingwithencodingsreturnoracceptEncodinginstancesasarguments(whenamethodacceptsanEncodinginstanceasanargument,itcanbepassedanEncodingnameoraliasinstead).

"somestring".encoding

#=>#<Encoding:UTF-8>

string="somestring".encode(Encoding::ISO_8859_1

#=>"somestring"

string.encoding

"somestring".encode"ISO-8859-1"

#=>"somestring"

Encoding::ASCII_8BITisaspecialencodingthatisusuallyusedforabytestring,notacharacter

string.Butasthenameinsists,itscharactersintherangeofASCIIareconsideredasASCIIcharacters.ThisisusefulwhenyouuseASCII-8BITcharacterswithotherASCIIcompatiblecharacters.

Changinganencoding

TheassociatedEncodingofaStringcanbechangedintwodifferentways.

First,itispossibletosettheEncodingofastringtoanewEncodingwithoutchangingtheinternalbyterepresentationofthestring,withString#force_encoding.ThisishowyoucantellRubythecorrectencodingofastring.

string

#=>"R\xC3\xA9sum\xC3\xA9"

string.encoding

string.force_encoding(Encoding::UTF_8)

#=>"R\u00E9sum\u00E9"

Second,itispossibletotranscodeastring,i.e.translateitsinternalbyterepresentationtoanotherencoding.Itsassociatedencodingisalsosettotheotherencoding.SeeString#encodeforthevariousformsoftranscoding,andtheEncoding::Converterclassforadditionalcontroloverthetranscodingprocess.

string

#=>"R\u00E9sum\u00E9"

string.encoding

string=string.encode!(Encoding::ISO_8859_1)

#=>"R\xE9sum\xE9"

string.encoding

#=>#<Encoding::ISO-8859-1>

Scriptencoding

AllRubyscriptcodehasanassociatedEncodingwhichanyStringliteralcreatedinthesourcecodewillbeassociatedto.

ThedefaultscriptencodingisEncoding::UTF-8afterv2.0,butitcanbechangedbyamagiccommentonthefirstlineofthesourcecodefile(orsecondline,ifthereisashebanglineonthefirst).Thecommentmustcontainthewordcodingorencoding,followedbyacolon,spaceandtheEncodingnameoralias:

#encoding:UTF-8

"somestring".encoding

The__ENCODING__keywordreturnsthescriptencodingofthefilewhichthekeywordiswritten:

#encoding:ISO-8859-1

__ENCODING__

ruby-Kwillchangethedefaultlocaleencoding,butthisisnotrecommended.RubysourcefilesshoulddeclareitsscriptencodingbyamagiccommentevenwhentheyonlydependonUS-ASCIIstringsorregularexpressions.

Localeencoding

Thedefaultencodingoftheenvironment.Usuallyderivedfromlocale.

seeEncoding.locale_charmap,::find('locale')

Filesystemencoding

Thedefaultencodingofstringsfromthefilesystemoftheenvironment.Thisisusedforstringsoffilenamesorpaths.

see::find('filesystem')

Externalencoding

EachIOobjecthasanexternalencodingwhichindicatestheencodingthatRubywillusetoreaditsdata.BydefaultRubysetstheexternalencodingofanIOobjecttothedefaultexternalencoding.Thedefaultexternalencodingissetbylocaleencodingortheinterpreter-Eoption.::default_externalreturnsthecurrentvalueoftheexternalencoding.

ENV["LANG"]

#=>"UTF-8"

Encoding.default_external

$ruby-EISO-8859-1-e"pEncoding.default_external"

#<Encoding:ISO-8859-1>

$LANG=Cruby-e'pEncoding.default_external'

#<Encoding:US-ASCII>

Thedefaultexternalencodingmayalsobesetthrough::default_external=,butyoushouldnotdothisasstringscreatedbeforeandafterthechangewillhaveinconsistentencodings.Insteaduseruby-Etoinvokerubywiththecorrectexternalencoding.

WhenyouknowthattheactualencodingofthedataofanIOobjectisnotthedefaultexternalencoding,youcanresetitsexternalencodingwithIO#set_encodingorsetitatIOobject

creation(seeIO.newoptions).

Internalencoding

ToprocessthedataofanIOobjectwhichhasanencodingdifferentfromitsexternalencoding,youcansetitsinternalencoding.RubywillusethisinternalencodingtotranscodethedatawhenitisreadfromtheIOobject.

Conversely,whendataiswrittentotheIOobjectitistranscodedfromtheinternalencodingtotheexternalencodingoftheIOobject.

TheinternalencodingofanIOobjectcanbesetwithIO#set_encodingoratIOobjectcreation(seeIO.newoptions).

Theinternalencodingisoptionalandwhennotset,theRubydefaultinternalencodingisused.Ifnotexplicitlysetthisdefaultinternalencodingisnilmeaningthatbydefault,notranscodingoccurs.

Thedefaultinternalencodingcanbesetwiththeinterpreteroption-E.::default_internalreturnsthecurrentinternalencoding.

$ruby-e'pEncoding.default_internal'

$ruby-EISO-8859-1:UTF-8-e"p[Encoding.default_external,\

Encoding.default_internal]"

[#<Encoding:ISO-8859-1>,#<Encoding:UTF-8>]

Thedefaultinternalencodingmayalsobesetthrough::default_internal=,butyoushouldnotdothisasstringscreatedbeforeandafterthechangewillhaveinconsistentencodings.Insteaduseruby-Etoinvokerubywiththecorrectinternalencoding.

IOencodingexample

InthefollowingexampleaUTF-8encodedstring“Ru00E9sumu00E9”istranscodedforoutputtoISO-8859-1encoding,thenreadbackinandtranscodedtoUTF-8:

string="R\u00E9sum\u00E9"

open("transcoded.txt","w:ISO-8859-1")do|io|

io.write(string)

puts"rawtext:"

pFile.binread("transcoded.txt")

open("transcoded.txt","r:ISO-8859-1:UTF-8")do|

puts"transcodedtext:"

pio.read

Whilewritingthefile,theinternalencodingisnotspecifiedasitisonlynecessaryforreading.Whilereadingthefileboththeinternalandexternalencodingmustbespecifiedtoobtainthecorrectresult.

$rubyt.rb

rawtext:

"R\xE9sum\xE9"

transcodedtext:

"R\u00E9sum\u00E9"

InFilesencoding.ctranscode.c

ParentObject

PublicClassMethods

Returnsthehashofavailableencodingaliasandoriginalencodingname.

Encoding.aliases

#=>{"BINARY"=>"ASCII-8BIT","ASCII"=>"US-ASCII","ANSI_X3.4-1986"=>"US-ASCII",

"SJIS"=>"Shift_JIS","eucJP"=>"EUC-JP","CP932"=

Checksthecompatibilityoftwoobjects.

Iftheobjectsarebothstringstheyarecompatiblewhentheyareconcatenatable.Theencodingoftheconcatenatedstringwillbereturnediftheyarecompatible,niliftheyarenot.

Encoding.compatible?("\xa1".force_encoding("iso-8859-1"

Encoding.compatible?(

"\xa1".force_encoding("iso-8859-1"),

"\xa1\xa1".force_encoding("euc-jp"))

#=>nil

aliases->{"alias1"=>"orig1","alias2"→"orig2",...}

compatible?(obj1,obj2)→encornil

Iftheobjectsarenon-stringstheirencodingsarecompatiblewhentheyhaveanencodingand:

EitherencodingisUS-ASCIIcompatible

Oneoftheencodingsisa7-bitencoding

Returnsdefaultexternalencoding.

Thedefaultexternalencodingisusedbydefaultforstringscreatedfromthefollowinglocations:

Filedatareadfromdisk

StringIO

Zlib::GzipReader

Zlib::GzipWriter

String#inspect

Regexp#inspect

Whilestringscreatedfromtheselocationswillhavethisencoding,theencodingmaynotbevalid.BesuretocheckString#valid_encoding?.

Filedatawrittentodiskwillbetranscodedtothedefaultexternalencodingwhenwritten.

Thedefaultexternalencodingisinitializedbythelocaleor-Eoption.

Setsdefaultexternalencoding.Youshouldnotset::default_externalinrubycodeasstringscreatedbeforechangingthevaluemayhaveadifferent

default_external→enc

default_external=enc

encodingfromstringscreatedafterthevaluewaschanged.,insteadyoushoulduseruby-Etoinvokerubywiththecorrectdefault_external.

See::default_externalforinformationonhowthedefaultexternalencodingisused.

Returnsdefaultinternalencoding.Stringswillbetranscodedtothedefaultinternalencodinginthefollowingplacesifthedefaultinternalencodingisnotnil:

Etc.sysconfdirandEtc.systmpdir

Filedatareadfromdisk

FilenamesfromDir

Integer#chr

String#inspectandRegexp#inspect

StringsreturnedfromReadline

StringsreturnedfromSDBM

Time#zone

ValuesfromENV

ValuesinARGVincluding$PROGRAM_NAME

AdditionallyString#encodeandString#encode!usethedefaultinternalencodingifnoencodingisgiven.

Thelocaleencoding(__ENCODING__),not::default_internal,isusedastheencodingofcreatedstrings.

::default_internalisinitializedbythesourcefile'sinternal_encodingor-Eoption.

default_internal→enc

Setsdefaultinternalencodingorremovesdefaultinternalencodingwhenpassednil.Youshouldnotset::default_internalinrubycodeasstringscreatedbeforechangingthevaluemayhaveadifferentencodingfromstringscreatedafterthechange.Insteadyoushoulduseruby-Etoinvokerubywiththecorrectdefault_internal.

See::default_internalforinformationonhowthedefaultinternalencodingisused.

Searchtheencodingwithspecifiedname.nameshouldbeastring.

Encoding.find("US-ASCII")#=>#<Encoding:US-ASCII>

Nameswhichthismethodacceptareencodingnamesandaliasesincludingfollowingspecialaliases

“external”defaultexternalencoding

“internal”defaultinternalencoding

“locale”localeencoding

“filesystem”filesystemencoding

AnArgumentErrorisraisedwhennoencodingwithname.OnlyEncoding.find("internal")howeverreturnsnilwhennoencodingnamed“internal”,inotherwords,whenRubyhasnodefaultinternalencoding.

default_internal=encornil

find(string)→enc

Returnsthelistofloadedencodings.

Encoding.list

#=>[#<Encoding:ASCII-8BIT>,#<Encoding:UTF-8>,

#<Encoding:ISO-2022-JP(dummy)>]

Encoding.find("US-ASCII")

#=>#<Encoding:US-ASCII>

Encoding.list

#=>[#<Encoding:ASCII-8BIT>,#<Encoding:UTF-8>,

#<Encoding:US-ASCII>,#<Encoding:ISO-2022-JP(dummy)>]

Returnsthelistofavailableencodingnames.

Encoding.name_list

#=>["US-ASCII","ASCII-8BIT","UTF-8",

"ISO-8859-1","Shift_JIS","EUC-JP",

"Windows-31J",

"BINARY","CP932","eucJP"]

ReturnswhetherASCII-compatibleornot.

Encoding::UTF_8.ascii_compatible?#=>true

Encoding::UTF_16BE.ascii_compatible?#=>false

Returnstruefordummyencodings.Adummyencodingisanencodingforwhichcharacterhandlingisnotproperlyimplemented.Itisusedforstateful

list→[enc1,enc2,...]

name_list→["enc1","enc2",...]

ascii_compatible?→trueorfalse

dummy?→trueorfalse

encodings.

Encoding::ISO_2022_JP.dummy?#=>true

Encoding::UTF_8.dummy?#=>false

Returnsastringwhichrepresentstheencodingforprogrammers.

Encoding::UTF_8.inspect#=>"#<Encoding:UTF-8>"

Encoding::ISO_2022_JP.inspect#=>"#<Encoding:ISO-2022-JP(dummy)>"

Returnsthenameoftheencoding.

Encoding::UTF_8.name#=>"UTF-8"

Returnsthelistofnameandaliasesoftheencoding.

Encoding::WINDOWS_31J.names#=>["Windows-31J","CP932","csWindows31J"]

Returnsareplicatedencodingofencwhosenameisname.Thenewencodingshouldhavethesamebytestructureofenc.Ifnameisusedbyanotherencoding,raiseArgumentError.

Returnsthenameoftheencoding.

inspect→string

name→stringto_s→string

names→array

replicate(name)→encoding

name→stringto_s→string

Encoding::UTF_8.name#=>"UTF-8"

classEncoding::CompatibilityErrorRaisedbyEncodingandStringmethodswhenthesourceencodingisincompatiblewiththetargetencoding.

InFilesencoding.c

ParentEncodingError

classEncoding::Converter

InFilesencoding.c

ParentData

Constants

AFTER_OUTPUT

Stopconvertingaftersomeoutputiscompletebutbeforealloftheinputwasconsumed.See#primitive_convertforanexample.

CRLF_NEWLINE_DECORATOR

DecoratorforconvertingLFtoCRLF

CR_NEWLINE_DECORATOR

DecoratorforconvertingLFtoCR

INVALID_MASK

Maskforinvalidbytesequences

INVALID_REPLACE

Replaceinvalidbytesequences

PARTIAL_INPUT

Indicatesthesourcemaybepartofalargerstring.See#primitive_convertforanexample.

UNDEF_HEX_CHARREF

ReplacebytesequencesthatareundefinedinthedestinationencodingwithanXMLhexadecimalcharacterreference.ThisisvalidforXMLconversion.

UNDEF_MASK

Maskforavalidcharacterinthesourceencodingbutnorelatedcharacter(s)indestinationencoding.

UNDEF_REPLACE

Replacebytesequencesthatareundefinedinthedestinationencoding.

UNIVERSAL_NEWLINE_DECORATOR

DecoratorforconvertingCRLFandCRtoLF

XML_ATTR_CONTENT_DECORATOR

EscapeasXMLAttValue

XML_ATTR_QUOTE_DECORATOR

EscapeasXMLAttValue

XML_TEXT_DECORATOR

EscapeasXMLCharData

PublicClassMethods

ReturnsthecorrespondingASCIIcompatibleencoding.

ReturnsniliftheargumentisanASCIIcompatibleencoding.

“correspondingASCIIcompatibleencoding”isanASCIIcompatibleencodingwhichcanrepresentsexactlythesamecharactersasthegivenASCIIincompatibleencoding.So,noconversionundefined

Encoding::Converter.asciicompat_encoding(string)→encodingornilEncoding::Converter.asciicompat_encoding(encoding)→encodingornil

erroroccurswhenconvertingbetweenthetwoencodings.

Encoding::Converter.asciicompat_encoding("ISO-2022-JP"

Encoding::Converter.asciicompat_encoding("UTF-16BE")#=>#<Encoding:UTF-8>

Encoding::Converter.asciicompat_encoding("UTF-8")#=>nil

possibleoptionselements:

hashform:

:invalid=>nil#raiseerroroninvalidbytesequence(default)

:invalid=>:replace#replaceinvalidbytesequence

:undef=>nil#raiseerroronundefinedconversion(default)

:undef=>:replace#replaceundefinedconversion

:replace=>string#replacementstring("?"or"\uFFFD"ifnotspecified)

:newline=>:universal#decoratorforconvertingCRLFandCRtoLF

:newline=>:crlf#decoratorforconvertingLFtoCRLF

:newline=>:cr#decoratorforconvertingLFtoCR

:universal_newline=>true#decoratorforconvertingCRLFandCRtoLF

:crlf_newline=>true#decoratorforconvertingLFtoCRLF

:cr_newline=>true#decoratorforconvertingLFtoCR

:xml=>:text#escapeasXMLCharData.

:xml=>:attr#escapeasXMLAttValue

integerform:

Encoding::Converter::INVALID_REPLACE

Encoding::Converter::UNDEF_REPLACE

Encoding::Converter::UNDEF_HEX_CHARREF

Encoding::Converter::UNIVERSAL_NEWLINE_DECORATOR

Encoding::Converter::CRLF_NEWLINE_DECORATOR

Encoding::Converter::CR_NEWLINE_DECORATOR

Encoding::Converter::XML_TEXT_DECORATOR

Encoding::Converter::XML_ATTR_CONTENT_DECORATOR

Encoding::Converter::XML_ATTR_QUOTE_DECORATOR

::newcreatesaninstanceofEncoding::Converter.

Encoding::Converter.new(source_encoding,destination_encoding)Encoding::Converter.new(source_encoding,destination_encoding,opt)Encoding::Converter.new(convpath)

Source_encodingand#destination_encodingshouldbeastringorEncodingobject.

optshouldbenil,ahashoraninteger.

convpathshouldbeanarray.convpathmaycontain

two-elementarrayswhichcontainencodingsorencodingnames,or

stringsrepresentingdecoratornames.

::newoptionallytakesanoption.Theoptionshouldbeahashoraninteger.Theoptionhashcancontain:invalid=>nil,etc.Theoptionintegershouldbelogical-orofconstantssuchasEncoding::Converter::INVALID_REPLACE,etc.

:invalid=>nilRaiseerroroninvalidbytesequence.Thisisadefaultbehavior.

:invalid=>:replaceReplaceinvalidbytesequencebyreplacementstring.

:undef=>nilRaiseanerrorifacharacterin#source_encodingisnotdefinedindestination_encoding.Thisisadefaultbehavior.

:undef=>:replaceReplaceundefinedcharacterin#destination_encodingwithreplacementstring.

:replace=>stringSpecifythereplacementstring.Ifnot

specified,“uFFFD”isusedforUnicodeencodingsand“?”forothers.

:universal_newline=>trueConvertCRLFandCRtoLF.

:crlf_newline=>trueConvertLFtoCRLF.

:cr_newline=>trueConvertLFtoCR.

:xml=>:textEscapeasXMLCharData.ThisformcanbeusedasaHTML4.0#PCDATA.

'&'->'&'

'<'->'<'

'>'->'>'

undefinedcharactersin#destination_encoding->hexadecimalCharRefsuchas&xHH;

:xml=>:attrEscapeasXMLAttValue.Theconvertedresultisquotedas“…”.ThisformcanbeusedasaHTML4.0attributevalue.

'&'->'&'

'<'->'<'

'>'->'>'

'“'->'"'

undefinedcharactersin#destination_encoding->

hexadecimalCharRefsuchas&xHH;

Examples:

#UTF-16BEtoUTF-8

ec=Encoding::Converter.new("UTF-16BE","UTF-8")

#Usually,decoratorssuchasnewlineconversionareinsertedlast.

ec=Encoding::Converter.new("UTF-16BE","UTF-8",:universal_newline

pec.convpath#=>[[#<Encoding:UTF-16BE>,#<Encoding:UTF-8>],

#"universal_newline"]

#But,ifthelastencodingisASCIIincompatible,

#decoratorsareinsertedbeforethelastconversion.

ec=Encoding::Converter.new("UTF-8","UTF-16BE",:crlf_newline

pec.convpath#=>["crlf_newline",

#[#<Encoding:UTF-8>,#<Encoding:UTF-16BE>]]

#Conversionpathcanbespecifieddirectly.

ec=Encoding::Converter.new(["universal_newline",["EUC-JP"

pec.convpath#=>["universal_newline",

#[#<Encoding:EUC-JP>,#<Encoding:UTF-8>],

Returnsaconversionpath.

pEncoding::Converter.search_convpath("ISO-8859-1","EUC-JP"

#=>[[#<Encoding:ISO-8859-1>,#<Encoding:UTF-8>],

#[#<Encoding:UTF-8>,#<Encoding:EUC-JP>]]

pEncoding::Converter.search_convpath("ISO-8859-1","EUC-JP"

#[#<Encoding:UTF-8>,#<Encoding:EUC-JP>],

#"universal_newline"]

pEncoding::Converter.search_convpath("ISO-8859-1","UTF-32BE"

Encoding::Converter.search_convpath(source_encoding,destination_encoding)→aryEncoding::Converter.search_convpath(source_encoding,destination_encoding,opt)→ary

pEncoding::Converter.search_convpath("ISO-8859-1","UTF-32BE"

#"universal_newline",

Convertsource_stringandreturndestination_string.

source_stringisassumedasapartofsource.i.e.:partial_input=>trueisspecifiedinternally.finishmethodshouldbeusedlast.

ec=Encoding::Converter.new("utf-8","euc-jp")

putsec.convert("\u3042").dump#=>"\xA4\xA2"

putsec.finish.dump#=>""

ec=Encoding::Converter.new("euc-jp","utf-8")

putsec.convert("\xA4").dump#=>""

putsec.convert("\xA2").dump#=>"\xE3\x81\x82"

putsec.finish.dump#=>""

ec=Encoding::Converter.new("utf-8","iso-2022-jp")

putsec.convert("\xE3").dump#=>"".force_encoding("ISO-2022-JP")

putsec.convert("\x81").dump#=>"".force_encoding("ISO-2022-JP")

putsec.convert("\x82").dump#=>"\e$B$\"".force_encoding("ISO-2022-JP")

putsec.finish.dump#=>"\e(B".force_encoding("ISO-2022-JP")

Ifaconversionerroroccur,Encoding::UndefinedConversionErrororEncoding::InvalidByteSequenceErrorisraised.#convertdoesn'tsupplymethodstorecoverorrestartfromtheseexceptions.Whenyouwanttohandletheseconversionerrors,use#primitive_convert.

ec==other→trueorfalse

convert(source_string)→destination_string

Returnstheconversionpathofec.

Theresultisanarrayofconversions.

ec=Encoding::Converter.new("ISO-8859-1","EUC-JP",crlf_newline

pec.convpath

#[#<Encoding:UTF-8>,#<Encoding:EUC-JP>],

#"crlf_newline"]

Eachelementofthearrayisapairofencodingsorastring.Apairmeansanencodingconversion.Astringmeansadecorator.

Intheaboveexample,[#<Encoding:ISO-8859-1>,#<Encoding:UTF-8>]meansaconverterfromISO-8859-1toUTF-8.“crlf_newline”meansnewlineconverterfromLFtoCRLF.

ReturnsthedestinationencodingasanEncodingobject.

Finishestheconverter.Itreturnsthelastpartoftheconvertedstring.

pec.convert("\u3042")#=>"\e$B$\""

pec.finish#=>"\e(B"

Insertsstringintotheencodingconverter.Thestringwillbeconvertedtothedestinationencodingand

convpath→ary

destination_encoding→encoding

finish→string

insert_output(string)→nil

outputonlaterconversions.

Ifthedestinationencodingisstateful,stringisconvertedaccordingtothestateandthestateisupdated.

Thismethodshouldbeusedonlywhenaconversionerroroccurs.

ec=Encoding::Converter.new("utf-8","iso-8859-1")

src="HIRAGANALETTERAis\u{3042}."

dst=""

pec.primitive_convert(src,dst)#=>:undefined_conversion

puts"[#{dst.dump},#{src.dump}]"#=>["HIRAGANALETTERAis","."]

ec.insert_output("<err>")

pec.primitive_convert(src,dst)#=>:finished

puts"[#{dst.dump},#{src.dump}]"#=>["HIRAGANALETTERAis<err>.",""]

src="\u{306F3041306826613002}"#U+2661isnotrepresentableiniso-2022-jp

dst=""

pec.primitive_convert(src,dst)#=>:undefined_conversion

puts"[#{dst.dump},#{src.dump}]"#=>["\e$B$O$!$H".force_encoding("ISO-2022-JP"),"\xE3\x80\x82"]

ec.insert_output"?"#statechangerequiredtooutput"?".

pec.primitive_convert(src,dst)#=>:finished

puts"[#{dst.dump},#{src.dump}]"#=>["\e$B$O$!$H\e(B?\e$B!#\e(B".force_encoding("ISO-2022-JP"),""]

Returnsaprintableversionofec

ec=Encoding::Converter.new("iso-8859-1","utf-8")

putsec.inspect#=>#<Encoding::Converter:ISO-8859-1toUTF-8>

Returnsanexceptionobjectforthelastconversion.Returnsnilifthelastconversiondidnotproduceanerror.

“error”meansthat

inspect→string

last_error→exceptionornil

Encoding::InvalidByteSequenceErrorandEncoding::UndefinedConversionErrorfor#convertand:invalid_byte_sequence,:incomplete_inputand:undefined_conversionfor#primitive_convert.

ec=Encoding::Converter.new("utf-8","iso-8859-1")

pec.primitive_convert(src="\xf1abcd",dst="")#=>:invalid_byte_sequence

pec.last_error#=>#<Encoding::InvalidByteSequenceError:"\xF1"followedby"a"onUTF-8>

pec.primitive_convert(src,dst,nil,1)#=>:destination_buffer_full

pec.last_error#=>nil

possibleoptelements:

hashform:

:partial_input=>true#sourcebuffermaybepartoflargersource

:after_output=>true#stopconversionafteroutputbeforeinput

integerform:

Encoding::Converter::PARTIAL_INPUT

Encoding::Converter::AFTER_OUTPUT

possibleresults:

:invalid_byte_sequence

:incomplete_input

:undefined_conversion

:after_output

primitive_convert(source_buffer,destination_buffer)→symbolprimitive_convert(source_buffer,destination_buffer,destination_byteoffset)→symbolprimitive_convert(source_buffer,destination_buffer,destination_byteoffset,destination_bytesize)→symbolprimitive_convert(source_buffer,destination_buffer,destination_byteoffset,destination_bytesize,opt)→symbol

:destination_buffer_full

:source_buffer_empty

:finished

#primitive_convertconvertssource_bufferintodestination_buffer.

source_buffershouldbeastringornil.nilmeansanemptystring.

destination_buffershouldbeastring.

destination_byteoffsetshouldbeanintegerornil.nilmeanstheendofdestination_buffer.Ifitisomitted,nilisassumed.

destination_bytesizeshouldbeanintegerornil.nilmeansunlimited.Ifitisomitted,nilisassumed.

optshouldbenil,ahashoraninteger.nilmeansnoflags.Ifitisomitted,nilisassumed.

#primitive_convertconvertsthecontentofsource_bufferfrombeginningandstoretheresultintodestination_buffer.

destination_byteoffsetanddestination_bytesizespecifytheregionwhichtheconvertedresultisstored.destination_byteoffsetspecifiesthestartpositionindestination_bufferinbytes.Ifdestination_byteoffsetisnil,destination_buffer.bytesizeisusedforappendingtheresult.destination_bytesizespecifiesmaximumnumberofbytes.Ifdestination_bytesizeisnil,destinationsizeisunlimited.Afterconversion,destination_bufferisresizedtodestination_byteoffset+actuallyproducednumberofbytes.Alsodestination_buffer'sencodingissettodestination_encoding.

#primitive_convertdropstheconvertedpartofsource_buffer.thedroppedpartisconvertedindestination_bufferorbufferedinEncoding::Converter

object.

#primitive_convertstopsconversionwhenoneoffollowingconditionmet.

invalidbytesequencefoundinsourcebuffer(:invalid_byte_sequence)primitive_errinfoandlast_errormethodsreturnsthedetailoftheerror.

unexpectedendofsourcebuffer(:incomplete_input)thisoccuronlywhen:partial_inputisnotspecified.primitive_errinfoandlast_errormethodsreturnsthedetailoftheerror.

characternotrepresentableinoutputencoding(:undefined_conversion)primitive_errinfoandlast_errormethodsreturnsthedetailoftheerror.

aftersomeoutputisgenerated,beforeinputisdone(:after_output)thisoccuronlywhen:after_outputisspecified.

destinationbufferisfull(:destination_buffer_full)thisoccuronlywhendestination_bytesizeisnon-nil.

sourcebufferisempty(:source_buffer_empty)thisoccuronlywhen:partial_inputisspecified.

conversionisfinished(:finished)

example:

ec=Encoding::Converter.new("UTF-8","UTF-16BE")

ret=ec.primitive_convert(src="pi",dst="",nil,100)

p[ret,src,dst]#=>[:finished,"","\x00p\x00i"]

ec=Encoding::Converter.new("UTF-8","UTF-16BE")

ret=ec.primitive_convert(src="pi",dst="",nil,1)

p[ret,src,dst]#=>[:destination_buffer_full,"i","\x00"]

ret=ec.primitive_convert(src,dst="",nil,1)

p[ret,src,dst]#=>[:destination_buffer_full,"","p"]

p[ret,src,dst]#=>[:destination_buffer_full,"","\x00"]

p[ret,src,dst]#=>[:finished,"","i"]

#primitive_errinforeturnsimportantinformationregardingthelasterrorasa5-elementarray:

[result,enc1,enc2,error_bytes,readagain_bytes]

resultisthelastresultofprimitive_convert.

Otherelementsareonlymeaningfulwhenresultis:invalid_byte_sequence,:incomplete_inputor:undefined_conversion.

enc1andenc2indicateaconversionstepasapairofstrings.Forexample,aconverterfromEUC-JPtoISO-8859-1convertsastringasfollows:EUC-JP->UTF-8->ISO-8859-1.So[enc1,enc2]iseither[“EUC-JP”,“UTF-8”]or[“UTF-8”,“ISO-8859-1”].

error_bytesandreadagain_bytesindicatethebytesequenceswhichcausedtheerror.error_bytesisdiscardedportion.readagain_bytesisbufferedportionwhichisreadagainonnextconversion.

Example:

#\xffisinvalidasEUC-JP.

ec=Encoding::Converter.new("EUC-JP","Shift_JIS")

ec.primitive_convert(src="\xff",dst="",nil,10)

pec.primitive_errinfo

#=>[:invalid_byte_sequence,"EUC-JP","UTF-8","\xFF",""]

#HIRAGANALETTERA(\xa4\xa2inEUC-JP)isnotrepresentableinISO-8859-1.

#SincethiserrorisoccurinUTF-8toISO-8859-1conversion,

#error_bytesisHIRAGANALETTERAinUTF-8(\xE3\x81\x82).

ec=Encoding::Converter.new("EUC-JP","ISO-8859-1")

primitive_errinfo→array

ec.primitive_convert(src="\xa4\xa2",dst="",nil,10)

#=>[:undefined_conversion,"UTF-8","ISO-8859-1","\xE3\x81\x82",""]

#partialcharacterisinvalid

ec.primitive_convert(src="\xa4",dst="",nil,10)

#=>[:incomplete_input,"EUC-JP","UTF-8","\xA4",""]

#Encoding::Converter::PARTIAL_INPUTpreventsinvaliderrorsby

#partialcharacters.

ec.primitive_convert(src="\xa4",dst="",nil,10,Encoding

#=>[:source_buffer_empty,nil,nil,nil,nil]

#\xd8\x00\x00@isinvalidasUTF-16BEbecause

#nolowsurrogateafterhighsurrogate(\xd8\x00).

#Itisdetectedby3rdbyte(\00)whichispartofnextcharacter.

#Sothehighsurrogate(\xd8\x00)isdiscardedand

#the3rdbyteisreadagainlater.

#Sincethebyteisbufferedinec,itisdroppedfromsrc.

ec=Encoding::Converter.new("UTF-16BE","UTF-8")

ec.primitive_convert(src="\xd8\x00\x00@",dst="",nil,

#=>[:invalid_byte_sequence,"UTF-16BE","UTF-8","\xD8\x00","\x00"]

#=>"@"

#SimilartoUTF-16BE,\x00\xd8@\x00isinvalidasUTF-16LE.

#Theproblemisdetectedby4thbyte.

ec=Encoding::Converter.new("UTF-16LE","UTF-8")

ec.primitive_convert(src="\x00\xd8@\x00",dst="",nil,

#=>[:invalid_byte_sequence,"UTF-16LE","UTF-8","\x00\xD8","@\x00"]

call-seq

ec.putback->string

ec.putback(max_numbytes)->string

putback(p1=v1)

Putbackthebyteswhichwillbeconverted.

Thebytesarecausedbyinvalid_byte_sequenceerror.Wheninvalid_byte_sequenceerror,somebytesarediscardedandsomebytesarebufferedtobeconvertedlater.Thelatterbytescanbeputback.ItcanbeobservedbyEncoding::InvalidByteSequenceError#readagain_bytesand#primitive_errinfo.

ec=Encoding::Converter.new("utf-16le","iso-8859-1")

src="\x00\xd8\x61\x00"

dst=""

pec.primitive_convert(src,dst)#=>:invalid_byte_sequence

pec.primitive_errinfo#=>[:invalid_byte_sequence,"UTF-16LE","UTF-8","\x00\xD8","a\x00"]

pec.putback#=>"a\x00"

pec.putback#=>""#nomorebytestoputback

Returnsthereplacementstring.

ec=Encoding::Converter.new("euc-jp","us-ascii")

pec.replacement#=>"?"

ec=Encoding::Converter.new("euc-jp","utf-8")

pec.replacement#=>"\uFFFD"

Setsthereplacementstring.

ec=Encoding::Converter.new("utf-8","us-ascii",:undef

ec.replacement="<undef>"

pec.convert("a\u3042b")#=>"a<undef>b"

replacement→string

replacement=string

source_encoding→encoding

ReturnsthesourceencodingasanEncodingobject.

classEncoding::ConverterNotFoundErrorRaisedbytranscodingmethodswhenanamedencodingdoesnotcorrespondwithaknownconverter.

InFilesencoding.c

Parentrb_eEncodingError

classEncoding::InvalidByteSequenceErrorRaisedbyEncodingandStringmethodswhenthestringbeingtranscodedcontainsabyteinvalidfortheeitherthesourceortargetencoding.

InFilesencoding.c

Returnsthedestinationencodingasanencodingobject.

Returnsthedestinationencodingnameasastring.

ReturnsthediscardedbyteswhenEncoding::InvalidByteSequenceErroroccurs.

destination_encoding→string

destination_encoding_name→string

error_bytes→string

ec.convert("abc\xA1\xFFdef")

rescueEncoding::InvalidByteSequenceError

p$!#=>#<Encoding::InvalidByteSequenceError:"\xA1"followedby"\xFF"onEUC-JP>

puts$!.error_bytes.dump#=>"\xA1"

puts$!.readagain_bytes.dump#=>"\xFF"

Returnstrueiftheinvalidbytesequenceerroriscausedbyprematureendofstring.

ec.convert("abc\xA1z")

p$!#=>#<Encoding::InvalidByteSequenceError:"\xA1"followedby"z"onEUC-JP>

p$!.incomplete_input?#=>false

ec.convert("abc\xA1")

ec.finish

p$!#=>#<Encoding::InvalidByteSequenceError:incomplete"\xA1"onEUC-JP>

p$!.incomplete_input?#=>true

ReturnsthebytestobereadagainwhenEncoding::InvalidByteSequenceErroroccurs.

Returnsthesourceencodingasanencodingobject.

Notethattheresultmaynotbeequaltothesource

incomplete_input?→trueorfalse

readagain_bytes→string

encodingoftheencodingconverteriftheconversionhasmultiplesteps.

ec=Encoding::Converter.new("ISO-8859-1","EUC-JP")#ISO-8859-1->UTF-8->EUC-JP

ec.convert("\xa0")#NO-BREAKSPACE,whichisavailableinUTF-8butnotinEUC-JP.

rescueEncoding::UndefinedConversionError

p$!.source_encoding#=>#<Encoding:UTF-8>

p$!.destination_encoding#=>#<Encoding:EUC-JP>

p$!.source_encoding_name#=>"UTF-8"

p$!.destination_encoding_name#=>"EUC-JP"

Returnsthesourceencodingnameasastring.

source_encoding_name→string

classEncoding::UndefinedConversionErrorRaisedbyEncodingandStringmethodswhenatranscodingoperationfails.

InFilesencoding.c

Returnsthedestinationencodingasanencodingobject.

Returnsthedestinationencodingnameasastring.

Returnstheone-characterstringwhichcauseEncoding::UndefinedConversionError.

ec=Encoding::Converter.new("ISO-8859-1","EUC-JP")

destination_encoding→string

destination_encoding_name→string

error_char→string

ec.convert("\xa0")

puts$!.error_char.dump#=>"\xC2\xA0"

p$!.error_char.encoding#=>#<Encoding:UTF-8>

Returnsthesourceencodingasanencodingobject.

Notethattheresultmaynotbeequaltothesourceencodingoftheencodingconverteriftheconversionhasmultiplesteps.

ec=Encoding::Converter.new("ISO-8859-1","EUC-JP")#ISO-8859-1->UTF-8->EUC-JP

ec.convert("\xa0")#NO-BREAKSPACE,whichisavailableinUTF-8butnotinEUC-JP.

p$!.source_encoding#=>#<Encoding:UTF-8>

p$!.destination_encoding#=>#<Encoding:EUC-JP>

p$!.source_encoding_name#=>"UTF-8"

p$!.destination_encoding_name#=>"EUC-JP"

Returnsthesourceencodingnameasastring.

source_encoding_name→string

classEncodingErrorEncodingErroristhebaseclassforencodingerrors.

InFileserror.c

ParentStandardError

moduleEnumerableTheEnumerablemixinprovidescollectionclasseswithseveraltraversalandsearchingmethods,andwiththeabilitytosort.Theclassmustprovideamethodeach,whichyieldssuccessivemembersofthecollection.IfEnumerable#max,#min,or#sortisused,theobjectsinthecollectionmustalsoimplementameaningful<=>operator,asthesemethodsrelyonanorderingbetweenmembersofthecollection.

InFilesenum.cenumerator.c

Passeseachelementofthecollectiontothegivenblock.Themethodreturnstrueiftheblockneverreturnsfalseornil.Iftheblockisnotgiven,Rubyaddsanimplicitblockof{|obj|obj}whichwillcauseall?toreturntruewhennoneofthecollectionmembersarefalseornil.

%w[antbearcat].all?{|word|word.length>=3}#=>true

%w[antbearcat].all?{|word|word.length>=4}#=>false

[nil,true,99].all?#=>false

all?[{|obj|block}]→trueorfalse

Passeseachelementofthecollectiontothegivenblock.Themethodreturnstrueiftheblockeverreturnsavalueotherthanfalseornil.Iftheblockisnotgiven,Rubyaddsanimplicitblockof{|obj|obj}thatwillcauseany?toreturntrueifatleastoneofthecollectionmembersisnotfalseornil.

%w[antbearcat].any?{|word|word.length>=3}#=>true

%w[antbearcat].any?{|word|word.length>=4}#=>true

[nil,true,99].any?#=>true

Enumeratesovertheitems,chunkingthemtogetherbasedonthereturnvalueoftheblock.

Consecutiveelementswhichreturnthesameblockvaluearechunkedtogether.

Forexample,consecutiveevennumbersandoddnumberscanbechunkedasfollows.

[3,1,4,1,5,9,2,6,5,3,5].chunk{|n|

n.even?

}.each{|even,ary|

p[even,ary]

#=>[false,[3,1]]

#[true,[4]]

#[false,[1,5,9]]

#[true,[2,6]]

#[false,[5,3,5]]

Thismethodisespeciallyusefulforsortedseriesofelements.Thefollowingexamplecountswordsfor

any?[{|obj|block}]→trueorfalse

chunk{|elt|...}→an_enumeratorchunk(initial_state){|elt,state|...}→an_enumerator(deprecated)

eachinitialletter.

open("/usr/share/dict/words","r:iso-8859-1"){|f|

f.chunk{|line|line.ord}.each{|ch,lines|p[ch

#=>["\n",1]

#["A",1327]

#["B",1372]

#["C",1507]

#["D",791]

Thefollowingkeyvalueshavespecialmeaning:

niland:_separatorspecifiesthattheelementsshouldbedropped.

:_alonespecifiesthattheelementshouldbechunkedbyitself.

Anyothersymbolsthatbeginwithanunderscorewillraiseanerror:

items.chunk{|item|:_underscore}

#=>RuntimeError:symbolsbeginningwithanunderscorearereserved

niland:_separatorcanbeusedtoignoresomeelements.

Forexample,thesequenceofhyphensinsvnlogcanbeeliminatedasfollows:

sep="-"*72+"\n"

IO.popen("svnlogREADME"){|f|

f.chunk{|line|

line!=sep||nil

}.each{|_,lines|

pplines

#=>["r20018|knu|2008-10-2913:20:42+0900(Wed,29Oct2008)|2lines\n",

#"\n",

#"*README,README.ja:Updatetheportabilitysection.\n",

#"\n"]

#["r16725|knu|2008-05-3123:34:23+0900(Sat,31May2008)|2lines\n",

#"\n",

#"*README,README.ja:AddanoteaboutdefaultCflags.\n",

#"\n"]

Paragraphsseparatedbyemptylinescanbeparsedasfollows:

File.foreach("README").chunk{|line|

/\A\s*\z/!~line||nil

}.each{|_,lines|

pplines

:_alonecanbeusedtoforceitemsintotheirownchunk.Forexample,youcanputlinesthatcontainaURLbythemselves,andchunktherestofthelinestogether,likethis:

pattern=/http/

open(filename){|f|

f.chunk{|line|line=~pattern?:_alone:true}.

pplines

Returnsanewarraywiththeresultsofrunningblockonceforeveryelementinenum.

(1..4).map{|i|i*i}#=>[1,4,9,16]

(1..4).collect{"cat"}#=>["cat","cat","cat","cat"]

collect{|obj|block}→arraymap{|obj|block}→arraycollect→an_enumeratormap→an_enumerator

Returnsanewarraywiththeconcatenatedresultsofrunningblockonceforeveryelementinenum.

[1,2,3,4].flat_map{|e|[e,-e]}#=>[1,-1,2,-2,3,-3,4,-4]

[[1,2],[3,4]].flat_map{|e|e+[100]}#=>[1,2,100,3,4,100]

Returnsthenumberofitemsinenumthroughenumeration.Ifanargumentisgiven,thenumberofitemsinenumthatareequaltoitemarecounted.Ifablockisgiven,itcountsthenumberofelementsyieldingatruevalue.

ary=[1,2,4,2]

ary.count#=>4

ary.count(2)#=>2

ary.count{|x|x%2==0}#=>3

Callsblockforeachelementofenumrepeatedlyntimesorforeverifnoneornilisgiven.Ifanon-positivenumberisgivenorthecollectionisempty,

flat_map{|obj|block}→arraycollect_concat{|obj|block}→arrayflat_map→an_enumeratorcollect_concat→an_enumerator

count→intcount(item)→intcount{|obj|block}→int

cycle(n=nil){|obj|block}→nilcycle(n=nil)→an_enumerator

doesnothing.Returnsniliftheloophasfinishedwithoutgettinginterrupted.

#cyclesaveselementsinaninternalarraysochangestoenumafterthefirstpasshavenoeffect.

a=["a","b","c"]

a.cycle{|x|putsx}#print,a,b,c,a,b,c,..forever.

a.cycle(2){|x|putsx}#print,a,b,c,a,b,c.

Passeseachentryinenumtoblock.Returnsthefirstforwhichblockisnotfalse.Ifnoobjectmatches,callsifnoneandreturnsitsresultwhenitisspecified,orreturnsnilotherwise.

(1..10).detect{|i|i%5==0andi%7==0}#=>nil

(1..100).find{|i|i%5==0andi%7==0}#=>35

Dropsfirstnelementsfromenum,andreturnsrestelementsinanarray.

a=[1,2,3,4,5,0]

a.drop(3)#=>[4,5,0]

detect(ifnone=nil){|obj|block}→objornilfind(ifnone=nil){|obj|block}→objornildetect(ifnone=nil)→an_enumeratorfind(ifnone=nil)→an_enumerator

drop(n)→array

Dropselementsupto,butnotincluding,thefirstelementforwhichtheblockreturnsnilorfalseandreturnsanarraycontainingtheremainingelements.

a=[1,2,3,4,5,0]

a.drop_while{|i|i<3}#=>[3,4,5,0]

Iteratesthegivenblockforeacharrayofconsecutive<n>elements.Ifnoblockisgiven,returnsanenumerator.

(1..10).each_cons(3){|a|pa}

#outputsbelow

[1,2,3]

[2,3,4]

[3,4,5]

[4,5,6]

[5,6,7]

[6,7,8]

[7,8,9]

[8,9,10]

Callsblockonceforeachelementinself,passingthatelementasaparameter,convertingmultiplevaluesfromyieldtoanarray.

Ifnoblockisgiven,anenumeratorisreturned

drop_while{|arr|block}→arraydrop_while→an_enumerator

each_cons(n){...}→nileach_cons(n)→an_enumerator

each_entry{|obj|block}→enumeach_entry→an_enumerator

instead.

classFoo

includeEnumerable

defeach

yield1

yield1,2

Foo.new.each_entry{|o|po}

produces:

Iteratesthegivenblockforeachsliceof<n>elements.Ifnoblockisgiven,returnsanenumerator.

(1..10).each_slice(3){|a|pa}

#outputsbelow

[1,2,3]

[4,5,6]

[7,8,9]

Callsblockwithtwoarguments,theitemanditsindex,foreachiteminenum.Givenargumentsarepassedthroughtoeach().

each_slice(n){...}→nileach_slice(n)→an_enumerator

each_with_index(*args){|obj,i|block}→enumeach_with_index(*args)→an_enumerator

hash=Hash.new

%w(catdogwombat).each_with_index{|item,index|

hash[item]=index

hash#=>{"cat"=>0,"dog"=>1,"wombat"=>2}

Iteratesthegivenblockforeachelementwithanarbitraryobjectgiven,andreturnstheinitiallygivenobject.

Ifnoblockisgiven,returnsanenumerator.

evens=(1..10).each_with_object([]){|i,a|a<<i*2

#=>[2,4,6,8,10,12,14,16,18,20]

Returnsanarraycontainingtheitemsinenum.

(1..7).to_a#=>[1,2,3,4,5,6,7]

{'a'=>1,'b'=>2,'c'=>3}.to_a#=>[["a",1],["b",2],["c",3]]

require'prime'

Prime.entries10#=>[2,3,5,7]

Passeseachentryinenumtoblock.Returnsthefirst

each_with_object(obj){|(*args),memo_obj|...}→objeach_with_object(obj)→an_enumerator

to_a(*args)→arrayentries(*args)→array

detect(ifnone=nil){|obj|block}→objornilfind(ifnone=nil){|obj|block}→objornildetect(ifnone=nil)→an_enumeratorfind(ifnone=nil)→an_enumerator

forwhichblockisnotfalse.Ifnoobjectmatches,callsifnoneandreturnsitsresultwhenitisspecified,orreturnsnilotherwise.

(1..10).detect{|i|i%5==0andi%7==0}#=>nil

(1..100).find{|i|i%5==0andi%7==0}#=>35

Returnsanarraycontainingallelementsofenumforwhichthegivenblockreturnsatruevalue.

(1..10).find_all{|i|i%3==0}#=>[3,6,9]

Seealso#reject.

Compareseachentryinenumwithvalueorpassestoblock.Returnstheindexforthefirstforwhichtheevaluatedvalueisnon-false.Ifnoobjectmatches,returnsnil

Ifneitherblocknorargumentisgiven,anenumeratorisreturnedinstead.

find_all{|obj|block}→arrayselect{|obj|block}→arrayfind_all→an_enumeratorselect→an_enumerator

find_index(value)→intornilfind_index{|obj|block}→intornilfind_index→an_enumerator

(1..10).find_index{|i|i%5==0andi%7==0}

(1..100).find_index{|i|i%5==0andi%7==0}

(1..100).find_index(50)

Returnsthefirstelement,orthefirstnelements,oftheenumerable.Iftheenumerableisempty,thefirstformreturnsnil,andthesecondformreturnsanemptyarray.

%w[foobarbaz].first#=>"foo"

%w[foobarbaz].first(2)#=>["foo","bar"]

%w[foobarbaz].first(10)#=>["foo","bar","baz"]

[].first#=>nil

Returnsanewarraywiththeconcatenatedresultsofrunningblockonceforeveryelementinenum.

[1,2,3,4].flat_map{|e|[e,-e]}#=>[1,-1,2,-2,3,-3,4,-4]

[[1,2],[3,4]].flat_map{|e|e+[100]}#=>[1,2,100,3,4,100]

ReturnsanarrayofeveryelementinenumforwhichPattern===element.Iftheoptionalblockissupplied,

first→objornilfirst(n)→an_array

flat_map{|obj|block}→arraycollect_concat{|obj|block}→arrayflat_map→an_enumeratorcollect_concat→an_enumerator

grep(pattern)→arraygrep(pattern){|obj|block}→array

eachmatchingelementispassedtoit,andtheblock'sresultisstoredintheoutputarray.

(1..100).grep38..44#=>[38,39,40,41,42,43,44]

c=IO.constants

c.grep(/SEEK/)#=>[:SEEK_SET,:SEEK_CUR,:SEEK_END]

res=c.grep(/SEEK/){|v|IO.const_get(v)}

res#=>[0,1,2]

Groupsthecollectionbyresultoftheblock.Returnsahashwherethekeysaretheevaluatedresultfromtheblockandthevaluesarearraysofelementsinthecollectionthatcorrespondtothekey.

Ifnoblockisgivenanenumeratorisreturned.

(1..6).group_by{|i|i%3}#=>{0=>[3,6],1=>[1,4],2=>[2,5]}

Returnstrueifanymemberofenumequalsobj.Equalityistestedusing==.

IO.constants.include?:SEEK_SET#=>true

IO.constants.include?:SEEK_NO_FURTHER#=>false

group_by{|obj|block}→a_hashgroup_by→an_enumerator

include?(obj)→trueorfalsemember?(obj)→trueorfalse

inject(initial,sym)→objinject(sym)→objinject(initial){|memo,obj|block}→objinject{|memo,obj|block}→objreduce(initial,sym)→obj

Combinesallelementsofenumbyapplyingabinaryoperation,specifiedbyablockorasymbolthatnamesamethodoroperator.

Ifyouspecifyablock,thenforeachelementinenumtheblockispassedanaccumulatorvalue(memo)andtheelement.Ifyouspecifyasymbolinstead,theneachelementinthecollectionwillbepassedtothenamedmethodofmemo.Ineithercase,theresultbecomesthenewvalueformemo.Attheendoftheiteration,thefinalvalueofmemoisthereturnvalueforthemethod.

Ifyoudonotexplicitlyspecifyaninitialvalueformemo,thenthefirstelementofcollectionisusedastheinitialvalueofmemo.

#Sumsomenumbers

(5..10).reduce(:+)#=>45

#Sameusingablockandinject

(5..10).inject{|sum,n|sum+n}#=>45

#Multiplysomenumbers

(5..10).reduce(1,:*)#=>151200

#Sameusingablock

(5..10).inject(1){|product,n|product*n}#=>151200

#findthelongestword

longest=%w{catsheepbear}.injectdo|memo,word|

memo.length>word.length?memo:word

longest#=>"sheep"

Returnsalazyenumerator,whosemethodsmap/collect,flat_map/collect_concat,select/find_all,reject,grep,zip,take,#take_while,drop,and#drop_whileenumeratevaluesonlyonanas-needed

reduce(sym)→objreduce(initial){|memo,obj|block}→objreduce{|memo,obj|block}→obj

lazy→lazy_enumerator

basis.However,ifablockisgiventozip,valuesareenumeratedimmediately.

ExampleThefollowingprogramfindspythagoreantriples:

defpythagorean_triples

(1..Float::INFINITY).lazy.flat_map{|z|

(1..z).flat_map{|x|

(x..z).select{|y|

x**2+y**2==z**2

}.map{|y|

[x,y,z]

#showfirsttenpythagoreantriples

ppythagorean_triples.take(10).force#takeislazy,soforceisneeded

ppythagorean_triples.first(10)#firstiseager

#showpythagoreantripleslessthan100

ppythagorean_triples.take_while{|*,z|z<100}.force

Returnsanewarraywiththeresultsofrunningblockonceforeveryelementinenum.

(1..4).map{|i|i*i}#=>[1,4,9,16]

(1..4).collect{"cat"}#=>["cat","cat","cat","cat"]

collect{|obj|block}→arraymap{|obj|block}→arraycollect→an_enumeratormap→an_enumerator

max→obj

Returnstheobjectinenumwiththemaximumvalue.ThefirstformassumesallobjectsimplementComparable;thesecondusestheblocktoreturna<=>b.

a=%w(albatrossdoghorse)

a.max#=>"horse"

a.max{|a,b|a.length<=>b.length}#=>"albatross"

Ifthenargumentisgiven,maximumnelementsarereturnedasanarray.

a=%w[albatrossdoghorse]

a.max(2)#=>["horse","dog"]

a.max(2){|a,b|a.length<=>b.length}#=>["albatross","horse"]

Returnstheobjectinenumthatgivesthemaximumvaluefromthegivenblock.

a.max_by{|x|x.length}#=>"albatross"

Ifthenargumentisgiven,minimumnelementsarereturnedasanarray.

a.max_by(2){|x|x.length}#=>["albatross","horse"]

max{|a,b|block}→objmax(n)→objmax(n){|a,b|block}→obj

max_by{|obj|block}→objmax_by→an_enumeratormax_by(n){|obj|block}→objmax_by(n)→an_enumerator

enum.max_by(n)canbeusedtoimplementweightedrandomsampling.FollowingexampleimplementsanduseEnumerable#wsample.

moduleEnumerable

#weightedrandomsampling.

#PavlosS.Efraimidis,PaulG.Spirakis

#Weightedrandomsamplingwithareservoir

#InformationProcessingLetters

#Volume97,Issue5(16March2006)

defwsample(n)

self.max_by(n){|v|rand**(1.0/yield(v))}

e=(-20..20).to_a*10000

a=e.wsample(20000){|x|

Math.exp(-(x/5.0)**2)#normaldistribution

#ais20000samplesfrome.

pa.length#=>20000

h=a.group_by{|x|x}

-10.upto(10){|x|puts"*"*(h[x].length/30.0).to_iif

#******

#***********

#******************

#*****************************

#*****************************************

#****************************************************

#***************************************************************

#********************************************************************

#***********************************************************************

#**************************************************************

#****************************************************

#***************************************

#***************************

#******************

#***********

#*******

Returnstrueifanymemberofenumequalsobj.Equalityistestedusing==.

IO.constants.include?:SEEK_SET#=>true

IO.constants.include?:SEEK_NO_FURTHER#=>false

Returnstheobjectinenumwiththeminimumvalue.ThefirstformassumesallobjectsimplementComparable;thesecondusestheblocktoreturna<=>b.

a.min#=>"albatross"

a.min{|a,b|a.length<=>b.length}#=>"dog"

a.min(2)#=>["albatross","dog"]

a.min(2){|a,b|a.length<=>b.length}#=>["dog","horse"]

include?(obj)→trueorfalsemember?(obj)→trueorfalse

min→objmin{|a,b|block}→objmin(n)→arraymin(n){|a,b|block}→array

min_by{|obj|block}→objmin_by→an_enumeratormin_by(n){|obj|block}→arraymin_by(n)→an_enumerator

Returnstheobjectinenumthatgivestheminimumvaluefromthegivenblock.

a.min_by{|x|x.length}#=>"dog"

pa.min_by(2){|x|x.length}#=>["dog","horse"]

Returnstwoelementsarraywhichcontainstheminimumandthemaximumvalueintheenumerable.ThefirstformassumesallobjectsimplementComparable;thesecondusestheblocktoreturna<=>b.

a.minmax#=>["albatross","horse"]

a.minmax{|a,b|a.length<=>b.length}#=>["dog","albatross"]

Returnsatwoelementarraycontainingtheobjectsinenumthatcorrespondtotheminimumandmaximumvaluesrespectivelyfromthegivenblock.

minmax→[min,max]minmax{|a,b|block}→[min,max]

minmax_by{|obj|block}→[min,max]minmax_by→an_enumerator

a.minmax_by{|x|x.length}#=>["dog","albatross"]

Passeseachelementofthecollectiontothegivenblock.Themethodreturnstrueiftheblockneverreturnstrueforallelements.Iftheblockisnotgiven,none?willreturntrueonlyifnoneofthecollectionmembersistrue.

%w{antbearcat}.none?{|word|word.length==5}#=>true

%w{antbearcat}.none?{|word|word.length>=4}#=>false

[].none?#=>true

[nil].none?#=>true

[nil,false].none?#=>true

Passeseachelementofthecollectiontothegivenblock.Themethodreturnstrueiftheblockreturnstrueexactlyonce.Iftheblockisnotgiven,one?willreturntrueonlyifexactlyoneofthecollectionmembersistrue.

%w{antbearcat}.one?{|word|word.length==4}#=>true

%w{antbearcat}.one?{|word|word.length>4}#=>false

%w{antbearcat}.one?{|word|word.length<4}#=>false

[nil,true,99].one?#=>false

[nil,true,false].one?#=>true

Returnstwoarrays,thefirstcontainingtheelementsofenumforwhichtheblockevaluatestotrue,the

none?[{|obj|block}]→trueorfalse

one?[{|obj|block}]→trueorfalse

partition{|obj|block}→[true_array,false_array]partition→an_enumerator

secondcontainingtherest.

(1..6).partition{|v|v.even?}#=>[[2,4,6],[1,3,5]]

Combinesallelementsofenumbyapplyingabinaryoperation,specifiedbyablockorasymbolthatnamesamethodoroperator.

Ifyouspecifyablock,thenforeachelementinenumtheblockispassedanaccumulatorvalue(memo)andtheelement.Ifyouspecifyasymbolinstead,theneachelementinthecollectionwillbepassedtothenamedmethodofmemo.Ineithercase,theresultbecomesthenewvalueformemo.Attheendoftheiteration,thefinalvalueofmemoisthereturnvalueforthemethod.

Ifyoudonotexplicitlyspecifyaninitialvalueformemo,thenthefirstelementofcollectionisusedastheinitialvalueofmemo.

#Sumsomenumbers

(5..10).reduce(:+)#=>45

#Sameusingablockandinject

(5..10).inject{|sum,n|sum+n}#=>45

#Multiplysomenumbers

inject(initial,sym)→objinject(sym)→objinject(initial){|memo,obj|block}→objinject{|memo,obj|block}→objreduce(initial,sym)→objreduce(sym)→objreduce(initial){|memo,obj|block}→objreduce{|memo,obj|block}→obj

(5..10).reduce(1,:*)#=>151200

#Sameusingablock

(5..10).inject(1){|product,n|product*n}#=>151200

#findthelongestword

longest=%w{catsheepbear}.injectdo|memo,word|

memo.length>word.length?memo:word

longest#=>"sheep"

Returnsanarrayforallelementsofenumforwhichthegivenblockreturnsfalse.

(1..10).reject{|i|i%3==0}#=>[1,2,4,5,7,8,10]

[1,2,3,4,5].reject{|num|num.even?}#=>[1,3,5]

Seealso#find_all.

Buildsatemporaryarrayandtraversesthatarrayinreverseorder.

(1..3).reverse_each{|v|pv}

produces:

reject{|obj|block}→arrayreject→an_enumerator

reverse_each(*args){|item|block}→enumreverse_each(*args)→an_enumerator

Returnsanarraycontainingallelementsofenumforwhichthegivenblockreturnsatruevalue.

(1..10).find_all{|i|i%3==0}#=>[3,6,9]

Seealso#reject.

Createsanenumeratorforeachchunkedelements.Theendsofchunksaredefinedbypatternandtheblock.

Ifpattern===eltreturnstrueortheblockreturnstruefortheelement,theelementisendofachunk.

The===andblockiscalledfromthefirstelementtothelastelementofenum.

Theresultenumeratoryieldsthechunkedelementsasanarray.Soeachmethodcanbecalledasfollows:

enum.slice_after(pattern).each{|ary|...}

enum.slice_after{|elt|bool}.each{|ary|...}

OthermethodsoftheEnumeratorclassandEnumerablemodule,suchasmap,etc.,arealso

find_all{|obj|block}→arrayselect{|obj|block}→arrayfind_all→an_enumeratorselect→an_enumerator

slice_after(pattern)→an_enumeratorslice_after{|elt|bool}→an_enumerator

usable.

Forexample,continuationlines(linesendwithbackslash)canbeconcatenatedasfollows:

lines=["foo\n","bar\\\n","baz\n","\n","qux\n"]

e=lines.slice_after(/(?<!\)\n\z/)

pe.to_a

#=>[["foo\n"],["bar\\\n","baz\n"],["\n"],["qux\n"]]

pe.map{|ll|ll[0...-1].map{|l|l.sub(/\\n\z/,"")}.

#=>["foo\n","barbaz\n","\n","qux\n"]

Createsanenumeratorforeachchunkedelements.Thebeginningsofchunksaredefinedbypatternandtheblock.

Ifpattern===eltreturnstrueortheblockreturnstruefortheelement,theelementisbeginningofachunk.

The===andblockiscalledfromthefirstelementtothelastelementofenum.Theresultforthefirstelementisignored.

enum.slice_before(pattern).each{|ary|...}

enum.slice_before{|elt|bool}.each{|ary|...}

OthermethodsoftheEnumeratorclassandEnumerablemodule,suchasmap,etc.,arealsousable.

Forexample,iterationoverChangeLogentriescan

slice_before(pattern)→an_enumeratorslice_before{|elt|bool}→an_enumeratorslice_before(initial_state){|elt,state|bool}→an_enumerator(deprecated)

beimplementedasfollows:

#iterateoverChangeLogentries.

open("ChangeLog"){|f|

f.slice_before(/\A\S/).each{|e|ppe}

#sameasabove.blockisusedinsteadofpatternargument.

open("ChangeLog"){|f|

f.slice_before{|line|/\A\S/===line}.each{|e|

“svnproplist-R”producesmultilineoutputforeachfile.Theycanbechunkedasfollows:

IO.popen([{"LC_ALL"=>"C"},"svn","proplist","-R"]){

f.lines.slice_before(/\AProp/).each{|lines|plines

#=>["Propertieson'.':\n","svn:ignore\n","svk:merge\n"]

#["Propertieson'goruby.c':\n","svn:eol-style\n"]

#["Propertieson'complex.c':\n","svn:mime-type\n","svn:eol-style\n"]

#["Propertieson'regparse.c':\n","svn:eol-style\n"]

Iftheblockneedstomaintainstateovermultipleelements,localvariablescanbeused.Forexample,threeormoreconsecutiveincreasingnumberscanbesquashedasfollows:

a=[0,2,3,4,6,7,9]

prev=a[0]

pa.slice_before{|e|

prev,prev2=e,prev

prev2+1!=e

}.map{|es|

es.length<=2?es.join(","):"#{es.first}-#{es.last}"

}.join(",")

#=>"0,2-4,6,7,9"

Howeverlocalvariablesshouldbeusedcarefullyiftheresultenumeratorisenumeratedtwiceormore.Thelocalvariablesshouldbeinitializedforeach

enumeration.Enumerator.newcanbeusedtodoit.

#Wordwrapping.Thisassumesallcharactershavesamewidth.

defwordwrap(words,maxwidth)

Enumerator.new{|y|

#colsisinitializedinEnumerator.new.

cols=0

words.slice_before{|w|

cols+=1ifcols!=0

cols+=w.length

ifmaxwidth<cols

cols=w.length

}.each{|ws|y.yieldws}

text=(1..20).to_a.join("")

enum=wordwrap(text.split(/\s+/),10)

puts"-"*10

enum.each{|ws|putsws.join("")}#firstenumeration.

puts"-"*10

enum.each{|ws|putsws.join("")}#secondenumerationgeneratessameresultasthefirst.

puts"-"*10

#=>----------

#12345

#678910

#111213

#141516

#171819

#----------

#12345

#678910

#111213

#141516

#171819

#----------

mboxcontainsseriesofmailswhichstartwithUnixFromline.SoeachmailcanbeextractedbyslicebeforeUnixFromline.

#parsembox

open("mbox"){|f|

f.slice_before{|line|

line.start_with?"From"

}.each{|mail|

unix_from=mail.shift

i=mail.index("\n")

header=mail[0...i]

body=mail[(i+1)..-1]

body.popifbody.last=="\n"

fields=header.slice_before{|line|!"\t".include?

punix_from

ppfields

ppbody

#splitmailsinmbox(slicebeforeUnixFromlineafteranemptyline)

open("mbox"){|f|

f.slice_before(emp:true){|line,h|

prevemp=h[:emp]

h[:emp]=line=="\n"

prevemp&&line.start_with?("From")

}.each{|mail|

mail.popifmail.last=="\n"

ppmail

Createsanenumeratorforeachchunkedelements.Thebeginningsofchunksaredefinedbytheblock.

Thismethodspliteachchunkusingadjacentelements,elt_beforeandelt_after,inthereceiverenumerator.Thismethodsplitchunksbetweenelt_beforeandelt_afterwheretheblockreturnstrue.

Theblockiscalledthelengthofthereceiverenumeratorminusone.

slice_when{|elt_before,elt_after|bool}→an_enumerator

enum.slice_when{|elt_before,elt_after|bool}.each{

OthermethodsoftheEnumeratorclassandEnumerablemodule,suchasto_a,map,etc.,arealsousable.

Forexample,one-by-oneincreasingsubsequencecanbechunkedasfollows:

a=[1,2,4,9,10,11,12,15,16,19,20,21]

b=a.slice_when{|i,j|i+1!=j}

pb.to_a#=>[[1,2],[4],[9,10,11,12],[15,16],[19,20,21]]

c=b.map{|a|a.length<3?a:"#{a.first}-#{a.last}"

pc#=>[[1,2],[4],"9-12",[15,16],"19-21"]

d=c.join(",")

pd#=>"1,2,4,9-12,15,16,19-21"

Nearelements(threshold:6)insortedarraycanbechunkedasfollwos:

a=[3,11,14,25,28,29,29,41,55,57]

pa.slice_when{|i,j|6<j-i}.to_a

#=>[[3],[11,14],[25,28,29,29],[41],[55,57]]

Increasing(non-decreasing)subsequencecanbechunkedasfollows:

a=[0,9,2,2,3,2,7,5,9,5]

pa.slice_when{|i,j|i>j}.to_a

#=>[[0,9],[2,2,3],[2,7],[5,9],[5]]

Adjacentevensandoddscanbechunkedasfollows:(#chunkisanotherwaytodoit.)

a=[7,5,9,2,0,7,9,4,2,0]

pa.slice_when{|i,j|i.even?!=j.even?}.to_a

#=>[[7,5,9],[2,0],[7,9],[4,2,0]]

Paragraphs(non-emptylineswithtrailingemptylines)canbechunkedasfollows:(See#chunktoignoreemptylines.)

lines=["foo\n","bar\n","\n","baz\n","qux\n"]

plines.slice_when{|l1,l2|/\A\s*\z/=~l1&&/\S/=~

#=>[["foo\n","bar\n","\n"],["baz\n","qux\n"]]

Returnsanarraycontainingtheitemsinenumsorted,eitheraccordingtotheirown<=>method,orbyusingtheresultsofthesuppliedblock.Theblockshouldreturn-1,0,or+1dependingonthecomparisonbetweenaandb.AsofRuby1.8,themethodEnumerable#sort_byimplementsabuilt-inSchwartzianTransform,usefulwhenkeycomputationorcomparisonisexpensive.

%w(rheakeaflea).sort#=>["flea","kea","rhea"]

(1..10).sort{|a,b|b<=>a}#=>[10,9,8,7,6,5,4,3,2,1]

Sortsenumusingasetofkeysgeneratedbymappingthevaluesinenumthroughthegivenblock.

%w{applepearfig}.sort_by{|word|word.length}

#=>["fig","pear","apple"]

Thecurrentimplementationofsort_bygeneratesanarrayoftuplescontainingtheoriginalcollection

sort→arraysort{|a,b|block}→array

sort_by{|obj|block}→arraysort_by→an_enumerator

elementandthemappedvalue.Thismakessort_byfairlyexpensivewhenthekeysetsaresimple.

require'benchmark'

a=(1..100000).map{rand(100000)}

Benchmark.bm(10)do|b|

b.report("Sort"){a.sort}

b.report("Sortby"){a.sort_by{|a|a}}

produces:

usersystemtotalreal

Sort0.1800000.0000000.180000(0.175469)

Sortby1.9800000.0400002.020000(2.013586)

However,considerthecasewherecomparingthekeysisanon-trivialoperation.Thefollowingcodesortssomefilesonmodificationtimeusingthebasicsortmethod.

files=Dir["*"]

sorted=files.sort{|a,b|File.new(a).mtime<=>File

sorted#=>["mon","tues","wed","thurs"]

Thissortisinefficient:itgeneratestwonewFileobjectsduringeverycomparison.AslightlybettertechniqueistousetheKernel#testmethodtogeneratethemodificationtimesdirectly.

files=Dir["*"]

sorted=files.sort{|a,b|

test(M,a)<=>test(M,b)

ThisstillgeneratesmanyunnecessaryTimeobjects.Amoreefficienttechniqueistocachethesortkeys(modificationtimesinthiscase)beforethesort.Perl

usersoftencallthisapproachaSchwartzianTransform,afterRandalSchwartz.Weconstructatemporaryarray,whereeachelementisanarraycontainingoursortkeyalongwiththefilename.Wesortthisarray,andthenextractthefilenamefromtheresult.

sorted=Dir["*"].collect{|f|

[test(M,f),f]

}.sort.collect{|f|f[1]}

Thisisexactlywhatsort_bydoesinternally.

sorted=Dir["*"].sort_by{|f|test(M,f)}

Returnsfirstnelementsfromenum.

a=[1,2,3,4,5,0]

a.take(3)#=>[1,2,3]

a.take(30)#=>[1,2,3,4,5,0]

Passeselementstotheblockuntiltheblockreturnsnilorfalse,thenstopsiteratingandreturnsanarrayofallpriorelements.

a=[1,2,3,4,5,0]

a.take_while{|i|i<3}#=>[1,2]

take(n)→array

take_while{|arr|block}→arraytake_while→an_enumerator

to_a(*args)→array

Returnsanarraycontainingtheitemsinenum.

(1..7).to_a#=>[1,2,3,4,5,6,7]

{'a'=>1,'b'=>2,'c'=>3}.to_a#=>[["a",1],["b",2],["c",3]]

require'prime'

Prime.entries10#=>[2,3,5,7]

Returnstheresultofinterpretingenumasalistof[key,value]pairs.

%[helloworld].each_with_index.to_h

#=>{:hello=>0,:world=>1}

Takesoneelementfromenumandmergescorrespondingelementsfromeachargs.Thisgeneratesasequenceofn-elementarrays,wherenisonemorethanthecountofarguments.Thelengthoftheresultingsequencewillbeenum#size.Ifthesizeofanyargumentislessthanenum#size,nilvaluesaresupplied.Ifablockisgiven,itisinvokedforeachoutputarray,otherwiseanarrayofarraysisreturned.

a=[4,5,6]

b=[7,8,9]

a.zip(b)#=>[[4,7],[5,8],[6,9]]

[1,2,3].zip(a,b)#=>[[1,4,7],[2,5,8],[3,6,9]]

[1,2].zip(a,b)#=>[[1,4,7],[2,5,8]]

a.zip([1,2],[8])#=>[[4,1,8],[5,2,nil],[6,nil,nil]]

entries(*args)→array

to_h(*args)→hash

zip(arg,...)→an_array_of_arrayzip(arg,...){|arr|block}→nil

classEnumeratorAclasswhichallowsbothinternalandexternaliteration.

AnEnumeratorcanbecreatedbythefollowingmethods.

Kernel#to_enumKernel#enum_for::new

Mostmethodshavetwoforms:ablockformwherethecontentsareevaluatedforeachitemintheenumeration,andanon-blockformwhichreturnsanewEnumeratorwrappingtheiteration.

enumerator=%w(onetwothree).each

putsenumerator.class#=>Enumerator

enumerator.each_with_object("foo")do|item,obj|

puts"#{obj}:#{item}"

#foo:one

#foo:two

#foo:three

enum_with_obj=enumerator.each_with_object("foo"

putsenum_with_obj.class#=>Enumerator

enum_with_obj.eachdo|item,obj|

puts"#{obj}:#{item}"

#foo:one

#foo:two

#foo:three

ThisallowsyoutochainEnumeratorstogether.Forexample,youcanmapalist'selementstostringscontainingtheindexandtheelementasastringvia:

puts%w[foobarbaz].map.with_index{|w,i|"#{i}:#{w}"

#=>["0:foo","1:bar","2:baz"]

AnEnumeratorcanalsobeusedasanexternaliterator.Forexample,#nextreturnsthenextvalueoftheiteratororraisesStopIterationiftheEnumeratorisattheend.

e=[1,2,3].each#returnsanenumeratorobject.

putse.next#=>1

putse.next#=>2

putse.next#=>3

putse.next#raisesStopIteration

Youcanusethistoimplementaninternaliteratorasfollows:

defext_each(e)

whiletrue

vs=e.next_values

rescueStopIteration

return$!.result

y=yield(*vs)

e.feedy

o=Object.new

defo.each

putsyield

putsyield(1)

putsyield(1,2)

#useo.eachasaninternaliteratordirectly.

putso.each{|*x|putsx;[:b,*x]}

#=>[],[:b],[1],[:b,1],[1,2],[:b,1,2],3

#converto.eachtoanexternaliteratorfor

#implementinganinternaliterator.

putsext_each(o.to_enum){|*x|putsx;[:b,*x]}

#=>[],[:b],[1],[:b,1],[1,2],[:b,1,2],3

InFilesenumerator.c

ParentObject

PublicClassMethods

CreatesanewEnumeratorobject,whichcanbeusedasanEnumerable.

Inthefirstform,iterationisdefinedbythegivenblock,inwhicha“yielder”object,givenasblockparameter,canbeusedtoyieldavaluebycallingtheyieldmethod(aliasedas+<<+):

fib=Enumerator.newdo|y|

loopdo

a,b=b,a+b

pfib.take(10)#=>[1,1,2,3,5,8,13,21,34,55]

Theoptionalparametercanbeusedtospecifyhowtocalculatethesizeinalazyfashion(see#size).Itcaneitherbeavalueoracallableobject.

Inthesecond,deprecated,form,ageneratedEnumeratoriteratesoverthegivenobjectusingthegivenmethodwiththegivenargumentspassed.

Useofthisformisdiscouraged.UseKernel#enum_fororKernel#to_enuminstead.

e=Enumerator.new(ObjectSpace,:each_object)

#->ObjectSpace.enum_for(:each_object)

e.select{|obj|obj.is_a?(Class)}#=>arrayofallclasses

new(size=nil){|yielder|...}new(obj,method=:each,*args)

IteratesovertheblockaccordingtohowthisEnumeratorwasconstructed.Ifnoblockandnoargumentsaregiven,returnsself.

Examples"Hello,world!".scan(/\w+/)#=>["Hello","world"]

"Hello,world!".to_enum(:scan,/\w+/).to_a#=>["Hello","world"]

"Hello,world!".to_enum(:scan).each(/\w+/).to_a#=>["Hello","world"]

obj=Object.new

defobj.each_arg(a,b=:b,*rest)

yielda

yieldb

yieldrest

:method_returned

enum=obj.to_enum:each_arg,:a,:x

enum.each.to_a#=>[:a,:x,[]]

enum.each.equal?(enum)#=>true

enum.each{|elm|elm}#=>:method_returned

enum.each(:y,:z).to_a#=>[:a,:x,[:y,:z]]

enum.each(:y,:z).equal?(enum)#=>false

enum.each(:y,:z){|elm|elm}#=>:method_returned

Sameas#with_index,i.e.thereisnostartingoffset.

each{|elm|block}→objeach→enumeach(*appending_args){|elm|block}→objeach(*appending_args)→an_enumerator

each_with_index{|(*args),idx|...}each_with_index

Ifnoblockisgiven,anewEnumeratorisreturnedthatincludestheindex.

Iteratesthegivenblockforeachelementwithanarbitraryobject,obj,andreturnsobj

Ifnoblockisgiven,returnsanewEnumerator.

Exampleto_three=Enumerator.newdo|y|

3.timesdo|x|

to_three_with_string=to_three.with_object("foo")

to_three_with_string.eachdo|x,string|

puts"#{string}:#{x}"

#=>foo:0

#=>foo:1

#=>foo:2

Setsthevaluetobereturnedbythenextyieldinsidee.

Ifthevalueisnotset,theyieldreturnsnil.

Thisvalueisclearedafterbeingyielded.

#Array#mappassesthearray'selementsto"yield"andcollectsthe

each_with_object(obj){|(*args),obj|...}each_with_object(obj)with_object(obj){|(*args),obj|...}with_object(obj)

feedobj→nil

#resultsof"yield"asanarray.

#Followingexampleshowsthat"next"returnsthepassedelementsand

#valuespassedto"feed"arecollectedasanarraywhichcanbe

#obtainedbyStopIteration#result.

e=[1,2,3].map

pe.next#=>1

e.feed"a"

pe.next#=>2

e.feed"b"

pe.next#=>3

e.feed"c"

e.next

rescueStopIteration

p$!.result#=>["a","b","c"]

o=Object.new

defo.each

x=yield#(2)blocks

px#(5)=>"foo"

x=yield#(6)blocks

px#(8)=>nil

x=yield#(9)blocks

px#notreachedw/oanothere.next

e=o.to_enum

e.next#(1)

e.feed"foo"#(3)

e.next#(4)

e.next#(7)

Createsaprintableversionofe.

Returnsthenextobjectintheenumerator,andmovetheinternalpositionforward.Whenthepositionreachedattheend,StopIterationisraised.

inspect→string

next→object

Examplea=[1,2,3]

e=a.to_enum

pe.next#=>1

pe.next#=>2

pe.next#=>3

pe.next#raisesStopIteration

Notethatenumerationsequencebynextdoesnotaffectothernon-externalenumerationmethods,unlesstheunderlyingiterationmethodsitselfhasside-effect,e.g.IO#each_line.

Returnsthenextobjectasanarrayintheenumerator,andmovetheinternalpositionforward.Whenthepositionreachedattheend,StopIterationisraised.

Thismethodcanbeusedtodistinguishyieldandyieldnil.

Exampleo=Object.new

defo.each

yield1

yield1,2

yieldnil

yield[1,2]

e=o.to_enum

pe.next_values

e=o.to_enum

pe.next

next_values→array

pe.next

##yieldargsnext_valuesnext

#yield[]nil

#yield1[1]1

#yield1,2[1,2][1,2]

#yieldnil[nil]nil

#yield[1,2][[1,2]][1,2]

Notethatnext_valuesdoesnotaffectothernon-externalenumerationmethodsunlessunderlyingiterationmethoditselfhasside-effect,e.g.IO#each_line.

Returnsthenextobjectintheenumerator,butdoesn'tmovetheinternalpositionforward.Ifthepositionisalreadyattheend,StopIterationisraised.

Examplea=[1,2,3]

e=a.to_enum

pe.next#=>1

pe.peek#=>2

pe.next#=>2

pe.next#=>3

pe.peek#raisesStopIteration

Returnsthenextobjectasanarray,similarto#next_values,butdoesn'tmovetheinternalpositionforward.Ifthepositionisalreadyattheend,StopIterationisraised.

peek→object

peek_values→array

Exampleo=Object.new

defo.each

yield1

yield1,2

e=o.to_enum

pe.peek_values#=>[]

e.next

pe.peek_values#=>[1]

e.next

pe.peek_values#=>[1,2]

e.next

pe.peek_values#raisesStopIteration

Rewindstheenumerationsequencetothebeginning.

Iftheenclosedobjectrespondstoa“rewind”method,itiscalled.

Returnsthesizeoftheenumerator,ornilifitcan'tbecalculatedlazily.

(1..100).to_a.permutation(4).size#=>94109400

loop.size#=>Float::INFINITY

(1..100).drop_while.size#=>nil

Iteratesthegivenblockforeachelementwithanindex,whichstartsfromoffset.Ifnoblockisgiven,returnsanewEnumeratorthatincludestheindex,startingfromoffset

rewind→e

size→int,Float::INFINITYornil

with_index(offset=0){|(*args),idx|...}with_index(offset=0)

offset

thestartingindextouse

Iteratesthegivenblockforeachelementwithanarbitraryobject,obj,andreturnsobj

Ifnoblockisgiven,returnsanewEnumerator.

Exampleto_three=Enumerator.newdo|y|

3.timesdo|x|

to_three_with_string=to_three.with_object("foo")

to_three_with_string.eachdo|x,string|

puts"#{string}:#{x}"

#=>foo:0

#=>foo:1

#=>foo:2

each_with_object(obj){|(*args),obj|...}each_with_object(obj)with_object(obj){|(*args),obj|...}with_object(obj)

classEnumerator::GeneratorLazy

InFilesenumerator.c

ParentObject

classEnumerator::LazyLazy

InFilesenumerator.c

ParentEnumerator

PublicClassMethods

CreatesanewLazyenumerator.Whentheenumeratorisactuallyenumerated(e.g.bycallingforce),objwillbeenumeratedandeachvaluepassedtothegivenblock.Theblockcanyieldvaluesbackusingyielder.Forexample,tocreateamethodfilter_mapinbothlazyandnon-lazyfashions:

moduleEnumerable

deffilter_map(&block)

map(&block).compact

classEnumerator::Lazy

deffilter_map

Lazy.new(self)do|yielder,*values|

result=yield*values

yielder<<resultifresult

new(obj,size=nil){|yielder,*values|...}

(1..Float::INFINITY).lazy.filter_map{|i|i*iifi.even?

#=>[4,16,36,64,100]

Returnsanewlazyenumeratorwiththeconcatenatedresultsofrunningblockonceforeveryelementinlazy.

["foo","bar"].lazy.flat_map{|i|i.each_char.lazy}.force

#=>["f","o","o","b","a","r"]

Avaluexreturnedbyblockisdecomposedifeitherofthefollowingconditionsistrue:

a)<i>x</i>respondstobotheachandforce,whichmeansthat

<i>x</i>isalazyenumerator.

b)<i>x</i>isanarrayorrespondstoto_ary.

Otherwise,xiscontainedas-isinthereturnvalue.

[{a:1},{b:2}].lazy.flat_map{|i|i}.force

#=>[{:a=>1},{:b=>2}]

chunk(*args)

collect()

collect_concat{|obj|block}→a_lazy_enumeratorflat_map{|obj|block}→a_lazy_enumerator

SimilartoKernel#to_enum,exceptitreturnsalazyenumerator.ThismakesiteasytodefineEnumerablemethodsthatwillnaturallyremainlazyifcalledfromalazyenumerator.

Forexample,continuingfromtheexampleinKernel#to_enum:

#SeeKernel#to_enumforthedefinitionofrepeat

r=1..Float::INFINITY

r.repeat(2).first(5)#=>[1,1,2,2,3]

r.repeat(2).class#=>Enumerator

r.repeat(2).map{|n|n**2}.first(5)#=>endlessloop!

#worksnaturallyonlazyenumerator:

r.lazy.repeat(2).class#=>Enumerator::Lazy

r.lazy.repeat(2).map{|n|n**2}.first(5)#=>[1,1,4,4,9]

drop(p1)

drop_while()

to_enum(method=:each,*args)→lazy_enumenum_for(method=:each,*args)→lazy_enumto_enum(method=:each,*args){|*args|block}→lazy_enumenum_for(method=:each,*args){|*args|block}→lazy_enum

find_all()

collect_concat{|obj|block}→a_lazy_enumeratorflat_map{|obj|block}→a_lazy_enumerator

Returnsanewlazyenumeratorwiththeconcatenatedresultsofrunningblockonceforeveryelementinlazy.

["foo","bar"].lazy.flat_map{|i|i.each_char.lazy}.force

#=>["f","o","o","b","a","r"]

Avaluexreturnedbyblockisdecomposedifeitherofthefollowingconditionsistrue:

a)<i>x</i>respondstobotheachandforce,whichmeansthat

<i>x</i>isalazyenumerator.

b)<i>x</i>isanarrayorrespondstoto_ary.

Otherwise,xiscontainedas-isinthereturnvalue.

[{a:1},{b:2}].lazy.flat_map{|i|i}.force

#=>[{:a=>1},{:b=>2}]

grep(p1)

lazy()

reject()

select()

slice_after(*args)

slice_before(*args)

slice_when(*args)

SimilartoKernel#to_enum,exceptitreturnsalazyenumerator.ThismakesiteasytodefineEnumerablemethodsthatwillnaturallyremainlazyifcalledfromalazyenumerator.

Forexample,continuingfromtheexampleinKernel#to_enum:

#SeeKernel#to_enumforthedefinitionofrepeat

r=1..Float::INFINITY

r.repeat(2).first(5)#=>[1,1,2,2,3]

r.repeat(2).class#=>Enumerator

r.repeat(2).map{|n|n**2}.first(5)#=>endlessloop!

#worksnaturallyonlazyenumerator:

r.lazy.repeat(2).class#=>Enumerator::Lazy

r.lazy.repeat(2).map{|n|n**2}.first(5)#=>[1,1,4,4,9]

take(p1)

take_while()

to_enum(method=:each,*args)→lazy_enumenum_for(method=:each,*args)→lazy_enumto_enum(method=:each,*args){|*args|block}→lazy_enumenum_for(method=:each,*args){|*args|block}→lazy_enum

zip(*args)

classEnumerator::YielderLazy

InFilesenumerator.c

ParentObject

moduleErrnoRubyexceptionobjectsaresubclassesofException.However,operatingsystemstypicallyreporterrorsusingplainintegers.ModuleErrnoiscreateddynamicallytomaptheseoperatingsystemerrorstoRubyclasses,witheacherrornumbergeneratingitsownsubclassofSystemCallError.AsthesubclassiscreatedinmoduleErrno,itsnamewillstartErrno::.

ThenamesoftheErrno::classesdependontheenvironmentinwhichRubyruns.OnatypicalUnixorWindowsplatform,thereareErrnoclassessuchasErrno::EACCES,Errno::EAGAIN,Errno::EINTR,andsoon.

TheintegeroperatingsystemerrornumbercorrespondingtoaparticularerrorisavailableastheclassconstantErrno::error::Errno.

Errno::EACCES::Errno#=>13

Errno::EAGAIN::Errno#=>11

Errno::EINTR::Errno#=>4

ThefulllistofoperatingsystemerrorsonyourparticularplatformareavailableastheconstantsofErrno.

Errno.constants#=>:E2BIG,:EACCES,:EADDRINUSE,:EADDRNOTAVAIL,...

InFileserror.c

classExceptionDescendantsofclassExceptionareusedtocommunicatebetweenKernel#raiseandrescuestatementsinbegin...endblocks.Exceptionobjectscarryinformationabouttheexception–itstype(theexception'sclassname),anoptionaldescriptivestring,andoptionaltracebackinformation.ExceptionsubclassesmayaddadditionalinformationlikeNameError#name.

ProgramsmaymakesubclassesofException,typicallyofStandardErrororRuntimeError,toprovidecustomclassesandaddadditionalinformation.Seethesubclasslistbelowfordefaultsforraiseandrescue.

Whenanexceptionhasbeenraisedbutnotyethandled(inrescue,ensure,at_exitandENDblocks)theglobalvariable$!willcontainthecurrentexceptionand$@containsthecurrentexception'sbacktrace.

ItisrecommendedthatalibraryshouldhaveonesubclassofStandardErrororRuntimeErrorandhavespecificexceptiontypesinheritfromit.Thisallowstheusertorescueagenericexceptiontypetocatchallexceptionsthelibrarymayraiseeveniffutureversionsofthelibraryaddnewexceptionsubclasses.

Forexample:

classMyLibrary

classError<RuntimeError

classWidgetError<Error

classFrobError<Error

TohandlebothWidgetErrorandFrobErrorthelibraryusercanrescueMyLibrary::Error.

Thebuilt-insubclassesofExceptionare:

NoMemoryErrorScriptError

LoadErrorNotImplementedErrorSyntaxError

SecurityErrorSignalException

InterruptStandardError–defaultforrescue

ArgumentErrorUncaughtThrowError

EncodingErrorFiberErrorIOError

EOFErrorIndexError

KeyErrorStopIteration

LocalJumpErrorNameError

NoMethodErrorRangeError

FloatDomainErrorRegexpErrorRuntimeError–defaultforraiseSystemCallError

Errno::*ThreadErrorTypeErrorZeroDivisionError

SystemExitSystemStackErrorfatal–impossibletorescue

InFileserror.c

ParentObject

PublicClassMethods

Withnoargument,oriftheargumentisthesameasthereceiver,returnthereceiver.Otherwise,createanewexceptionobjectofthesameclassasthereceiver,butwithamessageequaltostring.to_str.

ConstructanewExceptionobject,optionallypassinginamessage.

Equality—IfobjisnotanException,returnsfalse.Otherwise,returnstrueifexcandobjsharesameclass,messages,andbacktrace.

Returnsanybacktraceassociatedwiththeexception.Thebacktraceisanarrayofstrings,eachcontainingeither“filename:lineNo:in`method'''or“filename:lineNo.''

raise"boom"

rescue=>detail

exception(string)→an_exceptionorexc

new(msg=nil)→exception

exc==obj→trueorfalse

backtrace→array

printdetail.backtrace.join("\n")

produces:

prog.rb:2:in`a'

prog.rb:6:in`b'

prog.rb:10

Returnsanybacktraceassociatedwiththeexception.Thismethodissimilarto#backtrace,butthebacktraceisanarrayof

Thread::Backtrace::Location.

Now,thismethodisnotaffectedby#set_backtrace.

Returnsthepreviousexception($!)atthetimethisexceptionwasraised.Thisisusefulforwrappingexceptionsandretainingtheoriginalexceptioninformation.

Withnoargument,oriftheargumentisthesameasthereceiver,returnthereceiver.Otherwise,createanewexceptionobjectofthesameclassasthereceiver,butwithamessageequaltostring.to_str.

Returnthisexception'sclassnameandmessage

backtrace_locations→array

cause→an_exceptionornil

exception(string)→an_exceptionorexc

inspect→string

message→string

Returnstheresultofinvokingexception.to_s.Normallythisreturnstheexception'smessageorname.Bysupplyingato_strmethod,exceptionsareagreeingtobeusedwhereStringsareexpected.

Setsthebacktraceinformationassociatedwithexc.ThebacktracemustbeanarrayofStringobjectsorasingleStringintheformatdescribedin#backtrace.

Returnsexception'smessage(orthenameoftheexceptionifnomessageisset).

set_backtrace(backtrace)→array

to_s→string

classFalseClassTheglobalvaluefalseistheonlyinstanceofclassFalseClassandrepresentsalogicallyfalsevalueinbooleanexpressions.Theclassprovidesoperatorsallowingfalsetoparticipatecorrectlyinlogicalexpressions.

InFilesobject.c

ParentObject

And—Returnsfalse.objisalwaysevaluatedasitistheargumenttoamethodcall—thereisnoshort-circuitevaluationinthiscase.

ExclusiveOr—Ifobjisnilorfalse,returnsfalse;otherwise,returnstrue.

false&obj→falsenil&obj→false

false^obj→trueorfalsenil^obj→trueorfalse

Aliasfor:to_s

'nufsaid…

Or—Returnsfalseifobjisnilorfalse;trueotherwise.

inspect()

to_s→"false"

false|obj→trueorfalsenil|obj→trueorfalse

classFiberFibersareprimitivesforimplementinglightweightcooperativeconcurrencyinRuby.Basicallytheyareameansofcreatingcodeblocksthatcanbepausedandresumed,muchlikethreads.ThemaindifferenceisthattheyareneverpreemptedandthattheschedulingmustbedonebytheprogrammerandnottheVM.

Asopposedtootherstacklesslightweightconcurrencymodels,eachfibercomeswithasmall4KBstack.Thisenablesthefibertobepausedfromdeeplynestedfunctioncallswithinthefiberblock.

Whenafiberiscreateditwillnotrunautomatically.RatheritmustbebeexplicitlyaskedtorunusingtheFiber#resumemethod.ThecoderunninginsidethefibercangiveupcontrolbycallingFiber.yieldinwhichcaseityieldscontrolbacktocaller(thecalleroftheFiber#resume).

UponyieldingorterminationtheFiberreturnsthevalueofthelastexecutedexpression

Forinstance:

fiber=Fiber.newdo

Fiber.yield1

putsfiber.resume

produces

FiberError:deadfibercalled

TheFiber#resumemethodacceptsanarbitrarynumberofparameters,ifitisthefirstcalltoresumethentheywillbepassedasblockarguments.OtherwisetheywillbethereturnvalueofthecalltoFiber.yield

Example:

fiber=Fiber.newdo|first|

second=Fiber.yieldfirst+2

putsfiber.resume10

putsfiber.resume14

putsfiber.resume18

produces

FiberError:deadfibercalled

InFilescont.c

ParentObject

PublicClassMethods

Returnsthecurrentfiber.Youneedtorequire'fiber'beforeusingthismethod.Ifyouarenotrunninginthecontextofafiberthismethodwillreturntherootfiber.

Yieldscontrolbacktothecontextthatresumedthefiber,passingalonganyargumentsthatwerepassedtoit.Thefiberwillresumeprocessingatthispointwhenresumeiscallednext.AnyargumentspassedtothenextresumewillbethevaluethatthisFiber.yieldexpressionevaluatesto.

Returnstrueifthefibercanstillberesumed(ortransferredto).Afterfinishingexecutionofthefiberblockthismethodwillalwaysreturnfalse.Youneedtorequire'fiber'beforeusingthismethod.

current()→fiber

yield(args,...)→obj

alive?→trueorfalse

ResumesthefiberfromthepointatwhichthelastFiber.yieldwascalled,orstartsrunningitifitisthefirstcalltoresume.ArgumentspassedtoresumewillbethevalueoftheFiber.yieldexpressionorwillbepassedasblockparameterstothefiber'sblockifthisisthefirstresume.

Alternatively,whenresumeiscalleditevaluatestotheargumentspassedtothenextFiber.yieldstatementinsidethefiber'sblockortotheblockvalueifitrunstocompletionwithoutanyFiber.yield

Transfercontroltoanotherfiber,resumingitfromwhereitlaststoppedorstartingitifitwasnotresumedbefore.ThecallingfiberwillbesuspendedmuchlikeinacalltoFiber.yield.Youneedtorequire'fiber'beforeusingthismethod.

Thefiberwhichreceivesthetransfercallistreatsitmuchlikearesumecall.Argumentspassedtotransferaretreatedlikethosepassedtoresume.

Youcannotresumeafiberthattransferredcontroltoanotherone.Thiswillcauseadoubleresumeerror.Youneedtotransfercontrolbacktothisfiberbeforeitcanyieldandresume.

Example:

fiber1=Fiber.newdo

puts"InFiber1"

Fiber.yield

fiber2=Fiber.newdo

puts"InFiber2"

resume(args,...)→obj

transfer(args,...)→obj

fiber1.transfer

puts"Neverseethismessage"

fiber3=Fiber.newdo

puts"InFiber3"

fiber2.resume

fiber3.resume

produces

Infiber2

Infiber1

Infiber3

classFiberErrorRaisedwhenaninvalidoperationisattemptedonaFiber,inparticularwhenattemptingtocall/resumeadeadfiber,attemptingtoyieldfromtherootfiber,orcallingafiberacrossthreads.

fiber=Fiber.new{}

fiber.resume#=>nil

fiber.resume#=>FiberError:deadfibercalled

InFilescont.c

ParentStandardError

classFileAFileisanabstractionofanyfileobjectaccessiblebytheprogramandiscloselyassociatedwithclassIOFileincludesthemethodsofmoduleFileTestasclassmethods,allowingyoutowrite(forexample)File.exist?("foo").

InthedescriptionofFilemethods,permissionbitsareaplatform-specificsetofbitsthatindicatepermissionsofafile.OnUnix-basedsystems,permissionsareviewedasasetofthreeoctets,fortheowner,thegroup,andtherestoftheworld.Foreachoftheseentities,permissionsmaybesettoread,write,orexecutethefile:

Thepermissionbits0644(inoctal)wouldthusbeinterpretedasread/writeforowner,andread-onlyforgroupandother.Higher-orderbitsmayalsobeusedtoindicatethetypeoffile(plain,directory,pipe,socket,andsoon)andvariousotherspecialfeatures.Ifthepermissionsareforadirectory,themeaningoftheexecutebitchanges;whensetthedirectorycanbesearched.

Onnon-Posixoperatingsystems,theremaybeonlytheabilitytomakeafileread-onlyorread-write.Inthiscase,theremainingpermissionbits

willbesynthesizedtoresembletypicalvalues.Forinstance,onWindowsNTthedefaultpermissionbitsare0644,whichmeansread/writeforowner,read-onlyforallothers.Theonlychangethatcanbemadeistomakethefileread-only,whichisreportedas0444.

VariousconstantsforthemethodsinFilecanbefoundinFile::Constants.

InFilesdir.cfile.cio.c

ParentIO

Constants

ALT_SEPARATOR

platformspecificalternativeseparator

PATH_SEPARATOR

pathlistseparator

SEPARATOR

separatesdirectorypartsinpath

Separator

separatesdirectorypartsinpath

PublicClassMethods

Convertsapathnametoanabsolutepathname.Relativepathsarereferencedfromthecurrentworkingdirectoryoftheprocessunlessdir_stringisgiven,inwhichcaseitwillbeusedasthestartingpoint.Ifthegivenpathnamestartswitha“~''itisNOTexpanded,itistreatedasanormaldirectoryname.

File.absolute_path("~oracle/bin")#=>"<relative_path>/~oracle/bin"

ReturnsthelastaccesstimeforthenamedfileasaTimeobject).

file_namecanbeanIOobject.

File.atime("testfile")#=>WedApr0908:51:48CDT2003

Returnsthelastcomponentofthefilenamegiveninfile_name,whichcanbeformedusingbothFile::SEPARATORandFile::ALT_SEPARATORastheseparatorwhenFile::ALT_SEPARATORisnotnil.Ifsuffixisgivenandpresentattheendoffile_name,itisremoved.Ifsuffixis“.*”,anyextensionwillbe

absolute_path(file_name[,dir_string])→abs_file_name

atime(file_name)→time

basename(file_name[,suffix])→base_name

removed.

File.basename("/home/gumby/work/ruby.rb")#=>"ruby.rb"

File.basename("/home/gumby/work/ruby.rb",".rb")#=>"ruby"

File.basename("/home/gumby/work/ruby.rb",".*")#=>"ruby"

Returnsthebirthtimeforthenamedfile.

NotethatonWindows(NTFS),returnscreationtime(birthtime).

File.birthtime("testfile")#=>WedApr0908:53:13CDT2003

Returnstrueifthenamedfileisablockdevice.

Returnstrueifthenamedfileisacharacterdevice.

Changespermissionbitsonthenamedfile(s)tothebitpatternrepresentedbymode_int.Actualeffectsareoperatingsystemdependent(seethebeginningofthissection).OnUnixsystems,seechmod(2)fordetails.Returnsthenumberoffilesprocessed.

File.chmod(0644,"testfile","out")#=>2

birthtime(file_name)→time

blockdev?(file_name)→trueorfalse

chardev?(file_name)→trueorfalse

chmod(mode_int,file_name,...)→integer

Changestheownerandgroupofthenamedfile(s)tothegivennumericownerandgroupid's.Onlyaprocesswithsuperuserprivilegesmaychangetheownerofafile.Thecurrentownerofafilemaychangethefile'sgrouptoanygrouptowhichtheownerbelongs.Anilor-1ownerorgroupidisignored.Returnsthenumberoffilesprocessed.

File.chown(nil,100,"testfile")

Returnsthechangetimeforthenamedfile(thetimeatwhichdirectoryinformationaboutthefilewaschanged,notthefileitself).

File.ctime("testfile")#=>WedApr0908:53:13CDT2003

Deletesthenamedfiles,returningthenumberofnamespassedasarguments.Raisesanexceptiononanyerror.SeealsoDir::rmdir.

Returnstrueifthenamedfileisadirectory,orasymlinkthatpointsatadirectory,andfalseotherwise.

chown(owner_int,group_int,file_name,...)→integer

ctime(file_name)→time

delete(file_name,...)→integerunlink(file_name,...)→integer

directory?(file_name)→trueorfalse

File.directory?(".")

Returnsallcomponentsofthefilenamegiveninfile_nameexceptthelastone.ThefilenamecanbeformedusingbothFile::SEPARATORandFile::ALT_SEPARATORastheseparatorwhenFile::ALT_SEPARATORisnotnil.

File.dirname("/home/gumby/work/ruby.rb")#=>"/home/gumby/work"

Returnstrueifthenamedfileisexecutablebytheeffectiveuseridofthisprocess.

Returnstrueifthenamedfileisexecutablebytherealuseridofthisprocess.

Returntrueifthenamedfileexists.

“fileexists”meansthatstat()orfstat()systemcallissuccessful.

dirname(file_name)→dir_name

executable?(file_name)→trueorfalse

executable_real?(file_name)→trueorfalse

Convertsapathnametoanabsolutepathname.Relativepathsarereferencedfromthecurrentworkingdirectoryoftheprocessunlessdir_stringisgiven,inwhichcaseitwillbeusedasthestartingpoint.Thegivenpathnamemaystartwitha“~'',whichexpandstotheprocessowner'shomedirectory(theenvironmentvariableHOMEmustbesetcorrectly).“~user''expandstothenameduser'shomedirectory.

File.expand_path("~oracle/bin")#=>"/home/oracle/bin"

Asimpleexampleofusingdir_stringisasfollows.

File.expand_path("ruby","/usr/bin")#=>"/usr/bin/ruby"

Amorecomplexexamplewhichalsoresolvesparentdirectoryisasfollows.Supposeweareinbin/mygemandwanttheabsolutepathoflib/mygem.rb.

File.expand_path("../../lib/mygem.rb",__FILE__)

#=>".../path/to/project/lib/mygem.rb"

Sofirstitresolvestheparentof__FILE__,thatisbin/,thengototheparent,therootoftheprojectandappendslib/mygem.rb.

Returnstheextension(theportionoffilenameinpathstartingfromthelastperiod).

Ifpathisadotfile,orstartswithaperiod,thenthestartingdotisnotdealtwiththestartoftheextension.

Anemptystringwillalsobereturnedwhentheperiod

expand_path(file_name[,dir_string])→abs_file_name

extname(path)→string

isthelastcharacterinpath.

File.extname("test.rb")#=>".rb"

File.extname("a/b/d/test.rb")#=>".rb"

File.extname("foo.")#=>""

File.extname("test")#=>""

File.extname(".profile")#=>""

File.extname(".profile.sh")#=>".sh"

Returnstrueifthenamedfileexistsandisaregularfile.

filecanbeanIOobject.

Ifthefileargumentisasymboliclink,itwillresolvethesymboliclinkandusethefilereferencedbythelink.

Returnstrueifpathmatchesagainstpattern.Thepatternisnotaregularexpression;insteaditfollowsrulessimilartoshellfilenameglobbing.Itmaycontainthefollowingmetacharacters:*

Matchesallfilesregularfiles

file?(file)→trueorfalse

fnmatch(pattern,path,[flags])→(trueorfalse)fnmatch?(pattern,path,[flags])→(trueorfalse)

Matchesallfilesthathavecinthem(includingatthebeginningorend).

Tomatchhiddenfiles(thatstartwitha.settheFile::FNM_DOTMATCHflag.

Matchesdirectoriesrecursivelyorfilesexpansively.

MatchespatternaandpatternbifFile::FNM_EXTGLOBflagisenabled.BehaveslikeaRegexpunion((?:a|b)).

flagsisabitwiseORoftheFNM_XXXconstants.ThesameglobpatternandflagsareusedbyDir.glob.

Examples:

File.fnmatch('cat','cat')#=>true#matchentirestring

File.fnmatch('cat','category')#=>false#onlymatchpartialstring

File.fnmatch('c{at,ub}s','cats')#=>false#{}isn'tsupportedbydefault

File.fnmatch('c{at,ub}s','cats',File::FNM_EXTGLOB)#=>true#{}issupportedonFNM_EXTGLOB

File.fnmatch('c?t','cat')#=>true#'?'matchonly1character

File.fnmatch('c??t','cat')#=>false#ditto

File.fnmatch('c*','cats')#=>true#'*'match0ormorecharacters

File.fnmatch('c*t','c/a/b/t')#=>true#ditto

File.fnmatch('ca[a-z]','cat')#=>true#inclusivebracketexpression

File.fnmatch('ca[^t]','cat')#=>false#exclusivebracketexpression('^'or'!')

File.fnmatch('cat','CAT')#=>false#casesensitive

File.fnmatch('cat','CAT',File::FNM_CASEFOLD)#=>true#caseinsensitive

File.fnmatch('?','/',File::FNM_PATHNAME)#=>false#wildcarddoesn'tmatch'/'onFNM_PATHNAME

File.fnmatch('*','/',File::FNM_PATHNAME)#=>false#ditto

File.fnmatch('[/]','/',File::FNM_PATHNAME)#=>false#ditto

File.fnmatch('\?','?')#=>true#escapedwildcardbecomesordinary

File.fnmatch('\a','a')#=>true#escapedordinaryremainsordinary

File.fnmatch('\a','\a',File::FNM_NOESCAPE)#=>true#FNM_NOESCAPEmakes'\'ordinary

File.fnmatch('[\?]','?')#=>true#canescapeinsidebracketexpression

File.fnmatch('*','.profile')#=>false#wildcarddoesn'tmatchleading

File.fnmatch('*','.profile',File::FNM_DOTMATCH)#=>true#periodbydefault.

File.fnmatch('.*','.profile')#=>true

rbfiles='**''/''*.rb'#youdon'thavetodolikethis.justwriteinsinglestring.

File.fnmatch(rbfiles,'main.rb')#=>false

File.fnmatch(rbfiles,'./main.rb')#=>false

File.fnmatch(rbfiles,'lib/song.rb')#=>true

File.fnmatch('**.rb','main.rb')#=>true

File.fnmatch('**.rb','./main.rb')#=>false

File.fnmatch('**.rb','lib/song.rb')#=>true

File.fnmatch('*','dave/.profile')

pattern='*''/''*'

File.fnmatch(pattern,'dave/.profile',File::FNM_PATHNAME

pattern='**''/''foo'

File.fnmatch(pattern,'a/b/c/foo',File::FNM_PATHNAME)

File.fnmatch(pattern,'/a/b/c/foo',File::FNM_PATHNAME

File.fnmatch(pattern,'c:/a/b/c/foo',File::FNM_PATHNAME

File.fnmatch(pattern,'a/.b/c/foo',File::FNM_PATHNAME

fnmatch(pattern,path,[flags])→(trueorfalse)fnmatch?(pattern,path,[flags])→(trueor

Returnstrueifpathmatchesagainstpattern.Thepatternisnotaregularexpression;insteaditfollowsrulessimilartoshellfilenameglobbing.Itmaycontainthefollowingmetacharacters:*

Matchesallfilesregularfiles

Matchesallfilesthathavecinthem(includingatthebeginningorend).

Tomatchhiddenfiles(thatstartwitha.settheFile::FNM_DOTMATCHflag.

Matchesdirectoriesrecursivelyorfilesexpansively.

false)

MatchespatternaandpatternbifFile::FNM_EXTGLOBflagisenabled.BehaveslikeaRegexpunion((?:a|b)).

flagsisabitwiseORoftheFNM_XXXconstants.ThesameglobpatternandflagsareusedbyDir.glob.

Examples:

File.fnmatch('cat','cat')#=>true#matchentirestring

File.fnmatch('cat','category')#=>false#onlymatchpartialstring

File.fnmatch('c{at,ub}s','cats')#=>false#{}isn'tsupportedbydefault

File.fnmatch('c{at,ub}s','cats',File::FNM_EXTGLOB)#=>true#{}issupportedonFNM_EXTGLOB

File.fnmatch('c?t','cat')#=>true#'?'matchonly1character

File.fnmatch('c??t','cat')#=>false#ditto

File.fnmatch('c*','cats')#=>true#'*'match0ormorecharacters

File.fnmatch('c*t','c/a/b/t')#=>true#ditto

File.fnmatch('ca[a-z]','cat')#=>true#inclusivebracketexpression

File.fnmatch('ca[^t]','cat')#=>false#exclusivebracketexpression('^'or'!')

File.fnmatch('cat','CAT')#=>false#casesensitive

File.fnmatch('cat','CAT',File::FNM_CASEFOLD)#=>true#caseinsensitive

File.fnmatch('?','/',File::FNM_PATHNAME)#=>false#wildcarddoesn'tmatch'/'onFNM_PATHNAME

File.fnmatch('*','/',File::FNM_PATHNAME)#=>false#ditto

File.fnmatch('[/]','/',File::FNM_PATHNAME)#=>false#ditto

File.fnmatch('\?','?')#=>true#escapedwildcardbecomesordinary

File.fnmatch('\a','a')#=>true#escapedordinaryremainsordinary

File.fnmatch('\a','\a',File::FNM_NOESCAPE)#=>true#FNM_NOESCAPEmakes'\'ordinary

File.fnmatch('[\?]','?')#=>true#canescapeinsidebracketexpression

File.fnmatch('*','.profile')#=>false#wildcarddoesn'tmatchleading

File.fnmatch('*','.profile',File::FNM_DOTMATCH)#=>true#periodbydefault.

File.fnmatch('.*','.profile')#=>true

rbfiles='**''/''*.rb'#youdon'thavetodolikethis.justwriteinsinglestring.

File.fnmatch(rbfiles,'main.rb')#=>false

File.fnmatch(rbfiles,'./main.rb')#=>false

File.fnmatch(rbfiles,'lib/song.rb')#=>true

File.fnmatch('**.rb','main.rb')#=>true

File.fnmatch('**.rb','./main.rb')#=>false

File.fnmatch('**.rb','lib/song.rb')#=>true

File.fnmatch('*','dave/.profile')

pattern='*''/''*'

File.fnmatch(pattern,'dave/.profile',File::FNM_PATHNAME

pattern='**''/''foo'

File.fnmatch(pattern,'a/b/c/foo',File::FNM_PATHNAME)

File.fnmatch(pattern,'/a/b/c/foo',File::FNM_PATHNAME

File.fnmatch(pattern,'c:/a/b/c/foo',File::FNM_PATHNAME

File.fnmatch(pattern,'a/.b/c/foo',File::FNM_PATHNAME

Identifiesthetypeofthenamedfile;thereturnstringisoneof“file'',“directory'',“characterSpecial'',“blockSpecial'',“fifo'',“link'',“socket'',or“unknown''.

File.ftype("testfile")#=>"file"

File.ftype("/dev/tty")#=>"characterSpecial"

File.ftype("/tmp/.X11-unix/X0")#=>"socket"

Returnstrueifthenamedfileexistsandtheeffectivegroupidofthecallingprocessistheownerofthefile.ReturnsfalseonWindows.

Returnstrueifthenamedfilesareidentical.

file_1andfile_2canbeanIOobject.

open("a","w"){}

pFile.identical?("a","a")#=>true

pFile.identical?("a","./a")#=>true

File.link("a","b")

ftype(file_name)→string

grpowned?(file_name)→trueorfalse

identical?(file_1,file_2)→trueorfalse

pFile.identical?("a","b")#=>true

File.symlink("a","c")

pFile.identical?("a","c")#=>true

open("d","w"){}

pFile.identical?("a","d")#=>false

ReturnsanewstringformedbyjoiningthestringsusingFile::SEPARATOR.

File.join("usr","mail","gumby")#=>"usr/mail/gumby"

EquivalenttoFile::chmod,butdoesnotfollowsymboliclinks(soitwillchangethepermissionsassociatedwiththelink,notthefilereferencedbythelink).Oftennotavailable.

EquivalenttoFile::chown,butdoesnotfollowsymboliclinks(soitwillchangetheownerassociatedwiththelink,notthefilereferencedbythelink).Oftennotavailable.Returnsnumberoffilesintheargumentlist.

Createsanewnameforanexistingfileusingahardlink.Willnotoverwritenew_nameifitalreadyexists(raisingasubclassofSystemCallError).Notavailableonallplatforms.

File.link("testfile",".testfile")#=>0

IO.readlines(".testfile")[0]#=>"Thisislineone\n"

join(string,...)→string

lchmod(mode_int,file_name,...)→integer

lchown(owner_int,group_int,file_name,..)→integer

link(old_name,new_name)→0

SameasFile::stat,butdoesnotfollowthelastsymboliclink.Instead,reportsonthelinkitself.

File.symlink("testfile","link2test")#=>0

File.stat("testfile").size#=>66

File.lstat("link2test").size#=>8

File.stat("link2test").size#=>66

ReturnsthemodificationtimeforthenamedfileasaTimeobject.

File.mtime("testfile")#=>TueApr0812:58:04CDT2003

OpensthefilenamedbyfilenameaccordingtothegivenmodeandreturnsanewFileobject.

SeeIO.newforadescriptionofmodeandopt.

Ifafileisbeingcreated,permissionbitsmaybegiveninperm.Thesemodeandpermissionbitsareplatformdependent;onUnixsystems,seeopen(2)andchmod(2)manpagesfordetails.

Examplesf=File.new("testfile","r")

f=File.new("newfile","w+")

f=File.new("newfile",File::CREAT|File::TRUNC|File::RDWR,0644)

lstat(file_name)→stat

mtime(file_name)→time

new(filename,mode="r"[,opt])→filenew(filename[,mode[,perm]][,opt])→file

Withnoassociatedblock,File.openisasynonymfor::new.Iftheoptionalcodeblockisgiven,itwillbepassedtheopenedfileasanargumentandtheFileobjectwillautomaticallybeclosedwhentheblockterminates.ThevalueoftheblockwillbereturnedfromFile.open.

Ifafileisbeingcreated,itsinitialpermissionsmaybesetusingthepermparameter.See::newforfurtherdiscussion.

SeeIO.newforadescriptionofthemodeandoptparameters.

Returnstrueifthenamedfileexistsandtheeffectiveusedidofthecallingprocessistheownerofthefile.

Returnsthestringrepresentationofthepath

File.path("/dev/null")#=>"/dev/null"

File.path(Pathname.new("/tmp"))#=>"/tmp"

open(filename,mode="r"[,opt])→fileopen(filename[,mode[,perm]][,opt])→fileopen(filename,mode="r"[,opt]){|file|block}→objopen(filename[,mode[,perm]][,opt]){|file|block}→obj

owned?(file_name)→trueorfalse

path(path)→string

pipe?(file_name)→trueorfalse

Returnstrueifthenamedfileisapipe.

Returnstrueifthenamedfileisreadablebytheeffectiveuseridofthisprocess.

Returnstrueifthenamedfileisreadablebytherealuseridofthisprocess.

Returnsthenameofthefilereferencedbythegivenlink.Notavailableonallplatforms.

File.readlink("link2test")#=>"testfile"

Returnsthereal(absolute)pathnameofpathnameintheactualfilesystem.Therealpathnamedoesn'tcontainsymlinksoruselessdots.

Ifdir_stringisgiven,itisusedasabasedirectoryforinterpretingrelativepathnameinsteadofthecurrentdirectory.

Thelastcomponentoftherealpathnamecanbenonexistent.

readable?(file_name)→trueorfalse

readable_real?(file_name)→trueorfalse

readlink(link_name)→file_name

realdirpath(pathname[,dir_string])→real_pathname

realpath(pathname[,dir_string])→

Returnsthereal(absolute)pathnameofpathnameintheactualfilesystemnotcontainingsymlinksoruselessdots.

Ifdir_stringisgiven,itisusedasabasedirectoryforinterpretingrelativepathnameinsteadofthecurrentdirectory.

Allcomponentsofthepathnamemustexistwhenthismethodiscalled.

Renamesthegivenfiletothenewname.RaisesaSystemCallErrorifthefilecannotberenamed.

File.rename("afile","afile.bak")#=>0

Returnstrueifthenamedfilehasthesetgidbitset.

Returnstrueifthenamedfilehasthesetuidbitset.

Returnsthesizeoffile_name.

Returnsniliffile_namedoesn'texistorhaszerosize,thesizeofthefileotherwise.

real_pathname

rename(old_name,new_name)→0

setgid?(file_name)→trueorfalse

setuid?(file_name)→trueorfalse

size(file_name)→integer

size?(file_name)→Integerornil

Returnstrueifthenamedfileisasocket.

Splitsthegivenstringintoadirectoryandafilecomponentandreturnstheminatwo-elementarray.SeealsoFile::dirnameandFile::basename.

File.split("/home/gumby/.profile")#=>["/home/gumby",".profile"]

ReturnsaFile::Statobjectforthenamedfile(seeFile::Stat).

File.stat("testfile").mtime#=>TueApr0812:58:04CDT2003

Returnstrueifthenamedfilehasthestickybitset.

Createsasymboliclinkcallednew_namefortheexistingfileold_name.RaisesaNotImplementedexceptiononplatformsthatdonotsupportsymboliclinks.

socket?(file_name)→trueorfalse

split(file_name)→array

stat(file_name)→stat

sticky?(file_name)→trueorfalse

symlink(old_name,new_name)→0

symlink?(file_name)→trueorfalse

Returnstrueifthenamedfileisasymboliclink.

Truncatesthefilefile_nametobeatmostintegerbyteslong.Notavailableonallplatforms.

f=File.new("out","w")

f.write("1234567890")#=>10

f.close#=>nil

File.truncate("out",5)#=>0

File.size("out")#=>5

Returnsthecurrentumaskvalueforthisprocess.Iftheoptionalargumentisgiven,settheumasktothatvalueandreturnthepreviousvalue.Umaskvaluesaresubtractedfromthedefaultpermissions,soaumaskof0222wouldmakeafileread-onlyforeveryone.

File.umask(0006)#=>18

File.umask#=>6

Deletesthenamedfiles,returningthenumberofnamespassedasarguments.Raisesanexceptiononanyerror.SeealsoDir::rmdir.

Setstheaccessandmodificationtimesofeachnamedfiletothefirsttwoarguments.Returnsthenumberoffilenamesintheargumentlist.

truncate(file_name,integer)→0

umask()→integerumask(integer)→integer

delete(file_name,...)→integerunlink(file_name,...)→integer

utime(atime,mtime,file_name,...)→integer

Iffile_nameisreadablebyothers,returnsanintegerrepresentingthefilepermissionbitsoffile_name.Returnsnilotherwise.Themeaningofthebitsisplatformdependent;onUnixsystems,seestat(2).

File.world_readable?("/etc/passwd")#=>420

m=File.world_readable?("/etc/passwd")

sprintf("%o",m)#=>"644"

Iffile_nameiswritablebyothers,returnsanintegerrepresentingthefilepermissionbitsoffile_name.Returnsnilotherwise.Themeaningofthebitsisplatformdependent;onUnixsystems,seestat(2).

File.world_writable?("/tmp")#=>511

m=File.world_writable?("/tmp")

sprintf("%o",m)#=>"777"

Returnstrueifthenamedfileiswritablebytheeffectiveuseridofthisprocess.

Returnstrueifthenamedfileiswritablebytherealuseridofthisprocess.

world_readable?(file_name)→fixnumornil

world_writable?(file_name)→fixnumornil

writable?(file_name)→trueorfalse

writable_real?(file_name)→trueorfalse

Returnstrueifthenamedfileexistsandhasazerosize.

Returnsthelastaccesstime(aTimeobject)

for<i>file</i>,orepochif<i>file</>hasnotbeenaccessed

File.new("testfile").atime#=>WedDec3118:00:00CST1969

Returnsthebirthtimeforfile.

File.new("testfile").birthtime#=>WedApr0908:53:14CDT2003

Changespermissionbitsonfiletothebitpatternrepresentedbymode_int.Actualeffectsareplatformdependent;onUnixsystems,seechmod(2)fordetails.Followssymboliclinks.AlsoseeFile#lchmod.

f=File.new("out","w");

f.chmod(0644)#=>0

zero?(file_name)→trueorfalse

atime→time

birthtime→time

chmod(mode_int)→0

Changestheownerandgroupoffiletothegivennumericownerandgroupid's.Onlyaprocesswithsuperuserprivilegesmaychangetheownerofafile.Thecurrentownerofafilemaychangethefile'sgrouptoanygrouptowhichtheownerbelongs.Anilor-1ownerorgroupidisignored.Followssymboliclinks.SeealsoFile#lchown.

File.new("testfile").chown(502,1000)

Returnsthechangetimeforfile(thatis,thetimedirectoryinformationaboutthefilewaschanged,notthefileitself).

File.new("testfile").ctime#=>WedApr0908:53:14CDT2003

Locksorunlocksafileaccordingtolocking_constant(alogicalorofthevaluesinthetablebelow).ReturnsfalseifFile::LOCK_NBisspecifiedandtheoperationwouldotherwisehaveblocked.Notavailableonallplatforms.

Lockingconstants(inclassFile):

LOCK_EX|Exclusivelock.Onlyoneprocessmayholdan

|exclusivelockforagivenfileatatime.

----------+------------------------------------------------

LOCK_NB|Don'tblockwhenlocking.Maybecombined

|withotherlockoptionsusinglogicalor.

----------+------------------------------------------------

LOCK_SH|Sharedlock.Multipleprocessesmayeachholda

chown(owner_int,group_int)→0

ctime→time

flock(locking_constant)→0orfalse

|sharedlockforagivenfileatthesametime.

----------+------------------------------------------------

LOCK_UN|Unlock.

Example:

#updateacounterusingwritelock

#don'tuse"w"becauseittruncatesthefilebeforelock.

File.open("counter",File::RDWR|File::CREAT,0644){|f

f.flock(File::LOCK_EX)

value=f.read.to_i+1

f.rewind

f.write("#{value}\n")

f.flush

f.truncate(f.pos)

#readthecounterusingreadlock

File.open("counter","r"){|f|

f.flock(File::LOCK_SH)

pf.read

SameasIO#stat,butdoesnotfollowthelastsymboliclink.Instead,reportsonthelinkitself.

f=File.new("link2test")

f.lstat.size#=>8

f.stat.size#=>66

Returnsthemodificationtimeforfile.

File.new("testfile").mtime#=>WedApr0908:53:14CDT2003

lstat→stat

mtime→time

Returnsthepathnameusedtocreatefileasastring.Doesnotnormalizethename.

File.new("testfile").path#=>"testfile"

File.new("/tmp/../tmp/xxx","w").path#=>"/tmp/../tmp/xxx"

Returnsthesizeoffileinbytes.

File.new("testfile").size#=>66

Returnsthepathnameusedtocreatefileasastring.Doesnotnormalizethename.

File.new("testfile").path#=>"testfile"

File.new("/tmp/../tmp/xxx","w").path#=>"/tmp/../tmp/xxx"

Truncatesfiletoatmostintegerbytes.Thefilemustbeopenedforwriting.Notavailableonallplatforms.

f.syswrite("1234567890")#=>10

f.truncate(5)#=>0

f.close()#=>nil

File.size("out")#=>5

path→filenameto_path→filename

size→integer

path→filenameto_path→filename

truncate(integer)→0

moduleFile::ConstantsFile::Constantsprovidesfile-relatedconstants.Allpossiblefileconstantsarelistedinthedocumentationbuttheymaynotallbepresentonyourplatform.

Iftheunderlyingplatformdoesn'tdefineaconstantthecorrespondingRubyconstantisnotdefined.

Yourplatformdocumentations(e.g.manopen(2))maydescribemoredetailedinformation.

InFilesdir.c

Constants

APPEND

appendoneachwrite

BINARY

disablelinecodeconversion

createfileifitdoesnotexist

DIRECT

TrytominimizecacheeffectsoftheI/Otoandfromthisfile.

anywriteoperationperformsynchronouslyexceptsomemetadata

errorifCREATandthefileexists

LOCK_EX

exclusivelock.seeFile#flock

LOCK_NB

non-blockinglock.usedwithLOCK_SHorLOCK_EX.seeFile#flock

LOCK_SH

sharedlock.seeFile#flock

LOCK_UN

unlock.seeFile#flock

NOATIME

donotchangeatime

NOCTTY

nottomakeopenedIOthecontrollingterminaldevice

NOFOLLOW

donotfollowsymlinks

NONBLOCK

donotblockonopenorfordatatobecomeavailable

Nameofthenulldevice

RDONLY

openforreadingonly

openforreadingandwriting

anyreadoperationperformsynchronously.usedwithSYNCorDSYNC.

anywriteoperationperformsynchronously

truncatesizeto0

WRONLY

openforwritingonly

classFile::StatObjectsofclassFile::StatencapsulatecommonstatusinformationforFileobjects.TheinformationisrecordedatthemomenttheFile::Statobjectiscreated;changesmadetothefileafterthatpointwillnotbereflected.File::StatobjectsarereturnedbyIO#stat,File::stat,File#lstat,andFile::lstat.Manyofthesemethodsreturnplatform-specificvalues,andnotallvaluesaremeaningfulonallsystems.SeealsoKernel#test.

InFilesdir.c

ParentObject

IncludedModulesComparable

PublicClassMethods

CreateaFile::Statobjectforthegivenfilename(raisinganexceptionifthefiledoesn'texist).

File::Stat.new(file_name)→stat

ComparesFile::Statobjectsbycomparingtheirrespectivemodificationtimes.

nilisreturnedifother_statisnotaFile::Statobject

f1=File.new("f1","w")

sleep1

f2=File.new("f2","w")

f1.stat<=>f2.stat#=>-1

ReturnsthelastaccesstimeforthisfileasanobjectofclassTime.

File.stat("testfile").atime#=>WedDec3118:00:00CST1969

Returnsthebirthtimeforstat.Iftheplatformdoesn'thavebirthtime,returnsctime.

File.write("testfile","foo")

sleep10

File.write("testfile","bar")

sleep10

File.chmod(0644,"testfile")

sleep10

File.read("testfile")

File.stat("testfile").birthtime#=>2014-02-2411:19:17+0900

File.stat("testfile").mtime#=>2014-02-2411:19:27+0900

File.stat("testfile").ctime#=>2014-02-2411:19:37+0900

File.stat("testfile").atime#=>2014-02-2411:19:47+0900

stat<=>other_stat→-1,0,1,nil

atime→time

birthtime→aTime

Returnsthenativefilesystem'sblocksize.Willreturnnilonplatformsthatdon'tsupportthisinformation.

File.stat("testfile").blksize#=>4096

Returnstrueifthefileisablockdevice,falseifitisn'toriftheoperatingsystemdoesn'tsupportthisfeature.

File.stat("testfile").blockdev?#=>false

File.stat("/dev/hda1").blockdev?#=>true

Returnsthenumberofnativefilesystemblocksallocatedforthisfile,orniliftheoperatingsystemdoesn'tsupportthisfeature.

File.stat("testfile").blocks#=>2

Returnstrueifthefileisacharacterdevice,falseifitisn'toriftheoperatingsystemdoesn'tsupportthisfeature.

File.stat("/dev/tty").chardev?#=>true

Returnsthechangetimeforstat(thatis,thetimedirectoryinformationaboutthefilewaschanged,notthefileitself).

blksize→integerornil

blockdev?→trueorfalse

blocks→integerornil

chardev?→trueorfalse

ctime→aTime

File.stat("testfile").ctime#=>WedApr0908:53:14CDT2003

Returnsanintegerrepresentingthedeviceonwhichstatresides.

File.stat("testfile").dev#=>774

ReturnsthemajorpartofFile_Stat#devornil.

File.stat("/dev/fd1").dev_major#=>2

File.stat("/dev/tty").dev_major#=>5

ReturnstheminorpartofFile_Stat#devornil.

File.stat("/dev/fd1").dev_minor#=>1

File.stat("/dev/tty").dev_minor#=>0

dev→fixnum

dev_major→fixnum

dev_minor→fixnum

executable?→trueorfalse

Returnstrueifstatisexecutableoriftheoperatingsystemdoesn'tdistinguishexecutablefilesfromnonexecutablefiles.Thetestsaremadeusingtheeffectiveowneroftheprocess.

File.stat("testfile").executable?#=>false

Sameasexecutable?,buttestsusingtherealowneroftheprocess.

Returnstrueifstatisaregularfile(notadevicefile,pipe,socket,etc.).

File.stat("testfile").file?#=>true

Identifiesthetypeofstat.Thereturnstringisoneof:“file'',“directory'',“characterSpecial'',“blockSpecial'',“fifo'',“link'',“socket'',or“unknown''.

File.stat("/dev/tty").ftype#=>"characterSpecial"

Returnsthenumericgroupidoftheownerofstat.

File.stat("testfile").gid#=>500

Returnstrueiftheeffectivegroupidoftheprocessisthesameasthegroupidofstat.OnWindowsNT,

executable_real?→trueorfalse

file?→trueorfalse

ftype→string

gid→fixnum

grpowned?→trueorfalse

returnsfalse.

File.stat("testfile").grpowned?#=>true

File.stat("/etc/passwd").grpowned?#=>false

Returnstheinodenumberforstat.

File.stat("testfile").ino#=>1083669

Produceanicelyformatteddescriptionofstat.

File.stat("/etc/passwd").inspect

#=>"#<File::Statdev=0xe000005,ino=1078078,mode=0100644,

#nlink=1,uid=0,gid=0,rdev=0x0,size=1374,blksize=4096,

#blocks=8,atime=WedDec1010:16:12CST2003,

#mtime=FriSep1215:41:41CDT2003,

#ctime=MonOct2711:20:27CST2003,

#birthtime=MonAug0408:13:49CDT2003>"

Returnsanintegerrepresentingthepermissionbitsofstat.Themeaningofthebitsisplatformdependent;onUnixsystems,seestat(2).

File.chmod(0644,"testfile")#=>1

s=File.stat("testfile")

sprintf("%o",s.mode)#=>"100644"

Returnsthemodificationtimeofstat.

File.stat("testfile").mtime#=>WedApr0908:53:14CDT2003

ino→fixnum

inspect→string

mode→fixnum

mtime→aTime

Returnsthenumberofhardlinkstostat.

File.stat("testfile").nlink#=>1

File.link("testfile","testfile.bak")#=>0

File.stat("testfile").nlink#=>2

Returnstrueiftheeffectiveuseridoftheprocessisthesameastheownerofstat.

File.stat("testfile").owned?#=>true

File.stat("/etc/passwd").owned?#=>false

Returnstrueiftheoperatingsystemsupportspipesandstatisapipe;falseotherwise.

Returnsanintegerrepresentingthedevicetypeonwhichstatresides.Returnsniliftheoperatingsystemdoesn'tsupportthisfeature.

File.stat("/dev/fd1").rdev#=>513

File.stat("/dev/tty").rdev#=>1280

ReturnsthemajorpartofFile_Stat#rdevornil.

File.stat("/dev/fd1").rdev_major#=>2

File.stat("/dev/tty").rdev_major#=>5

nlink→fixnum

owned?→trueorfalse

pipe?→trueorfalse

rdev→fixnumornil

rdev_major→fixnum

rdev_minor→fixnum

ReturnstheminorpartofFile_Stat#rdevornil.

File.stat("/dev/fd1").rdev_minor#=>1

File.stat("/dev/tty").rdev_minor#=>0

Returnstrueifstatisreadablebytheeffectiveuseridofthisprocess.

File.stat("testfile").readable?#=>true

Returnstrueifstatisreadablebytherealuseridofthisprocess.

File.stat("testfile").readable_real?#=>true

Returnstrueifstathastheset-group-idpermissionbitset,falseifitdoesn'toriftheoperatingsystemdoesn'tsupportthisfeature.

File.stat("/usr/sbin/lpc").setgid?#=>true

Returnstrueifstathastheset-user-idpermissionbitset,falseifitdoesn'toriftheoperatingsystemdoesn'tsupportthisfeature.

File.stat("/bin/su").setuid?#=>true

Returnsthesizeofstatinbytes.

readable?→trueorfalse

readable_real?→trueorfalse

setgid?→trueorfalse

setuid?→trueorfalse

size→fixnum

Returnsthesizeofstatinbytes.

Returnstrueifstatisasocket,falseifitisn'toriftheoperatingsystemdoesn'tsupportthisfeature.

File.stat("testfile").socket?#=>false

Returnstrueifstathasitsstickybitset,falseifitdoesn'toriftheoperatingsystemdoesn'tsupportthisfeature.

File.stat("testfile").sticky?#=>false

Returnstrueifstatisasymboliclink,falseifitisn'toriftheoperatingsystemdoesn'tsupportthisfeature.AsFile::statautomaticallyfollowssymboliclinks,symlink?willalwaysbefalseforanobjectreturnedbyFile::stat.

File.symlink("testfile","alink")#=>0

File.stat("alink").symlink?#=>false

File.lstat("alink").symlink?#=>true

size→integer

socket?→trueorfalse

sticky?→trueorfalse

symlink?→trueorfalse

uid→fixnum

Returnsthenumericuseridoftheownerofstat.

File.stat("testfile").uid#=>501

Ifstatisreadablebyothers,returnsanintegerrepresentingthefilepermissionbitsofstat.Returnsnilotherwise.Themeaningofthebitsisplatformdependent;onUnixsystems,seestat(2).

m=File.stat("/etc/passwd").world_readable?#=>420

sprintf("%o",m)#=>"644"

Ifstatiswritablebyothers,returnsanintegerrepresentingthefilepermissionbitsofstat.Returnsnilotherwise.Themeaningofthebitsisplatformdependent;onUnixsystems,seestat(2).

m=File.stat("/tmp").world_writable?#=>511

sprintf("%o",m)#=>"777"

Returnstrueifstatiswritablebytheeffectiveuseridofthisprocess.

File.stat("testfile").writable?#=>true

Returnstrueifstatiswritablebytherealuseridofthisprocess.

File.stat("testfile").writable_real?#=>true

world_readable?→fixnumornil

world_writable?→fixnumornil

writable?→trueorfalse

writable_real?→trueorfalse

Returnstrueifstatisazero-lengthfile;falseotherwise.

File.stat("testfile").zero?#=>false

zero?→trueorfalse

moduleFileTestFileTestimplementsfiletestoperationssimilartothoseusedinFile::Stat.Itexistsasastandalonemodule,anditsmethodsarealsoinsinuatedintotheFileclass.(Notethatthisisnotdonebyinclusion:theinterpretercheats).

InFilesfile.c

Returnstrueifthenamedfileisablockdevice.

Returnstrueifthenamedfileisacharacterdevice.

blockdev?(file_name)→trueorfalse

chardev?(file_name)→trueorfalse

Returnstrueifthenamedfileisexecutablebytheeffectiveuseridofthisprocess.

Returnstrueifthenamedfileisexecutablebytherealuseridofthisprocess.

Returntrueifthenamedfileexists.

“fileexists”meansthatstat()orfstat()systemcallissuccessful.

Returnstrueifthenamedfileexistsandisaregularfile.

filecanbeanIOobject.

Ifthefileargumentisasymboliclink,itwillresolvethesymboliclinkandusethefilereferencedbythelink.

Returnstrueifthenamedfileexistsandtheeffective

executable?(file_name)→trueorfalse

executable_real?(file_name)→trueorfalse

file?(file)→trueorfalse

grpowned?(file_name)→trueorfalse

groupidofthecallingprocessistheownerofthefile.ReturnsfalseonWindows.

Returnstrueifthenamedfilesareidentical.

file_1andfile_2canbeanIOobject.

open("a","w"){}

pFile.identical?("a","a")#=>true

pFile.identical?("a","./a")#=>true

File.link("a","b")

pFile.identical?("a","b")#=>true

File.symlink("a","c")

pFile.identical?("a","c")#=>true

open("d","w"){}

pFile.identical?("a","d")#=>false

Returnstrueifthenamedfileexistsandtheeffectiveusedidofthecallingprocessistheownerofthefile.

Returnstrueifthenamedfileisapipe.

Returnstrueifthenamedfileisreadablebytheeffectiveuseridofthisprocess.

identical?(file_1,file_2)→trueorfalse

owned?(file_name)→trueorfalse

pipe?(file_name)→trueorfalse

readable?(file_name)→trueorfalse

readable_real?(file_name)→trueorfalse

Returnstrueifthenamedfileisreadablebytherealuseridofthisprocess.

Returnstrueifthenamedfilehasthesetgidbitset.

Returnstrueifthenamedfilehasthesetuidbitset.

Returnsthesizeoffile_name.

Returnsniliffile_namedoesn'texistorhaszerosize,thesizeofthefileotherwise.

Returnstrueifthenamedfileisasocket.

Returnstrueifthenamedfilehasthestickybitset.

Returnstrueifthenamedfileisasymboliclink.

setgid?(file_name)→trueorfalse

setuid?(file_name)→trueorfalse

size(file_name)→integer

size?(file_name)→Integerornil

socket?(file_name)→trueorfalse

sticky?(file_name)→trueorfalse

symlink?(file_name)→trueorfalse

Iffile_nameisreadablebyothers,returnsanintegerrepresentingthefilepermissionbitsoffile_name.Returnsnilotherwise.Themeaningofthebitsisplatformdependent;onUnixsystems,seestat(2).

File.world_readable?("/etc/passwd")#=>420

m=File.world_readable?("/etc/passwd")

sprintf("%o",m)#=>"644"

Iffile_nameiswritablebyothers,returnsanintegerrepresentingthefilepermissionbitsoffile_name.Returnsnilotherwise.Themeaningofthebitsisplatformdependent;onUnixsystems,seestat(2).

File.world_writable?("/tmp")#=>511

m=File.world_writable?("/tmp")

sprintf("%o",m)#=>"777"

Returnstrueifthenamedfileiswritablebytheeffectiveuseridofthisprocess.

Returnstrueifthenamedfileiswritablebytherealuseridofthisprocess.

world_readable?(file_name)→fixnumornil

world_writable?(file_name)→fixnumornil

writable?(file_name)→trueorfalse

writable_real?(file_name)→trueorfalse

zero?(file_name)→trueorfalse

Returnstrueifthenamedfileexistsandhasazerosize.

classFixnumHoldsIntegervaluesthatcanberepresentedinanativemachineword(minus1bit).IfanyoperationonaFixnumexceedsthisrange,thevalueisautomaticallyconvertedtoaBignum.

Fixnumobjectshaveimmediatevalue.Thismeansthatwhentheyareassignedorpassedasparameters,theactualobjectispassed,ratherthanareferencetothatobject.

AssignmentdoesnotaliasFixnumobjects.ThereiseffectivelyonlyoneFixnumobjectinstanceforanygivenintegervalue,so,forexample,youcannotaddasingletonmethodtoaFixnum.AnyattempttoaddasingletonmethodtoaFixnumobjectwillraiseaTypeError.

InFilesnumeric.c

ParentInteger

Returnsfixmoduloother.

SeeNumeric#divmodformoreinformation.

BitwiseAND.

Performsmultiplication:theclassoftheresultingobjectdependsontheclassofnumericandonthemagnitudeoftheresult.ItmayreturnaBignum.

Raisesfixtothepowerofnumeric,whichmaybenegativeorfractional.

2**3#=>8

2**-1#=>(1/2)

2**0.5#=>1.4142135623731

Performsaddition:theclassoftheresultingobjectdependsontheclassofnumericandonthemagnitudeoftheresult.ItmayreturnaBignum.

Performssubtraction:theclassoftheresultingobjectdependsontheclassofnumericandonthemagnitudeoftheresult.ItmayreturnaBignum.

fix%other→realmodulo(other)→real

fix&integer→integer_result

fix*numeric→numeric_result

fix**numeric→numeric_result

fix+numeric→numeric_result

fix-numeric→numeric_result

Negatesfix,whichmayreturnaBignum.

Performsdivision:theclassoftheresultingobjectdependsontheclassofnumericandonthemagnitudeoftheresult.ItmayreturnaBignum.

Returnstrueifthevalueoffixislessthanthatofreal.

Shiftsfixleftcountpositions,orrightifcountisnegative.

Returnstrueifthevalueoffixislessthanorequaltothatofreal.

Comparison—Returns-1,0,+1ornildependingonwhetherfixislessthan,equalto,orgreaterthannumeric.

ThisisthebasisforthetestsintheComparablemodule.

-fix→integer

fix/numeric→numeric_result

fix<real→trueorfalse

fix<<count→integer

fix<=real→trueorfalse

fix<=>numeric→-1,0,+1ornil

fix==other→trueorfalse

Returntrueiffixequalsothernumerically.

1==2#=>false

1==1.0#=>true

Returntrueiffixequalsothernumerically.

1==2#=>false

1==1.0#=>true

Returnstrueifthevalueoffixisgreaterthanthatofreal.

Returnstrueifthevalueoffixisgreaterthanorequaltothatofreal.

Shiftsfixrightcountpositions,orleftifcountisnegative.

BitReference—Returnsthe+n+thbitinthebinaryrepresentationoffix,wherefix[0]istheleastsignificantbit.

Forexample:

a=0b11001100101010

30.downto(0)do|n|printa[n]end

#=>0000000000000000011001100101010

fix==other→trueorfalse

fix>real→trueorfalse

fix>=real→trueorfalse

fix>>count→integer

fix[n]→0,1

BitwiseEXCLUSIVEOR.

Returnstheabsolutevalueoffix.

-12345.abs#=>12345

12345.abs#=>12345

Returnsthenumberofbitsofthevalueofint.

“thenumberofbits”meansthatthebitpositionofthehighestbitwhichisdifferenttothesignbit.(Thebitpositionofthebit2**nisn+1.)Ifthereisnosuchbit(zeroorminusone),zeroisreturned.

I.e.Thismethodreturnsceil(log2(int<0?-int:int+1)).

(-2**12-1).bit_length#=>13

(-2**12).bit_length#=>12

(-2**12+1).bit_length#=>12

-0x101.bit_length#=>9

-0x100.bit_length#=>8

-0xff.bit_length#=>8

-2.bit_length#=>1

-1.bit_length#=>0

0.bit_length#=>0

1.bit_length#=>1

0xff.bit_length#=>8

0x100.bit_length#=>9

(2**12-1).bit_length#=>12

(2**12).bit_length#=>13

(2**12+1).bit_length#=>13

ThismethodcanbeusedtodetectoverflowinArray#packasfollows.

fix^integer→integer_result

abs→integermagnitude→integer

bit_length→integer

ifn.bit_length<32

[n].pack("l")#nooverflow

raise"overflow"

Performsintegerdivision:returnsintegerresultofdividingfixbynumeric.

SeeNumeric#divmod.

Returnstrueiffixisanevennumber.

Returnsthefloatingpointresultofdividingfixbynumeric.

654321.fdiv(13731)#=>47.6528293642124

654321.fdiv(13731.24)#=>47.6519964693647

Aliasfor:to_s

Returnstheabsolutevalueoffix.

-12345.abs#=>12345

12345.abs#=>12345

div(numeric)→integer

even?→trueorfalse

inspect(p1=v1)

abs→integermagnitude→integer

Returnsfixmoduloother.

SeeNumeric#divmodformoreinformation.

Returnstrueiffixisanoddnumber.

Returnsthenumberofbytesinthemachinerepresentationoffix.

1.size#=>4

-1.size#=>4

2147483647.size#=>4

ReturnstheIntegerequaltoint+1.

1.next#=>2

(-1).next#=>0

ConvertsfixtoaFloat.

Returnsastringcontainingtherepresentationoffixradixbase(between2and36).

12345.to_s#=>"12345"

fix%other→realmodulo(other)→real

odd?→trueorfalse

size→fixnum

next→integersucc→integer

to_f→float

to_s(base=10)→string

12345.to_s(2)#=>"11000000111001"

12345.to_s(8)#=>"30071"

12345.to_s(10)#=>"12345"

12345.to_s(16)#=>"3039"

12345.to_s(36)#=>"9ix"

Returnstrueiffixiszero.

BitwiseOR.

One'scomplement:returnsanumberwhereeachbitisflipped.

zero?→trueorfalse

fix|integer→integer_result

~fix→integer

classFloatFloatobjectsrepresentinexactrealnumbersusingthenativearchitecture'sdouble-precisionfloatingpointrepresentation.

Floatingpointhasadifferentarithmeticandisaninexactnumber.Soyoushouldknowitsesotericsystem.seefollowing:

docs.sun.com/source/806-3568/ncg_goldberg.htmlwiki.github.com/rdp/ruby_tutorials_core/ruby-talk-faq#wiki-floats_impreciseen.wikipedia.org/wiki/Floating_point#Accuracy_problems

InFilescomplex.cnumeric.crational.c

ParentNumeric

Constants

Theminimumnumberofsignificantdecimaldigitsinadouble-precisionfloatingpoint.

Usuallydefaultsto15.

EPSILON

Thedifferencebetween1andthesmallestdouble-precisionfloatingpointnumbergreaterthan1.

Usuallydefaultsto2.2204460492503131e-16.

INFINITY

Anexpressionrepresentingpositiveinfinity.

MANT_DIG

Thenumberofbasedigitsforthedoubledatatype.

Thelargestpossibleintegerinadouble-precisionfloatingpointnumber.

Usuallydefaultsto1.7976931348623157e+308.

MAX_10_EXP

Thelargestpositiveexponentinadouble-precisionfloatingpointwhere10raisedtothispowerminus1.

MAX_EXP

Thelargestpossibleexponentvalueinadouble-precisionfloatingpoint.

MIN.0.0.next_floatreturnsthesmallestpositivefloatingpointnumberincludingdenormalizednumbers.

MIN_10_EXP

Thesmallestnegativeexponentinadouble-precisionfloatingpointwhere10raisedtothispowerminus1.

Usuallydefaultsto-307.

MIN_EXP

Thesmallestposableexponentvalueinadouble-precisionfloatingpoint.

Usuallydefaultsto-1021.

Anexpressionrepresentingavaluewhichis“notanumber”.

Thebaseofthefloatingpoint,ornumberofuniquedigitsusedtorepresentthenumber.

Usuallydefaultsto2onmostsystems,whichwouldrepresentabase-10decimal.

ROUNDS

Roundingtowardsnegativeinfinity

Returnthemoduloafterdivisionoffloatbyother.

6543.21.modulo(137)#=>104.21

6543.21.modulo(137.24)#=>92.9299999999996

Returnsanewfloatwhichistheproductoffloatandother.

Raisesfloattothepowerofother.

2.0**3#=>8.0

Returnsanewfloatwhichisthesumoffloatandother.

Returnsanewfloatwhichisthedifferenceoffloatandother.

Returnsfloat,negated.

float%other→floatmodulo(other)→float

float*other→float

float**other→float

float+other→float

float-other→float

-float→float

float/other→float

Returnsanewfloatwhichistheresultofdividingfloatbyother.

Returnstrueiffloatislessthanreal.

TheresultofNaN<NaNisundefined,sotheimplementation-dependentvalueisreturned.

Returnstrueiffloatislessthanorequaltoreal.

TheresultofNaN<=NaNisundefined,sotheimplementation-dependentvalueisreturned.

Returns-1,0,+1ornildependingonwhetherfloatislessthan,equalto,orgreaterthanreal.ThisisthebasisforthetestsinComparable.

TheresultofNaN<=>NaNisundefined,sotheimplementation-dependentvalueisreturned.

Returnstrueonlyifobjhasthesamevalueasfloat.Contrastthiswith#eql?,whichrequiresobjtobeaFloat.

TheresultofNaN==NaNisundefined,sotheimplementation-dependentvalueisreturned.

1.0==1#=>true

float<real→trueorfalse

float<=real→trueorfalse

float<=>real→-1,0,+1ornil

float==obj→trueorfalse

Returnstrueonlyifobjhasthesamevalueasfloat.Contrastthiswith#eql?,whichrequiresobjtobeaFloat.

TheresultofNaN==NaNisundefined,sotheimplementation-dependentvalueisreturned.

1.0==1#=>true

Returnstrueiffloatisgreaterthanreal.

TheresultofNaN>NaNisundefined,sotheimplementation-dependentvalueisreturned.

Returnstrueiffloatisgreaterthanorequaltoreal.

TheresultofNaN>=NaNisundefined,sotheimplementation-dependentvalueisreturned.

Returnstheabsolutevalueoffloat.

(-34.56).abs#=>34.56

-34.56.abs#=>34.56

Returns0ifthevalueispositive,piotherwise.

float==obj→trueorfalse

float>real→trueorfalse

float>=real→trueorfalse

abs→floatmagnitude→float

arg→0orfloatangle→0orfloatphase→0orfloat

ReturnsthesmallestIntegergreaterthanorequaltofloat.

1.2.ceil#=>2

2.0.ceil#=>2

(-1.2).ceil#=>-1

(-2.0).ceil#=>-2

ReturnsanarraywithbothanumericandafloatrepresentedasFloatobjects.

ThisisachievedbyconvertinganumerictoaFloat.

1.2.coerce(3)#=>[3.0,1.2]

2.5.coerce(1.1)#=>[1.1,2.5]

Returnsthedenominator(alwayspositive).Theresultismachinedependent.

Seenumerator.

SeeNumeric#divmod.

42.0.divmod6#=>[7,0.0]

42.0.divmod5#=>[8,2.0]

ceil→integer

ReturnstrueonlyifobjisaFloatwiththesamevalueasfloat.ContrastthiswithFloat#==,whichperformstypeconversions.

TheresultofNaN.eql?(NaN)isundefined,sotheimplementation-dependentvalueisreturned.

1.0.eql?(1)#=>false

Returnsfloat/numeric,sameasFloat#/.

ReturnstrueiffloatisavalidIEEEfloatingpointnumber(itisnotinfinite,and#nan?isfalse).

Returnsthelargestintegerlessthanorequaltofloat.

1.2.floor#=>1

2.0.floor#=>2

(-1.2).floor#=>-2

(-2.0).floor#=>-2

Returnsahashcodeforthisfloat.

SeealsoObject#hash.

fdiv(numeric)→floatquo(numeric)→float

finite?→trueorfalse

floor→integer

hash→integer

infinite?→nil,-1,+1

Returnvaluescorrespondingtothevalueoffloat:finite

-Infinity

+Infinity1

Forexample:

(0.0).infinite?#=>nil

(-1.0/0.0).infinite?#=>-1

(+1.0/0.0).infinite?#=>1

Aliasfor:to_s

Returnstheabsolutevalueoffloat.

(-34.56).abs#=>34.56

-34.56.abs#=>34.56

Returnthemoduloafterdivisionoffloatbyother.

6543.21.modulo(137)#=>104.21

6543.21.modulo(137.24)#=>92.9299999999996

ReturnstrueiffloatisaninvalidIEEEfloatingpoint

inspect()

abs→floatmagnitude→float

float%other→floatmodulo(other)→float

nan?→trueorfalse

number.

a=-1.0#=>-1.0

a.nan?#=>false

a=0.0/0.0#=>NaN

a.nan?#=>true

Returnsthenextrepresentablefloating-pointnumber.

Float::MAX.next_floatandFloat::INFINITY.next_floatisFloat::INFINITY.

Float::NAN.next_floatisFloat::NAN.

Forexample:

p0.01.next_float#=>0.010000000000000002

p1.0.next_float#=>1.0000000000000002

p100.0.next_float#=>100.00000000000001

p0.01.next_float-0.01#=>1.734723475976807e-18

p1.0.next_float-1.0#=>2.220446049250313e-16

p100.0.next_float-100.0#=>1.4210854715202004e-14

f=0.01;20.times{printf"%-20a%s\n",f,f.to_s;f

#=>0x1.47ae147ae147bp-70.01

#0x1.47ae147ae147cp-70.010000000000000002

#0x1.47ae147ae147dp-70.010000000000000004

#0x1.47ae147ae147ep-70.010000000000000005

#0x1.47ae147ae147fp-70.010000000000000007

#0x1.47ae147ae148p-70.010000000000000009

#0x1.47ae147ae1481p-70.01000000000000001

#0x1.47ae147ae1482p-70.010000000000000012

#0x1.47ae147ae1483p-70.010000000000000014

#0x1.47ae147ae1484p-70.010000000000000016

#0x1.47ae147ae1485p-70.010000000000000018

#0x1.47ae147ae1486p-70.01000000000000002

#0x1.47ae147ae1487p-70.010000000000000021

#0x1.47ae147ae1488p-70.010000000000000023

#0x1.47ae147ae1489p-70.010000000000000024

#0x1.47ae147ae148ap-70.010000000000000026

#0x1.47ae147ae148bp-70.010000000000000028

#0x1.47ae147ae148cp-70.01000000000000003

#0x1.47ae147ae148dp-70.010000000000000031

next_float→float

#0x1.47ae147ae148ep-70.010000000000000033

100.times{f+=0.1}

pf#=>9.99999999999998#shouldbe10.0intheidealworld.

p10-f#=>1.9539925233402755e-14#thefloating-pointerror.

p(10.0.next_float-10)#=>1.7763568394002505e-15#1ulp(unitsinthelastplace).

p((10-f)/(10.0.next_float-10))#=>11.0#theerroris11ulp.

p((10-f)/(10*Float::EPSILON))#=>8.8#approximationoftheabove.

p"%a"%f#=>"0x1.3fffffffffff5p+3"#thelasthexdigitis5.16-5=11ulp.

Returnsthenumerator.Theresultismachinedependent.

n=0.3.numerator#=>5404319552844595

d=0.3.denominator#=>18014398509481984

n.fdiv(d)#=>0.3

Returnsthepreviousrepresentablefloatint-pointnumber.

(-Float::MAX).#prev_floatand(-Float::INFINITY).#prev_floatis-Float::INFINITY.

Float::NAN.prev_floatisFloat::NAN.

Forexample:

p0.01.prev_float#=>0.009999999999999998

p1.0.prev_float#=>0.9999999999999999

p100.0.prev_float#=>99.99999999999999

numerator→integer

prev_float→float

p0.01-0.01.prev_float#=>1.734723475976807e-18

p1.0-1.0.prev_float#=>1.1102230246251565e-16

p100.0-100.0.prev_float#=>1.4210854715202004e-14

f=0.01;20.times{printf"%-20a%s\n",f,f.to_s;f

#=>0x1.47ae147ae147bp-70.01

#0x1.47ae147ae147ap-70.009999999999999998

#0x1.47ae147ae1479p-70.009999999999999997

#0x1.47ae147ae1478p-70.009999999999999995

#0x1.47ae147ae1477p-70.009999999999999993

#0x1.47ae147ae1476p-70.009999999999999992

#0x1.47ae147ae1475p-70.00999999999999999

#0x1.47ae147ae1474p-70.009999999999999988

#0x1.47ae147ae1473p-70.009999999999999986

#0x1.47ae147ae1472p-70.009999999999999985

#0x1.47ae147ae1471p-70.009999999999999983

#0x1.47ae147ae147p-70.009999999999999981

#0x1.47ae147ae146fp-70.00999999999999998

#0x1.47ae147ae146ep-70.009999999999999978

#0x1.47ae147ae146dp-70.009999999999999976

#0x1.47ae147ae146cp-70.009999999999999974

#0x1.47ae147ae146bp-70.009999999999999972

#0x1.47ae147ae146ap-70.00999999999999997

#0x1.47ae147ae1469p-70.009999999999999969

#0x1.47ae147ae1468p-70.009999999999999967

Returnsfloat/numeric,sameasFloat#/.

Returnsasimplerapproximationofthevalue(flt-|eps|<=result<=flt+|eps|).iftheoptionalepsisnotgiven,itwillbechosenautomatically.

0.3.rationalize#=>(3/10)

1.333.rationalize#=>(1333/1000)

1.333.rationalize(0.01)#=>(4/3)

Seeto_r.

fdiv(numeric)→floatquo(numeric)→float

Roundsfloattoagivenprecisionindecimaldigits(default0digits).

Precisionmaybenegative.Returnsafloatingpointnumberwhenndigitsismorethanzero.

1.4.round#=>1

1.5.round#=>2

1.6.round#=>2

(-1.5).round#=>-2

1.234567.round(2)#=>1.23

1.234567.round(3)#=>1.235

1.234567.round(4)#=>1.2346

1.234567.round(5)#=>1.23457

34567.89.round(-5)#=>0

34567.89.round(-4)#=>30000

34567.89.round(-3)#=>35000

34567.89.round(-2)#=>34600

34567.89.round(-1)#=>34570

34567.89.round(0)#=>34568

34567.89.round(1)#=>34567.9

34567.89.round(2)#=>34567.89

34567.89.round(3)#=>34567.89

Sincefloatisalreadyafloat,returnsself.

ReturnsthefloattruncatedtoanInteger.

Synonymsareto_i,to_int,andtruncate.

round([ndigits])→integerorfloat

to_f→self

to_i→integerto_int→integertruncate→integer

Returnsthevalueasarational.

NOTE:0.3.to_risn'tthesameas'0.3'.to_r.Thelatterisequivalentto'3/10'.#to_r,buttheformerisn'tso.

2.0.to_r#=>(2/1)

2.5.to_r#=>(5/2)

-0.75.to_r#=>(-3/4)

0.0.to_r#=>(0/1)

Seerationalize.

Returnsastringcontainingarepresentationofself.Aswellasafixedorexponentialformofthefloat,thecallmayreturnNaN,Infinity,and-Infinity.

to_r→rational

to_s→string

zero?→trueorfalse

Returnstrueiffloatis0.0.

classFloatDomainErrorRaisedwhenattemptingtoconvertspecialfloatvalues(inparticularinfiniteorNaN)tonumericalclasseswhichdon'tsupportthem.

Float::INFINITY.to_r

#=>FloatDomainError:Infinity

InFilesnumeric.c

ParentRangeError

moduleGCTheGCmoduleprovidesaninterfacetoRuby'smarkandsweepgarbagecollectionmechanism.

SomeoftheunderlyingmethodsarealsoavailableviatheObjectSpacemodule.

YoumayobtaininformationabouttheoperationoftheGCthroughGC::Profiler.

InFilesgc.c

Constants

INTERNAL_CONSTANTS

PublicClassMethods

ThenumberoftimesGCoccurred.

ItreturnsthenumberoftimesGCoccurredsincetheprocessstarted.

count→Integer

Disablesgarbagecollection,returningtrueifgarbagecollectionwasalreadydisabled.

GC.disable#=>false

GC.disable#=>true

Enablesgarbagecollection,returningtrueifgarbagecollectionwaspreviouslydisabled.

GC.disable#=>false

GC.enable#=>true

GC.enable#=>false

Returnsinformationaboutthemostrecentgarbagecollection.

Returnsthesizeofmemoryallocatedbymalloc().

OnlyavailableifrubywasbuiltwithCALC_EXACT_MALLOC_SIZE.

Returnsthenumberofmalloc()allocations.

OnlyavailableifrubywasbuiltwithCALC_EXACT_MALLOC_SIZE.

disable→trueorfalse

enable→trueorfalse

latest_gc_info->{:gc_by→:newobj}latest_gc_info(hash)→hashlatest_gc_info(:major_by)→:malloc

malloc_allocated_size→Integer

malloc_allocations→Integer

Initiatesgarbagecollection,unlessmanuallydisabled.

Thismethodisdefinedwithkeywordargumentsthatdefaulttotrue:

defGC.start(full_mark:true,immediate_sweep:true);

Usefull_mark:falsetoperformaminorGC.Useimmediate_sweep:falsetodefersweeping(uselazysweep).

Note:Thesekeywordargumentsareimplementationandversiondependent.Theyarenotguaranteedtobefuture-compatible,andmaybeignorediftheunderlyingimplementationdoesnotsupportthem.

ReturnsaHashcontaininginformationabouttheGC.

ThehashincludesinformationaboutinternalstatisticsaboutGCsuchas:

:count=>0,

:heap_allocated_pages=>24,

:heap_sorted_length=>24,

:heap_allocatable_pages=>0,

:heap_available_slots=>9783,

:heap_live_slots=>7713,

start→nilgarbage_collect→nilstart(full_mark:true,immediate_sweep:true)→nilgarbage_collect(full_mark:true,immediate_sweep:true)→nil

stat→Hashstat(hash)→hashstat(:key)→Numeric

:heap_free_slots=>2070,

:heap_final_slots=>0,

:heap_marked_slots=>0,

:heap_swept_slots=>0,

:heap_eden_pages=>24,

:heap_tomb_pages=>0,

:total_allocated_pages=>24,

:total_freed_pages=>0,

:total_allocated_objects=>7796,

:total_freed_objects=>83,

:malloc_increase_bytes=>2389312,

:malloc_increase_bytes_limit=>16777216,

:minor_gc_count=>0,

:major_gc_count=>0,

:remembered_wb_unprotected_objects=>0,

:remembered_wb_unprotected_objects_limit=>0,

:old_objects=>0,

:old_objects_limit=>0,

:oldmalloc_increase_bytes=>2389760,

:oldmalloc_increase_bytes_limit=>16777216

Thecontentsofthehashareimplementationspecificandmaybechangedinthefuture.

ThismethodisonlyexpectedtoworkonCRuby.

ReturnscurrentstatusofGCstressmode.

UpdatestheGCstressmode.

Whenstressmodeisenabled,theGCisinvokedateveryGCopportunity:allmemoryandobjectallocations.

Enablingstressmodewilldegradeperformance,itisonlyfordebugging.

flagcanbetrue,false,orafixnumbit-ORedfollowingflags.

stress→fixnum,trueorfalse

stress=flag→flag

0x01::nomajorGC

0x02::noimmediatesweep

0x04::fullmarkaftermalloc/calloc/realloc

Verifyinternalconsistency.

Thismethodisimplementationspecific.NowthismethodchecksgenerationalconsistencyifRGenGCissupported.

verify_internal_consistency→nil

moduleGC::ProfilerTheGCprofilerprovidesaccesstoinformationonGCrunsincludingtime,lengthandobjectspacesize.

Example:

GC::Profiler.enable

require'rdoc/rdoc'

GC::Profiler.report

GC::Profiler.disable

SeealsoGC.count,GC.malloc_allocated_sizeandGC.malloc_allocations

InFilesgc.c

PublicClassMethods

ClearstheGCprofilerdata.

StopstheGCprofiler.

GC::Profiler.clear→nil

GC::Profiler.disable→nil

StartstheGCprofiler.

ThecurrentstatusofGCprofilemode.

ReturnsanArrayofindividualrawprofiledataHashesorderedfromearliesttolatestby:GC_INVOKE_TIME.

Forexample:

:GC_TIME=>1.3000000000000858e-05,

:GC_INVOKE_TIME=>0.010634999999999999,

:HEAP_USE_SIZE=>289640,

:HEAP_TOTAL_SIZE=>588960,

:HEAP_TOTAL_OBJECTS=>14724,

:GC_IS_MARKED=>false

Thekeysmean::GC_TIME

TimeelapsedinsecondsforthisGCrun

:GC_INVOKE_TIME

TimeelapsedinsecondsfromstartuptowhentheGCwasinvoked

:HEAP_USE_SIZE

Totalbytesofheapused

:HEAP_TOTAL_SIZE

Totalsizeofheapinbytes

GC::Profiler.enable→nil

GC::Profiler.enabled?→trueorfalse

GC::Profiler.raw_data→[Hash,...]

:HEAP_TOTAL_OBJECTS

Totalnumberofobjects

:GC_IS_MARKED

ReturnstrueiftheGCisinmarkphase

IfrubywasbuiltwithGC_PROFILE_MORE_DETAIL,youwillalsohaveaccesstothefollowinghashkeys::GC_MARK_TIME

:GC_SWEEP_TIME

:ALLOCATE_INCREASE

:ALLOCATE_LIMIT

:HEAP_USE_PAGES

:HEAP_LIVE_OBJECTS

:HEAP_FREE_OBJECTS

:HAVE_FINALIZE

Writesthe::resultto$stdoutorthegivenIOobject.

Returnsaprofiledatareportsuchas:

GC1invokes.

IndexInvokeTime(sec)UseSize(byte)TotalSize(byte)TotalObjectGCtime(ms)

10.012159240212940106470.00000000000001530000

Thetotaltimeusedforgarbagecollectioninseconds

GeneratedbyRDoc3.12.2.

GC::Profiler.reportGC::Profiler.report(io)

GC::Profiler.result→String

GC::Profiler.total_time→float

GeneratedwiththeDarkfishRdocGenerator3.

classHashAHashisadictionary-likecollectionofuniquekeysandtheirvalues.Alsocalledassociativearrays,theyaresimilartoArrays,butwhereanArrayusesintegersasitsindex,aHashallowsyoutouseanyobjecttype.

Hashesenumeratetheirvaluesintheorderthatthecorrespondingkeyswereinserted.

AHashcanbeeasilycreatedbyusingitsimplicitform:

grades={"JaneDoe"=>10,"JimDoe"=>6}

Hashesallowanalternatesyntaxformwhenyourkeysarealwayssymbols.Insteadof

options={:font_size=>10,:font_family=>"Arial"

Youcouldwriteitas:

options={font_size:10,font_family:"Arial"}

Eachnamedkeyisasymbolyoucanaccessinhash:

options[:font_size]#=>10

AHashcanalsobecreatedthroughits::newmethod:

grades=Hash.new

grades["DorothyDoe"]=9

Hasheshaveadefaultvaluethatisreturnedwhenaccessingkeysthatdonotexistinthehash.Ifnodefaultissetnilisused.Youcansetthedefaultvaluebysendingitasanargumentto::new:

grades=Hash.new(0)

Orbyusingthedefault=method:

grades={"TimmyDoe"=>8}

grades.default=0

AccessingavalueinaHashrequiresusingitskey:

putsgrades["JaneDoe"]#=>0

CommonUses

Hashesareaneasywaytorepresentdatastructures,suchas

books={}

books[:matz]="TheRubyLanguage"

books[:black]="TheWell-GroundedRubyist"

Hashesarealsocommonlyusedasawaytohavenamedparametersinfunctions.Notethatnobracketsareusedbelow.Ifahashisthelastargumentonamethodcall,nobracesareneeded,thuscreatingareallycleaninterface:

Person.create(name:"JohnDoe",age:27)

defself.create(params)

@name=params[:name]

@age=params[:age]

HashKeys

Twoobjectsrefertothesamehashkeywhentheirhashvalueisidenticalandthetwoobjectsareeql?toeachother.

Auser-definedclassmaybeusedasahashkeyifthehashandeql?methodsareoverriddentoprovidemeaningfulbehavior.Bydefault,separateinstancesrefertoseparatehashkeys.

Atypicalimplementationofhashisbasedontheobject'sdatawhileeql?isusuallyaliasedtotheoverridden==method:

classBook

attr_reader:author,:title

definitialize(author,title)

@author=author

@title=title

def==(other)

self.class===otherand

other.author==@authorand

other.title==@title

aliaseql?==

defhash

@author.hash^@title.hash#XOR

book1=Book.new'matz','RubyinaNutshell'

book2=Book.new'matz','RubyinaNutshell'

reviews={}

reviews[book1]='Greatreference!'

reviews[book2]='Niceandcompact!'

reviews.length#=>1

SeealsoObject#hashandObject#eql?

InFileshash.c

ParentObject

IncludedModules

Enumerable

PublicClassMethods

Createsanewhashpopulatedwiththegivenobjects.

Similartotheliteral{key=>value,...}.Inthefirstform,keysandvaluesoccurinpairs,sotheremustbeanevennumberofarguments.

Thesecondandthirdformtakeasingleargumentwhichiseitheranarrayofkey-valuepairsoranobjectconvertibletoahash.

Hash["a",100,"b",200]#=>{"a"=>100,"b"=>200}

Hash[[["a",100],["b",200]]]#=>{"a"=>100,"b"=>200}

Hash["a"=>100,"b"=>200]#=>{"a"=>100,"b"=>200}

Returnsanew,emptyhash.Ifthishashissubsequentlyaccessedbyakeythatdoesn'tcorrespondtoahashentry,thevaluereturneddependsonthestyleofnewusedtocreatethehash.Inthefirstform,theaccessreturnsnil.Ifobjisspecified,thissingleobjectwillbeusedforalldefaultvalues.Ifablockisspecified,itwillbecalledwiththehashobjectandthekey,andshouldreturnthedefaultvalue.Itistheblock'sresponsibilitytostorethevalueinthehashifrequired.

Hash[key,value,...]→new_hashHash[[[key,value],...]]→new_hashHash[object]→new_hash

new→new_hashnew(obj)→new_hashnew{|hash,key|block}→new_hash

h=Hash.new("GoFish")

h["a"]=100

h["b"]=200

h["a"]#=>100

h["c"]#=>"GoFish"

#Thefollowingaltersthesingledefaultobject

h["c"].upcase!#=>"GOFISH"

h["d"]#=>"GOFISH"

h.keys#=>["a","b"]

#Whilethiscreatesanewdefaultobjecteachtime

h=Hash.new{|hash,key|hash[key]="GoFish:#{key}"

h["c"]#=>"GoFish:c"

h["c"].upcase!#=>"GOFISH:C"

h["d"]#=>"GoFish:d"

h.keys#=>["c","d"]

Trytoconvertobjintoahash,using#to_hashmethod.Returnsconvertedhashornilifobjcannotbeconvertedforanyreason.

Hash.try_convert({1=>2})#=>{1=>2}

Hash.try_convert("1=>2")#=>nil

Equality—Twohashesareequaliftheyeachcontainthesamenumberofkeysandifeachkey-valuepairisequalto(accordingtoObject#==)thecorrespondingelementsintheotherhash.

h1={"a"=>1,"c"=>2}

h2={7=>35,"c"=>2,"a"=>1}

h3={"a"=>1,"c"=>2,7=>35}

h4={"a"=>1,"d"=>2,"f"=>35}

try_convert(obj)→hashornil

hsh==other_hash→trueorfalse

h1==h2#=>false

h2==h3#=>true

h3==h4#=>false

ElementReference—Retrievesthevalueobjectcorrespondingtothekeyobject.Ifnotfound,returnsthedefaultvalue(seeHash::newfordetails).

h={"a"=>100,"b"=>200}

h["a"]#=>100

h["c"]#=>nil

hsh[key]→value

hsh[key]=value→valuestore(key,value)→value

Associatesthevaluegivenbyvaluewiththekeygivenbykey.

h={"a"=>100,"b"=>200}

h["a"]=9

h["c"]=4

h#=>{"a"=>9,"b"=>200,"c"=>4}

h.store("d",42)#=>42

h#=>{"a"=>9,"b"=>200,"c"=>4,"d"=>42}

keyshouldnothaveitsvaluechangedwhileitisinuseasakey(anunfrozenStringpassedasakeywillbeduplicatedandfrozen).

b="b".freeze

h={a=>100,b=>200}

h.key(100).equal?a#=>false

h.key(200).equal?b#=>true

SeealsoEnumerable#any?

Searchesthroughthehashcomparingobjwiththekeyusing==.Returnsthekey-valuepair(twoelementsarray)ornilifnomatchisfound.SeeArray#assoc.

h={"colors"=>["red","blue","green"],

"letters"=>["a","b","c"]}

h.assoc("letters")#=>["letters",["a","b","c"]]

h.assoc("foo")#=>nil

ElementAssignment

any?[{|(key,value)|block}]→trueorfalse

assoc(obj)→an_arrayornil

Removesallkey-valuepairsfromhsh.

h={"a"=>100,"b"=>200}#=>{"a"=>100,"b"=>200}

h.clear#=>{}

Makeshshcompareitskeysbytheiridentity,i.e.itwillconsiderexactsameobjectsassamekeys.

h1={"a"=>100,"b"=>200,:c=>"c"}

h1["a"]#=>100

h1.compare_by_identity

h1.compare_by_identity?#=>true

h1["a".dup]#=>nil#differentobjects.

h1[:c]#=>"c"#samesymbolsareallsame.

Returnstrueifhshwillcompareitskeysbytheiridentity.AlsoseeHash#compare_by_identity.

Returnsthedefaultvalue,thevaluethatwouldbereturnedbyhshifkeydidnotexistinhsh.SeealsoHash::newandHash#default=.

h=Hash.new#=>{}

h.default#=>nil

h.default(2)#=>nil

h=Hash.new("cat")#=>{}

h.default#=>"cat"

h.default(2)#=>"cat"

clear→hsh

compare_by_identity→hsh

compare_by_identity?→trueorfalse

default(key=nil)→obj

h=Hash.new{|h,k|h[k]=k.to_i*10}#=>{}

h.default#=>nil

h.default(2)#=>20

Setsthedefaultvalue,thevaluereturnedforakeythatdoesnotexistinthehash.ItisnotpossibletosetthedefaulttoaProcthatwillbeexecutedoneachkeylookup.

h={"a"=>100,"b"=>200}

h.default="Gofish"

h["a"]#=>100

h["z"]#=>"Gofish"

#Thisdoesn'tdowhatyoumighthope...

h.default=procdo|hash,key|

hash[key]=key+key

h[2]#=>#<Proc:0x401b3948@-:6>

h["cat"]#=>#<Proc:0x401b3948@-:6>

IfHash::newwasinvokedwithablock,returnthatblock,otherwisereturnnil.

h=Hash.new{|h,k|h[k]=k*k}#=>{}

p=h.default_proc#=>#<Proc:0x401b3d08@-:1>

a=[]#=>[]

p.call(a,2)

a#=>[nil,nil,4]

Setsthedefaultproctobeexecutedoneachfailedkeylookup.

h.default_proc=procdo|hash,key|

default=obj→obj

default_proc→anObject

default_proc=proc_objornil

hash[key]=key+key

h[2]#=>4

h["cat"]#=>"catcat"

Deletesthekey-valuepairandreturnsthevaluefromhshwhosekeyisequaltokey.Ifthekeyisnotfound,returnsthedefaultvalue.Iftheoptionalcodeblockisgivenandthekeyisnotfound,passinthekeyandreturntheresultofblock.

h={"a"=>100,"b"=>200}

h.delete("a")#=>100

h.delete("z")#=>nil

h.delete("z"){|el|"#{el}notfound"}#=>"znotfound"

Deleteseverykey-valuepairfromhshforwhichblockevaluatestotrue.

h={"a"=>100,"b"=>200,"c"=>300}

h.delete_if{|key,value|key>="b"}#=>{"a"=>100}

Callsblockonceforeachkeyinhsh,passingthe

delete(key)→valuedelete(key){|key|block}→value

delete_if{|key,value|block}→hshdelete_if→an_enumerator

each{|key,value|block}→hsheach_pair{|key,value|block}→hsheach→an_enumeratoreach_pair→an_enumerator

key-valuepairasparameters.

h={"a"=>100,"b"=>200}

h.each{|key,value|puts"#{key}is#{value}"}

produces:

ais100

bis200

Callsblockonceforeachkeyinhsh,passingthekeyasaparameter.

h={"a"=>100,"b"=>200}

h.each_key{|key|putskey}

produces:

Callsblockonceforeachkeyinhsh,passingthekey-valuepairasparameters.

each_key{|key|block}→hsheach_key→an_enumerator

each{|key,value|block}→hsheach_pair{|key,value|block}→hsheach→an_enumeratoreach_pair→an_enumerator

h={"a"=>100,"b"=>200}

h.each{|key,value|puts"#{key}is#{value}"}

produces:

ais100

bis200

Callsblockonceforeachkeyinhsh,passingthevalueasaparameter.

h={"a"=>100,"b"=>200}

h.each_value{|value|putsvalue}

produces:

Returnstrueifhshcontainsnokey-valuepairs.

{}.empty?#=>true

Returnstrueifhashandotherarebothhasheswiththesamecontent.

each_value{|value|block}→hsheach_value→an_enumerator

fetch(key[,default])→objfetch(key){|key|block}→obj

Returnsavaluefromthehashforthegivenkey.Ifthekeycan'tbefound,thereareseveraloptions:Withnootherarguments,itwillraiseanKeyErrorexception;ifdefaultisgiven,thenthatwillbereturned;iftheoptionalcodeblockisspecified,thenthatwillberunanditsresultreturned.

h={"a"=>100,"b"=>200}

h.fetch("a")#=>100

h.fetch("z","gofish")#=>"gofish"

h.fetch("z"){|el|"gofish,#{el}"}#=>"gofish,z"

Thefollowingexampleshowsthatanexceptionisraisedifthekeyisnotfoundandadefaultvalueisnotsupplied.

h={"a"=>100,"b"=>200}

h.fetch("z")

produces:

prog.rb:2:in`fetch':keynotfound(KeyError)

fromprog.rb:2

Returnsanewarraythatisaone-dimensionalflatteningofthishash.Thatis,foreverykeyorvaluethatisanarray,extractitselementsintothenewarray.UnlikeArray#flatten,thismethoddoesnotflattenrecursivelybydefault.Theoptionallevelargumentdeterminesthelevelofrecursiontoflatten.

a={1=>"one",2=>[2,"two"],3=>"three"}

a.flatten#=>[1,"one",2,[2,"two"],3,"three"]

a.flatten(2)#=>[1,"one",2,2,"two",3,"three"]

flatten→an_arrayflatten(level)→an_array

Returnstrueifthegivenkeyispresentinhsh.

h={"a"=>100,"b"=>200}

h.has_key?("a")#=>true

h.has_key?("z")#=>false

Returnstrueifthegivenvalueispresentforsomekeyinhsh.

h={"a"=>100,"b"=>200}

h.has_value?(100)#=>true

h.has_value?(999)#=>false

Computeahash-codeforthishash.Twohasheswiththesamecontentwillhavethesamehashcode(andwillcompareusingeql?).

SeealsoObject#hash.

h={"a"=>100,"b"=>200}

has_key?(key)→trueorfalseinclude?(key)→trueorfalsekey?(key)→trueorfalsemember?(key)→trueorfalse

has_value?(value)→trueorfalsevalue?(value)→trueorfalse

hash→fixnum

Returnthecontentsofthishashasastring.

h={"c"=>300,"a"=>100,"d"=>400,"c"=>300}

h.to_s#=>"{\"c\"=>300,\"a\"=>100,\"d\"=>400}"

Alsoaliasedas:to_s

Returnsanewhashcreatedbyusinghsh'svaluesaskeys,andthekeysasvalues.

h={"n"=>100,"m"=>100,"y"=>300,"d"=>200,

h.invert#=>{0=>"a",100=>"m",200=>"d",300=>"y"}

Deleteseverykey-valuepairfromhshforwhichblockevaluatestofalse.

Returnsthekeyofanoccurrenceofagivenvalue.Ifthevalueisnotfound,returnsnil.

h={"a"=>100,"b"=>200,"c"=>300,"d"=>300}

h.key(200)#=>"b"

h.key(300)#=>"c"

h.key(999)#=>nil

to_s→stringinspect→string

invert→new_hash

keep_if{|key,value|block}→hshkeep_if→an_enumerator

key(value)→key

h={"a"=>100,"b"=>200}

Returnsanewarraypopulatedwiththekeysfromthishash.SeealsoHash#values.

h={"a"=>100,"b"=>200,"c"=>300,"d"=>400}

h.keys#=>["a","b","c","d"]

Returnsthenumberofkey-valuepairsinthehash.

h={"d"=>100,"a"=>200,"v"=>300,"e"=>400}

h.length#=>4

h.delete("a")#=>200

h.length#=>3

keys→array

length→fixnumsize→fixnum

h={"a"=>100,"b"=>200}

Returnsanewhashcontainingthecontentsofother_hashandthecontentsofhsh.Ifnoblockisspecified,thevalueforentrieswithduplicatekeyswillbethatofother_hash.Otherwisethevalueforeachduplicatekeyisdeterminedbycallingtheblockwiththekey,itsvalueinhshanditsvalueinother_hash.

h1={"a"=>100,"b"=>200}

h2={"b"=>254,"c"=>300}

h1.merge(h2)#=>{"a"=>100,"b"=>254,"c"=>300}

h1.merge(h2){|key,oldval,newval|newval-oldval}

#=>{"a"=>100,"b"=>54,"c"=>300}

h1#=>{"a"=>100,"b"=>200}

Addsthecontentsofother_hashtohsh.Ifnoblockisspecified,entrieswithduplicatekeysareoverwrittenwiththevaluesfromother_hash,otherwisethevalueofeachduplicatekeyisdeterminedbycallingtheblockwiththekey,itsvalueinhshanditsvalueinother_hash.

h1={"a"=>100,"b"=>200}

merge(other_hash)→new_hashmerge(other_hash){|key,oldval,newval|block}→new_hash

merge!(other_hash)→hshupdate(other_hash)→hshmerge!(other_hash){|key,oldval,newval|block}→hshupdate(other_hash){|key,oldval,newval|block}→hsh

h2={"b"=>254,"c"=>300}

h1.merge!(h2)#=>{"a"=>100,"b"=>254,"c"=>300}

h1={"a"=>100,"b"=>200}

h2={"b"=>254,"c"=>300}

h1.merge!(h2){|key,v1,v2|v1}

#=>{"a"=>100,"b"=>200,"c"=>300}

Searchesthroughthehashcomparingobjwiththevalueusing==.Returnsthefirstkey-valuepair(two-elementarray)thatmatches.SeealsoArray#rassoc.

a={1=>"one",2=>"two",3=>"three","ii"=>"two"

a.rassoc("two")#=>[2,"two"]

a.rassoc("four")#=>nil

Rebuildsthehashbasedonthecurrenthashvaluesforeachkey.Ifvaluesofkeyobjectshavechangedsincetheywereinserted,thismethodwillreindexhsh.IfHash#rehashiscalledwhileaniteratoristraversingthehash,anRuntimeErrorwillberaisedintheiterator.

a=["a","b"]

c=["c","d"]

h={a=>100,c=>300}

h[a]#=>100

a[0]="z"

h[a]#=>nil

h.rehash#=>{["z","b"]=>100,["c","d"]=>300}

h[a]#=>100

rassoc(obj)→an_arrayornil

rehash→hsh

reject{|key,value|block}→a_hash

Returnsanewhashconsistingofentriesforwhichtheblockreturnsfalse.

h={"a"=>100,"b"=>200,"c"=>300}

h.reject{|k,v|k<"b"}#=>{"b"=>200,"c"=>300}

h.reject{|k,v|v>100}#=>{"a"=>100}

EquivalenttoHash#delete_if,butreturnsnilifnochangesweremade.

Replacesthecontentsofhshwiththecontentsofother_hash.

h={"a"=>100,"b"=>200}

h.replace({"c"=>300,"d"=>400})#=>{"c"=>300,"d"=>400}

Returnsanewhashconsistingofentriesforwhichtheblockreturnstrue.

h={"a"=>100,"b"=>200,"c"=>300}

h.select{|k,v|k>"a"}#=>{"b"=>200,"c"=>300}

h.select{|k,v|v<200}#=>{"a"=>100}

reject→an_enumerator

reject!{|key,value|block}→hshornilreject!→an_enumerator

replace(other_hash)→hsh

select{|key,value|block}→a_hashselect→an_enumerator

EquivalenttoHash#keep_if,butreturnsnilifnochangesweremade.

Removesakey-valuepairfromhshandreturnsitasthetwo-itemarray[key,value],orthehash'sdefaultvalueifthehashisempty.

h={1=>"a",2=>"b",3=>"c"}

h.shift#=>[1,"a"]

h#=>{2=>"b",3=>"c"}

Returnsthenumberofkey-valuepairsinthehash.

h={"d"=>100,"a"=>200,"v"=>300,"e"=>400}

h.length#=>4

h.delete("a")#=>200

h.length#=>3

select!{|key,value|block}→hshornilselect!→an_enumerator

shift→anArrayorobj

hsh[key]=value→valuestore(key,value)→value

Associatesthevaluegivenbyvaluewiththekeygivenbykey.

h={"a"=>100,"b"=>200}

h["a"]=9

h["c"]=4

h#=>{"a"=>9,"b"=>200,"c"=>4}

h.store("d",42)#=>42

h#=>{"a"=>9,"b"=>200,"c"=>4,"d"=>42}

keyshouldnothaveitsvaluechangedwhileitisinuseasakey(anunfrozenStringpassedasakeywillbeduplicatedandfrozen).

b="b".freeze

h={a=>100,b=>200}

h.key(100).equal?a#=>false

h.key(200).equal?b#=>true

Convertshshtoanestedarrayof[key,value]arrays.

h={"c"=>300,"a"=>100,"d"=>400,"c"=>300}

h.to_a#=>[["c",300],["a",100],["d",400]]

Returnsself.IfcalledonasubclassofHash,convertsthereceivertoaHashobject.

ElementAssignment

to_a→array

to_h→hshornew_hash

Returnsself.

Aliasfor:inspect

Addsthecontentsofother_hashtohsh.Ifnoblockisspecified,entrieswithduplicatekeysareoverwrittenwiththevaluesfromother_hash,otherwisethevalueofeachduplicatekeyisdeterminedbycallingtheblockwiththekey,itsvalueinhshanditsvalueinother_hash.

h1={"a"=>100,"b"=>200}

h2={"b"=>254,"c"=>300}

h1.merge!(h2)#=>{"a"=>100,"b"=>254,"c"=>300}

h1={"a"=>100,"b"=>200}

h2={"b"=>254,"c"=>300}

h1.merge!(h2){|key,v1,v2|v1}

#=>{"a"=>100,"b"=>200,"c"=>300}

Returnstrueifthegivenvalueispresentforsomekeyinhsh.

h={"a"=>100,"b"=>200}

to_hash→hsh

to_s()

merge!(other_hash)→hshupdate(other_hash)→hshmerge!(other_hash){|key,oldval,newval|block}→hshupdate(other_hash){|key,oldval,newval|block}→hsh

has_value?(value)→trueorfalsevalue?(value)→trueorfalse

h.has_value?(100)#=>true

h.has_value?(999)#=>false

Returnsanewarraypopulatedwiththevaluesfromhsh.SeealsoHash#keys.

h={"a"=>100,"b"=>200,"c"=>300}

h.values#=>[100,200,300]

Returnanarraycontainingthevaluesassociatedwiththegivenkeys.AlsoseeHash.select.

h={"cat"=>"feline","dog"=>"canine","cow"=>"bovine"

h.values_at("cow","cat")#=>["bovine","feline"]

values→array

values_at(key,...)→array

classIOTheIOclassisthebasisforallinputandoutputinRuby.AnI/Ostreammaybeduplexed(thatis,bidirectional),andsomayusemorethanonenativeoperatingsystemstream.

ManyoftheexamplesinthissectionusetheFileclass,theonlystandardsubclassofIO.Thetwoclassesarecloselyassociated.LiketheFileclass,theSocketlibrarysubclassesfromIO(suchasTCPSocketorUDPSocket).

TheKernel#openmethodcancreateanIO(orFile)objectforthesetypesofarguments:

Aplainstringrepresentsafilenamesuitablefortheunderlyingoperatingsystem.Astringstartingwith"|"indicatesasubprocess.Theremainderofthestringfollowingthe"|"isinvokedasaprocesswithappropriateinput/outputchannelsconnectedtoit.Astringequalto"|-"willcreateanotherRubyinstanceasasubprocess.

TheIOmaybeopenedwithdifferentfilemodes(read-only,write-only)andencodingsforproperconversion.See::newfortheseoptions.SeeKernel#openfordetailsofthevariouscommand

formatsdescribedabove.

::popen,theOpen3library,orProcess#spawnmayalsobeusedtocommunicatewithsubprocessesthroughanIO.

Rubywillconvertpathnamesbetweendifferentoperatingsystemconventionsifpossible.Forinstance,onaWindowssystemthefilename"/gumby/ruby/test.rb"willbeopenedas"\gumby\ruby\test.rb".WhenspecifyingaWindows-stylefilenameinaRubystring,remembertoescapethebackslashes:

"c:\\gumby\\ruby\\test.rb"

OurexamplesherewillusetheUnix-styleforwardslashes;File::ALT_SEPARATORcanbeusedtogettheplatform-specificseparatorcharacter.

TheglobalconstantARGF(alsoaccessibleas$<)providesanIO-likestreamwhichallowsaccesstoallfilesmentionedonthecommandline(orSTDINifnofilesarementioned).ARGF#pathanditsaliasARGF#filenameareprovidedtoaccessthenameofthefilecurrentlybeingread.

io/console

Theio/consoleextensionprovidesmethodsforinteractingwiththeconsole.TheconsolecanbeaccessedfromIO.consoleorthestandardinput/output/errorIOobjects.

Requiringio/consoleaddsthefollowingmethods:

IO::consoleIO#rawIO#raw!IO#cookedIO#cooked!IO#getchIO#echo=IO#echo?IO#noechoIO#winsizeIO#winsize=IO#iflushIO#ioflushIO#oflush

Example:

require'io/console'

rows,columns=$stdin.winsize

puts"Yourscreenis#{columns}wideand#{rows}tall"

InFilesfile.cio.c

ParentObject

IncludedModulesFile::ConstantsEnumerable

Constants

EWOULDBLOCKWaitReadable

EAGAINWaitReadable

EWOULDBLOCKWaitWritable

EAGAINWaitWritable

SEEK_CUR

SetI/Opositionfromthecurrentposition

SEEK_DATA

SetI/Opositiontothenextlocationcontainingdata

SEEK_END

SetI/Opositionfromtheend

SEEK_HOLE

SetI/Opositiontothenexthole

SEEK_SET

SetI/Opositionfromthebeginning

PublicClassMethods

Opensthefile,optionallyseekstothegivenoffset,thenreturnslengthbytes(defaultingtotherestofthefile).binreadensuresthefileisclosedbeforereturning.Theopenmodewouldbe“rb:ASCII-8BIT”.

IO.binread("testfile")#=>"Thisislineone\nThisislinetwo\nThisislinethree\nAndsoon...\n"

IO.binread("testfile",20)#=>"Thisislineone\nThi"

IO.binread("testfile",20,10)#=>"neone\nThisisline"

SameasIO.writeexceptopeningthefileinbinarymodeandASCII-8BITencoding(“wb:ASCII-8BIT”).

::copy_streamcopiessrctodst.srcanddstiseither

binread(name,[length[,offset]])→string

binwrite(name,string,[offset])→fixnumbinwrite(name,string,[offset],open_args)→fixnum

copy_stream(src,dst)copy_stream(src,dst,copy_length)copy_stream(src,dst,copy_length,src_offset)

afilenameoranIO.

Thismethodreturnsthenumberofbytescopied.

Ifoptionalargumentsarenotgiven,thestartpositionofthecopyisthebeginningofthefilenameorthecurrentfileoffsetoftheIO.Theendpositionofthecopyistheendoffile.

Ifcopy_lengthisgiven,Nomorethancopy_lengthbytesarecopied.

Ifsrc_offsetisgiven,itspecifiesthestartpositionofthecopy.

Whensrc_offsetisspecifiedandsrcisanIO,::copy_streamdoesn'tmovethecurrentfileoffset.

SynonymforIO.new.

ExecutestheblockforeverylineinthenamedI/Oport,wherelinesareseparatedbysep.

IO.foreach("testfile"){|x|print"GOT",x}

produces:

GOTThisislineone

for_fd(fd,mode[,opt])→io

foreach(name,sep=$/[,open_args]){|line|block}→nilforeach(name,limit[,open_args]){|line|block}→nilforeach(name,sep,limit[,open_args]){|line|block}→nilforeach(...)→an_enumerator

GOTThisislinetwo

GOTThisislinethree

GOTAndsoon...

Ifthelastargumentisahash,it'sthekeywordargumenttoopen.SeeIO.readfordetail.

ReturnsanewIOobject(astream)forthegivenintegerfiledescriptorfdandmodestring.optmaybeusedtospecifypartsofmodeinamorereadablefashion.Seealso::sysopenand::for_fd.

::newiscalledbyvariousFileandIOopeningmethodssuchas::open,Kernel#open,andFile.open.

OpenModeWhenmodeisanintegeritmustbecombinationofthemodesdefinedinFile::Constants(+File::RDONLY+,+File::WRONLY|File::CREAT+).Seetheopen(2)manpageformoreinformation.

Whenmodeisastringitmustbeinoneofthefollowingforms:

fmode":"ext_enc

fmode":"ext_enc":"int_enc

fmode":""BOM|UTF-*"

fmodeisanIOopenmodestring,ext_encistheexternalencodingfortheIOandint_encistheinternalencoding.

IOOpenModeRubyallowsthefollowingopenmodes:

"r"Read-only,startsatbeginningoffile(defaultmode).

new(fd[,mode][,opt])→io

"r+"Read-write,startsatbeginningoffile.

"w"Write-only,truncatesexistingfile

tozerolengthorcreatesanewfileforwriting.

"w+"Read-write,truncatesexistingfiletozerolength

orcreatesanewfileforreadingandwriting.

"a"Write-only,eachwritecallappendsdataatendoffile.

Createsanewfileforwritingiffiledoesnotexist.

"a+"Read-write,eachwritecallappendsdataatendoffile.

Createsanewfileforreadingandwritingiffiledoes

notexist.

Thefollowingmodesmustbeusedseparately,andalongwithoneormoreofthemodesseenabove.

"b"Binaryfilemode

SuppressesEOL<->CRLFconversiononWindows.And

setsexternalencodingtoASCII-8BITunlessexplicitly

specified.

"t"Textfilemode

WhentheopenmodeoforiginalIOisreadonly,themodecannotbechangedtobewritable.Similarly,theopenmodecannotbechangedfromwriteonlytoreadable.

Whensuchachangeisattemptedtheerrorisraisedindifferentlocationsaccordingtotheplatform.

IOEncodingWhenext_encisspecified,stringsreadwillbetaggedbytheencodingwhenreading,andstringsoutputwillbeconvertedtothespecifiedencodingwhenwriting.

Whenext_encandint_encarespecifiedreadstringswillbeconvertedfromext_enctoint_encuponinput,andwrittenstringswillbeconvertedfromint_encto

ext_encuponoutput.SeeEncodingforfurtherdetailsoftranscodingoninputandoutput.

If“BOM|UTF-8”,“BOM|UTF-16LE”or“BOM|UTF16-BE”areused,rubychecksforaUnicodeBOMintheinputdocumenttohelpdeterminetheencoding.ForUTF-16encodingsthefileopenmodemustbebinary.Whenpresent,theBOMisstrippedandtheexternalencodingfromtheBOMisused.WhentheBOMismissingthegivenUnicodeencodingisusedasext_enc.(TheBOM-setencodingoptioniscaseinsensitive,so“bom|utf-8”isalsovalid.)

Optionsoptcanbeusedinsteadofmodeforimprovedreadability.Thefollowingkeysaresupported:

:modeSameasmodeparameter

:external_encodingExternalencodingfortheIO.“-”isasynonymforthedefaultexternalencoding.

:internal_encodingInternalencodingfortheIO.“-”isasynonymforthedefaultinternalencoding.

Ifthevalueisnilnoconversionoccurs.

:encodingSpecifiesexternalandinternalencodingsas“extern:intern”.

:textmodeIfthevalueistruthvalue,sameas“t”inargumentmode.

:binmodeIfthevalueistruthvalue,sameas“b”inargument

:autocloseIfthevalueisfalse,thefdwillbekeptopenafterthisIOinstancegetsfinalized.

Also,optcanhavesamekeysinString#encodeforcontrollingconversionbetweentheexternalencodingandtheinternalencoding.

Example1fd=IO.sysopen("/dev/tty","w")

a=IO.new(fd,"w")

$stderr.puts"Hello"

a.puts"World"

Produces:

Example2require'fcntl'

fd=STDERR.fcntl(Fcntl::F_DUPFD)

io=IO.new(fd,mode:'w:UTF-16LE',cr_newline:true)

io.puts"Hello,World!"

fd=STDERR.fcntl(Fcntl::F_DUPFD)

io=IO.new(fd,mode:'w',cr_newline:true,

external_encoding:Encoding::UTF_16LE)

io.puts"Hello,World!"

Bothofaboveprint“Hello,World!”inUTF-16LEtostandarderroroutputwithconvertingEOLgeneratedbyputstoCR.

Withnoassociatedblock,IO.openisasynonymfor::new.Iftheoptionalcodeblockisgiven,itwillbepassedioasanargument,andtheIOobjectwillautomaticallybeclosedwhentheblockterminates.Inthisinstance,::openreturnsthevalueoftheblock.

See::newforadescriptionofthefd,modeandoptparameters.

Createsapairofpipeendpoints(connectedtoeachother)andreturnsthemasatwo-elementarrayofIOobjects:[read_io,write_io].

Ifablockisgiven,theblockiscalledandreturnsthevalueoftheblock.read_ioandwrite_ioaresenttotheblockasarguments.Ifread_ioandwrite_ioarenotclosedwhentheblockexits,theyareclosed.i.e.closingread_ioand/orwrite_iodoesn'tcauseanerror.

Notavailableonallplatforms.

Ifanencoding(encodingnameorencodingobject)isspecifiedasanoptionalargument,readstringfrompipeistaggedwiththeencodingspecified.Iftheargumentisacolonseparatedtwoencodingnames“A:B”,thereadstringisconvertedfromencodingA

open(fd,mode="r"[,opt])→ioopen(fd,mode="r"[,opt]){|io|block}→obj

pipe→[read_io,write_io]pipe(ext_enc)→[read_io,write_io]pipe("ext_enc:int_enc"[,opt])→[read_io,write_io]pipe(ext_enc,int_enc[,opt])→[read_io,write_io]pipe(...){|read_io,write_io|...}

(externalencoding)toencodingB(internalencoding),thentaggedwithB.Iftwooptionalargumentsarespecified,thosemustbeencodingobjectsorencodingnames,andthefirstoneistheexternalencoding,andthesecondoneistheinternalencoding.Iftheexternalencodingandtheinternalencodingisspecified,optionalhashargumentspecifytheconversionoption.

Intheexamplebelow,thetwoprocessesclosetheendsofthepipethattheyarenotusing.Thisisnotjustacosmeticnicety.Thereadendofapipewillnotgenerateanendoffileconditionifthereareanywriterswiththepipestillopen.Inthecaseoftheparentprocess,therd.readwillneverreturnifitdoesnotfirstissueawr.close.

rd,wr=IO.pipe

iffork

wr.close

puts"Parentgot:<#{rd.read}>"

rd.close

Process.wait

rd.close

puts"Sendingmessagetoparent"

wr.write"HiDad"

wr.close

produces:

Sendingmessagetoparent

Parentgot:<HiDad>

Runsthespecifiedcommandasasubprocess;the

popen([env,]cmd,mode="r"[,opt])→iopopen([env,]cmd,mode="r"[,opt]){|io|block}→obj

subprocess'sstandardinputandoutputwillbeconnectedtothereturnedIOobject.

ThePIDofthestartedprocesscanbeobtainedby#pidmethod.

cmdisastringoranarrayasfollows.

"-":fork

commandline:commandlinestringwhichispassedtoashell

[env,cmdname,arg1,...,opts]:commandnameandzeroormorearguments(noshell)

[env,[cmdname,argv0],arg1,...,opts]:commandname,argv[0]andzeroormorearguments(noshell)

(envandoptsareoptional.)

IfcmdisaString“-'',thenanewinstanceofRubyisstartedasthesubprocess.

IfcmdisanArrayofString,thenitwillbeusedasthesubprocess'sargvbypassingashell.Thearraycancontainsahashatfirstforenvironmentsandahashatlastforoptionssimilartospawn.

Thedefaultmodeforthenewfileobjectis“r'',butmodemaybesettoanyofthemodeslistedinthedescriptionforclassIO.Thelastargumentoptqualifiesmode.

#setIOencoding

IO.popen("nkf-efilename",:external_encoding=>"EUC-JP"

euc_jp_string=nkf_io.read

#mergestandardoutputandstandarderrorusing

#spawnoption.SeethedocumentofKernel.spawn.

IO.popen(["ls","/",:err=>[:child,:out]]){|ls_io|

ls_result_with_error=ls_io.read

#spawnoptionscanbemixedwithIOoptions

IO.popen(["ls","/"],:err=>[:child,:out]){|ls_io|

ls_result_with_error=ls_io.read

RaisesexceptionswhichIO.pipeandKernel.spawnraise.

Ifablockisgiven,RubywillrunthecommandasachildconnectedtoRubywithapipe.Ruby'sendofthepipewillbepassedasaparametertotheblock.Attheendofblock,Rubyclosesthepipeandsets$?.InthiscaseIO.popenreturnsthevalueoftheblock.

Ifablockisgivenwithacmdof“-'',theblockwillberunintwoseparateprocesses:onceintheparent,andonceinachild.Theparentprocesswillbepassedthepipeobjectasaparametertotheblock,thechildversionoftheblockwillbepassednil,andthechild'sstandardinandstandardoutwillbeconnectedtotheparentthroughthepipe.Notavailableonallplatforms.

f=IO.popen("uname")

pf.readlines

f.close

puts"Parentis#{Process.pid}"

IO.popen("date"){|f|putsf.gets}

IO.popen("-"){|f|$stderr.puts"#{Process.pid}ishere,fis#{f.inspect}"

IO.popen(%wsed-es|^|<foo>|-es&$&;zot;&","r+"){|f

f.puts"bar";f.close_write;putsf.gets

produces:

["Linux\n"]

Parentis21346

ThuJan1522:41:19JST2009

21346ishere,fis#<IO:fd3>

21352ishere,fisnil

#<Process::Status:pid21352exit0>

<foo>bar;zot;

Opensthefile,optionallyseekstothegivenoffset,thenreturnslengthbytes(defaultingtotherestofthefile).readensuresthefileisclosedbeforereturning.

OptionsTheoptionshashacceptsthefollowingkeys:

encodingstringorencoding

Specifiestheencodingofthereadstring.encoding:willbeignorediflengthisspecified.SeeEncoding.aliasesforpossibleencodings.

modestring

Specifiesthemodeargumentforopen().Itmuststartwithan“r”otherwiseitwillcauseanerror.See::newforthelistofpossiblemodes.

open_argsarrayofstrings

Specifiesargumentsforopen()asanarray.Thiskeycannotbeusedincombinationwitheitherencoding:ormode:.

Examples:

IO.read("testfile")#=>"Thisislineone\nThisislinetwo\nThisislinethree\nAndsoon...\n"

IO.read("testfile",20)#=>"Thisislineone\nThi"

IO.read("testfile",20,10)#=>"neone\nThisisline"

IO.read("binfile",mode:"rb")#=>"\xF7\x00\x00\x0E\x12"

read(name,[length[,offset]][,opt])→string

readlines(name,sep=$/[,open_args])→

Readstheentirefilespecifiedbynameasindividuallines,andreturnsthoselinesinanarray.Linesareseparatedbysep.

a=IO.readlines("testfile")

a[0]#=>"Thisislineone\n"

Ifthelastargumentisahash,it'sthekeywordargumenttoopen.SeeIO.readfordetail.

Callsselect(2)systemcall.ItmonitorsgivenarraysofIOobjects,waitsoneormoreofIOobjectsreadyforreading,arereadyforwriting,andhavependingexceptionsrespectively,andreturnsanarraythatcontainsarraysofthoseIOobjects.ItwillreturnnilifoptionaltimeoutvalueisgivenandnoIOobjectisreadyintimeoutseconds.

IO.selectpeeksthebufferofIOobjectsfortestingreadability.IftheIObufferisnotempty,IO.selectimmediatelynotifyreadability.This“peek”isonlyhappenforIOobjects.ItisnothappenforIO-likeobjectssuchasOpenSSL::SSL::SSLSocket.

ThebestwaytouseIO.selectisinvokingitafternonblockingmethodssuchasread_nonblock,write_nonblock,etc.ThemethodsraisesanexceptionwhichisextendedbyIO::WaitReadableor

arrayreadlines(name,limit[,open_args])→arrayreadlines(name,sep,limit[,open_args])→array

select(read_array[,write_array[,error_array[,timeout]]])→arrayornil

IO::WaitWritable.ThemodulesnotifyhowthecallershouldwaitwithIO.select.IfIO::WaitReadableisraised,thecallershouldwaitforreading.IfIO::WaitWritableisraised,thecallershouldwaitforwriting.

So,blockingread(readpartial)canbeemulatedusingread_nonblockandIO.selectasfollows:

result=io_like.read_nonblock(maxlen)

rescueIO::WaitReadable

IO.select([io_like])

rescueIO::WaitWritable

IO.select(nil,[io_like])

Especially,thecombinationofnonblockingmethodsandIO.selectispreferredforIOlikeobjectssuchasOpenSSL::SSL::SSLSocket.Ithasto_iomethodtoreturnunderlyingIOobject.IO.selectcallsto_iotoobtainthefiledescriptortowait.

ThismeansthatreadabilitynotifiedbyIO.selectdoesn'tmeanreadabilityfromOpenSSL::SSL::SSLSocketobject.

MostpossiblesituationisOpenSSL::SSL::SSLSocketbufferssomedata.IO.selectdoesn'tseethebuffer.SoIO.selectcanblockwhenOpenSSL::SSL::SSLSocket#readpartialdoesn'tblock.

Howeverseveralmorecomplicatedsituationexists.

SSLisaprotocolwhichissequenceofrecords.Therecordconsistsmultiplebytes.So,theremotesideofSSLsendsapartialrecord,IO.selectnotifiesreadabilitybutOpenSSL::SSL::SSLSocketcannot

decryptabyteandOpenSSL::SSL::SSLSocket#readpartialwillblocks.

Also,theremotesidecanrequestSSLrenegotiationwhichforcesthelocalSSLenginewritessomedata.ThismeansOpenSSL::SSL::SSLSocket#readpartialmayinvokewritesystemcallanditcanblock.Insuchsituation,OpenSSL::SSL::SSLSocket#read_nonblockraisesIO::WaitWritableinsteadofblocking.So,thecallershouldwaitforreadyforwritabilityasaboveexample.

ThecombinationofnonblockingmethodsandIO.selectisalsousefulforstreamssuchastty,pipesocketsocketwhenmultipleprocessreadformastream.

Finally,Linuxkerneldevelopersdoesn'tguaranteethatreadabilityofselect(2)meansreadabilityoffollowingread(2)evenforsingleprocess.Seeselect(2)manualonGNU/Linuxsystem.

InvokingIO.selectbeforeIO#readpartialworkswellinusual.HoweveritisnotthebestwaytouseIO.select.

Thewritabilitynotifiedbyselect(2)doesn'tshowhowmanybyteswritable.IO#writemethodblocksuntilgivenwholestringiswritten.So,IO#write(twoormorebytes)canblockafterwritabilityisnotifiedbyIO.select.IO#write_nonblockisrequiredtoavoidtheblocking.

Blockingwrite(write)canbeemulatedusingwrite_nonblockandIO.selectasfollows:IO::WaitReadableshouldalsoberescuedforSSLrenegotiationinOpenSSL::SSL::SSLSocket.

while0<string.bytesize

written=io_like.write_nonblock(string)

string=string.byteslice(written..-1)

Parametersread_arrayanarrayofIOobjectsthatwaituntilreadyforread

write_arrayanarrayofIOobjectsthatwaituntilreadyforwrite

error_arrayanarrayofIOobjectsthatwaitforexceptions

timeoutanumericvalueinsecond

Examplerp,wp=IO.pipe

mesg="ping"

100.times{

#IO.selectfollowsIO#read.NotthebestwaytouseIO.select.

rs,ws,=IO.select([rp],[wp])

ifr=rs[0]

ret=r.read(5)

printret

caseret

when/ping/

mesg="pong\n"

when/pong/

mesg="ping"

ifw=ws[0]

w.write(mesg)

produces:

pingpong

(snipped)

Opensthegivenpath,returningtheunderlyingfiledescriptorasaFixnum.

IO.sysopen("testfile")#=>3

TrytoconvertobjintoanIO,using#to_iomethod.ReturnsconvertedIOornilifobjcannotbeconvertedforanyreason.

IO.try_convert(STDOUT)#=>STDOUT

IO.try_convert("STDOUT")#=>nil

require'zlib'

f=open("/tmp/zz.gz")#=>#<File:/tmp/zz.gz>

z=Zlib::GzipReader.open(f)#=>#<Zlib::GzipReader:0x81d8744>

IO.try_convert(z)#=>#<File:/tmp/zz.gz>

Opensthefile,optionallyseekstothegivenoffset,

sysopen(path,[mode,[perm]])→fixnum

try_convert(obj)→ioornil

write(name,string,[offset])→fixnumwrite(name,string,[offset],open_args)→fixnum

writesstring,thenreturnsthelengthwritten.writeensuresthefileisclosedbeforereturning.Ifoffsetisnotgiven,thefileistruncated.Otherwise,itisnottruncated.

Ifthelastargumentisahash,itspecifiesoptionforinternalopen().Thekeywouldbethefollowing.open_args:isexclusivetoothers.

encoding:stringorencoding

specifiesencodingofthereadstring.encodingwill

iflengthisspecified.

mode:string

specifiesmodeargumentforopen().itshouldstart

otherwiseitwouldcauseerror.

perm:fixnum

specifiespermargumentforopen().

open_args:array

specifiesargumentsforopen()asanarray.

IO.write("testfile","0123456789",20)#=>10

#Filecouldcontain:"Thisislineone\nThi0123456789two\nThisislinethree\nAndsoon...\n"

IO.write("testfile","0123456789")#=>10

#Filewouldnowread:"0123456789"

StringOutput—Writesobjtoios.objwillbeconvertedtoastringusingto_s.

$stdout<<"Hello"<<"world!\n"

ios<<obj→ios

produces:

Helloworld!

Announceanintentiontoaccessdatafromthecurrentfileinaspecificpattern.Onplatformsthatdonotsupporttheposix_fadvise(2)systemcall,thismethodisano-op.

adviceisoneofthefollowingsymbols:

:normalNoadvicetogive;thedefaultassumptionforanopenfile.

:sequentialThedatawillbeaccessedsequentiallywithloweroffsetsreadbeforehigherones.

:randomThedatawillbeaccessedinrandomorder.

:willneedThedatawillbeaccessedinthenearfuture.

:dontneedThedatawillnotbeaccessedinthenearfuture.

:noreuseThedatawillonlybeaccessedonce.

Thesemanticsofapieceofadviceareplatform-dependent.Seeman2posix_fadvisefordetails.

“data”meanstheregionofthecurrentfilethatbeginsatoffsetandextendsforlenbytes.Iflenis0,theregionendsatthelastbyteofthefile.Bydefault,bothoffsetandlenare0,meaningthattheadviceappliestotheentirefile.

advise(advice,offset=0,len=0)→nil

Ifanerroroccurs,oneofthefollowingexceptionswillberaised:IOError

TheIOstreamisclosed.

Errno::EBADF

Thefiledescriptorofthecurrentfileisinvalid.

Errno::EINVAL

Aninvalidvalueforadvicewasgiven.

Errno::ESPIPE

ThefiledescriptorofthecurrentfilereferstoaFIFOorpipe.(LinuxraisesErrno::EINVALinthiscase).

TypeError

EitheradvicewasnotaSymbol,oroneoftheotherargumentswasnotanInteger.

RangeError

Oneoftheargumentsgivenwastoobig/small.

Thislistisnotexhaustive;otherErrnoexceptionsarealsopossible.

Setsauto-closeflag.

f=open("/dev/null")

IO.for_fd(f.fileno)

f.gets#maycauseIOError

f=open("/dev/null")

IO.for_fd(f.fileno).autoclose=true

f.gets#won'tcauseIOError

autoclose=bool→trueorfalse

autoclose?→trueorfalse

Returnstrueiftheunderlyingfiledescriptorofioswillbeclosedautomaticallyatitsfinalization,otherwisefalse.

Putsiosintobinarymode.Onceastreamisinbinarymode,itcannotberesettononbinarymode.

newlineconversiondisabled

encodingconversiondisabled

contentistreatedasASCII-8BIT

Returnstrueifiosisbinmode.

Thisisadeprecatedaliasforeach_byte.

Thisisadeprecatedaliasforeach_char.

Closesiosandflushesanypendingwritestotheoperatingsystem.Thestreamisunavailableforanyfurtherdataoperations;anIOErrorisraisedifsuchanattemptismade.I/Ostreamsareautomaticallyclosedwhentheyareclaimedbythegarbagecollector.

IfiosisopenedbyIO.popen,closesets$?.

binmode→ios

binmode?→trueorfalse

bytes()

chars()

close→nil

Setsaclose-on-execflag.

f=open("/dev/null")

f.close_on_exec=true

system("cat","/proc/self/fd/#{f.fileno}")#cat:/proc/self/fd/3:Nosuchfileordirectory

f.closed?#=>false

Rubysetsclose-on-execflagsofallfiledescriptorsbydefaultsinceRuby2.0.0.Soyoudon'tneedtosetbyyourself.Also,unsettingaclose-on-execflagcancausefiledescriptorleakifanotherthreadusefork()andexec()(viasystem()methodforexample).Ifyoureallyneedsfiledescriptorinheritancetochildprocess,usespawn()'sargumentsuchasfd=>fd.

Returnstrueifioswillbeclosedonexec.

f=open("/dev/null")

f.close_on_exec?#=>false

f.close_on_exec=true

f.close_on_exec?#=>true

f.close_on_exec=false

f.close_on_exec?#=>false

ClosesthereadendofaduplexI/Ostream(i.e.,onethatcontainsbothareadandawritestream,suchasapipe).WillraiseanIOErrorifthestreamisnotduplexed.

f=IO.popen("/bin/sh","r+")

f.close_read

f.readlines

produces:

close_on_exec=bool→trueorfalse

close_on_exec?→trueorfalse

close_read→nil

prog.rb:3:in`readlines':notopenedforreading(IOError)

fromprog.rb:3

ClosesthewriteendofaduplexI/Ostream(i.e.,onethatcontainsbothareadandawritestream,suchasapipe).WillraiseanIOErrorifthestreamisnotduplexed.

f.close_write

f.print"nowhere"

produces:

prog.rb:3:in`write':notopenedforwriting(IOError)

fromprog.rb:3:in`print'

fromprog.rb:3

Returnstrueifiosiscompletelyclosed(forduplexstreams,bothreaderandwriter),falseotherwise.

f=File.new("testfile")

f.close#=>nil

f.closed?#=>true

f.close_write#=>nil

f.closed?#=>false

f.close_read#=>nil

f.closed?#=>true

Thisisadeprecatedaliasforeach_codepoint.

close_write→nil

closed?→trueorfalse

codepoints()

Executestheblockforeverylineinios,wherelinesareseparatedbysep.iosmustbeopenedforreadingoranIOErrorwillberaised.

f.each{|line|puts"#{f.lineno}:#{line}"}

produces:

1:Thisislineone

2:Thisislinetwo

3:Thisislinethree

4:Andsoon...

Callsthegivenblockonceforeachbyte(0..255)inios,passingthebyteasanargument.ThestreammustbeopenedforreadingoranIOErrorwillberaised.

checksum=0

each(sep=$/){|line|block}→ioseach(limit){|line|block}→ioseach(sep,limit){|line|block}→ioseach(...)→an_enumeratoreach_line(sep=$/){|line|block}→ioseach_line(limit){|line|block}→ioseach_line(sep,limit){|line|block}→ioseach_line(...)→an_enumerator

each_byte{|byte|block}→ioseach_byte→an_enumerator

f.each_byte{|x|checksum^=x}#=>#<File:testfile>

checksum#=>12

Callsthegivenblockonceforeachcharacterinios,passingthecharacterasanargument.ThestreammustbeopenedforreadingoranIOErrorwillberaised.

f.each_char{|c|printc,''}#=>#<File:testfile>

PassestheIntegerordinalofeachcharacterinios,passingthecodepointasanargument.ThestreammustbeopenedforreadingoranIOErrorwillberaised.

each_char{|c|block}→ioseach_char→an_enumerator

each_codepoint{|c|block}→ioscodepoints{|c|block}→ioseach_codepoint→an_enumeratorcodepoints→an_enumerator

each(sep=$/){|line|block}→ioseach(limit){|line|block}→ioseach(sep,limit){|line|block}→ioseach(...)→an_enumeratoreach_line(sep=$/){|line|block}→ios

Executestheblockforeverylineinios,wherelinesareseparatedbysep.iosmustbeopenedforreadingoranIOErrorwillberaised.

f.each{|line|puts"#{f.lineno}:#{line}"}

produces:

1:Thisislineone

2:Thisislinetwo

3:Thisislinethree

4:Andsoon...

Returnstrueifiosisatendoffilethatmeanstherearenomoredatatoread.ThestreammustbeopenedforreadingoranIOErrorwillberaised.

dummy=f.readlines

f.eof#=>true

Ifiosisastreamsuchaspipeorsocket,IO#eof?blocksuntiltheotherendsendssomedataorclosesit.

r,w=IO.pipe

Thread.new{sleep1;w.close}

r.eof?#=>trueafter1secondblocking

r,w=IO.pipe

Thread.new{sleep1;w.puts"a"}

each_line(limit){|line|block}→ioseach_line(sep,limit){|line|block}→ioseach_line(...)→an_enumerator

eof→trueorfalseeof?→trueorfalse

r.eof?#=>falseafter1secondblocking

r,w=IO.pipe

r.eof?#blocksforever

NotethatIO#eof?readsdatatotheinputbytebuffer.SoIO#sysreadmaynotbehaveasyouintendwithIO#eof?,unlessyoucallIO#rewindfirst(whichisnotavailableforsomestreams).

Returnstrueifiosisatendoffilethatmeanstherearenomoredatatoread.ThestreammustbeopenedforreadingoranIOErrorwillberaised.

dummy=f.readlines

f.eof#=>true

Ifiosisastreamsuchaspipeorsocket,IO#eof?blocksuntiltheotherendsendssomedataorclosesit.

r,w=IO.pipe

Thread.new{sleep1;w.close}

r.eof?#=>trueafter1secondblocking

r,w=IO.pipe

Thread.new{sleep1;w.puts"a"}

r.eof?#=>falseafter1secondblocking

r,w=IO.pipe

r.eof?#blocksforever

NotethatIO#eof?readsdatatotheinputbytebuffer.SoIO#sysreadmaynotbehaveasyouintendwithIO#eof?,unlessyoucallIO#rewindfirst(whichisnotavailableforsomestreams).

eof→trueorfalseeof?→trueorfalse

ReturnstheEncodingobjectthatrepresentstheencodingofthefile.Ifioiswritemodeandnoencodingisspecified,returnsnil.

Providesamechanismforissuinglow-levelcommandstocontrolorqueryfile-orientedI/Ostreams.Argumentsandresultsareplatformdependent.Ifargisanumber,itsvalueispasseddirectly.Ifitisastring,itisinterpretedasabinarysequenceofbytes(Array#packmightbeausefulwaytobuildthisstring).OnUnixplatforms,seefcntl(2)fordetails.Notimplementedonallplatforms.

Immediatelywritesallbuffereddatainiostodisk.

Iftheunderlyingoperatingsystemdoesnotsupportfdatasync(2),IO#fsynciscalledinstead(whichmightraiseaNotImplementedError).

Returnsanintegerrepresentingthenumericfiledescriptorforios.

$stdin.fileno#=>0

$stdout.fileno#=>1

Alsoaliasedas:to_i

Flushesanybuffereddatawithiniostotheunderlying

external_encoding→encoding

fcntl(integer_cmd,arg)→integer

fdatasync→0ornil

fileno→fixnumto_i→fixnum

flush→ios

operatingsystem(notethatthisisRubyinternalbufferingonly;theOSmaybufferthedataaswell).

$stdout.print"nonewline"

$stdout.flush

produces:

nonewline

Immediatelywritesallbuffereddatainiostodisk.NotethatfsyncdiffersfromusingIO#sync=.ThelatterensuresthatdataisflushedfromRuby'sbuffers,butdoesnotguaranteethattheunderlyingoperatingsystemactuallywritesittodisk.

NotImplementedErrorisraisediftheunderlyingoperatingsystemdoesnotsupportfsync(2).

Getsthenext8-bitbyte(0..255)fromios.Returnsnilifcalledatendoffile.

f.getbyte#=>84

f.getbyte#=>104

Readsaone-characterstringfromios.Returnsnilifcalledatendoffile.

f.getc#=>"h"

f.getc#=>"e"

fsync→0ornil

getbyte→fixnumornil

getc→stringornil

Readsthenext“line''fromtheI/Ostream;linesareseparatedbysep.Aseparatorofnilreadstheentirecontents,andazero-lengthseparatorreadstheinputaparagraphatatime(twosuccessivenewlinesintheinputseparateparagraphs).ThestreammustbeopenedforreadingoranIOErrorwillberaised.Thelinereadinwillbereturnedandalsoassignedto$_.Returnsnilifcalledatendoffile.Ifthefirstargumentisaninteger,oroptionalsecondargumentisgiven,thereturningstringwouldnotbelongerthanthegivenvalueinbytes.

File.new("testfile").gets#=>"Thisislineone\n"

$_#=>"Thisislineone\n"

ReturnastringdescribingthisIOobject.

ReturnstheEncodingoftheinternalstringifconversionisspecified.Otherwisereturnsnil.

Providesamechanismforissuinglow-levelcommandstocontrolorqueryI/Odevices.Argumentsandresultsareplatformdependent.Ifargisanumber,itsvalueispasseddirectly.Ifitisastring,itisinterpretedasabinarysequenceofbytes.OnUnixplatforms,seeioctl(2)fordetails.Not

gets(sep=$/)→stringornilgets(limit)→stringornilgets(sep,limit)→stringornil

inspect→string

internal_encoding→encoding

ioctl(integer_cmd,arg)→integer

implementedonallplatforms.

Returnstrueifiosisassociatedwithaterminaldevice(tty),falseotherwise.

File.new("testfile").isatty#=>false

File.new("/dev/tty").isatty#=>true

Returnsthecurrentlinenumberinios.Thestreammustbeopenedforreading.linenocountsthenumberoftimesgetsiscalledratherthanthenumberofnewlinesencountered.Thetwovalueswilldifferifgetsiscalledwithaseparatorotherthannewline.

Methodsthatuse$/likeeach,linesandreadlinewillalsoincrementlineno.

Seealsothe$.variable.

f.lineno#=>0

f.gets#=>"Thisislineone\n"

f.lineno#=>1

f.gets#=>"Thisislinetwo\n"

f.lineno#=>2

Manuallysetsthecurrentlinenumbertothegivenvalue.$.isupdatedonlyonthenextread.

$.#=>1

f.lineno=1000

isatty→trueorfalsetty?→trueorfalse

lineno→integer

lineno=integer→integer

f.lineno#=>1000

$.#=>1#linenooflastread

$.#=>1001#linenooflastread

Thisisadeprecatedaliasforeach_line.

ReturnstheprocessIDofachildprocessassociatedwithios.ThiswillbesetbyIO.popen.

pipe=IO.popen("-")

ifpipe

$stderr.puts"Inparent,childpidis#{pipe.pid}"

$stderr.puts"Inchild,pidis#{$$}"

produces:

Inchild,pidis26209

Inparent,childpidis26209

Returnsthecurrentoffset(inbytes)ofios.

f.pos#=>0

f.pos#=>17

Seekstothegivenposition(inbytes)inios.Itisnot

lines(*args)

pid→fixnum

pos=integer→integer

guaranteedthatseekingtotherightpositionwheniosistextmode.

f.pos=17

Writesthegivenobject(s)toios.Thestreammustbeopenedforwriting.Iftheoutputfieldseparator($,)isnotnil,itwillbeinsertedbetweeneachobject.Iftheoutputrecordseparator($\</code>)isnot<code>nil,itwillbeappendedtotheoutput.Ifnoargumentsaregiven,prints$_.Objectsthataren'tstringswillbeconvertedbycallingtheirto_smethod.Withnoargument,printsthecontentsofthevariable$_.Returnsnil.

$stdout.print("Thisis",100,"percent.\n")

produces:

Thisis100percent.

Formatsandwritestoios,convertingparametersundercontroloftheformatstring.SeeKernel#sprintffordetails.

IfobjisNumeric,writethecharacterwhosecodeistheleast-significantbyteofobj,otherwisewritethefirstbyteofthestringrepresentationofobjtoios.

print()→nilprint(obj,...)→nil

printf(format_string[,obj,...])→nil

putc(obj)→obj

Note:Thismethodisnotsafeforusewithmulti-bytecharactersasitwilltruncatethem.

$stdout.putc"A"

$stdout.putc65

produces:

WritesthegivenobjectstoiosaswithIO#print.Writesarecordseparator(typicallyanewline)afteranythatdonotalreadyendwithanewlinesequence.Ifcalledwithanarrayargument,writeseachelementonanewline.Ifcalledwithoutarguments,outputsasinglerecordseparator.

$stdout.puts("this","is","a","test")

produces:

ReadslengthbytesfromtheI/Ostream.

lengthmustbeanon-negativeintegerornil.

Iflengthisapositiveinteger,ittriestoreadlengthbyteswithoutanyconversion(binarymode).Itreturnsnilorastringwhoselengthis1tolengthbytes.nilmeansitmetEOFatbeginning.The1tolength-1bytesstringmeansitmetEOFafterreading

puts(obj,...)→nil

read([length[,outbuf]])→string,outbuf,ornil

theresult.Thelengthbytesstringmeansitdoesn'tmeetEOF.TheresultedstringisalwaysASCII-8BITencoding.

Iflengthisomittedorisnil,itreadsuntilEOFandtheencodingconversionisapplied.ItreturnsastringevenifEOFismetatbeginning.

Iflengthiszero,itreturns"".

Iftheoptionaloutbufargumentispresent,itmustreferenceaString,whichwillreceivethedata.Theoutbufwillcontainonlythereceiveddataafterthemethodcallevenifitisnotemptyatthebeginning.

Atendoffile,itreturnsnilor""dependonlength.ios.read()andios.read(nil)returns"".ios.read(positive-integer)returnsnil.

f.read(16)#=>"Thisislineone"

#readswholefile

open("file"){|f|

data=f.read#Thisreturnsastringevenifthefileisempty.

#iterateoverfixedlengthrecords.

open("fixed-record-file"){|f|

whilerecord=f.read(256)

#iterateovervariablelengthrecords.

#recordisprefixedby32-bitlength.

open("variable-record-file"){|f|

whilelen=f.read(4)

len=len.unpack("N")[0]#32-bitlength

record=f.read(len)#Thisreturnsastringeveniflenis0.

Notethatthismethodbehaveslikefread()functioninC.Thismeansitretrytoinvokeread(2)systemcalltoreaddatawiththespecifiedlength(oruntilEOF).Thisbehaviorispreservedevenifiosisnon-blockingmode.(Thismethodisnon-blockingflaginsensitiveasothermethods.)Ifyouneedthebehaviorlikesingleread(2)systemcall,considerreadpartial,#read_nonblockandsysread.

Readsatmostmaxlenbytesfromiosusingtheread(2)systemcallafterO_NONBLOCKissetfortheunderlyingfiledescriptor.

Iftheoptionaloutbufargumentispresent,itmustreferenceaString,whichwillreceivethedata.Theoutbufwillcontainonlythereceiveddataafterthemethodcallevenifitisnotemptyatthebeginning.

#read_nonblockjustcallstheread(2)systemcall.Itcausesallerrorstheread(2)systemcallcauses:Errno::EWOULDBLOCK,Errno::EINTR,etc.Thecallershouldcaresucherrors.

IftheexceptionisErrno::EWOULDBLOCKorErrno::AGAIN,itisextendedbyIO::WaitReadable.SoIO::WaitReadablecanbeusedtorescuetheexceptionsforretryingread_nonblock.

#read_nonblockcausesEOFErroronEOF.

Ifthereadbytebufferisnotempty,#read_nonblockreadsfromthebufferlikereadpartial.Inthiscase,theread(2)systemcallisnotcalled.

When#read_nonblockraisesanexceptionkindofIO::WaitReadable,#read_nonblockshouldnotbecalleduntilioisreadableforavoidingbusyloop.This

read_nonblock(maxlen)→stringread_nonblock(maxlen,outbuf)→outbuf

canbedoneasfollows.

#emulatesblockingread(readpartial).

result=io.read_nonblock(maxlen)

IO.select([io])

Although#read_nonblockdoesn'traiseIO::WaitWritable.OpenSSL::Buffering#read_nonblockcanraiseIO::WaitWritable.IfIOandSSLshouldbeusedpolymorphically,IO::WaitWritableshouldberescuedtoo.SeethedocumentofOpenSSL::Buffering#read_nonblockforsamplecode.

Notethatthismethodisidenticaltoreadpartialexceptthenon-blockingflagisset.

ReadsabyteaswithIO#getbyte,butraisesanEOFErroronendoffile.

Readsaone-characterstringfromios.RaisesanEOFErroronendoffile.

f.readchar#=>"h"

f.readchar#=>"e"

ReadsalineaswithIO#gets,butraisesanEOFErroronendoffile.

readbyte→fixnum

readchar→string

readline(sep=$/)→stringreadline(limit)→stringreadline(sep,limit)→string

Readsallofthelinesinios,andreturnstheminanArray.Linesareseparatedbytheoptionalsep.Ifsepisnil,therestofthestreamisreturnedasasinglerecord.Ifthefirstargumentisaninteger,oroptionalsecondargumentisgiven,thereturningstringwouldnotbelongerthanthegivenvalueinbytes.ThestreammustbeopenedforreadingoranIOErrorwillberaised.

f.readlines[0]#=>"Thisislineone\n"

ReadsatmostmaxlenbytesfromtheI/Ostream.Itblocksonlyifioshasnodataimmediatelyavailable.Itdoesn'tblockifsomedataavailable.Iftheoptionaloutbufargumentispresent,itmustreferenceaString,whichwillreceivethedata.Theoutbufwillcontainonlythereceiveddataafterthemethodcallevenifitisnotemptyatthebeginning.ItraisesEOFErroronendoffile.

readpartialisdesignedforstreamssuchaspipe,socket,tty,etc.Itblocksonlywhennodataimmediatelyavailable.Thismeansthatitblocksonlywhenfollowingallconditionshold.

thebytebufferintheIOobjectisempty.

thecontentofthestreamisempty.

thestreamisnotreachedtoEOF.

readlines(sep=$/)→arrayreadlines(limit)→arrayreadlines(sep,limit)→array

readpartial(maxlen)→stringreadpartial(maxlen,outbuf)→outbuf

Whenreadpartialblocks,itwaitsdataorEOFonthestream.Ifsomedataisreached,readpartialreturnswiththedata.IfEOFisreached,readpartialraisesEOFError.

Whenreadpartialdoesn'tblocks,itreturnsorraisesimmediately.Ifthebytebufferisnotempty,itreturnsthedatainthebuffer.Otherwiseifthestreamhassomecontent,itreturnsthedatainthestream.OtherwiseifthestreamisreachedtoEOF,itraisesEOFError.

r,w=IO.pipe#bufferpipecontent

w<<"abc"#"""abc".

r.readpartial(4096)#=>"abc"""""

r.readpartial(4096)#blocksbecausebufferandpipeisempty.

w<<"abc"#"""abc"

w.close#"""abc"EOF

r.readpartial(4096)#=>"abc"""EOF

r.readpartial(4096)#raisesEOFError

w<<"abc\ndef\n"#"""abc\ndef\n"

r.gets#=>"abc\n""def\n"""

w<<"ghi\n"#"def\n""ghi\n"

r.readpartial(4096)#=>"def\n""""ghi\n"

r.readpartial(4096)#=>"ghi\n"""""

Notethatreadpartialbehavessimilartosysread.Thedifferencesare:

Ifthebytebufferisnotempty,readfromthebytebufferinsteadof“sysreadforbufferedIO(IOError)”.

Itdoesn'tcauseErrno::EWOULDBLOCKandErrno::EINTR.WhenreadpartialmeetsEWOULDBLOCKandEINTRbyreadsystemcall,readpartialretrythesystemcall.

Thelatermeansthatreadpartialisnonblocking-flag

insensitive.Itblocksonthesituation#sysreadcausesErrno::EWOULDBLOCKasifthefdisblockingmode.

ReassociatesioswiththeI/Ostreamgiveninother_IOortoanewstreamopenedonpath.Thismaydynamicallychangetheactualclassofthisstream.

f1=File.new("testfile")

f2=File.new("testfile")

f2.readlines[0]#=>"Thisislineone\n"

f2.reopen(f1)#=>#<File:testfile>

f2.readlines[0]#=>"Thisislineone\n"

Positionsiostothebeginningofinput,resettinglinenotozero.

f.readline#=>"Thisislineone\n"

f.rewind#=>0

f.lineno#=>0

f.readline#=>"Thisislineone\n"

Notethatitcannotbeusedwithstreamssuchaspipes,ttys,andsockets.

SeekstoagivenoffsetanIntegerinthestreamaccordingtothevalueofwhence:

:CURorIO::SEEK_CUR|Seeksto_amount_pluscurrentposition

----------------------+--------------------------------------------------

:ENDorIO::SEEK_END|Seeksto_amount_plusendofstream(you

|probablywantanegativevaluefor_amount_)

----------------------+--------------------------------------------------

reopen(other_IO)→iosreopen(path,mode_str)→ios

rewind→0

seek(amount,whence=IO::SEEK_SET)→0

:SETorIO::SEEK_SET|Seekstotheabsolutelocationgivenby_amount_

Example:

f.seek(-13,IO::SEEK_END)#=>0

f.readline#=>"Andsoon...\n"

Ifsingleargumentisspecified,readstringfromioistaggedwiththeencodingspecified.Ifencodingisacolonseparatedtwoencodingnames“A:B”,thereadstringisconvertedfromencodingA(externalencoding)toencodingB(internalencoding),thentaggedwithB.Iftwoargumentsarespecified,thosemustbeencodingobjectsorencodingnames,andthefirstoneistheexternalencoding,andthesecondoneistheinternalencoding.Iftheexternalencodingandtheinternalencodingisspecified,optionalhashargumentspecifytheconversionoption.

ReturnsstatusinformationforiosasanobjectoftypeFile::Stat.

s=f.stat

"%o"%s.mode#=>"100644"

s.blksize#=>4096

s.atime#=>WedApr0908:53:54CDT2003

set_encoding(ext_enc)→ioset_encoding("ext_enc:int_enc")→ioset_encoding(ext_enc,int_enc)→ioset_encoding("ext_enc:int_enc",opt)→ioset_encoding(ext_enc,int_enc,opt)→io

stat→stat

Returnsthecurrent“syncmode''ofios.Whensyncmodeistrue,alloutputisimmediatelyflushedtotheunderlyingoperatingsystemandisnotbufferedbyRubyinternally.SeealsoIO#fsync.

f.sync#=>false

Setsthe“syncmode''totrueorfalse.Whensyncmodeistrue,alloutputisimmediatelyflushedtotheunderlyingoperatingsystemandisnotbufferedinternally.Returnsthenewstate.SeealsoIO#fsync.

f.sync=true

(producesnooutput)

Readsmaxlenbytesfromiosusingalow-levelreadandreturnsthemasastring.Donotmixwithothermethodsthatreadfromiosoryoumaygetunpredictableresults.Iftheoptionaloutbufargumentispresent,itmustreferenceaString,whichwillreceivethedata.Theoutbufwillcontainonlythereceiveddataafterthemethodcallevenifitisnotemptyatthebeginning.RaisesSystemCallErroronerrorandEOFErroratendoffile.

f.sysread(16)#=>"Thisislineone"

sync→trueorfalse

sync=boolean→boolean

sysread(maxlen[,outbuf])→string

Seekstoagivenoffsetinthestreamaccordingtothevalueofwhence(seeIO#seekforvaluesofwhence).Returnsthenewoffsetintothefile.

f.sysseek(-13,IO::SEEK_END)#=>53

f.sysread(10)#=>"Andsoon."

Writesthegivenstringtoiosusingalow-levelwrite.Returnsthenumberofbyteswritten.Donotmixwithothermethodsthatwritetoiosoryoumaygetunpredictableresults.RaisesSystemCallErroronerror.

f.syswrite("ABCDEF")#=>6

Returnsthecurrentoffset(inbytes)ofios.

f.pos#=>0

f.pos#=>17

Aliasfor:fileno

Returnsios.

sysseek(offset,whence=IO::SEEK_SET)→integer

syswrite(string)→integer

to_i()

to_io→ios

Returnstrueifiosisassociatedwithaterminaldevice(tty),falseotherwise.

File.new("testfile").isatty#=>false

File.new("/dev/tty").isatty#=>true

Pushesbackbytes(passedasaparameter)ontoios,suchthatasubsequentbufferedreadwillreturnit.Onlyonebytemaybepushedbackbeforeasubsequentreadoperation(thatis,youwillbeabletoreadonlythelastofseveralbytesthathavebeenpushedback).Hasnoeffectwithunbufferedreads(suchasIO#sysread).

f=File.new("testfile")#=>#<File:testfile>

b=f.getbyte#=>0x38

f.ungetbyte(b)#=>nil

f.getbyte#=>0x38

Pushesbackonecharacter(passedasaparameter)ontoios,suchthatasubsequentbufferedcharacterreadwillreturnit.Onlyonecharactermaybepushedbackbeforeasubsequentreadoperation(thatis,youwillbeabletoreadonlythelastofseveralcharactersthathavebeenpushedback).Hasnoeffectwithunbufferedreads(suchasIO#sysread).

f=File.new("testfile")#=>#<File:testfile>

c=f.getc#=>"8"

f.ungetc(c)#=>nil

isatty→trueorfalsetty?→trueorfalse

ungetbyte(string)→nilungetbyte(integer)→nil

ungetc(string)→nil

f.getc#=>"8"

Writesthegivenstringtoios.Thestreammustbeopenedforwriting.Iftheargumentisnotastring,itwillbeconvertedtoastringusingto_s.Returnsthenumberofbyteswritten.

count=$stdout.write("Thisisatest\n")

puts"Thatwas#{count}bytesofdata"

produces:

Thisisatest

Thatwas15bytesofdata

Writesthegivenstringtoiosusingthewrite(2)systemcallafterO_NONBLOCKissetfortheunderlyingfiledescriptor.

Itreturnsthenumberofbyteswritten.

#write_nonblockjustcallsthewrite(2)systemcall.Itcausesallerrorsthewrite(2)systemcallcauses:Errno::EWOULDBLOCK,Errno::EINTR,etc.Theresultmayalsobesmallerthanstring.length(partialwrite).Thecallershouldcaresucherrorsandpartialwrite.

IftheexceptionisErrno::EWOULDBLOCKorErrno::AGAIN,itisextendedbyIO::WaitWritable.SoIO::WaitWritablecanbeusedtorescuetheexceptionsforretryingwrite_nonblock.

#Createsapipe.

r,w=IO.pipe

write(string)→integer

write_nonblock(string)→integerwrite_nonblock(string[,options])→integer

#write_nonblockwritesonly65536bytesandreturn65536.

#(Thepipesizeis65536bytesonthisenvironment.)

s="a"*100000

pw.write_nonblock(s)#=>65536

#write_nonblockcannotwriteabyteandraiseEWOULDBLOCK(EAGAIN).

pw.write_nonblock("b")#Resourcetemporarilyunavailable(Errno::EAGAIN)

Ifthewritebufferisnotempty,itisflushedatfirst.

When#write_nonblockraisesanexceptionkindofIO::WaitWritable,#write_nonblockshouldnotbecalleduntilioiswritableforavoidingbusyloop.Thiscanbedoneasfollows.

result=io.write_nonblock(string)

rescueIO::WaitWritable,Errno::EINTR

IO.select(nil,[io])

Notethatthisdoesn'tguaranteetowritealldatainstring.Thelengthwrittenisreportedasresultanditshouldbecheckedlater.

OnsomeplatformssuchasWindows,#write_nonblockisnotsupportedaccordingtothekindoftheIOobject.Insuchcases,#write_nonblockraisesErrno::EBADF.

Byspecifying`exception:false`,theoptionshashallowsyoutoindicatethat#write_nonblockshouldnotraiseanIO::WaitWritableexception,butreturnthesymbol:wait_writableinstead.

classIO::EAGAINWaitReadable

InFilesfile.c

Parentrb_eEAGAIN

IncludedModulesIO::WaitReadable

classIO::EAGAINWaitWritable

InFilesfile.c

Parentrb_eEAGAIN

IncludedModulesIO::WaitWritable

classIO::EINPROGRESSWaitReadable

InFilesfile.c

Parentrb_eEINPROGRESS

classIO::EINPROGRESSWaitWritable

InFilesfile.c

Parentrb_eEINPROGRESS

classIO::EWOULDBLOCKWaitReadable

InFilesfile.c

Parentrb_eEWOULDBLOCK

classIO::EWOULDBLOCKWaitWritable

InFilesfile.c

Parentrb_eEWOULDBLOCK

moduleIO::WaitReadable

InFilesfile.c

moduleIO::WaitWritable

InFilesfile.c

classIOErrorRaisedwhenanIOoperationfails.

File.open("/etc/hosts"){|f|f<<"example"}

#=>IOError:notopenedforwriting

File.open("/etc/hosts"){|f|f.close;f.read}

#=>IOError:closedstream

NotethatsomeIOfailuresraise+SystemCallError+sandthesearenotsubclassesofIOError:

File.open("does/not/exist")

#=>Errno::ENOENT:Nosuchfileordirectory-does/not/exist

InFilesio.c

ParentStandardError

classIndexErrorRaisedwhenthegivenindexisinvalid.

a=[:foo,:bar]

a.fetch(0)#=>:foo

a[4]#=>nil

a.fetch(4)#=>IndexError:index4outsideofarraybounds:-2...2

InFileserror.c

ParentStandardError

classIntegerThisclassisthebasisforthetwoconcreteclassesthatholdwholenumbers,BignumandFixnum.

InFilesnumeric.crational.c

ParentNumeric

AsintisalreadyanInteger,allthesemethodssimplyreturnthereceiver.

Synonymsareto_int,floor,ceil,truncate.

Returnsastringcontainingthecharacterrepresentedbytheint'svalueaccordingtoencoding.

65.chr#=>"A"

230.chr#=>"\346"

255.chr(Encoding::UTF_8)#=>"\303\277"

to_i→integer

chr([encoding])→string

Returns1.

Iteratesthegivenblock,passingdecreasingvaluesfromintdowntoandincludinglimit.

5.downto(1){|n|printn,".."}

print"Liftoff!\n"

#=>"5..4..3..2..1..Liftoff!"

Returnstrueifintisanevennumber.

Returnsthegreatestcommondivisor(alwayspositive).0.gcd(x)andx.gcd(0)returnabs(x).

2.gcd(2)#=>2

3.gcd(-7)#=>1

((1<<31)-1).gcd((1<<61)-1)#=>1

Returnsanarray;[int.gcd(int2),int.lcm(int2)].

denominator→1

downto(limit){|i|block}→selfdownto(limit)→an_enumerator

even?→trueorfalse

to_i→integer

gcd(int2)→integer

gcdlcm(int2)→array

2.gcdlcm(2)#=>[2,2]

3.gcdlcm(-7)#=>[1,21]

((1<<31)-1).gcdlcm((1<<61)-1)#=>[1,4951760154835678088235319297]

SinceintisalreadyanInteger,thisalwaysreturnstrue.

Returnstheleastcommonmultiple(alwayspositive).0.lcm(x)andx.lcm(0)returnzero.

2.lcm(2)#=>2

3.lcm(-7)#=>21

((1<<31)-1).lcm((1<<61)-1)#=>4951760154835678088235319297

ReturnstheIntegerequaltoint+1,sameas#next.

1.next#=>2

(-1).next#=>0

Returnsself.

Returnstrueifintisanoddnumber.

integer?→true

lcm(int2)→integer

numerator→self

odd?→trueorfalse

ord→self

Returnstheintitself.

a.ord#=>97

ThismethodisintendedforcompatibilitytocharacterconstantinRuby1.9.

Forexample,?a.ordreturns97bothin1.8and1.9.

ReturnstheIntegerequaltoint-1.

1.pred#=>0

(-1).pred#=>-2

Returnsthevalueasarational.Theoptionalargumentepsisalwaysignored.

Roundsinttoagivenprecisionindecimaldigits(default0digits).

Precisionmaybenegative.Returnsafloatingpointnumberwhenndigitsispositive,selfforzero,androunddownfornegative.

1.round#=>1

1.round(2)#=>1.0

15.round(-1)#=>20

ReturnstheIntegerequaltoint+1,sameas#next.

1.next#=>2

pred→integer

(-1).next#=>0

Iteratesthegivenblockinttimes,passinginvaluesfromzerotoint-1.

5.timesdo|i|

printi,""

#=>01234

Returnsthevalueasarational.

1.to_r#=>(1/1)

(1<<64).to_r#=>(18446744073709551616/1)

AsintisalreadyanInteger,allthesemethodssimply

times{|i|block}→selftimes→an_enumerator

to_i→integer

to_r→rational

to_i→integer

returnthereceiver.

Iteratesthegivenblock,passinginintegervaluesfromintuptoandincludinglimit.

Forexample:

5.upto(10){|i|printi,""}

#=>5678910

upto(limit){|i|block}→selfupto(limit)→an_enumerator

classInterruptRaisedwiththeinterruptsignalisreceived,typicallybecausetheuserpressedonControl-C(onmostposixplatforms).Assuch,itisasubclassofSignalException.

puts"Pressctrl-Cwhenyougetbored"

loop{}

rescueInterrupt=>e

puts"Note:YouwilltypicallyuseSignal.trapinstead."

produces:

Pressctrl-Cwhenyougetbored

thenwaitsuntilitisinterruptedwithControl-Candthenprints:

Note:YouwilltypicallyuseSignal.trapinstead.

InFileserror.csignal.c

ParentSignalException

moduleKernelTheKernelmoduleisincludedbyclassObject,soitsmethodsareavailableineveryRubyobject.

TheKernelinstancemethodsaredocumentedinclassObjectwhilethemodulemethodsaredocumentedhere.Thesemethodsarecalledwithoutareceiverandthuscanbecalledinfunctionalform:

sprintf"%.1f",1.234#=>"1.2"

InFilescomplex.ccont.cerror.ceval.ceval_jump.cfile.cio.cload.cobject.cproc.cprocess.crandom.crational.cruby.csignal.cvm_backtrace.c

vm_eval.cvm_trace.c

ReturnsargasanArray.

Firsttriestocallto_aryonarg,thento_a.

Array(1..5)#=>[1,2,3,4,5]

Returnsx+i*y;

Complex(1,2)#=>(1+2i)

Complex('1+2i')#=>(1+2i)

Complex(nil)#=>TypeError

Complex(1,nil)#=>TypeError

Syntaxofstringform:

stringform=extraspaces,complex,extraspaces;

complex=realpart|[sign],imaginarypart

|realpart,sign,imaginarypart

|rational,"@",rational;

realpart=rational;

imaginarypart=imaginaryunit|unsignedrational,imaginaryunit;

rational=[sign],unsignedrational;

unsignedrational=numerator|numerator,"/",denominator;

numerator=integerpart|fractionalpart|integerpart,fractionalpart;

denominator=digits;

integerpart=digits;

fractionalpart=".",digits,[("e"|"E"),[sign],digits];

imaginaryunit="i"|"I"|"j"|"J";

sign="-"|"+";

digits=digit,{digit|"_",digit};

digit="0"|"1"|"2"|"3"|"4"|"5"|"6"|"7"|"8"|"9";

extraspaces=?\s*?;

Array(arg)→array

Complex(x[,y])→numeric

SeeString#to_c.

Returnsargconvertedtoafloat.Numerictypesareconverteddirectly,therestareconvertedusingarg.to_f.ConvertingnilgeneratesaTypeError.

Float(1)#=>1.0

Float("123.456")#=>123.456

ConvertsargtoaHashbycallingarg.to_hash.ReturnsanemptyHashwhenargisnilor[].

Hash([])#=>{}

Hash(nil)#=>{}

Hash(key::value)#=>{:key=>:value}

Hash([1,2,3])#=>TypeError

ConvertsargtoaFixnumorBignum.Numerictypesareconverteddirectly(withfloatingpointnumbersbeingtruncated).base(0,orbetween2and36)isabaseforintegerstringrepresentation.IfargisaString,whenbaseisomittedorequalszero,radixindicators(0,0b,and0x)arehonored.Inanycase,stringsshouldbestrictlyconformedtonumericrepresentation.ThisbehaviorisdifferentfromthatofString#to_i.Nonstringvalueswillbeconvertedbyfirsttryingto_int,thento_i.PassingnilraisesaTypeError.

Integer(123.999)#=>123

Integer("0x1a")#=>26

Integer(Time.new)#=>1204973019

Integer("0930",10)#=>930

Float(arg)→float

Hash(arg)→hash

Integer(arg,base=0)→integer

Integer("111",2)#=>7

Integer(nil)#=>TypeError

Returnsx/y;

Rational(1,2)#=>(1/2)

Rational('1/2')#=>(1/2)

Rational(nil)#=>TypeError

Rational(1,nil)#=>TypeError

Syntaxofstringform:

stringform=extraspaces,rational,extraspaces;

rational=[sign],unsignedrational;

unsignedrational=numerator|numerator,"/",denominator;

numerator=integerpart|fractionalpart|integerpart,fractionalpart;

denominator=digits;

integerpart=digits;

fractionalpart=".",digits,[("e"|"E"),[sign],digits];

sign="-"|"+";

digits=digit,{digit|"_",digit};

digit="0"|"1"|"2"|"3"|"4"|"5"|"6"|"7"|"8"|"9";

extraspaces=?\s*?;

SeeString#to_r.

ReturnsargasaString.

Firsttriestocallitsto_strmethod,thenitsto_smethod.

String(self)#=>"main"

String(self.class)#=>"Object"

String(123456)#=>"123456"

Returnsthecallednameofthecurrentmethodasa

Rational(x[,y])→numeric

String(arg)→string

__callee__→symbol

Symbol.Ifcalledoutsideofamethod,itreturnsnil.

Returnsthecanonicalizedabsolutepathofthedirectoryofthefilefromwhichthismethodiscalled.Itmeanssymlinksinthepathisresolved.If__FILE__isnil,itreturnsnil.ThereturnvalueequalstoFile.dirname(File.realpath(__FILE__)).

ReturnsthenameatthedefinitionofthecurrentmethodasaSymbol.Ifcalledoutsideofamethod,itreturnsnil.

Returnsthestandardoutputofrunningcmdinasubshell.Thebuilt-insyntax%x{...}usesthismethod.Sets$?totheprocessstatus.

%xdate`#=>"WedApr908:56:30CDT2003\n"

%xlstestdir`.split[1]#=>"main.rb"

%xechooops&&exit99`#=>"oops\n"

$?.exitstatus#=>99

Terminateexecutionimmediately,effectivelybycallingKernel.exit(false).Ifmsgisgiven,itiswrittentoSTDERRpriortoterminating.

__dir__→string

__method__→symbol

`cmd`→string

abortKernel::abort([msg])Process::abort([msg])

ConvertsblocktoaProcobject(andthereforebindsitatthepointofcall)andregistersitforexecutionwhentheprogramexits.Ifmultiplehandlersareregistered,theyareexecutedinreverseorderofregistration.

defdo_at_exit(str1)

at_exit{printstr1}

at_exit{puts"cruelworld"}

do_at_exit("goodbye")

produces:

goodbyecruelworld

Registersfilenametobeloaded(usingKernel::require)thefirsttimethatmodule(whichmaybeaStringorasymbol)isaccessed.

autoload(:MyModule,"/usr/local/lib/modules/my_module.rb")

Returnsfilenametobeloadedifnameisregisteredasautoload.

autoload(:B,"b")

autoload?(:B)#=>"b"

ReturnsaBindingobject,describingthevariableandmethodbindingsatthepointofcall.Thisobjectcanbeusedwhencallingevaltoexecutetheevaluated

at_exit{block}→proc

autoload(module,filename)→nil

autoload?(name)→Stringornil

binding→a_binding

commandinthisenvironment.SeealsothedescriptionofclassBinding.

defget_binding(param)

returnbinding

b=get_binding("hello")

eval("param",b)#=>"hello"

Returnstrueifyieldwouldexecuteablockinthecurrentcontext.Theiterator?formismildlydeprecated.

deftry

ifblock_given?

"noblock"

try#=>"noblock"

try{"hello"}#=>"hello"

trydo"hello"end#=>"hello"

GeneratesaContinuationobject,whichitpassestotheassociatedblock.Youneedtorequire'continuation'beforeusingthismethod.Performingacont.callwillcausethecallcctoreturn(aswillfallingthroughtheendoftheblock).Thevaluereturnedbythecallccisthevalueoftheblock,orthevaluepassedtocont.call.SeeclassContinuationformoredetails.Alsosee#throwforanalternativemechanismforunwindingacallstack.

block_given?→trueorfalseiterator?→trueorfalse

callcc{|cont|block}→obj

Returnsthecurrentexecutionstack—anarraycontainingstringsintheformfile:lineorfile:line:in`method'.

Theoptionalstartparameterdeterminesthenumberofinitialstackentriestoomitfromthetopofthestack.

Asecondoptionallengthparametercanbeusedtolimithowmanyentriesarereturnedfromthestack.

Returnsnilifstartisgreaterthanthesizeofcurrentexecutionstack.

Optionallyyoucanpassarange,whichwillreturnanarraycontainingtheentrieswithinthespecifiedrange.

defa(skip)

caller(skip)

defb(skip)

a(skip)

defc(skip)

b(skip)

c(0)#=>["prog:2:in`a'","prog:5:in`b'","prog:8:in`c'","prog:10:in`<main>'"]

c(1)#=>["prog:5:in`b'","prog:8:in`c'","prog:11:in`<main>'"]

c(2)#=>["prog:8:in`c'","prog:12:in`<main>'"]

c(3)#=>["prog:13:in`<main>'"]

c(4)#=>[]

c(5)#=>nil

Returnsthecurrentexecutionstack—anarray

caller(start=1,length=nil)→arrayornilcaller(range)→arrayornil

caller_locations(start=1,length=nil)→arrayornilcaller_locations(range)→arrayornil

containingbacktracelocationobjects.

SeeThread::Backtrace::Locationformoreinformation.

Theoptionalstartparameterdeterminesthenumberofinitialstackentriestoomitfromthetopofthestack.

Asecondoptionallengthparametercanbeusedtolimithowmanyentriesarereturnedfromthestack.

Returnsnilifstartisgreaterthanthesizeofcurrentexecutionstack.

Optionallyyoucanpassarange,whichwillreturnanarraycontainingtheentrieswithinthespecifiedrange.

catchexecutesitsblock.Ifthrowisnotcalled,theblockexecutesnormally,andcatchreturnsthevalueofthelastexpressionevaluated.

catch(1){123}#=>123

If+throw(tag2,val)+iscalled,Rubysearchesupitsstackforacatchblockwhosetaghasthesameobject_idastag2.Whenfound,theblockstopsexecutingandreturnsval(ornilifnosecondargumentwasgiventothrow).

catch(1){throw(1,456)}#=>456

catch(1){throw(1)}#=>nil

Whentagispassedasthefirstargument,catchyieldsitastheparameteroftheblock.

catch(1){|x|x+2}#=>3

catch([tag]){|tag|block}→obj

Whennotagisgiven,catchyieldsanewuniqueobject(asfromObject.new)astheblockparameter.Thisobjectcanthenbeusedastheargumenttothrow,andwillmatchthecorrectcatchblock.

catchdo|obj_A|

catchdo|obj_B|

throw(obj_B,123)

puts"Thisputsisnotreached"

puts"Thisputsisdisplayed"

#=>456

catchdo|obj_A|

catchdo|obj_B|

throw(obj_A,123)

puts"Thisputsisstillnotreached"

puts"Nowthisputsisalsonotreached"

#=>123

Equivalentto$_=$_.chomp(string).SeeString#chomp.Availableonlywhen-p/-ncommandlineoptionspecified.

Equivalentto($_.dup).chop!,exceptnilisneverreturned.SeeString#chop!.Availableonlywhen-p/-ncommandlineoptionspecified.

chomp→$_chomp(string)→$_

chop→$_

EvaluatestheRubyexpression(s)instring.Ifbindingisgiven,whichmustbeaBindingobject,theevaluationisperformedinitscontext.Iftheoptionalfilenameandlinenoparametersarepresent,theywillbeusedwhenreportingsyntaxerrors.

defget_binding(str)

returnbinding

str="hello"

eval"str+'Fred'"#=>"helloFred"

eval"str+'Fred'",get_binding("bye")#=>"byeFred"

Replacesthecurrentprocessbyrunningthegivenexternalcommand,whichcantakeoneofthefollowingforms:

exec(commandline)

commandlinestringwhichispassedtothestandardshell

exec(cmdname,arg1,...)

commandnameandoneormorearguments(noshell)

exec([cmdname,argv0],arg1,...)

commandname,argvandzeroormorearguments(noshell)

Inthefirstform,thestringistakenasacommandlinethatissubjecttoshellexpansionbeforebeingexecuted.

eval(string[,binding[,filename[,lineno]]])→obj

exec([env,]command...[,options])

Thestandardshellalwaysmeans"/bin/sh"onUnix-likesystems,sameasENV["RUBYSHELL"](orENV["COMSPEC"]onWindowsNTseries),andsimilar.

Ifthestringfromthefirstform(exec("command"))followsthesesimplerules:

nometacharacters

noshellreservedwordandnospecialbuilt-in

Rubyinvokesthecommanddirectlywithoutshell

Youcanforceshellinvocationbyadding“;”tothestring(because“;”isametacharacter).

Notethatthisbehaviorisobservablebypidobtained(returnvalueofspawn()andIO#pidforIO.popen)isthepidoftheinvokedcommand,notshell.

Inthesecondform(exec("command1","arg1",...)),thefirstistakenasacommandnameandtherestarepassedasparameterstocommandwithnoshellexpansion.

Inthethirdform(exec(["command","argv0"],"arg1",...)),startingatwo-elementarrayatthebeginningofthecommand,thefirstelementisthecommandtobeexecuted,andthesecondargumentisusedastheargv[0]value,whichmayshowupinprocesslistings.

Inordertoexecutethecommand,oneoftheexec(2)systemcallsareused,sotherunningcommandmayinheritsomeoftheenvironmentoftheoriginalprogram(includingopenfiledescriptors).

Thisbehaviorismodifiedbythegivenenvandoptionsparameters.See::spawnfordetails.

Ifthecommandfailstoexecute(typically

Errno::ENOENTwhenitwasnotfound)aSystemCallErrorexceptionisraised.

Thismethodmodifiesprocessattributesaccordingtogivenoptionsbeforeexec(2)systemcall.See::spawnformoredetailsaboutthegivenoptions.

Themodifiedattributesmayberetainedwhenexec(2)systemcallfails.

Forexample,hardresourcelimitsarenotrestorable.

Considertocreateachildprocessusing::spawnor#systemifthisisnotacceptable.

exec"echo*"#echoeslistoffilesincurrentdirectory

#nevergethere

exec"echo","*"#echoesanasterisk

#nevergethere

InitiatestheterminationoftheRubyscriptbyraisingtheSystemExitexception.Thisexceptionmaybecaught.Theoptionalparameterisusedtoreturnastatuscodetotheinvokingenvironment.trueandFALSEofstatusmeanssuccessandfailurerespectively.Theinterpretationofotherintegervaluesaresystemdependent.

puts"nevergethere"

rescueSystemExit

puts"rescuedaSystemExitexception"

puts"afterbeginblock"

exit(status=true)Kernel::exit(status=true)Process::exit(status=true)

produces:

rescuedaSystemExitexception

afterbeginblock

Justpriortotermination,Rubyexecutesanyat_exitfunctions(seeKernel::at_exit)andrunsanyobjectfinalizers(seeObjectSpace.define_finalizer).

at_exit{puts"at_exitfunction"}

ObjectSpace.define_finalizer("string",proc{puts"infinalizer"})

produces:

at_exitfunction

infinalizer

Exitstheprocessimmediately.Noexithandlersarerun.statusisreturnedtotheunderlyingsystemastheexitstatus.

Process.exit!(true)

Withnoarguments,raisestheexceptionin$!orraisesaRuntimeErrorif$!isnil.WithasingleStringargument,raisesaRuntimeErrorwiththestringasamessage.Otherwise,thefirstparametershouldbe

exit!(status=false)

raiseraise(string)raise(exception[,string[,array]])failfail(string)fail(exception[,string[,array]])

thenameofanExceptionclass(oranobjectthatreturnsanExceptionobjectwhensentanexceptionmessage).Theoptionalsecondparametersetsthemessageassociatedwiththeexception,andthethirdparameterisanarrayofcallbackinformation.Exceptionsarecaughtbytherescueclauseofbegin...endblocks.

raise"Failedtocreatesocket"

raiseArgumentError,"Noparameters",caller

Createsasubprocess.Ifablockisspecified,thatblockisruninthesubprocess,andthesubprocessterminateswithastatusofzero.Otherwise,theforkcallreturnstwice,onceintheparent,returningtheprocessIDofthechild,andonceinthechild,returningnil.ThechildprocesscanexitusingKernel.exit!toavoidrunninganyat_exitfunctions.TheparentprocessshoulduseProcess.waittocollecttheterminationstatusesofitschildrenoruseProcess.detachtoregisterdisinterestintheirstatus;otherwise,theoperatingsystemmayaccumulatezombieprocesses.

Thethreadcallingforkistheonlythreadinthecreatedchildprocess.forkdoesn'tcopyotherthreads.

Ifforkisnotusable,Process.respond_to?(:fork)returnsfalse.

Notethatfork(2)isnotavailableonsomeplatformslikeWindowsandNetBSD4.Thereforeyoushouldusespawn()insteadoffork().

fork[{block}]→fixnumornilfork[{block}]→fixnumornil

Returnsthestringresultingfromapplyingformat_stringtoanyadditionalarguments.Withintheformatstring,anycharactersotherthanformatsequencesarecopiedtotheresult.

Thesyntaxofaformatsequenceisfollows.

%[flags][width][.precision]type

Aformatsequenceconsistsofapercentsign,followedbyoptionalflags,width,andprecisionindicators,thenterminatedwithafieldtypecharacter.Thefieldtypecontrolshowthecorrespondingsprintfargumentistobeinterpreted,whiletheflagsmodifythatinterpretation.

Thefieldtypecharactersare:

Field|IntegerFormat

------+--------------------------------------------------------------

b|Convertargumentasabinarynumber.

|Negativenumberswillbedisplayedasatwo'scomplement

|prefixedwith`..1'.

B|Equivalentto`b',butusesanuppercase0Bforprefix

|inthealternativeformatby#.

d|Convertargumentasadecimalnumber.

i|Identicalto`d'.

o|Convertargumentasanoctalnumber.

|prefixedwith`..7'.

u|Identicalto`d'.

x|Convertargumentasahexadecimalnumber.

|prefixedwith`..f'(representinganinfinitestringof

|leading'ff's).

X|Equivalentto`x',butusesuppercaseletters.

Field|FloatFormat

------+--------------------------------------------------------------

format(format_string[,arguments...])→stringsprintf(format_string[,arguments...])→string

e|Convertfloatingpointargumentintoexponentialnotation

|withonedigitbeforethedecimalpointas[-]d.dddddde[+-]dd.

|Theprecisionspecifiesthenumberofdigitsafterthedecimal

|point(defaultingtosix).

E|Equivalentto`e',butusesanuppercaseEtoindicate

|theexponent.

f|Convertfloatingpointargumentas[-]ddd.dddddd,

|wheretheprecisionspecifiesthenumberofdigitsafter

|thedecimalpoint.

g|Convertafloatingpointnumberusingexponentialform

|iftheexponentislessthan-4orgreaterthanor

|equaltotheprecision,orindd.ddddformotherwise.

|Theprecisionspecifiesthenumberofsignificantdigits.

G|Equivalentto`g',butuseanuppercase`E'inexponentform.

a|Convertfloatingpointargumentas[-]0xh.hhhhp[+-]dd,

|whichisconsistedfromoptionalsign,"0x",fractionpart

|ashexadecimal,"p",andexponentialpartasdecimal.

A|Equivalentto`a',butuseuppercase`X'and`P'.

Field|OtherFormat

------+--------------------------------------------------------------

c|Argumentisthenumericcodeforasinglecharacteror

|asinglecharacterstringitself.

p|Thevaluingofargument.inspect.

s|Argumentisastringtobesubstituted.Iftheformat

|sequencecontainsaprecision,atmostthatmanycharacters

|willbecopied.

%|Apercentsignitselfwillbedisplayed.Noargumenttaken.

Theflagsmodifiesthebehavioroftheformats.Theflagcharactersare:

Flag|Appliesto|Meaning

---------+---------------+-----------------------------------------

space|bBdiouxX|Leaveaspaceatthestartof

|aAeEfgG|non-negativenumbers.

|(numericfmt)|For`o',`x',`X',`b'and`B',use

||aminussignwithabsolutevaluefor

||negativevalues.

---------+---------------+-----------------------------------------

(digit)$|all|Specifiestheabsoluteargumentnumber

||forthisfield.Absoluteandrelative

||argumentnumberscannotbemixedina

||sprintfstring.

---------+---------------+-----------------------------------------

#|bBoxX|Useanalternativeformat.

|aAeEfgG|Fortheconversions`o',increasetheprecision

||untilthefirstdigitwillbe`0'if

||itisnotformattedascomplements.

||Fortheconversions`x',`X',`b'and`B'

||onnon-zero,prefixtheresultwith``0x'',

||``0X'',``0b''and``0B'',respectively.

||Forà',À',è',È',`f',`g',and'G',

||forceadecimalpointtobeadded,

||evenifnodigitsfollow.

||For`g'and'G',donotremovetrailingzeros.

---------+---------------+-----------------------------------------

+|bBdiouxX|Addaleadingplussigntonon-negative

|aAeEfgG|numbers.

||negativevalues.

---------+---------------+-----------------------------------------

-|all|Left-justifytheresultofthisconversion.

---------+---------------+-----------------------------------------

0(zero)|bBdiouxX|Padwithzeros,notspaces.

|aAeEfgG|For`o',`x',`X',`b'and`B',radix-1

|(numericfmt)|isusedfornegativenumbersformattedas

||complements.

---------+---------------+-----------------------------------------

*|all|Usethenextargumentasthefieldwidth.

||Ifnegative,left-justifytheresult.Ifthe

||asteriskisfollowedbyanumberandadollar

||sign,usetheindicatedargumentasthewidth.

Examplesofflags:

#`+'andspaceflagspecifiesthesignofnon-negativenumbers.

sprintf("%d",123)#=>"123"

sprintf("%+d",123)#=>"+123"

sprintf("%d",123)#=>"123"

#`#'flagfor`o'increasesnumberofdigitstoshow`0'.

#`+'andspaceflagchangesformatofnegativenumbers.

sprintf("%o",123)#=>"173"

sprintf("%#o",123)#=>"0173"

sprintf("%+o",-123)#=>"-173"

sprintf("%o",-123)#=>"..7605"

sprintf("%#o",-123)#=>"..7605"

#`#'flagfor`x'addaprefix`0x'fornon-zeronumbers.

#`+'andspaceflagdisablescomplementsfornegativenumbers.

sprintf("%x",123)#=>"7b"

sprintf("%#x",123)#=>"0x7b"

sprintf("%+x",-123)#=>"-7b"

sprintf("%x",-123)#=>"..f85"

sprintf("%#x",-123)#=>"0x..f85"

sprintf("%#x",0)#=>"0"

#`#'for`X'usestheprefix`0X'.

sprintf("%X",123)#=>"7B"

sprintf("%#X",123)#=>"0X7B"

#`#'flagfor`b'addaprefix`0b'fornon-zeronumbers.

sprintf("%b",123)#=>"1111011"

sprintf("%#b",123)#=>"0b1111011"

sprintf("%+b",-123)#=>"-1111011"

sprintf("%b",-123)#=>"..10000101"

sprintf("%#b",-123)#=>"0b..10000101"

sprintf("%#b",0)#=>"0"

#`#'for`B'usestheprefix`0B'.

sprintf("%B",123)#=>"1111011"

sprintf("%#B",123)#=>"0B1111011"

#`#'for`e'forcestoshowthedecimalpoint.

sprintf("%.0e",1)#=>"1e+00"

sprintf("%#.0e",1)#=>"1.e+00"

#`#'for`f'forcestoshowthedecimalpoint.

sprintf("%.0f",1234)#=>"1234"

sprintf("%#.0f",1234)#=>"1234."

#`#'for`g'forcestoshowthedecimalpoint.

#Italsodisablesstrippinglowestzeros.

sprintf("%g",123.4)#=>"123.4"

sprintf("%#g",123.4)#=>"123.400"

sprintf("%g",123456)#=>"123456"

sprintf("%#g",123456)#=>"123456."

Thefieldwidthisanoptionalinteger,followedoptionallybyaperiodandaprecision.Thewidthspecifiestheminimumnumberofcharactersthatwillbewrittentotheresultforthisfield.

Examplesofwidth:

#paddingisdonebyspaces,width=20

#0orradix-1.<------------------>

sprintf("%20d",123)#=>"123"

sprintf("%+20d",123)#=>"+123"

sprintf("%020d",123)#=>"00000000000000000123"

sprintf("%+020d",123)#=>"+0000000000000000123"

sprintf("%020d",123)#=>"0000000000000000123"

sprintf("%-20d",123)#=>"123"

sprintf("%-+20d",123)#=>"+123"

sprintf("%-20d",123)#=>"123"

sprintf("%020x",-123)#=>"..ffffffffffffffff85"

Fornumericfields,theprecisioncontrolsthenumberofdecimalplacesdisplayed.Forstringfields,theprecisiondeterminesthemaximumnumberofcharacterstobecopiedfromthestring.(Thus,theformatsequence%10.10swillalwayscontributeexactlytencharacterstotheresult.)

Examplesofprecisions:

#precisionfor`d','o','x'and'b'is

#minimumnumberofdigits<------>

sprintf("%20.8d",123)#=>"00000123"

sprintf("%20.8o",123)#=>"00000173"

sprintf("%20.8x",123)#=>"0000007b"

sprintf("%20.8b",123)#=>"01111011"

sprintf("%20.8d",-123)#=>"-00000123"

sprintf("%20.8o",-123)#=>"..777605"

sprintf("%20.8x",-123)#=>"..ffff85"

sprintf("%20.8b",-11)#=>"..110101"

#"0x"and"0b"for`#x'and`#b'isnotcountedfor

#precisionbut"0"for`#o'iscounted.<------>

sprintf("%#20.8d",123)#=>"00000123"

sprintf("%#20.8o",123)#=>"00000173"

sprintf("%#20.8x",123)#=>"0x0000007b"

sprintf("%#20.8b",123)#=>"0b01111011"

sprintf("%#20.8d",-123)#=>"-00000123"

sprintf("%#20.8o",-123)#=>"..777605"

sprintf("%#20.8x",-123)#=>"0x..ffff85"

sprintf("%#20.8b",-11)#=>"0b..110101"

#precisionfor`e'isnumberof

#digitsafterthedecimalpoint<------>

sprintf("%20.8e",1234.56789)#=>"1.23456789e+03"

#precisionfor`f'isnumberof

sprintf("%20.8f",1234.56789)#=>"1234.56789000"

#precisionfor`g'isnumberof

#significantdigits<------->

sprintf("%20.8g",1234.56789)#=>"1234.5679"

#<------->

sprintf("%20.8g",123456789)#=>"1.2345679e+08"

#precisionfor`s'is

#maximumnumberofcharacters<------>

sprintf("%20.8s","stringtest")#=>"stringt"

Examples:

sprintf("%d%04x",123,123)#=>"123007b"

sprintf("%08b'%4s'",123,123)#=>"01111011'123'"

sprintf("%1$*2$s%2$d%1$s","hello",8)#=>"hello8hello"

sprintf("%1$*2$s%2$d","hello",-8)#=>"hello-8"

sprintf("%+g:%g:%-g",1.23,1.23,1.23)#=>"+1.23:1.23:1.23"

sprintf("%u",-123)#=>"-123"

Formorecomplexformatting,Rubysupportsareferencebyname.%<name>sstyleusesformatstyle,but%{name}styledoesn't.

Examples:

sprintf("%<foo>d:%<bar>f",{:foo=>1,:bar=>2})

#=>1:2.000000

sprintf("%{foo}f",{:foo=>1})

#=>"1f"

gets(sep=$/)→stringornilgets(limit)→stringornilgets(sep,limit)→stringornil

Returns(andassignsto$_)thenextlinefromthelistoffilesinARGV(or$*),orfromstandardinputifnofilesarepresentonthecommandline.Returnsnilatendoffile.Theoptionalargumentspecifiestherecordseparator.Theseparatorisincludedwiththecontentsofeachrecord.Aseparatorofnilreadstheentirecontents,andazero-lengthseparatorreadstheinputoneparagraphatatime,whereparagraphsaredividedbytwoconsecutivenewlines.Ifthefirstargumentisaninteger,oroptionalsecondargumentisgiven,thereturningstringwouldnotbelongerthanthegivenvalueinbytes.IfmultiplefilenamesarepresentinARGV,+gets(nil)+willreadthecontentsonefileatatime.

ARGV<<"testfile"

printwhilegets

produces:

Thisislineone

Thisislinetwo

Thisislinethree

Andsoon...

Thestyleofprogrammingusing$_asanimplicitparameterisgraduallylosingfavorintheRubycommunity.

Returnsanarrayofthenamesofglobalvariables.

global_variables.grep/std/#=>[:$stdin,:$stdout,:$stderr]

global_variables→array

gsub(pattern,replacement)→$_gsub(pattern){|...|block}→$_

Equivalentto$_.gsub...,exceptthat$_willbeupdatedifsubstitutionoccurs.Availableonlywhen-p/-ncommandlineoptionspecified.

Returnstrueifyieldwouldexecuteablockinthecurrentcontext.Theiterator?formismildlydeprecated.

deftry

ifblock_given?

"noblock"

try#=>"noblock"

try{"hello"}#=>"hello"

trydo"hello"end#=>"hello"

EquivalenttoProc.new,excepttheresultingProcobjectscheckthenumberofparameterspassedwhencalled.

LoadsandexecutestheRubyprograminthefilefilename.Ifthefilenamedoesnotresolvetoanabsolutepath,thefileissearchedforinthelibrarydirectorieslistedin$:.Iftheoptionalwrapparameteristrue,theloadedscriptwillbeexecutedunderananonymousmodule,protectingthecallingprogram'sglobalnamespace.Innocircumstancewillanylocalvariablesintheloadedfilebepropagatedtothe

block_given?→trueorfalseiterator?→trueorfalse

lambda{|...|block}→a_proc

load(filename,wrap=false)→true

loadingenvironment.

Returnsthenamesofthecurrentlocalvariables.

fred=1

foriin1..10

local_variables#=>[:fred,:i]

Repeatedlyexecutestheblock.

loopdo

print"Input:"

line=gets

breakif!lineorline=~/^qQ/

StopIterationraisedintheblockbreakstheloop.

CreatesanIOobjectconnectedtothegivenstream,file,orsubprocess.

Ifpathdoesnotstartwithapipecharacter(|),treatitasthenameofafiletoopenusingthespecifiedmode(defaultingto“r”).

local_variables→array

loop{block}loop→an_enumerator

open(path[,mode[,perm]][,opt])→ioornilopen(path[,mode[,perm]][,opt]){|io|block}→obj

Themodeiseitherastringoraninteger.Ifitisaninteger,itmustbebitwise-orofopen(2)flags,suchasFile::RDWRorFile::EXCL.Ifitisastring,itiseither“fmode”,“fmode:ext_enc”,or“fmode:ext_enc:int_enc”.

SeethedocumentationofIO.newforfulldocumentationofthemodestringdirectives.

Ifafileisbeingcreated,itsinitialpermissionsmaybesetusingthepermparameter.SeeFile.newandtheopen(2)andchmod(2)manpagesforadescriptionofpermissions.

Ifablockisspecified,itwillbeinvokedwiththeIOobjectasaparameter,andtheIOwillbeautomaticallyclosedwhentheblockterminates.Thecallreturnsthevalueoftheblock.

Ifpathstartswithapipecharacter("|"),asubprocessiscreated,connectedtothecallerbyapairofpipes.ThereturnedIOobjectmaybeusedtowritetothestandardinputandreadfromthestandardoutputofthissubprocess.

Ifthecommandfollowingthepipeisasingleminussign("|-"),Rubyforks,andthissubprocessisconnectedtotheparent.Ifthecommandisnot"-",thesubprocessrunsthecommand.

Whenthesubprocessisruby(openedvia"|-"),theopencallreturnsnil.Ifablockisassociatedwiththeopencall,thatblockwillruntwice—onceintheparentandonceinthechild.

TheblockparameterwillbeanIOobjectintheparentandnilinthechild.Theparent'sIOobjectwillbeconnectedtothechild's$stdinand$stdout.Thesubprocesswillbeterminatedattheendoftheblock.

ExamplesReadingfrom“testfile”:

open("testfile")do|f|

printf.gets

Produces:

Thisislineone

Openasubprocessandreaditsoutput:

cmd=open("|date")

printcmd.gets

cmd.close

Produces:

WedApr908:56:31CDT2003

OpenasubprocessrunningthesameRubyprogram:

f=open("|-","w+")

iff==nil

puts"inChild"

puts"Got:#{f.gets}"

Produces:

Got:inChild

OpenasubprocessusingablocktoreceivetheIOobject:

open"|-"do|f|

iffthen

#parentprocess

puts"Got:#{f.gets}"

#childprocess

puts"inChild"

Produces:

Got:inChild

Foreachobject,directlywritesobj.inspectfollowedbyanewlinetotheprogram'sstandardoutput.

S=Struct.new(:name,:state)

s=S['dave','TX']

produces:

#<Sname="dave",state="TX">

Printseachobjectinturnto$stdout.Iftheoutputfieldseparator($,)isnotnil,itscontentswillappearbetweeneachfield.Iftheoutputrecordseparator($\</code>)isnotnil,itwillbeappendedtothe

output.Ifnoargumentsaregiven,prints

<code>$_.Objectsthataren'tstringswillbeconvertedbycallingtheirto_smethod.

print"cat",[1,2,3],99,"\n"

$,=","

$\="\n"

print"cat",[1,2,3],99

produces:

cat12399

p(obj)→objp(obj1,obj2,...)→[obj,...]p()→nil

print(obj,...)→nil

cat,1,2,3,99

Equivalentto:

io.write(sprintf(string,obj,...))

$stdout.write(sprintf(string,obj,...))

EquivalenttoProc.new.

Equivalentto:

$stdout.putc(int)

RefertothedocumentationforIO#putcforimportantinformationregardingmulti-bytecharacters.

Equivalentto

$stdout.puts(obj,...)

printf(io,string[,obj...])→nilprintf(string[,obj...])→nil

proc{|...|block}→a_proc

putc(int)→int

puts(obj,...)→nil

raiseraise(string)raise(exception[,string[,array]])failfail(string)

Withnoarguments,raisestheexceptionin$!orraisesaRuntimeErrorif$!isnil.WithasingleStringargument,raisesaRuntimeErrorwiththestringasamessage.Otherwise,thefirstparametershouldbethenameofanExceptionclass(oranobjectthatreturnsanExceptionobjectwhensentanexceptionmessage).Theoptionalsecondparametersetsthemessageassociatedwiththeexception,andthethirdparameterisanarrayofcallbackinformation.Exceptionsarecaughtbytherescueclauseofbegin...endblocks.

raise"Failedtocreatesocket"

raiseArgumentError,"Noparameters",caller

Ifcalledwithoutanargument,orifmax.to_i.abs==0,randreturnsapseudo-randomfloatingpointnumberbetween0.0and1.0,including0.0andexcluding1.0.

rand#=>0.2725926052826416

Whenmax.absisgreaterthanorequalto1,randreturnsapseudo-randomintegergreaterthanorequalto0andlessthanmax.to_i.abs.

rand(100)#=>12

WhenmaxisaRange,randreturnsarandomnumberwhererange.member?(number)==true.

Negativeorfloatingpointvaluesformaxareallowed,butmaygivesurprisingresults.

rand(-100)#=>87

rand(-0.5)#=>0.8130921818028143

rand(1.9)#equivalenttorand(1),whichisalways0

fail(exception[,string[,array]])

rand(max=0)→number

#srandmaybeusedtoensurethatsequencesofrandomnumbersarereproduciblebetweendifferentrunsofaprogram.

SeealsoRandom#rand.

EquivalenttoKernel::gets,exceptreadlineraisesEOFErroratendoffile.

ReturnsanarraycontainingthelinesreturnedbycallingKernel.gets(sep)untiltheendoffile.

Loadsthegivenname,returningtrueifsuccessfulandfalseifthefeatureisalreadyloaded.

Ifthefilenamedoesnotresolvetoanabsolutepath,itwillbesearchedforinthedirectorieslistedin$LOAD_PATH($:).

Ifthefilenamehastheextension“.rb”,itisloadedasasourcefile;iftheextensionis“.so”,“.o”,or“.dll”,orthedefaultsharedlibraryextensiononthecurrentplatform,RubyloadsthesharedlibraryasaRubyextension.Otherwise,Rubytriesadding“.rb”,“.so”,andsoontothenameuntilfound.Ifthefilenamedcannotbefound,aLoadErrorwillberaised.

readline(sep=$/)→stringreadline(limit)→stringreadline(sep,limit)→string

readlines(sep=$/)→arrayreadlines(limit)→arrayreadlines(sep,limit)→array

require(name)→trueorfalse

ForRubyextensionsthefilenamegivenmayuseanysharedlibraryextension.Forexample,onLinuxthesocketextensionis“socket.so”andrequire'socket.dll'willloadthesocketextension.

Theabsolutepathoftheloadedfileisaddedto$LOADED_FEATURES($").Afilewillnotbeloadedagainifitspathalreadyappearsin$".Forexample,require'a';require'./a'willnotloada.rbagain.

require"my-library.rb"

require"db-driver"

Anyconstantsorglobalswithintheloadedsourcefilewillbeavailableinthecallingprogram'sglobalnamespace.However,localvariableswillnotbepropagatedtotheloadingenvironment.

Rubytriestoloadthelibrarynamedstringrelativetotherequiringfile'spath.Ifthefile'spathcannotbedeterminedaLoadErrorisraised.Ifafileisloadedtrueisreturnedandfalseotherwise.

Callsselect(2)systemcall.ItmonitorsgivenarraysofIOobjects,waitsoneormoreofIOobjectsreadyforreading,arereadyforwriting,andhavependingexceptionsrespectively,andreturnsanarraythatcontainsarraysofthoseIOobjects.ItwillreturnnilifoptionaltimeoutvalueisgivenandnoIOobjectisreadyintimeoutseconds.

require_relative(string)→trueorfalse

select(read_array[,write_array[,error_array[,timeout]]])→arrayornil

IO.selectpeeksthebufferofIOobjectsfortestingreadability.IftheIObufferisnotempty,IO.selectimmediatelynotifyreadability.This“peek”isonlyhappenforIOobjects.ItisnothappenforIO-likeobjectssuchasOpenSSL::SSL::SSLSocket.

ThebestwaytouseIO.selectisinvokingitafternonblockingmethodssuchasread_nonblock,write_nonblock,etc.ThemethodsraisesanexceptionwhichisextendedbyIO::WaitReadableorIO::WaitWritable.ThemodulesnotifyhowthecallershouldwaitwithIO.select.IfIO::WaitReadableisraised,thecallershouldwaitforreading.IfIO::WaitWritableisraised,thecallershouldwaitforwriting.

So,blockingread(readpartial)canbeemulatedusingread_nonblockandIO.selectasfollows:

result=io_like.read_nonblock(maxlen)

Especially,thecombinationofnonblockingmethodsandIO.selectispreferredforIOlikeobjectssuchasOpenSSL::SSL::SSLSocket.Ithasto_iomethodtoreturnunderlyingIOobject.IO.selectcallsto_iotoobtainthefiledescriptortowait.

ThismeansthatreadabilitynotifiedbyIO.selectdoesn'tmeanreadabilityfromOpenSSL::SSL::SSLSocketobject.

MostpossiblesituationisOpenSSL::SSL::SSLSocketbufferssomedata.IO.selectdoesn'tseethebuffer.SoIO.selectcanblockwhenOpenSSL::SSL::SSLSocket#readpartialdoesn'tblock.

Howeverseveralmorecomplicatedsituationexists.

SSLisaprotocolwhichissequenceofrecords.Therecordconsistsmultiplebytes.So,theremotesideofSSLsendsapartialrecord,IO.selectnotifiesreadabilitybutOpenSSL::SSL::SSLSocketcannotdecryptabyteandOpenSSL::SSL::SSLSocket#readpartialwillblocks.

Also,theremotesidecanrequestSSLrenegotiationwhichforcesthelocalSSLenginewritessomedata.ThismeansOpenSSL::SSL::SSLSocket#readpartialmayinvokewritesystemcallanditcanblock.Insuchsituation,OpenSSL::SSL::SSLSocket#read_nonblockraisesIO::WaitWritableinsteadofblocking.So,thecallershouldwaitforreadyforwritabilityasaboveexample.

ThecombinationofnonblockingmethodsandIO.selectisalsousefulforstreamssuchastty,pipesocketsocketwhenmultipleprocessreadformastream.

Finally,Linuxkerneldevelopersdoesn'tguaranteethatreadabilityofselect(2)meansreadabilityoffollowingread(2)evenforsingleprocess.Seeselect(2)manualonGNU/Linuxsystem.

InvokingIO.selectbeforeIO#readpartialworkswellinusual.HoweveritisnotthebestwaytouseIO.select.

Thewritabilitynotifiedbyselect(2)doesn'tshowhowmanybyteswritable.IO#writemethodblocksuntil

givenwholestringiswritten.So,IO#write(twoormorebytes)canblockafterwritabilityisnotifiedbyIO.select.IO#write_nonblockisrequiredtoavoidtheblocking.

Blockingwrite(write)canbeemulatedusingwrite_nonblockandIO.selectasfollows:IO::WaitReadableshouldalsoberescuedforSSLrenegotiationinOpenSSL::SSL::SSLSocket.

while0<string.bytesize

written=io_like.write_nonblock(string)

string=string.byteslice(written..-1)

Parametersread_arrayanarrayofIOobjectsthatwaituntilreadyforread

write_arrayanarrayofIOobjectsthatwaituntilreadyforwrite

error_arrayanarrayofIOobjectsthatwaitforexceptions

timeoutanumericvalueinsecond

Examplerp,wp=IO.pipe

mesg="ping"

100.times{

#IO.selectfollowsIO#read.NotthebestwaytouseIO.select.

rs,ws,=IO.select([rp],[wp])

ifr=rs[0]

ret=r.read(5)

printret

caseret

when/ping/

mesg="pong\n"

when/pong/

mesg="ping"

ifw=ws[0]

w.write(mesg)

produces:

pingpong

(snipped)

Establishesprocasthehandlerfortracing,ordisablestracingiftheparameterisnil.

Note:thismethodisobsolete,pleaseuseTracePointinstead.

proctakesuptosixparameters:

aneventname

afilename

alinenumber

anobjectid

set_trace_func(proc)→procset_trace_func(nil)→nil

abinding

thenameofaclass

procisinvokedwheneveraneventoccurs.

Eventsare:c-call

callaC-languageroutine

c-return

returnfromaC-languageroutine

callaRubymethod

startaclassormoduledefinition),

finishaclassormoduledefinition),

executecodeonanewline

raiseanexception

return

returnfromaRubymethod

Tracingisdisabledwithinthecontextofproc.

classTest

deftest

set_trace_funcproc{|event,file,line,id,binding

printf"%8s%s:%-2d%10s%8s\n",event,file,line

t=Test.new

t.test

lineprog.rb:11false

c-callprog.rb:11newClass

c-callprog.rb:11initializeObject

c-returnprog.rb:11initializeObject

c-returnprog.rb:11newClass

lineprog.rb:12false

callprog.rb:2testTest

lineprog.rb:3testTest

lineprog.rb:4testTest

returnprog.rb:4testTest

Suspendsthecurrentthreadfordurationseconds(whichmaybeanynumber,includingaFloatwithfractionalseconds).Returnstheactualnumberofsecondsslept(rounded),whichmaybelessthanthataskedforifanotherthreadcallsThread#run.Calledwithoutanargument,sleep()willsleepforever.

Time.new#=>2008-03-0819:56:19+0900

sleep1.2#=>1

Time.new#=>2008-03-0819:56:20+0900

sleep1.9#=>2

Time.new#=>2008-03-0819:56:22+0900

spawnexecutesspecifiedcommandandreturnitspid.

pid=spawn("tarxfruby-2.0.0-p195.tar.bz2")

Process.waitpid

pid=spawn(RbConfig.ruby,"-eputs'Hello,world!'")

Process.waitpid

Thismethodissimilarto#systembutitdoesn'twaitforthecommandtofinish.

sleep([duration])→fixnum

spawn([env,]command...[,options])→pidspawn([env,]command...[,options])→pid

TheparentprocessshoulduseProcess.waittocollecttheterminationstatusofitschildoruseProcess.detachtoregisterdisinterestintheirstatus;otherwise,theoperatingsystemmayaccumulatezombieprocesses.

spawnhasbunchofoptionstospecifyprocessattributes:

env:hash

name=>val:settheenvironmentvariable

name=>nil:unsettheenvironmentvariable

command...:

commandline:commandlinestringwhich

cmdname,arg1,...:commandnameandoneor

[cmdname,argv0],arg1,...:commandname,argv[0]

options:hash

clearingenvironmentvariables:

:unsetenv_others=>true:clearenvironmentvariables

:unsetenv_others=>false:don'tclear(default)

processgroup:

:pgroup=>trueor0:makeanewprocessgroup

:pgroup=>pgid:jointospecifiedprocessgroup

:pgroup=>nil:don'tchangetheprocessgroup

createnewprocessgroup:Windowsonly

:new_pgroup=>true:thenewprocessistheroot

:new_pgroup=>false:don'tcreateanewprocessgroup(default)

resourcelimit:resourcenameiscore,cpu,data,etc.SeeProcess.setrlimit.

:rlimit_resourcename=>limit

:rlimit_resourcename=>[cur_limit,max_limit]

umask:

:umask=>int

redirection:

FD:singlefiledescriptorinchildprocess

[FD,FD,...]:multiplefiledescriptorinchildprocess

value:

FD:redirecttothefiledescriptorinparentprocess

string:redirecttofilewithopen(string,"r"or"w")

[string]:redirecttofilewithopen(string,File::RDONLY)

[string,open_mode]:redirecttofilewithopen(string,open_mode,0644)

[string,open_mode,perm]:redirecttofilewithopen(string,open_mode,perm)

[:child,FD]:redirecttotheredirectedfiledescriptor

:close:closethefiledescriptorinchildprocess

FDisoneoffollows

:in:thefiledescriptor0whichisthestandardinput

:out:thefiledescriptor1whichisthestandardoutput

:err:thefiledescriptor2whichisthestandarderror

integer:thefiledescriptorofspecifiedtheinteger

io:thefiledescriptorspecifiedasio.fileno

filedescriptorinheritance:closenon-redirectednon-standardfds(3,4,5,...)ornot

:close_others=>true:don'tinherit

currentdirectory:

:chdir=>str

The'cmdname,arg1,...'formdoesnotusetheshell

ondifferentOSes,differentthingsareprovidedas

commands.Anexampleofthisis'echo',whichisabuilt

onWindows,butisanormalprogramonLinuxandMac

Thismeansthat%xProcess.spawn'echo','%Path%'`will

thecontentsofthe%x%Path%`environmentvariableon

but%xProcess.spawn'echo','$PATH'`printstheliteral

Ifahashisgivenasenv,theenvironmentisupdatedbyenvbeforeexec(2)inthechildprocess.Ifapairinenvhasnilasthevalue,thevariableisdeleted.

#setFOOasBARandunsetBAZ.

pid=spawn({"FOO"=>"BAR","BAZ"=>nil},command)

Ifahashisgivenasoptions,itspecifiesprocessgroup,createnewprocessgroup,resourcelimit,currentdirectory,umaskandredirectsforthechildprocess.Also,itcanbespecifiedtoclearenvironmentvariables.

The:unsetenv_otherskeyinoptionsspecifiestoclearenvironmentvariables,otherthanspecifiedbyenv.

pid=spawn(command,:unsetenv_others=>true)#noenvironmentvariable

pid=spawn({"FOO"=>"BAR"},command,:unsetenv_others=

The:pgroupkeyinoptionsspecifiesaprocessgroup.Thecorrespondingvalueshouldbetrue,zero

orpositiveinteger.trueandzeromeanstheprocessshouldbeaprocessleaderofanewprocessgroup.Othervaluesspecifiesaprocessgrouptobebelongs.

pid=spawn(command,:pgroup=>true)#processleader

pid=spawn(command,:pgroup=>10)#belongstotheprocessgroup10

The:new_pgroupkeyinoptionsspecifiestopassCREATE_NEW_PROCESS_GROUPflagtoCreateProcessW()thatisWindowsAPI.ThisoptionisonlyforWindows.truemeansthenewprocessistherootprocessofthenewprocessgroup.ThenewprocesshasCTRL+Cdisabled.ThisflagisnecessaryforProcess.kill(:SIGINT,pid)onthesubprocess.:new_pgroupisfalsebydefault.

pid=spawn(command,:new_pgroup=>true)#newprocessgroup

pid=spawn(command,:new_pgroup=>false)#sameprocessgroup

The:rlimit_fookeyspecifiesaresourcelimit.fooshouldbeoneofresourcetypessuchascore.Thecorrespondingvalueshouldbeanintegeroranarraywhichhaveoneortwointegers:sameascur_limitandmax_limitargumentsforProcess.setrlimit.

cur,max=Process.getrlimit(:CORE)

pid=spawn(command,:rlimit_core=>[0,max])#disablecoretemporary.

pid=spawn(command,:rlimit_core=>max)#enablecoredump

pid=spawn(command,:rlimit_core=>0)#neverdumpcore.

The:umaskkeyinoptionsspecifiestheumask.

pid=spawn(command,:umask=>077)

The:in,:out,:err,afixnum,anIOandanarraykeyspecifiesaredirection.Theredirectionmapsafiledescriptorinthechildprocess.

Forexample,stderrcanbemergedintostdoutasfollows:

pid=spawn(command,:err=>:out)

pid=spawn(command,2=>1)

pid=spawn(command,STDERR=>:out)

pid=spawn(command,STDERR=>STDOUT)

Thehashkeysspecifiesafiledescriptorinthechildprocessstartedbyspawn.:err,2andSTDERRspecifiesthestandarderrorstream(stderr).

Thehashvaluesspecifiesafiledescriptorintheparentprocesswhichinvokesspawn.:out,1andSTDOUTspecifiesthestandardoutputstream(stdout).

Intheaboveexample,thestandardoutputinthechildprocessisnotspecified.Soitisinheritedfromtheparentprocess.

Thestandardinputstream(stdin)canbespecifiedby:in,0andSTDIN.

Afilenamecanbespecifiedasahashvalue.

pid=spawn(command,:in=>"/dev/null")#readmode

pid=spawn(command,:out=>"/dev/null")#writemode

pid=spawn(command,:err=>"log")#writemode

pid=spawn(command,[:out,:err]=>"/dev/null")#writemode

pid=spawn(command,3=>"/dev/null")#readmode

Forstdoutandstderr(andcombinationofthem),itisopenedinwritemode.Otherwisereadmodeisused.

Forspecifyingflagsandpermissionoffilecreationexplicitly,anarrayisusedinstead.

pid=spawn(command,:in=>["file"])#readmodeisassumed

pid=spawn(command,:in=>["file","r"])

pid=spawn(command,:out=>["log","w"])#0644assumed

pid=spawn(command,:out=>["log","w",0600])

pid=spawn(command,:out=>["log",File::WRONLY|File::

Thearrayspecifiesafilename,flagsandpermission.Theflagscanbeastringoraninteger.Iftheflagsisomittedornil,File::RDONLYisassumed.Thepermissionshouldbeaninteger.Ifthepermissionisomittedornil,0644isassumed.

IfanarrayofIOsandintegersarespecifiedasahashkey,alltheelementsareredirected.

#stdoutandstderrisredirectedtologfile.

#Thefile"log"isopenedjustonce.

pid=spawn(command,[:out,:err]=>["log","w"])

Anotherwaytomergemultiplefiledescriptorsis[:child,fd].[:child,fd]meansthefiledescriptorinthechildprocess.Thisisdifferentfromfd.Forexample,:err=>:outmeansredirectingchildstderrtoparentstdout.But:err=>[:child,:out]meansredirectingchildstderrtochildstdout.Theydifferifstdoutisredirectedinthechildprocessasfollows.

pid=spawn(command,:out=>["log","w"],:err=>[:child

[:child,:out]canbeusedtomergestderrintostdoutinIO.popen.Inthiscase,IO.popenredirectsstdouttoapipeinthechildprocessand[:child,:out]referstheredirectedstdout.

io=IO.popen(["sh","-c","echoout;echoerr>&2",:

pio.read#=>"out\nerr\n"

The:chdirkeyinoptionsspecifiesthecurrentdirectory.

pid=spawn(command,:chdir=>"/var/tmp")

spawnclosesallnon-standardunspecified

descriptorsbydefault.The“standard”descriptorsare0,1and2.Thisbehaviorisspecifiedby:close_othersoption.:close_othersdoesn'taffectthestandarddescriptorswhichareclosedonlyif:closeisspecifiedexplicitly.

pid=spawn(command,:close_others=>true)#close3,4,5,...(default)

pid=spawn(command,:close_others=>false)#don'tclose3,4,5,...

:close_othersistruebydefaultforspawnandIO.popen.

Notethatfdswhichclose-on-execflagisalreadysetareclosedregardlessof:close_othersoption.

SoIO.pipeandspawncanbeusedasIO.popen.

#similartor=IO.popen(command)

r,w=IO.pipe

pid=spawn(command,:out=>w)#r,wisclosedinthechildprocess.

w.close

:closeisspecifiedasahashvaluetocloseafdindividually.

f=open(foo)

system(command,f=>:close)#don'tinheritf.

Ifafiledescriptorneedtobeinherited,io=>iocanbeused.

#valgrindhas--log-fdoptionforlogdestination.

#log_w=>log_windicateslog_w.filenoinheritstochildprocess.

log_r,log_w=IO.pipe

pid=spawn("valgrind","--log-fd=#{log_w.fileno}","echo"

log_w.close

plog_r.read

Itisalsopossibletoexchangefiledescriptors.

pid=spawn(command,:out=>:err,:err=>:out)

Thehashkeysspecifyfiledescriptorsinthechildprocess.Thehashvaluesspecifiesfiledescriptorsintheparentprocess.Sotheabovespecifiesexchangingstdoutandstderr.Internally,spawnusesanextrafiledescriptortoresolvesuchcyclicfiledescriptormapping.

SeeKernel.execforthestandardshell.

Returnsthestringresultingfromapplyingformat_stringtoanyadditionalarguments.Withintheformatstring,anycharactersotherthanformatsequencesarecopiedtotheresult.

Thesyntaxofaformatsequenceisfollows.

%[flags][width][.precision]type

Aformatsequenceconsistsofapercentsign,followedbyoptionalflags,width,andprecisionindicators,thenterminatedwithafieldtypecharacter.Thefieldtypecontrolshowthecorrespondingsprintfargumentistobeinterpreted,whiletheflagsmodifythatinterpretation.

Thefieldtypecharactersare:

Field|IntegerFormat

------+--------------------------------------------------------------

b|Convertargumentasabinarynumber.

|prefixedwith`..1'.

B|Equivalentto`b',butusesanuppercase0Bforprefix

|inthealternativeformatby#.

d|Convertargumentasadecimalnumber.

format(format_string[,arguments...])→stringsprintf(format_string[,arguments...])→string

i|Identicalto`d'.

o|Convertargumentasanoctalnumber.

|prefixedwith`..7'.

u|Identicalto`d'.

x|Convertargumentasahexadecimalnumber.

|prefixedwith`..f'(representinganinfinitestringof

|leading'ff's).

X|Equivalentto`x',butusesuppercaseletters.

Field|FloatFormat

------+--------------------------------------------------------------

e|Convertfloatingpointargumentintoexponentialnotation

|withonedigitbeforethedecimalpointas[-]d.dddddde[+-]dd.

|Theprecisionspecifiesthenumberofdigitsafterthedecimal

|point(defaultingtosix).

E|Equivalentto`e',butusesanuppercaseEtoindicate

|theexponent.

f|Convertfloatingpointargumentas[-]ddd.dddddd,

|wheretheprecisionspecifiesthenumberofdigitsafter

|thedecimalpoint.

g|Convertafloatingpointnumberusingexponentialform

|iftheexponentislessthan-4orgreaterthanor

|equaltotheprecision,orindd.ddddformotherwise.

|Theprecisionspecifiesthenumberofsignificantdigits.

G|Equivalentto`g',butuseanuppercase`E'inexponentform.

a|Convertfloatingpointargumentas[-]0xh.hhhhp[+-]dd,

|whichisconsistedfromoptionalsign,"0x",fractionpart

|ashexadecimal,"p",andexponentialpartasdecimal.

A|Equivalentto`a',butuseuppercase`X'and`P'.

Field|OtherFormat

------+--------------------------------------------------------------

c|Argumentisthenumericcodeforasinglecharacteror

|asinglecharacterstringitself.

p|Thevaluingofargument.inspect.

s|Argumentisastringtobesubstituted.Iftheformat

|sequencecontainsaprecision,atmostthatmanycharacters

|willbecopied.

%|Apercentsignitselfwillbedisplayed.Noargumenttaken.

Theflagsmodifiesthebehavioroftheformats.Theflagcharactersare:

Flag|Appliesto|Meaning

---------+---------------+-----------------------------------------

space|bBdiouxX|Leaveaspaceatthestartof

|aAeEfgG|non-negativenumbers.

||negativevalues.

---------+---------------+-----------------------------------------

(digit)$|all|Specifiestheabsoluteargumentnumber

||forthisfield.Absoluteandrelative

||argumentnumberscannotbemixedina

||sprintfstring.

---------+---------------+-----------------------------------------

#|bBoxX|Useanalternativeformat.

|aAeEfgG|Fortheconversions`o',increasetheprecision

||untilthefirstdigitwillbe`0'if

||itisnotformattedascomplements.

||Fortheconversions`x',`X',`b'and`B'

||onnon-zero,prefixtheresultwith``0x'',

||``0X'',``0b''and``0B'',respectively.

||Forà',À',è',È',`f',`g',and'G',

||forceadecimalpointtobeadded,

||evenifnodigitsfollow.

||For`g'and'G',donotremovetrailingzeros.

---------+---------------+-----------------------------------------

+|bBdiouxX|Addaleadingplussigntonon-negative

|aAeEfgG|numbers.

||negativevalues.

---------+---------------+-----------------------------------------

-|all|Left-justifytheresultofthisconversion.

---------+---------------+-----------------------------------------

0(zero)|bBdiouxX|Padwithzeros,notspaces.

|aAeEfgG|For`o',`x',`X',`b'and`B',radix-1

|(numericfmt)|isusedfornegativenumbersformattedas

||complements.

---------+---------------+-----------------------------------------

*|all|Usethenextargumentasthefieldwidth.

||Ifnegative,left-justifytheresult.Ifthe

||asteriskisfollowedbyanumberandadollar

||sign,usetheindicatedargumentasthewidth.

Examplesofflags:

#`+'andspaceflagspecifiesthesignofnon-negativenumbers.

sprintf("%d",123)#=>"123"

sprintf("%+d",123)#=>"+123"

sprintf("%d",123)#=>"123"

#`#'flagfor`o'increasesnumberofdigitstoshow`0'.

#`+'andspaceflagchangesformatofnegativenumbers.

sprintf("%o",123)#=>"173"

sprintf("%#o",123)#=>"0173"

sprintf("%+o",-123)#=>"-173"

sprintf("%o",-123)#=>"..7605"

sprintf("%#o",-123)#=>"..7605"

#`#'flagfor`x'addaprefix`0x'fornon-zeronumbers.

sprintf("%x",123)#=>"7b"

sprintf("%#x",123)#=>"0x7b"

sprintf("%+x",-123)#=>"-7b"

sprintf("%x",-123)#=>"..f85"

sprintf("%#x",-123)#=>"0x..f85"

sprintf("%#x",0)#=>"0"

#`#'for`X'usestheprefix`0X'.

sprintf("%X",123)#=>"7B"

sprintf("%#X",123)#=>"0X7B"

#`#'flagfor`b'addaprefix`0b'fornon-zeronumbers.

sprintf("%b",123)#=>"1111011"

sprintf("%#b",123)#=>"0b1111011"

sprintf("%+b",-123)#=>"-1111011"

sprintf("%b",-123)#=>"..10000101"

sprintf("%#b",-123)#=>"0b..10000101"

sprintf("%#b",0)#=>"0"

#`#'for`B'usestheprefix`0B'.

sprintf("%B",123)#=>"1111011"

sprintf("%#B",123)#=>"0B1111011"

#`#'for`e'forcestoshowthedecimalpoint.

sprintf("%.0e",1)#=>"1e+00"

sprintf("%#.0e",1)#=>"1.e+00"

#`#'for`f'forcestoshowthedecimalpoint.

sprintf("%.0f",1234)#=>"1234"

sprintf("%#.0f",1234)#=>"1234."

#`#'for`g'forcestoshowthedecimalpoint.

#Italsodisablesstrippinglowestzeros.

sprintf("%g",123.4)#=>"123.4"

sprintf("%#g",123.4)#=>"123.400"

sprintf("%g",123456)#=>"123456"

sprintf("%#g",123456)#=>"123456."

Thefieldwidthisanoptionalinteger,followedoptionallybyaperiodandaprecision.Thewidthspecifiestheminimumnumberofcharactersthatwillbewrittentotheresultforthisfield.

Examplesofwidth:

#paddingisdonebyspaces,width=20

#0orradix-1.<------------------>

sprintf("%20d",123)#=>"123"

sprintf("%+20d",123)#=>"+123"

sprintf("%020d",123)#=>"00000000000000000123"

sprintf("%+020d",123)#=>"+0000000000000000123"

sprintf("%020d",123)#=>"0000000000000000123"

sprintf("%-20d",123)#=>"123"

sprintf("%-+20d",123)#=>"+123"

sprintf("%-20d",123)#=>"123"

sprintf("%020x",-123)#=>"..ffffffffffffffff85"

Fornumericfields,theprecisioncontrolsthenumberofdecimalplacesdisplayed.Forstringfields,theprecisiondeterminesthemaximumnumberofcharacterstobecopiedfromthestring.(Thus,theformatsequence%10.10swillalwayscontributeexactlytencharacterstotheresult.)

Examplesofprecisions:

#precisionfor`d','o','x'and'b'is

#minimumnumberofdigits<------>

sprintf("%20.8d",123)#=>"00000123"

sprintf("%20.8o",123)#=>"00000173"

sprintf("%20.8x",123)#=>"0000007b"

sprintf("%20.8b",123)#=>"01111011"

sprintf("%20.8d",-123)#=>"-00000123"

sprintf("%20.8o",-123)#=>"..777605"

sprintf("%20.8x",-123)#=>"..ffff85"

sprintf("%20.8b",-11)#=>"..110101"

#"0x"and"0b"for`#x'and`#b'isnotcountedfor

#precisionbut"0"for`#o'iscounted.<------>

sprintf("%#20.8d",123)#=>"00000123"

sprintf("%#20.8o",123)#=>"00000173"

sprintf("%#20.8x",123)#=>"0x0000007b"

sprintf("%#20.8b",123)#=>"0b01111011"

sprintf("%#20.8d",-123)#=>"-00000123"

sprintf("%#20.8o",-123)#=>"..777605"

sprintf("%#20.8x",-123)#=>"0x..ffff85"

sprintf("%#20.8b",-11)#=>"0b..110101"

#precisionfor`e'isnumberof

sprintf("%20.8e",1234.56789)#=>"1.23456789e+03"

#precisionfor`f'isnumberof

sprintf("%20.8f",1234.56789)#=>"1234.56789000"

#precisionfor`g'isnumberof

#significantdigits<------->

sprintf("%20.8g",1234.56789)#=>"1234.5679"

#<------->

sprintf("%20.8g",123456789)#=>"1.2345679e+08"

#precisionfor`s'is

#maximumnumberofcharacters<------>

sprintf("%20.8s","stringtest")#=>"stringt"

Examples:

sprintf("%d%04x",123,123)#=>"123007b"

sprintf("%08b'%4s'",123,123)#=>"01111011'123'"

sprintf("%1$*2$s%2$d%1$s","hello",8)#=>"hello8hello"

sprintf("%1$*2$s%2$d","hello",-8)#=>"hello-8"

sprintf("%+g:%g:%-g",1.23,1.23,1.23)#=>"+1.23:1.23:1.23"

sprintf("%u",-123)#=>"-123"

Formorecomplexformatting,Rubysupportsareferencebyname.%<name>sstyleusesformatstyle,but%{name}styledoesn't.

Examples:

sprintf("%<foo>d:%<bar>f",{:foo=>1,:bar=>2})

#=>1:2.000000

sprintf("%{foo}f",{:foo=>1})

#=>"1f"

Seedsthesystempseudo-randomnumbergenerator,Random::DEFAULT,withnumber.Thepreviousseedvalueisreturned.

Ifnumberisomitted,seedsthegeneratorusingasourceofentropyprovidedbytheoperatingsystem,ifavailable(/dev/urandomonUnixsystemsortheRSAcryptographicprovideronWindows),whichisthencombinedwiththetime,theprocessid,andasequencenumber.

srandmaybeusedtoensurerepeatablesequencesofpseudo-randomnumbersbetweendifferentrunsoftheprogram.Bysettingtheseedtoaknownvalue,programscanbemadedeterministicduringtesting.

srand1234#=>268519324636777531569100071560086917274

[rand,rand]#=>[0.1915194503788923,0.6221087710398319]

[rand(10),rand(1000)]#=>[4,664]

srand1234#=>1234

[rand,rand]#=>[0.1915194503788923,0.6221087710398319]

Equivalentto$_.sub(args),exceptthat$_willbeupdatedifsubstitutionoccurs.Availableonlywhen-p/-ncommandlineoptionspecified.

srand(number=Random.new_seed)→old_seed

sub(pattern,replacement)→$_sub(pattern){|...|block}→$_

Callstheoperatingsystemfunctionidentifiedby_num_and

returnstheresultofthefunctionorraisesSystemCallErrorif

itfailed.

Argumentsforthefunctioncanfollow_num_.Theymustbeeither

+String+objectsor+Integer+objects.A+String+objectispassed

asapointertothebytesequence.An+Integer+objectispassed

asanintegerwhosebitsizeissameasapointer.

Uptonineparametersmaybepassed(14ontheAtari-ST).

Thefunctionidentifiedby_num_issystem

dependent.OnsomeUnixsystems,thenumbersmaybeobtainedfroma

headerfilecalled<code>syscall.h</code>.

syscall4,1,"hello\n",6#'4'iswrite(2)onourbox

<em>produces:</em>

Calling+syscall+onaplatformwhichdoesnothaveanywayto

anarbitrarysystemfunctionjustfailswithNotImplementedError.

Notesyscallisessentiallyunsafeandunportable.Feelfreetoshootyourfoot.DL(Fiddle)libraryispreferredforsaferandabitmoreportableprogramming.

Executescommand…inasubshell.command…isoneoffollowingforms.

commandline:commandlinestringwhichispassedtothestandardshell

cmdname,arg1,...:commandnameandoneormorearguments(noshell)

[cmdname,argv0],arg1,...:commandname,argv[0]andzeroormorearguments(noshell)

syscall(num[,args...])→integer

system([env,]command...[,options])→true,falseornil

systemreturnstrueifthecommandgiveszeroexitstatus,falsefornonzeroexitstatus.Returnsnilifcommandexecutionfails.Anerrorstatusisavailablein$?.TheargumentsareprocessedinthesamewayasforKernel.spawn.

Thehasharguments,envandoptions,aresameasexecandspawn.SeeKernel.spawnfordetails.

system("echo*")

system("echo","*")

produces:

config.hmain.rb

Usesthecharactercmdtoperformvarioustestsonfile1(firsttablebelow)oronfile1andfile2(secondtable).

Filetestsonasinglefile:

CmdReturnsMeaning

"A"|Time|Lastaccesstimeforfile1

"b"|boolean|Trueiffile1isablockdevice

"c"|boolean|Trueiffile1isacharacterdevice

"C"|Time|Lastchangetimeforfile1

"d"|boolean|Trueiffile1existsandisadirectory

"e"|boolean|Trueiffile1exists

"f"|boolean|Trueiffile1existsandisaregularfile

"g"|boolean|Trueiffile1hasthe\CF{setgid}bit

||set(falseunderNT)

"G"|boolean|Trueiffile1existsandhasagroup

||ownershipequaltothecaller'sgroup

"k"|boolean|Trueiffile1existsandhasthestickybitset

"l"|boolean|Trueiffile1existsandisasymboliclink

"M"|Time|Lastmodificationtimeforfile1

"o"|boolean|Trueiffile1existsandisownedby

test(cmd,file1[,file2])→obj

||thecaller'seffectiveuid

"O"|boolean|Trueiffile1existsandisownedby

||thecaller'srealuid

"p"|boolean|Trueiffile1existsandisafifo

"r"|boolean|Trueiffile1isreadablebytheeffective

||uid/gidofthecaller

"R"|boolean|Trueiffileisreadablebythereal

||uid/gidofthecaller

"s"|int/nil|Iffile1hasnonzerosize,returnthesize,

||otherwisereturnnil

"S"|boolean|Trueiffile1existsandisasocket

"u"|boolean|Trueiffile1hasthesetuidbitset

"w"|boolean|Trueiffile1existsandiswritableby

||theeffectiveuid/gid

"W"|boolean|Trueiffile1existsandiswritableby

||therealuid/gid

"x"|boolean|Trueiffile1existsandisexecutableby

||theeffectiveuid/gid

"X"|boolean|Trueiffile1existsandisexecutableby

||therealuid/gid

"z"|boolean|Trueiffile1existsandhasazerolength

Teststhattaketwofiles:

"-"|boolean|Trueiffile1andfile2areidentical

"="|boolean|Trueifthemodificationtimesoffile1

||andfile2areequal

"<"|boolean|Trueifthemodificationtimeoffile1

||ispriortothatoffile2

">"|boolean|Trueifthemodificationtimeoffile1

||isafterthatoffile2

Transferscontroltotheendoftheactivecatchblockwaitingfortag.RaisesUncaughtThrowErrorifthereisnocatchblockforthetag.Theoptionalsecondparametersuppliesareturnvalueforthecatchblock,whichotherwisedefaultstonil.Forexamples,seeKernel::catch.

throw(tag[,obj])

Controlstracingofassignmentstoglobalvariables.Theparametersymbolidentifiesthevariable(aseitherastringnameorasymbolidentifier).cmd(whichmaybeastringoraProcobject)orblockisexecutedwheneverthevariableisassigned.TheblockorProcobjectreceivesthevariable'snewvalueasaparameter.AlsoseeKernel::untrace_var.

trace_var:$_,proc{|v|puts"$_isnow'#{v}'"}

$_="hello"

$_='there'

produces:

$_isnow'hello'

$_isnow'there'

Specifiesthehandlingofsignals.Thefirstparameterisasignalname(astringsuchas“SIGALRM'',“SIGUSR1'',andsoon)orasignalnumber.Thecharacters“SIG''maybeomittedfromthesignalname.Thecommandorblockspecifiescodetoberunwhenthesignalisraised.Ifthecommandisthestring“IGNORE''or“SIG_IGN'',thesignalwillbeignored.Ifthecommandis“DEFAULT''or“SIG_DFL'',theRuby'sdefaulthandlerwillbeinvoked.Ifthecommandis“EXIT'',thescriptwillbeterminatedbythesignal.Ifthecommandis“SYSTEM_DEFAULT'',theoperatingsystem'sdefaulthandlerwillbeinvoked.Otherwise,thegivencommandorblockwillberun.Thespecialsignalname“EXIT''orsignalnumberzerowillbeinvoked

trace_var(symbol,cmd)→niltrace_var(symbol){|val|block}→nil

trap(signal,command)→objtrap(signal){||block}→obj

justpriortoprogramtermination.trapreturnstheprevioushandlerforthegivensignal.

Signal.trap(0,proc{puts"Terminating:#{$$}"})

Signal.trap("CLD"){puts"Childdied"}

fork&&Process.wait

produces:

Terminating:27461

Childdied

Terminating:27460

Removestracingforthespecifiedcommandonthegivenglobalvariableandreturnsnil.Ifnocommandisspecified,removesalltracingforthatvariableandreturnsanarraycontainingthecommandsactuallyremoved.

DisplayseachofthegivenmessagesfollowedbyarecordseparatoronSTDERRunlesswarningshavebeendisabled(forexamplewiththe-W0flag).

warn("warning1","warning2")

<em>produces:</em>

warning1

warning2

untrace_var(symbol[,cmd])→arrayornil

warn(msg,...)→nil

classKeyErrorRaisedwhenthespecifiedkeyisnotfound.ItisasubclassofIndexError.

h={"foo"=>:bar}

h.fetch("foo")#=>:bar

h.fetch("baz")#=>KeyError:keynotfound:"baz"

InFileserror.c

ParentIndexError

classLoadErrorRaisedwhenafilerequired(aRubyscript,extensionlibrary,…)failstoload.

require'this/file/does/not/exist'

raisestheexception:

LoadError:nosuchfiletoload--this/file/does/not/exist

InFileserror.c

ParentScriptError

Attributes

thepathfailedtoload

rb_intern_const("path") [R]

classLocalJumpErrorRaisedwhenRubycan'tyieldasrequested.

Atypicalscenarioisattemptingtoyieldwhennoblockisgiven:

defcall_block

yield42

call_block

raisestheexception:

LocalJumpError:noblockgiven(yield)

Amoresubtleexample:

defget_me_a_return

Proc.new{return42}

get_me_a_return.call

raisestheexception:

LocalJumpError:unexpectedreturn

InFilesproc.c

ParentStandardError

ReturnstheexitvalueassociatedwiththisLocalJumpError.

Thereasonthisblockwasterminated::break,:redo,:retry,:next,:return,or:noreason.

exit_value→obj

reason→symbol

moduleMarshalThemarshalinglibraryconvertscollectionsofRubyobjectsintoabytestream,allowingthemtobestoredoutsidethecurrentlyactivescript.Thisdatamaysubsequentlybereadandtheoriginalobjectsreconstituted.

Marshaleddatahasmajorandminorversionnumbersstoredalongwiththeobjectinformation.Innormaluse,marshalingcanonlyloaddatawrittenwiththesamemajorversionnumberandanequalorlowerminorversionnumber.IfRuby's“verbose''flagisset(normallyusing-d,-v,-w,or–verbose)themajorandminornumbersmustmatchexactly.MarshalversioningisindependentofRuby'sversionnumbers.Youcanextracttheversionbyreadingthefirsttwobytesofmarshaleddata.

str=Marshal.dump("thing")

RUBY_VERSION#=>"1.9.0"

str[0].ord#=>4

str[1].ord#=>8

Someobjectscannotbedumped:iftheobjectstobedumpedincludebindings,procedureormethodobjects,instancesofclassIO,orsingletonobjects,aTypeErrorwillberaised.

Ifyourclasshasspecialserializationneeds(for

example,ifyouwanttoserializeinsomespecificformat),orifitcontainsobjectsthatwouldotherwisenotbeserializable,youcanimplementyourownserializationstrategy.

Therearetwomethodsofdoingthis,yourobjectcandefineeithermarshal_dumpandmarshal_loador_dumpand_load.marshal_dumpwilltakeprecedenceover_dumpifbotharedefined.marshal_dumpmayresultinsmallerMarshalstrings.

Securityconsiderations

Bydesign,::loadcandeserializealmostanyclassloadedintotheRubyprocess.InmanycasesthiscanleadtoremotecodeexecutioniftheMarshaldataisloadedfromanuntrustedsource.

Asaresult,::loadisnotsuitableasageneralpurposeserializationformatandyoushouldneverunmarshalusersuppliedinputorotheruntrusteddata.

Ifyouneedtodeserializeuntrusteddata,useJSONoranotherserializationformatthatisonlyabletoloadsimple,'primitive'typessuchasString,Array,Hash,etc.Neverallowuserinputtospecifyarbitrarytypestodeserializeinto.

marshal_dumpandmarshal_load

Whendumpinganobjectthemethodmarshal_dumpwillbecalled.marshal_dumpmustreturnaresultcontainingtheinformationnecessaryformarshal_loadtoreconstitutetheobject.Theresultcanbeanyobject.

Whenloadinganobjectdumpedusingmarshal_dumptheobjectisfirstallocatedthenmarshal_loadiscalledwiththeresultfrommarshal_dump.marshal_loadmustrecreatetheobjectfromtheinformationintheresult.

Example:

classMyObj

definitializename,version,data

@name=name

@version=version

@data=data

defmarshal_dump

[@name,@version]

defmarshal_loadarray

@name,@version=array

_dumpand_load

Use_dumpand_loadwhenyouneedtoallocatetheobjectyou'rerestoringyourself.

Whendumpinganobjecttheinstancemethod_dumpiscalledwithanIntegerwhichindicatesthemaximumdepthofobjectstodump(avalueof-1impliesthatyoushoulddisabledepthchecking)._dumpmustreturnaStringcontainingtheinformationnecessarytoreconstitutetheobject.

Theclassmethod_loadshouldtakeaStringanduseittoreturnanobjectofthesameclass.

Example:

classMyObj

definitializename,version,data

@name=name

@version=version

@data=data

def_dumplevel

[@name,@version].join':'

defself._loadargs

new(*args.split(':'))

Since::dumpoutputsastringyoucanhave

_dumpreturnaMarshalstringwhichisMarshal.loadedin_loadforcomplexobjects.

InFilesmarshal.c

Constants

MAJOR_VERSION

majorversion

MINOR_VERSION

minorversion

PublicClassMethods

Serializesobjandalldescendantobjects.IfanIOisspecified,theserializeddatawillbewrittentoit,otherwisethedatawillbereturnedasaString.Iflimitisspecified,thetraversalofsubobjectswillbelimitedtothatdepth.Iflimitisnegative,nocheckingofdepthwillbeperformed.

classKlass

definitialize(str)

@str=str

defsay_hello

dump(obj[,anIO],limit=-1)→anIO

(producesnooutput)

o=Klass.new("hello\n")

data=Marshal.dump(o)

obj=Marshal.load(data)

obj.say_hello#=>"hello\n"

Marshalcan'tdumpfollowingobjects:

anonymousClass/Module.

objectswhicharerelatedtosystem(ex:Dir,File::Stat,IO,File,Socketandsoon)

aninstanceofMatchData,Data,Method,UnboundMethod,Proc,Thread,ThreadGroup,Continuation

objectswhichdefinesingletonmethods

ReturnstheresultofconvertingtheserializeddatainsourceintoaRubyobject(possiblywithassociatedsubordinateobjects).sourcemaybeeitheraninstanceofIOoranobjectthatrespondstoto_str.Ifprocisspecified,eachobjectwillbepassedtotheproc,astheobjectisbeingdeserialized.

Neverpassuntrusteddata(includingusersuppliedinput)tothismethod.Pleaseseetheoverviewforfurtherdetails.

ReturnstheresultofconvertingtheserializeddatainsourceintoaRubyobject(possiblywithassociatedsubordinateobjects).sourcemaybeeitheraninstanceofIOoranobjectthatrespondstoto_str.If

load(source[,proc])→objrestore(source[,proc])→obj

procisspecified,eachobjectwillbepassedtotheproc,astheobjectisbeingdeserialized.

Neverpassuntrusteddata(includingusersuppliedinput)tothismethod.Pleaseseetheoverviewforfurtherdetails.

classMatchDataMatchDataisthetypeofthespecialvariable$~,andisthetypeoftheobjectreturnedbyRegexp#matchandRegexp.last_match.Itencapsulatesalltheresultsofapatternmatch,resultsnormallyaccessedthroughthespecialvariables$&,$',$`,$1,$2,andsoon.

InFilesre.c

ParentObject

Equality—Twomatchdataareequaliftheirtargetstrings,patterns,andmatchedpositionsareidentical.

mtch==mtch2→trueorfalseeql?(mtch2)→trueorfalse

mtch[i]→strornilmtch[start,length]→arraymtch[range]→arraymtch[name]→strornil

MatchReference–MatchDataactsasanarray,andmaybeaccessedusingthenormalarrayindexingtechniques.mtch[0]isequivalenttothespecialvariable$&,andreturnstheentirematchedstring.mtch[1],mtch[2],andsoonreturnthevaluesofthematchedbackreferences(portionsofthepatternbetweenparentheses).

m=/(.)(.)(\d+)(\d)/.match("THX1138.")

m#=>#<MatchData"HX1138"1:"H"2:"X"3:"113"4:"8">

m[0]#=>"HX1138"

m[1,2]#=>["H","X"]

m[1..3]#=>["H","X","113"]

m[-3,2]#=>["X","113"]

m=/(?<foo>a+)b/.match("ccaaab")

m#=>#<MatchData"aaab"foo:"aaa">

m["foo"]#=>"aaa"

m[:foo]#=>"aaa"

Returnstheoffsetofthestartofthenthelementofthematcharrayinthestring.ncanbeastringorsymboltoreferenceanamedcapture.

m=/(.)(.)(\d+)(\d)/.match("THX1138.")

m.begin(0)#=>1

m.begin(2)#=>2

m=/(?<foo>.)(.)(?<bar>.)/.match("hoge")

pm.begin(:foo)#=>0

pm.begin(:bar)#=>2

Returnsthearrayofcaptures;equivalenttomtch.to_a[1..-1].

f1,f2,f3,f4=/(.)(.)(\d+)(\d)/.match("THX1138.").captures

begin(n)→integer

captures→array

f1#=>"H"

f2#=>"X"

f3#=>"113"

f4#=>"8"

Returnstheoffsetofthecharacterimmediatelyfollowingtheendofthenthelementofthematcharrayinthestring.ncanbeastringorsymboltoreferenceanamedcapture.

m=/(.)(.)(\d+)(\d)/.match("THX1138.")

m.end(0)#=>7

m.end(2)#=>3

pm.end(:foo)#=>1

pm.end(:bar)#=>3

Equality—Twomatchdataareequaliftheirtargetstrings,patterns,andmatchedpositionsareidentical.

Produceahashbasedonthetargetstring,regexpandmatchedpositionsofthismatchdata.

SeealsoObject#hash.

Returnsaprintableversionofmtch.

puts/.$/.match("foo").inspect

#=>#<MatchData"o">

end(n)→integer

mtch==mtch2→trueorfalseeql?(mtch2)→trueorfalse

hash→integer

inspect→str

puts/(.)(.)(.)/.match("foo").inspect

#=>#<MatchData"foo"1:"f"2:"o"3:"o">

puts/(.)(.)?(.)/.match("fo").inspect

#=>#<MatchData"fo"1:"f"2:nil3:"o">

puts/(?<foo>.)(?<bar>.)(?<baz>.)/.match("hoge").inspect

#=>#<MatchData"hog"foo:"h"bar:"o"baz:"g">

Returnsthenumberofelementsinthematcharray.

m=/(.)(.)(\d+)(\d)/.match("THX1138.")

m.length#=>5

m.size#=>5

Returnsalistofnamesofcapturesasanarrayofstrings.Itissameasmtch.regexp.names.

/(?<foo>.)(?<bar>.)(?<baz>.)/.match("hoge").names

#=>["foo","bar","baz"]

m=/(?<x>.)(?<y>.)?/.match("a")#=>#<MatchData"a"x:"a"y:nil>

m.names#=>["x","y"]

Returnsatwo-elementarraycontainingthebeginningandendingoffsetsofthenthmatch.ncanbeastringorsymboltoreferenceanamedcapture.

m=/(.)(.)(\d+)(\d)/.match("THX1138.")

m.offset(0)#=>[1,7]

m.offset(4)#=>[6,7]

length→integersize→integer

names→[name1,name2,...]

offset(n)→array

pm.offset(:foo)#=>[0,1]

pm.offset(:bar)#=>[2,3]

Returnstheportionoftheoriginalstringafterthecurrentmatch.Equivalenttothespecialvariable$'.

m=/(.)(.)(\d+)(\d)/.match("THX1138:TheMovie")

m.post_match#=>":TheMovie"

Returnstheportionoftheoriginalstringbeforethecurrentmatch.Equivalenttothespecialvariable$`.

m=/(.)(.)(\d+)(\d)/.match("THX1138.")

m.pre_match#=>"T"

Returnstheregexp.

m=/a.*b/.match("abc")

m.regexp#=>/a.*b/

Returnsthenumberofelementsinthematcharray.

m=/(.)(.)(\d+)(\d)/.match("THX1138.")

m.length#=>5

m.size#=>5

Returnsafrozencopyofthestringpassedinto

post_match→str

pre_match→str

regexp→regexp

string→str

match.

m=/(.)(.)(\d+)(\d)/.match("THX1138.")

m.string#=>"THX1138."

Returnsthearrayofmatches.

m=/(.)(.)(\d+)(\d)/.match("THX1138.")

m.to_a#=>["HX1138","H","X","113","8"]

Becauseto_aiscalledwhenexpanding*variable,there'sausefulassignmentshortcutforextractingmatchedfields.Thisisslightlyslowerthanaccessingthefieldsdirectly(asanintermediatearrayisgenerated).

all,f1,f2,f3=*(/(.)(.)(\d+)(\d)/.match("THX1138."))

all#=>"HX1138"

f1#=>"H"

f2#=>"X"

f3#=>"113"

Returnstheentirematchedstring.

m=/(.)(.)(\d+)(\d)/.match("THX1138.")

m.to_s#=>"HX1138"

Useseachindextoaccessthematchingvalues,returninganarrayofthecorrespondingmatches.

m=/(.)(.)(\d+)(\d)/.match("THX1138:TheMovie")

m.to_a#=>["HX1138","H","X","113","8"]

m.values_at(0,2,-2)#=>["HX1138","X","113"]

to_a→anArray

to_s→str

values_at([index]*)→array

moduleMathTheMathmodulecontainsmodulefunctionsforbasictrigonometricandtranscendentalfunctions.SeeclassFloatforalistofconstantsthatdefineRuby'sfloatingpointaccuracy.

Domainsandcodomainsaregivenonlyforreal(notcomplex)numbers.

InFilesmath.c

Constants

DefinitionofthemathematicalconstantE(e)asaFloatnumber.

DefinitionofthemathematicalconstantPIasaFloatnumber.

PublicClassMethods

acos(x)→Float

Computesthearccosineofx.Returns0..PI.

Domain:[-1,1]

Codomain:[0,PI]

Math.acos(0)==Math::PI/2#=>true

Computestheinversehyperboliccosineofx.

Domain:[1,INFINITY)

Codomain:[0,INFINITY)

Math.acosh(1)#=>0.0

Computesthearcsineofx.Returns-PI/2..PI/2.

Domain:[-1,-1]

Codomain:[-PI/2,PI/2]

Math.asin(1)==Math::PI/2#=>true

Computestheinversehyperbolicsineofx.

Domain:(-INFINITY,INFINITY)

Codomain:(-INFINITY,INFINITY)

Math.asinh(1)#=>0.881373587019543

Computesthearctangentofx.Returns-PI/2..PI/2.

acosh(x)→Float

asin(x)→Float

asinh(x)→Float

atan(x)→Float

Codomain:(-PI/2,PI/2)

Math.atan(0)#=>0.0

Computesthearctangentgivenyandx.ReturnsaFloatintherange-PI..PI.

Codomain:[-PI,PI]

Math.atan2(-0.0,-1.0)#=>-3.141592653589793

Math.atan2(-1.0,-1.0)#=>-2.356194490192345

Math.atan2(-1.0,0.0)#=>-1.5707963267948966

Math.atan2(-1.0,1.0)#=>-0.7853981633974483

Math.atan2(-0.0,1.0)#=>-0.0

Math.atan2(0.0,1.0)#=>0.0

Math.atan2(1.0,1.0)#=>0.7853981633974483

Math.atan2(1.0,0.0)#=>1.5707963267948966

Math.atan2(1.0,-1.0)#=>2.356194490192345

Math.atan2(0.0,-1.0)#=>3.141592653589793

Math.atan2(INFINITY,INFINITY)#=>0.7853981633974483

Math.atan2(INFINITY,-INFINITY)#=>2.356194490192345

Math.atan2(-INFINITY,INFINITY)#=>-0.7853981633974483

Math.atan2(-INFINITY,-INFINITY)#=>-2.356194490192345

Computestheinversehyperbolictangentofx.

Domain:(-1,1)

Math.atanh(1)#=>Infinity

Returnsthecuberootofx.

atan2(y,x)→Float

atanh(x)→Float

cbrt(x)→Float

Domain:[0,INFINITY)

-9.upto(9){|x|

p[x,Math.cbrt(x),Math.cbrt(x)**3]

#=>[-9,-2.0800838230519,-9.0]

#[-8,-2.0,-8.0]

#[-7,-1.91293118277239,-7.0]

#[-6,-1.81712059283214,-6.0]

#[-5,-1.7099759466767,-5.0]

#[-4,-1.5874010519682,-4.0]

#[-3,-1.44224957030741,-3.0]

#[-2,-1.25992104989487,-2.0]

#[-1,-1.0,-1.0]

#[0,0.0,0.0]

#[1,1.0,1.0]

#[2,1.25992104989487,2.0]

#[3,1.44224957030741,3.0]

#[4,1.5874010519682,4.0]

#[5,1.7099759466767,5.0]

#[6,1.81712059283214,6.0]

#[7,1.91293118277239,7.0]

#[8,2.0,8.0]

#[9,2.0800838230519,9.0]

Computesthecosineofx(expressedinradians).ReturnsaFloatintherange-1.0..1.0.

Codomain:[-1,1]

Math.cos(Math::PI)#=>-1.0

Computesthehyperboliccosineofx(expressedinradians).

cos(x)→Float

cosh(x)→Float

Math.cosh(0)#=>1.0

Calculatestheerrorfunctionofx.

Codomain:(-1,1)

Math.erf(0)#=>0.0

Calculatesthecomplementaryerrorfunctionofx.

Codomain:(0,2)

Math.erfc(0)#=>1.0

Returnse**x.

Codomain:(0,INFINITY)

Math.exp(0)#=>1.0

Math.exp(1)#=>2.718281828459045

Math.exp(1.5)#=>4.4816890703380645

Returnsatwo-elementarraycontainingthenormalizedfraction(aFloat)andexponent(aFixnum)ofx.

erf(x)→Float

erfc(x)→Float

exp(x)→Float

frexp(x)→[fraction,exponent]

fraction,exponent=Math.frexp(1234)#=>[0.6025390625,11]

fraction*2**exponent#=>1234.0

Calculatesthegammafunctionofx.

Notethatgamma(n)issameasfact(n-1)forintegern>0.Howevergamma(n)returnsfloatandcanbeanapproximation.

deffact(n)(1..n).inject(1){|r,i|r*i}end

1.upto(26){|i|p[i,Math.gamma(i),fact(i-1)]}

#=>[1,1.0,1]

#[2,1.0,1]

#[3,2.0,2]

#[4,6.0,6]

#[5,24.0,24]

#[6,120.0,120]

#[7,720.0,720]

#[8,5040.0,5040]

#[9,40320.0,40320]

#[10,362880.0,362880]

#[11,3628800.0,3628800]

#[12,39916800.0,39916800]

#[13,479001600.0,479001600]

#[14,6227020800.0,6227020800]

#[15,87178291200.0,87178291200]

#[16,1307674368000.0,1307674368000]

#[17,20922789888000.0,20922789888000]

#[18,355687428096000.0,355687428096000]

#[19,6.402373705728e+15,6402373705728000]

#[20,1.21645100408832e+17,121645100408832000]

#[21,2.43290200817664e+18,2432902008176640000]

#[22,5.109094217170944e+19,51090942171709440000]

#[23,1.1240007277776077e+21,1124000727777607680000]

#[24,2.5852016738885062e+22,25852016738884976640000]

#[25,6.204484017332391e+23,620448401733239439360000]

#[26,1.5511210043330954e+25,15511210043330985984000000]

gamma(x)→Float

hypot(x,y)→Float

Returnssqrt(x**2+y**2),thehypotenuseofaright-angledtrianglewithsidesxandy.

Math.hypot(3,4)#=>5.0

Returnsthevalueoffraction*(2**exponent).

fraction,exponent=Math.frexp(1234)

Math.ldexp(fraction,exponent)#=>1234.0

Calculatesthelogarithmicgammaofxandthesignofgammaofx.

::lgammaissameas

[Math.log(Math.gamma(x).abs),Math.gamma(x)<0?-1:1]

butavoidoverflowby::gammaforlargex.

Math.lgamma(0)#=>[Infinity,1]

Returnsthelogarithmofx.Ifadditionalsecondargumentisgiven,itwillbethebaseoflogarithm.Otherwiseitise(forthenaturallogarithm).

Domain:(0,INFINITY)

Math.log(0)#=>-Infinity

Math.log(1)#=>0.0

Math.log(Math::E)#=>1.0

Math.log(Math::E**3)#=>3.0

ldexp(fraction,exponent)→float

lgamma(x)→[float,-1or1]

log(x)→Floatlog(x,base)→Float

Math.log(12,3)#=>2.2618595071429146

Returnsthebase10logarithmofx.

Domain:(0,INFINITY)

Math.log10(1)#=>0.0

Math.log10(10)#=>1.0

Math.log10(10**100)#=>100.0

Returnsthebase2logarithmofx.

Domain:(0,INFINITY)

Math.log2(1)#=>0.0

Math.log2(2)#=>1.0

Math.log2(32768)#=>15.0

Math.log2(65536)#=>16.0

Computesthesineofx(expressedinradians).ReturnsaFloatintherange-1.0..1.0.

Codomain:[-1,1]

Math.sin(Math::PI/2)#=>1.0

Computesthehyperbolicsineofx(expressedinradians).

log10(x)→Float

log2(x)→Float

sin(x)→Float

sinh(x)→Float

Math.sinh(0)#=>0.0

Returnsthenon-negativesquarerootofx.

Domain:[0,INFINITY)

0.upto(10){|x|

p[x,Math.sqrt(x),Math.sqrt(x)**2]

#=>[0,0.0,0.0]

#[1,1.0,1.0]

#[2,1.4142135623731,2.0]

#[3,1.73205080756888,3.0]

#[4,2.0,4.0]

#[5,2.23606797749979,5.0]

#[6,2.44948974278318,6.0]

#[7,2.64575131106459,7.0]

#[8,2.82842712474619,8.0]

#[9,3.0,9.0]

#[10,3.16227766016838,10.0]

Computesthetangentofx(expressedinradians).

Math.tan(0)#=>0.0

Computesthehyperbolictangentofx(expressedinradians).

sqrt(x)→Float

tan(x)→Float

tanh(x)→Float

Codomain:(-1,1)

Math.tanh(0)#=>0.0

classMath::DomainErrorRaisedwhenamathematicalfunctionisevaluatedoutsideofitsdomainofdefinition.

Forexample,sincecosreturnsvaluesintherange-1..1,itsinversefunctionacosisonlydefinedonthatinterval:

Math.acos(42)

produces:

Math::DomainError:Numericalargumentisoutofdomain-"acos"

InFilesmath.c

ParentStandardError

classMethodProc

InFilesproc.c

ParentObject

Twomethodobjectsareequaliftheyareboundtothesameobjectandrefertothesamemethoddefinitionandtheirownersarethesameclassormodule.

Invokesthemethwiththespecifiedarguments,returningthemethod'sreturnvalue.

m=12.method("+")

m.call(3)#=>15

m.call(20)#=>32

eql?(other_meth)→trueorfalsemeth==other_meth→trueorfalse

call(args,...)→objmeth[args,...]→obj

Returnsanindicationofthenumberofargumentsacceptedbyamethod.Returnsanonnegativeintegerformethodsthattakeafixednumberofarguments.ForRubymethodsthattakeavariablenumberofarguments,returns-n-1,wherenisthenumberofrequiredarguments.FormethodswritteninC,returns-1ifthecalltakesavariablenumberofarguments.

classC

defone;end

deftwo(a);end

defthree(*a);end

deffour(a,b);end

deffive(a,b,*c);end

defsix(a,b,*c,&d);end

c=C.new

c.method(:one).arity#=>0

c.method(:two).arity#=>1

c.method(:three).arity#=>-1

c.method(:four).arity#=>2

c.method(:five).arity#=>-3

c.method(:six).arity#=>-3

"cat".method(:size).arity#=>0

"cat".method(:replace).arity#=>1

"cat".method(:squeeze).arity#=>-1

"cat".method(:count).arity#=>-1

Invokesthemethwiththespecifiedarguments,returningthemethod'sreturnvalue.

m=12.method("+")

m.call(3)#=>15

m.call(20)#=>32

arity→fixnum

call(args,...)→objmeth[args,...]→obj

Returnsacloneofthismethod.

classA

deffoo

return"bar"

m=A.new.method(:foo)

m.call#=>"bar"

n=m.clone.call#=>"bar"

Returnsacurriedprocbasedonthemethod.Whentheprociscalledwithanumberofargumentsthatislowerthanthemethod'sarity,thenanothercurriedprocisreturned.Onlywhenenoughargumentshavebeensuppliedtosatisfythemethodsignature,willthemethodactuallybecalled.

Theoptionalarityargumentshouldbesuppliedwhencurryingmethodswithvariableargumentstodeterminehowmanyargumentsareneededbeforethemethodiscalled.

deffoo(a,b,c)

[a,b,c]

proc=self.method(:foo).curry

proc2=proc.call(1,2)#=>#<Proc>

proc2.call(3)#=>[1,2,3]

defvararg(*args)

proc=self.method(:vararg).curry(4)

proc2=proc.call(:x)#=>#<Proc>

clone→new_method

curry→proccurry(arity)→proc

proc3=proc2.call(:y,:z)#=>#<Proc>

proc3.call(:a)#=>[:x,:y,:z,:a]

Twomethodobjectsareequaliftheyareboundtothesameobjectandrefertothesamemethoddefinitionandtheirownersarethesameclassormodule.

Returnsahashvaluecorrespondingtothemethodobject.

SeealsoObject#hash.

Returnsthenameoftheunderlyingmethod.

"cat".method(:count).inspect#=>"#<Method:String#count>"

Returnsthenameofthemethod.

Returnstheoriginalnameofthemethod.

Returnstheclassormodulethatdefinesthemethod.

hash→integer

name→symbol

original_name→symbol

owner→class_or_module

Returnstheparameterinformationofthismethod.

Returnstheboundreceiverofthemethodobject.

ReturnstheRubysourcefilenameandlinenumbercontainingthismethodornilifthismethodwasnotdefinedinRuby(i.e.native)

ReturnsaMethodofsuperclass,whichwouldbecalledwhensuperisused.

ReturnsaProcobjectcorrespondingtothismethod.

Dissociatesmethfromitscurrentreceiver.TheresultingUnboundMethodcansubsequentlybeboundtoanewobjectofthesameclass(seeUnboundMethod).

parameters→array

receiver→object

source_location→[String,Fixnum]

super_method()

to_proc→proc

unbind→unbound_method

classModuleAModuleisacollectionofmethodsandconstants.Themethodsinamodulemaybeinstancemethodsormodulemethods.Instancemethodsappearasmethodsinaclasswhenthemoduleisincluded,modulemethodsdonot.Conversely,modulemethodsmaybecalledwithoutcreatinganencapsulatingobject,whileinstancemethodsmaynot.(SeeModule#module_function.)

Inthedescriptionsthatfollow,theparametersymreferstoasymbol,whichiseitheraquotedstringoraSymbol(suchas:name).

moduleMod

includeMath

CONST=1

defmeth

Mod.class#=>Module

Mod.constants#=>[:CONST,:PI,:E]

Mod.instance_methods#=>[:meth]

InFilesclass.ceval.cload.c

object.cproc.cvm_eval.cvm_method.c

ParentObject

PublicClassMethods

Inthefirstform,returnsanarrayofthenamesofallconstantsaccessiblefromthepointofcall.Thislistincludesthenamesofallmodulesandclassesdefinedintheglobalscope.

Module.constants.first(4)

#=>[:ARGF,:ARGV,:ArgumentError,:Array]

Module.constants.include?(:SEEK_SET)#=>false

classIO

Module.constants.include?(:SEEK_SET)#=>true

Thesecondformcallstheinstancemethodconstants.

ReturnsthelistofModulesnestedatthepointofcall.

moduleM1

moduleM2

$a=Module.nesting

constants→arrayconstants(inherited)→array

nesting→array

$a#=>[M1::M2,M1]

$a[0].name#=>"M1::M2"

Createsanewanonymousmodule.Ifablockisgiven,itispassedthemoduleobject,andtheblockisevaluatedinthecontextofthismoduleusingmodule_eval.

fred=Module.newdo

defmeth1

"hello"

defmeth2

a="mystring"

a.extend(fred)#=>"mystring"

a.meth1#=>"hello"

a.meth2#=>"bye"

Assignthemoduletoaconstant(namestartinguppercase)ifyouwanttotreatitlikearegularmodule.

Returnstrueifmodisasubclassofother.Returnsnilifthere'snorelationshipbetweenthetwo.(Thinkoftherelationshipintermsoftheclassdefinition:“classA<B”implies“A<B”.)

new→modnew{|mod|block}→mod

mod<other→true,false,ornil

Returnstrueifmodisasubclassofotheroristhesameasother.Returnsnilifthere'snorelationshipbetweenthetwo.(Thinkoftherelationshipintermsoftheclassdefinition:“classA<B”implies“A<B”.)

Comparison—Returns-1,0,+1ornildependingonwhethermoduleincludesother_module,theyarethesame,orifmoduleisincludedbyother_module.ThisisthebasisforthetestsinComparable.

Returnsnilifmodulehasnorelationshipwithother_module,ifother_moduleisnotamodule,orifthetwovaluesareincomparable.

obj="a"

other=obj.dup

obj==other#=>true

mod<=other→true,false,ornil

module<=>other_module→-1,0,+1,ornil

1==1.0#=>true

1.eql?1.0#=>false

CaseEquality—Returnstrueifobjisaninstanceofmodoroneofmod'sdescendants.Oflimiteduseformodules,butcanbeusedincasestatementstoclassifyobjectsbyclass.

Returnstrueifmodisanancestorofother.Returnsnilifthere'snorelationshipbetweenthetwo.(Thinkoftherelationshipintermsoftheclassdefinition:“classA<B”implies“B>A”.)

Returnstrueifmodisanancestorofother,orthetwomodulesarethesame.Returnsnilifthere'snorelationshipbetweenthetwo.(Thinkoftherelationshipintermsoftheclassdefinition:“classA<B”implies“B>A”.)

mod===obj→trueorfalse

mod>other→true,false,ornil

mod>=other→true,false,ornil

ancestors→array

Returnsalistofmodulesincluded/prependedinmod(includingmoditself).

moduleMod

includeMath

includeComparable

prependEnumerable

Mod.ancestors#=>[Enumerable,Mod,Comparable,Math]

Math.ancestors#=>[Math]

Enumerable.ancestors#=>[Enumerable]

Registersfilenametobeloaded(usingKernel::require)thefirsttimethatmodule(whichmaybeaStringorasymbol)isaccessedinthenamespaceofmod.

moduleA

A.autoload(:B,"b")

A::B.doit#autoloads"b"

Returnsfilenametobeloadedifnameisregisteredasautoloadinthenamespaceofmod.

moduleA

A.autoload(:B,"b")

A.autoload?(:B)#=>"b"

autoload(module,filename)→nil

autoload?(name)→Stringornil

class_eval(string[,filename[,lineno]])→objmodule_eval{||block}→obj

Evaluatesthestringorblockinthecontextofmod,exceptthatwhenablockisgiven,constant/classvariablelookupisnotaffected.Thiscanbeusedtoaddmethodstoaclass.module_evalreturnstheresultofevaluatingitsargument.Theoptionalfilenameandlinenoparameterssetthetextforerrormessages.

classThing

a=%q{defhello()"Hellothere!"end}

Thing.module_eval(a)

putsThing.new.hello()

Thing.module_eval("invalidcode","dummy",123)

produces:

Hellothere!

dummy:123:in`module_eval':undefinedlocalvariable

ormethod`code'forThing:Class

Evaluatesthegivenblockinthecontextoftheclass/module.Themethoddefinedintheblockwillbelongtothereceiver.Anyargumentspassedtothemethodwillbepassedtotheblock.Thiscanbeusediftheblockneedstoaccessinstancevariables.

classThing

Thing.class_exec{

defhello()"Hellothere!"end

produces:

Hellothere!

module_exec(arg...){|var...|block}→objclass_exec(arg...){|var...|block}→obj

Returnstrueifthegivenclassvariableisdefinedinobj.Stringargumentsareconvertedtosymbols.

classFred

@@foo=99

Fred.class_variable_defined?(:@@foo)#=>true

Fred.class_variable_defined?(:@@bar)#=>false

Returnsthevalueofthegivenclassvariable(orthrowsaNameErrorexception).The@@partofthevariablenameshouldbeincludedforregularclassvariables.Stringargumentsareconvertedtosymbols.

classFred

@@foo=99

Fred.class_variable_get(:@@foo)#=>99

Setstheclassvariablenamedbysymboltothegivenobject.Iftheclassvariablenameispassedasastring,thatstringisconvertedtoasymbol.

classFred

@@foo=99

deffoo

class_variable_defined?(symbol)→trueorfalseclass_variable_defined?(string)→trueorfalse

class_variable_get(symbol)→objclass_variable_get(string)→obj

class_variable_set(symbol,obj)→objclass_variable_set(string,obj)→obj

Fred.class_variable_set(:@@foo,101)#=>101

Fred.new.foo#=>101

Returnsanarrayofthenamesofclassvariablesinmod.Thisincludesthenamesofclassvariablesinanyincludedmodules,unlesstheinheritparameterissettofalse.

classOne

@@var1=1

classTwo<One

@@var2=2

One.class_variables#=>[:@@var1]

Two.class_variables#=>[:@@var2,:@@var1]

Two.class_variables(false)#=>[:@@var2]

Sayswhethermodoritsancestorshaveaconstantwiththegivenname:

Float.const_defined?(:EPSILON)#=>true,foundinFloatitself

Float.const_defined?("String")#=>true,foundinObject(ancestor)

BasicObject.const_defined?(:Hash)#=>false

IfmodisaModule,additionallyObjectanditsancestorsarechecked:

Math.const_defined?(:String)#=>true,foundinObject

class_variables(inherit=true)→array

const_defined?(sym,inherit=true)→trueorfalseconst_defined?(str,inherit=true)→trueorfalse

Ineachofthecheckedclassesormodules,iftheconstantisnotpresentbutthereisanautoloadforit,trueisreturneddirectlywithoutautoloading:

moduleAdmin

autoload:User,'admin/user'

Admin.const_defined?(:User)#=>true

Iftheconstantisnotfoundthecallbackconst_missingisnotcalledandthemethodreturnsfalse.

Ifinheritisfalse,thelookuponlycheckstheconstantsinthereceiver:

IO.const_defined?(:SYNC)#=>true,foundinFile::Constants(ancestor)

IO.const_defined?(:SYNC,false)#=>false,notfoundinIOitself

Inthiscase,thesamelogicforautoloadingapplies.

IftheargumentisnotavalidconstantnameaNameErrorisraisedwiththemessage“wrongconstantnamename”:

Hash.const_defined?'foobar'#=>NameError:wrongconstantnamefoobar

Checksforaconstantwiththegivennameinmod.Ifinheritisset,thelookupwillalsosearchtheancestors(andObjectifmodisaModule).

Thevalueoftheconstantisreturnedifadefinitionisfound,otherwiseaNameErrorisraised.

Math.const_get(:PI)#=>3.14159265358979

const_get(sym,inherit=true)→objconst_get(str,inherit=true)→obj

Thismethodwillrecursivelylookupconstantnamesifanamespacedclassnameisprovided.Forexample:

moduleFoo;classBar;endend

Object.const_get'Foo::Bar'

Theinheritflagisrespectedoneachlookup.Forexample:

moduleFoo

classBar

VAL=10

classBaz<Bar;end

Object.const_get'Foo::Baz::VAL'#=>10

Object.const_get'Foo::Baz::VAL',false#=>NameError

IftheargumentisnotavalidconstantnameaNameErrorwillberaisedwithawarning“wrongconstantname”.

Object.const_get'foobar'#=>NameError:wrongconstantnamefoobar

Invokedwhenareferenceismadetoanundefinedconstantinmod.Itispassedasymbolfortheundefinedconstant,andreturnsavaluetobeusedforthatconstant.Thefollowingcodeisanexampleofthesame:

defFoo.const_missing(name)

name#returntheconstantnameasSymbol

Foo::UNDEFINED_CONST#=>:UNDEFINED_CONST:symbolreturned

const_missing(sym)→obj

Inthenextexamplewhenareferenceismadetoanundefinedconstant,itattemptstoloadafilewhosenameisthelowercaseversionoftheconstant(thusclassFredisassumedtobeinfilefred.rb).Iffound,itreturnstheloadedclass.ItthereforeimplementsanautoloadfeaturesimilartoKernel#autoloadand#autoload.

defObject.const_missing(name)

@looked_for||={}

str_name=name.to_s

raise"Classnotfound:#{name}"if@looked_for[str_name

@looked_for[str_name]=1

file=str_name.downcase

requirefile

klass=const_get(name)

returnklassifklass

raise"Classnotfound:#{name}"

Setsthenamedconstanttothegivenobject,returningthatobject.Createsanewconstantifnoconstantwiththegivennamepreviouslyexisted.

Math.const_set("HIGH_SCHOOL_PI",22.0/7.0)#=>3.14285714285714

Math::HIGH_SCHOOL_PI-Math::PI#=>0.00126448926734968

IfsymorstrisnotavalidconstantnameaNameErrorwillberaisedwithawarning“wrongconstantname”.

Object.const_set('foobar',42)#=>NameError:wrongconstantnamefoobar

const_set(sym,obj)→objconst_set(str,obj)→obj

constants(inherit=true)→array

Returnsanarrayofthenamesoftheconstantsaccessibleinmod.Thisincludesthenamesofconstantsinanyincludedmodules(exampleatstartofsection),unlesstheinheritparameterissettofalse.

IO.constants.include?(:SYNC)#=>true

IO.constants(false).include?(:SYNC)#=>false

AlsoseeModule::const_defined?.

Preventsfurthermodificationstomod.

Thismethodreturnsself.

InvokesModule.append_featuresoneachparameterinreverseorder.

Returnstrueifmoduleisincludedinmodoroneofmod'sancestors.

moduleA

classB

includeA

classC<B

B.include?(A)#=>true

C.include?(A)#=>true

A.include?(A)#=>false

Returnsthelistofmodulesincludedinmod.

freeze→mod

include(module,...)→self

include?(module)→trueorfalse

included_modules→array

moduleMixin

moduleOuter

includeMixin

Mixin.included_modules#=>[]

Outer.included_modules#=>[Mixin]

Aliasfor:to_s

ReturnsanUnboundMethodrepresentingthegiveninstancemethodinmod.

classInterpreter

defdo_a()print"there,";end

defdo_d()print"Hello";end

defdo_e()print"!\n";end

defdo_v()print"Dave";end

Dispatcher={

"a"=>instance_method(:do_a),

"d"=>instance_method(:do_d),

"e"=>instance_method(:do_e),

"v"=>instance_method(:do_v)

definterpret(string)

string.each_char{|b|Dispatcher[b].bind(self).call

interpreter=Interpreter.new

interpreter.interpret('dave')

produces:

Hellothere,Dave!

inspect()

instance_method(symbol)→unbound_method

Returnsanarraycontainingthenamesofthepublicandprotectedinstancemethodsinthereceiver.Foramodule,thesearethepublicandprotectedmethods;foraclass,theyaretheinstance(notsingleton)methods.Iftheoptionalparameterisfalse,themethodsofanyancestorsarenotincluded.

moduleA

defmethod1()end

classB

includeA

defmethod2()end

classC<B

defmethod3()end

A.instance_methods(false)#=>[:method1]

B.instance_methods(false)#=>[:method2]

B.instance_methods(true).include?(:method1)#=>true

C.instance_methods(false)#=>[:method3]

C.instance_methods.include?(:method2)#=>true

Returnstrueifthenamedmethodisdefinedbymod(oritsincludedmodulesand,ifmodisaclass,itsancestors).Publicandprotectedmethodsarematched.Stringargumentsareconvertedtosymbols.

moduleA

defmethod1()end

classB

defmethod2()end

instance_methods(include_super=true)→array

method_defined?(symbol)→trueorfalsemethod_defined?(string)→trueorfalse

classC<B

includeA

defmethod3()end

A.method_defined?:method1#=>true

C.method_defined?"method1"#=>true

C.method_defined?"method4"#=>false

Evaluatesthestringorblockinthecontextofmod,exceptthatwhenablockisgiven,constant/classvariablelookupisnotaffected.Thiscanbeusedtoaddmethodstoaclass.module_evalreturnstheresultofevaluatingitsargument.Theoptionalfilenameandlinenoparameterssetthetextforerrormessages.

classThing

a=%q{defhello()"Hellothere!"end}

Thing.module_eval(a)

Thing.module_eval("invalidcode","dummy",123)

produces:

Hellothere!

dummy:123:in`module_eval':undefinedlocalvariable

ormethod`code'forThing:Class

class_eval(string[,filename[,lineno]])→objmodule_eval{||block}→obj

module_exec(arg...){|var...|block}→objclass_exec(arg...){|var...|block}→obj

Evaluatesthegivenblockinthecontextoftheclass/module.Themethoddefinedintheblockwillbelongtothereceiver.Anyargumentspassedtothemethodwillbepassedtotheblock.Thiscanbeusediftheblockneedstoaccessinstancevariables.

classThing

Thing.class_exec{

defhello()"Hellothere!"end

produces:

Hellothere!

Returnsthenameofthemodulemod.Returnsnilforanonymousmodules.

InvokesModule.prepend_featuresoneachparameterinreverseorder.

Makesexistingclassmethodsprivate.Oftenusedtohidethedefaultconstructornew.

Stringargumentsareconvertedtosymbols.

classSimpleSingleton#Notthreadsafe

private_class_method:new

defSimpleSingleton.create(*args,&block)

@me=new(*args,&block)if!@me

name→string

prepend(module,...)→self

private_class_method(symbol,...)→modprivate_class_method(string,...)→mod

Makesalistofexistingconstantsprivate.

Returnsalistoftheprivateinstancemethodsdefinedinmod.Iftheoptionalparameterisfalse,themethodsofanyancestorsarenotincluded.

moduleMod

defmethod1()end

private:method1

defmethod2()end

Mod.instance_methods#=>[:method2]

Mod.private_instance_methods#=>[:method1]

Returnstrueifthenamedprivatemethodisdefinedby_mod_(oritsincludedmodulesand,ifmodisaclass,itsancestors).Stringargumentsareconvertedtosymbols.

moduleA

defmethod1()end

classB

private

defmethod2()end

classC<B

includeA

private_constant(symbol,...)→mod

private_instance_methods(include_super=true)→array

private_method_defined?(symbol)→trueorfalseprivate_method_defined?(string)→trueorfalse

defmethod3()end

C.private_method_defined?"method1"#=>false

C.private_method_defined?"method2"#=>true

C.method_defined?"method2"#=>false

Returnsalistoftheprotectedinstancemethodsdefinedinmod.Iftheoptionalparameterisfalse,themethodsofanyancestorsarenotincluded.

Returnstrueifthenamedprotectedmethodisdefinedbymod(oritsincludedmodulesand,ifmodisaclass,itsancestors).Stringargumentsareconvertedtosymbols.

moduleA

defmethod1()end

classB

protected

defmethod2()end

classC<B

includeA

defmethod3()end

C.protected_method_defined?"method1"#=>false

C.protected_method_defined?"method2"#=>true

protected_instance_methods(include_super=true)→array

protected_method_defined?(symbol)→trueorfalseprotected_method_defined?(string)→trueorfalse

Makesalistofexistingclassmethodspublic.

Stringargumentsareconvertedtosymbols.

Makesalistofexistingconstantspublic.

Similarto#instance_method,searchespublicmethodonly.

Returnsalistofthepublicinstancemethodsdefinedinmod.Iftheoptionalparameterisfalse,themethodsofanyancestorsarenotincluded.

Returnstrueifthenamedpublicmethodisdefinedbymod(oritsincludedmodulesand,ifmodisaclass,itsancestors).Stringargumentsareconvertedtosymbols.

moduleA

defmethod1()end

public_class_method(symbol,...)→modpublic_class_method(string,...)→mod

public_constant(symbol,...)→mod

public_instance_method(symbol)→unbound_method

public_instance_methods(include_super=true)→array

public_method_defined?(symbol)→trueorfalsepublic_method_defined?(string)→trueorfalse

classB

protected

defmethod2()end

classC<B

includeA

defmethod3()end

C.public_method_defined?"method1"#=>true

C.public_method_defined?"method2"#=>false

Removesthedefinitionofthesym,returningthatconstant'svalue.

classDummy

@@var=99

puts@@var

remove_class_variable(:@@var)

p(defined?@@var)

produces:

Returnstrueifmodisasingletonclassorfalseifitisanordinaryclassormodule.

classC

C.singleton_class?#=>false

C.singleton_class.singleton_class?#=>true

remove_class_variable(sym)→obj

singleton_class?→trueorfalse

to_s→string

Returnsastringrepresentingthismoduleorclass.Forbasicclassesandmodules,thisisthename.Forsingletons,weshowinformationonthethingwe'reattachedtoaswell.

classMutexMuteximplementsasimplesemaphorethatcanbeusedtocoordinateaccesstoshareddatafrommultipleconcurrentthreads.

Example:

require'thread'

semaphore=Mutex.new

a=Thread.new{

semaphore.synchronize{

#accesssharedresource

b=Thread.new{

semaphore.synchronize{

#accesssharedresource

InFilesthread.c

ParentObject

PublicClassMethods

CreatesanewMutex

Attemptstograbthelockandwaitsifitisn'tavailable.RaisesThreadErrorifmutexwaslockedbythecurrentthread.

Returnstrueifthislockiscurrentlyheldbysomethread.

Returnstrueifthislockiscurrentlyheldbycurrentthread.ThisAPIisexperimental,andsubjecttochange.

Releasesthelockandsleepstimeoutsecondsifitisgivenandnon-nilorforever.RaisesThreadErrorifmutexwasn'tlockedbythecurrentthread.

Whenthethreadisnextwokenup,itwillattempttoreacquirethelock.

NotethatthismethodcanwakeupwithoutexplicitThread#wakeupcall.Forexample,receivingsignalandsoon.

new→mutex

lock→self

locked?→trueorfalse

owned?→trueorfalse

sleep(timeout=nil)→number

Obtainsalock,runstheblock,andreleasesthelockwhentheblockcompletes.SeetheexampleunderMutex.

Attemptstoobtainthelockandreturnsimmediately.Returnstrueifthelockwasgranted.

Releasesthelock.RaisesThreadErrorifmutexwasn'tlockedbythecurrentthread.

synchronize{...}→resultoftheblock

try_lock→trueorfalse

unlock→self

classNameErrorRaisedwhenagivennameisinvalidorundefined.

putsfoo

raisestheexception:

NameError:undefinedlocalvariableormethod`foo'formain:Object

Sinceconstantnamesmuststartwithacapital:

Fixnum.const_set:answer,42

raisestheexception:

NameError:wrongconstantnameanswer

InFileserror.c

ParentStandardError

PublicClassMethods

ConstructanewNameErrorexception.IfgiventhenameparametermaysubsequentlybeexaminedusingtheNameError.namemethod.

ReturnthenameassociatedwiththisNameErrorexception.

new(msg[,name])→name_error

name→stringornil

classNilClassTheclassofthesingletonobjectnil.

InFilescomplex.cobject.crational.c

ParentObject

And—Returnsfalse.objisalwaysevaluatedasitistheargumenttoamethodcall—thereisnoshort-circuitevaluationinthiscase.

ExclusiveOr—Ifobjisnilorfalse,returnsfalse;otherwise,returnstrue.

false&obj→falsenil&obj→false

false^obj→trueorfalsenil^obj→trueorfalse

inspect→"nil"

Alwaysreturnsthestring“nil”.

Onlytheobjectnilrespondstruetonil?.

Returnszeroasarational.Theoptionalargumentepsisalwaysignored.

Alwaysreturnsanemptyarray.

nil.to_a#=>[]

Returnszeroasacomplex.

Alwaysreturnszero.

nil.to_f#=>0.0

Alwaysreturnsanemptyhash.

nil.to_h#=>{}

Alwaysreturnszero.

nil.to_i#=>0

nil?→true

rationalize([eps])→(0/1)

to_a→[]

to_c→(0+0i)

to_f→0.0

to_h→{}

to_i→0

Returnszeroasarational.

Alwaysreturnstheemptystring.

Or—Returnsfalseifobjisnilorfalse;trueotherwise.

to_r→(0/1)

to_s→""

false|obj→trueorfalsenil|obj→trueorfalse

classNoMemoryErrorRaisedwhenmemoryallocationfails.

InFileserror.c

ParentException

classNoMethodErrorRaisedwhenamethodiscalledonareceiverwhichdoesn'thaveitdefinedandalsofailstorespondwithmethod_missing.

"hello".to_ary

raisestheexception:

NoMethodError:undefinedmethod`to_ary'for"hello":String

InFileserror.c

ParentNameError

PublicClassMethods

ConstructaNoMethodErrorexceptionforamethodofthegivennamecalledwiththegivenarguments.Thenamemaybeaccessedusingthe#namemethodontheresultingobject,andtheargumentsusingthe#argsmethod.

new(msg,name[,args])→no_method_error

Returntheargumentspassedinasthethirdparametertotheconstructor.

args→obj

classNotImplementedErrorRaisedwhenafeatureisnotimplementedonthecurrentplatform.Forexample,methodsdependingonthefsyncorforksystemcallsmayraisethisexceptioniftheunderlyingoperatingsystemorRubyruntimedoesnotsupportthem.

NotethatifforkraisesaNotImplementedError,thenrespond_to?(:fork)returnsfalse.

InFileserror.c

ParentScriptError

classNumericThetop-levelnumberclass.

InFilescomplex.cnumeric.crational.c

ParentObject

x.modulo(y)meansx-y*(x/y).floor

Equivalenttonum.divmod(numeric)[1].

See#divmod.

UnaryPlus—Returnsthereceiver'svalue.

modulo(numeric)→real

+num→num

UnaryMinus—Returnsthereceiver'svalue,negated.

Returnszeroifnumberequalsother,otherwisenilisreturnedifthetwovaluesareincomparable.

Returnstheabsolutevalueofnum.

12.abs#=>12

(-34.56).abs#=>34.56

-34.56.abs#=>34.56

#magnitudeisanaliasof#abs.

Returnssquareofself.

-num→numeric

number<=>other→0ornil

abs→numericmagnitude→numeric

abs2→real

ceil→integer

ReturnsthesmallestpossibleIntegerthatisgreaterthanorequaltonum.

NumericachievesthisbyconvertingitselftoaFloattheninvokingFloat#ceil.

1.ceil#=>1

1.2.ceil#=>2

(-1.2).ceil#=>-1

(-1.0).ceil#=>-1

Ifa+numericisthesametypeasnum,returnsanarraycontainingnumericandnum.Otherwise,returnsanarraywithbothanumericandnumrepresentedasFloatobjects.

ThiscoercionmechanismisusedbyRubytohandlemixed-typenumericoperations:itisintendedtofindacompatiblecommontypebetweenthetwooperandsoftheoperator.

1.coerce(2.5)#=>[2.5,1.0]

1.2.coerce(3)#=>[3.0,1.2]

1.coerce(2)#=>[2,1]

Returnsself.

conj→selfconjugate→self

Returnsthedenominator(alwayspositive).

Uses/toperformdivision,thenconvertstheresulttoaninteger.numericdoesnotdefinethe/operator;thisislefttosubclasses.

See#divmod.

Returnsanarraycontainingthequotientandmodulusobtainedbydividingnumbynumeric.

Ifq,r=*x.divmod(y),then

q=floor(x/y)

x=q*y+r

Thequotientisroundedtoward-infinity,asshowninthefollowingtable:

a|b|a.divmod(b)|a/b|a.modulo(b)|a.remainder(b)

------+-----+---------------+---------+-------------+---------------

13|4|3,1|3|1|1

------+-----+---------------+---------+-------------+---------------

13|-4|-4,-3|-4|-3|1

------+-----+---------------+---------+-------------+---------------

-13|4|-4,3|-4|3|-1

------+-----+---------------+---------+-------------+---------------

-13|-4|3,-1|3|-1|-1

------+-----+---------------+---------+-------------+---------------

11.5|4|2,3.5|2.875|3.5|3.5

------+-----+---------------+---------+-------------+---------------

11.5|-4|-3,-0.5|-2.875|-0.5|3.5

------+-----+---------------+---------+-------------+---------------

-11.5|4|-3,0.5|-2.875|0.5|-3.5

------+-----+---------------+---------+-------------+---------------

-11.5|-4|2,-3.5|2.875|-3.5|-3.5

div(numeric)→integer

Examples

11.divmod(3)#=>[3,2]

11.divmod(-3)#=>[-4,-1]

11.divmod(3.5)#=>[3,0.5]

(-11).divmod(3.5)#=>[-4,3.0]

(11.5).divmod(3.5)#=>[3,1.0]

Returnstrueifnumandnumericarethesametypeandhaveequalvalues.

1==1.0#=>true

1.eql?(1.0)#=>false

(1.0).eql?(1.0)#=>true

Returnsfloatdivision.

Returnsthelargestintegerlessthanorequaltonum.

NumericimplementsthisbyconvertinganIntegertoaFloatandinvokingFloat#floor.

1.floor#=>1

(-1).floor#=>-1

Returnsthecorrespondingimaginarynumber.Notavailableforcomplexnumbers.

Returnszero.

eql?(numeric)→trueorfalse

floor→integer

i→Complex(0,num)

imag→0imaginary→0

Returnszero.

Numericsareimmutablevalues,whichshouldnotbecopied.

AnyattempttousethismethodonaNumericwillraiseaTypeError.

ReturnstrueifnumisanInteger(includingFixnumandBignum).

(1.0).integer?#=>false

(1).integer?#=>true

Returnstheabsolutevalueofnum.

12.abs#=>12

(-34.56).abs#=>34.56

-34.56.abs#=>34.56

#magnitudeisanaliasof#abs.

x.modulo(y)meansx-y*(x/y).floor

imag→0imaginary→0

initialize_copy(p1)

integer?→trueorfalse

abs→numericmagnitude→numeric

modulo(numeric)→real

See#divmod.

Returnsselfifnumisnotzero,nilotherwise.

Thisbehaviorisusefulwhenchainingcomparisons:

a=%w(zBbbBbbBBaaAAaAAA)

b=a.sort{|a,b|(a.downcase<=>b.downcase).nonzero?

b#=>["A","a","AA","Aa","aA","BB","Bb","bB","bb","z"]

Returnsanarray;[num.abs,num.arg].

Returnsmostexactdivision(rationalforintegers,floatforfloats).

Returnsself.

nonzero?→selfornil

numerator→integer

polar→array

quo(int_or_rat)→ratquo(flo)→flo

real→self

real?→trueorfalse

ReturnstrueifnumisaRealnumber.(i.e.notComplex).

Returnsanarray;[num,0].

x.remainder(y)meansx-y*(x/y).truncate

See#divmod.

Roundsnumtoagivenprecisionindecimaldigits(default0digits).

Precisionmaybenegative.Returnsafloatingpointnumberwhenndigitsismorethanzero.

NumericimplementsthisbyconvertingitselftoaFloatandinvokingFloat#round.

TrapattemptstoaddmethodstoNumericobjects.AlwaysraisesaTypeError.

Numericsshouldbevalues;singleton_methodsshouldnotbeaddedtothem.

rect→arrayrectangular→array

remainder(numeric)→real

singleton_method_added(p1)

Invokesthegivenblockwiththesequenceofnumbersstartingatnum,incrementedbystep(defaultedto1)oneachcall.

Theloopfinisheswhenthevaluetobepassedtotheblockisgreaterthanlimit(ifstepispositive)orlessthanlimit(ifstepisnegative),wherelimitisdefaultedtoinfinity.

Intherecommendedkeywordargumentstyle,eitherorbothofstepandlimit(defaultinfinity)canbeomitted.Inthefixedpositionargumentstyle,zeroasastep(i.e.num.step(limit,0))isnotallowedforhistoricalcompatibilityreasons.

Ifalltheargumentsareintegers,theloopoperatesusinganintegercounter.

Ifanyoftheargumentsarefloatingpointnumbers,allareconvertedtofloats,andtheloopisexecutedthefollowingexpression:

floor(n+n*epsilon)+1

Wherethenisthefollowing:

n=(limit-num)/step

Otherwise,theloopstartsatnum,useseithertheless-than(<)orgreater-than(>)operatortocomparethecounteragainstlimit,andincrementsitselfusingthe+operator.

step(by:step,to:limit){|i|block}→selfstep(by:step,to:limit)→an_enumeratorstep(limit=nil,step=1){|i|block}→selfstep(limit=nil,step=1)→an_enumerator

Forexample:

p1.step.take(4)

p10.step(by:-1).take(4)

3.step(to:5){|i|printi,""}

1.step(10,2){|i|printi,""}

Math::E.step(to:Math::PI,by:0.2){|f|printf,""

Willproduce:

[1,2,3,4]

[10,9,8,7]

2.718281828459052.918281828459053.11828182845905

Returnsthevalueasacomplex.

Invokesthechildclass'sto_imethodtoconvertnumtoaninteger.

1.0.class=>Float

1.0.to_int.class=>Fixnum

1.0.to_i.class=>Fixnum

ReturnsnumtruncatedtoanInteger.

NumericimplementsthisbyconvertingitsvaluetoaFloatandinvokingFloat#truncate.

Returnstrueifnumhasazerovalue.

to_c→complex

to_int→integer

truncate→integer

zero?→trueorfalse

classObjectObjectisthedefaultrootofallRubyobjects.ObjectinheritsfromBasicObjectwhichallowscreatingalternateobjecthierarchies.MethodsonObjectareavailabletoallclassesunlessexplicitlyoverridden.

ObjectmixesintheKernelmodule,makingthebuilt-inkernelfunctionsgloballyaccessible.AlthoughtheinstancemethodsofObjectaredefinedbytheKernelmodule,wehavechosentodocumentthemhereforclarity.

WhenreferencingconstantsinclassesinheritingfromObjectyoudonotneedtousethefullnamespace.Forexample,referencingFileinsideYourClasswillfindthetop-levelFileclass.

InthedescriptionsofObject'smethods,theparametersymbolreferstoasymbol,whichiseitheraquotedstringoraSymbol(suchas:name).

InFilesclass.cenumerator.ceval.cgc.chash.c

io.cobject.cparse.cproc.cruby.cversion.cvm.cvm_eval.cvm_method.c

ParentBasicObject

IncludedModulesKernel

Constants

ARGFisastreamdesignedforuseinscriptsthatprocessfilesgivenascommand-lineargumentsorpassedinviaSTDIN.

SeeARGF(theclass)formoredetails.

ARGVcontainsthecommandlineargumentsusedtorunrubywiththefirstvaluecontainingthenameoftheexecutable.

AlibrarylikeOptionParsercanbeusedtoprocesscommand-linearguments.

DATAisaFilethatcontainsthedatasectionoftheexecutedfile.Tocreateadatasectionuse__END__:

$catt.rb

putsDATA.gets

__END__

helloworld!

$rubyt.rb

helloworld!

ENVisaHash-likeaccessorforenvironmentvariables.

SeeENV(theclass)formoredetails.

Analiasoffalse

Analiasofnil

RUBY_COPYRIGHT

Thecopyrightstringforruby

RUBY_DESCRIPTION

Thefullrubyversionstring,likeruby-vprints'

RUBY_ENGINE

Theengineorinterpreterthisrubyuses.

RUBY_PATCHLEVEL

Thepatchlevelforthisruby.Ifthisisadevelopmentbuildofrubythepatchlevelwillbe-1

RUBY_PLATFORM

Theplatformforthisruby

RUBY_RELEASE_DATE

Thedatethisrubywasreleased

RUBY_REVISION

TheSVNrevisionforthisruby.

RUBY_VERSION

Therunningversionofruby

SCRIPT_LINES__

WhenaHashisassignedtoSCRIPT_LINES__thecontentsoffilesloadedaftertheassignmentwillbeaddedasanArrayoflineswiththefilenameasthekey.

STDERR

Holdstheoriginalstderr

Holdstheoriginalstdin

STDOUT

Holdstheoriginalstdout

TOPLEVEL_BINDING

TheBindingofthetoplevelscope

Analiasoftrue

Returnstrueiftwoobjectsdonotmatch(usingthe=~method),otherwisefalse.

Returns0ifobjandotherarethesameobjectorobj==other,otherwisenil.

The<=>isusedbyvariousmethodstocompareobjects,forexampleEnumerable#sort,Enumerable#maxetc.

Yourimplementationof<=>shouldreturnoneofthefollowingvalues:-1,0,1ornil.-1meansselfissmallerthanother.0meansselfisequaltoother.1meansselfisbiggerthanother.Nilmeansthetwovaluescouldnotbecompared.

Whenyoudefine<=>,youcanincludeComparabletogainthemethods<=,<,==,>=,>andbetween?.

CaseEquality–ForclassObject,effectivelythesameascalling#==,buttypicallyoverriddenbydescendantstoprovidemeaningfulsemanticsincasestatements.

obj!~other→trueorfalse

obj<=>other→0ornil

obj===other→trueorfalse

obj=~other→nil

PatternMatch—Overriddenbydescendants(notablyRegexpandString)toprovidemeaningfulpattern-matchsemantics.

Returnstheclassofobj.Thismethodmustalwaysbecalledwithanexplicitreceiver,asclassisalsoareservedwordinRuby.

1.class#=>Fixnum

self.class#=>Object

Producesashallowcopyofobj—theinstancevariablesofobjarecopied,butnottheobjectstheyreference.clonecopiesthefrozenandtaintedstateofobj.SeealsothediscussionunderObject#dup.

classKlass

attr_accessor:str

s1=Klass.new#=>#<Klass:0x401b3a38>

s1.str="Hello"#=>"Hello"

s2=s1.clone#=>#<Klass:0x401b3998@str="Hello">

s2.str[1,4]="i"#=>"i"

s1.inspect#=>"#<Klass:0x401b3a38@str=\"Hi\">"

s2.inspect#=>"#<Klass:0x401b3998@str=\"Hi\">"

Thismethodmayhaveclass-specificbehavior.Ifso,thatbehaviorwillbedocumentedunderthe#initialize_copymethodoftheclass.

class→class

clone→an_object

define_singleton_method(symbol,method)→new_methoddefine_singleton_method(symbol){block}

Definesasingletonmethodinthereceiver.ThemethodparametercanbeaProc,aMethodoranUnboundMethodobject.Ifablockisspecified,itisusedasthemethodbody.

classA

class<<self

defclass_name

A.define_singleton_method(:who_am_i)do

"Iam:#{class_name}"

A.who_am_i#==>"Iam:A"

guy="Bob"

guy.define_singleton_method(:hello){"#{self}:Hellothere!"

guy.hello#=>"Bob:Hellothere!"

Printsobjonthegivenport(default$>).Equivalentto:

defdisplay(port=$>)

port.writeself

Forexample:

1.display

"cat".display

[4,5,6].display

produces:

1cat456

→proc

display(port=$>)→nil

Producesashallowcopyofobj—theinstancevariablesofobjarecopied,butnottheobjectstheyreference.dupcopiesthetaintedstateofobj.

Thismethodmayhaveclass-specificbehavior.Ifso,thatbehaviorwillbedocumentedunderthe#initialize_copymethodoftheclass.

ondupvscloneIngeneral,cloneanddupmayhavedifferentsemanticsindescendantclasses.Whilecloneisusedtoduplicateanobject,includingitsinternalstate,duptypicallyusestheclassofthedescendantobjecttocreatethenewinstance.

Whenusingdup,anymodulesthattheobjecthasbeenextendedwithwillnotbecopied.

classKlass

attr_accessor:str

moduleFoo

deffoo;'foo';end

s1=Klass.new#=>#<Klass:0x401b3a38>

s1.extend(Foo)#=>#<Klass:0x401b3a38>

s1.foo#=>"foo"

s2=s1.clone#=>#<Klass:0x401b3a38>

s2.foo#=>"foo"

s3=s1.dup#=>#<Klass:0x401b3a38>

s3.foo#=>NoMethodError:undefinedmethod`foo'for#<Klass:0x401b3a38>

dup→an_object

to_enum(method=:each,*args)→enum

CreatesanewEnumeratorwhichwillenumeratebycallingmethodonobj,passingargsifany.

Ifablockisgiven,itwillbeusedtocalculatethesizeoftheenumeratorwithouttheneedtoiterateit(seeEnumerator#size).

Examplesstr="xyz"

enum=str.enum_for(:each_byte)

enum.each{|b|putsb}

#=>120

#=>121

#=>122

#protectanarrayfrombeingmodifiedbysome_method

a=[1,2,3]

some_method(a.to_enum)

Itistypicaltocall#to_enumwhendefiningmethodsforagenericEnumerable,incasenoblockispassed.

Hereissuchanexample,withparameterpassingandasizingblock:

moduleEnumerable

#agenericmethodtorepeatthevaluesofanyenumerable

defrepeat(n)

raiseArgumentError,"#{n}isnegative!"ifn<0

unlessblock_given?

returnto_enum(__method__,n)do#__method__is:repeathere

sz=size#Callsizeandmultiplybyn...

sz*nifsz#butreturnnilifsizeitselfisnil

enum_for(method=:each,*args)→enumto_enum(method=:each,*args){|*args|block}→enumenum_for(method=:each,*args){|*args|block}→enum

eachdo|*val|

n.times{yield*val}

%[helloworld].repeat(2){|w|putsw}

#=>Prints'hello','hello','world','world'

enum=(1..14).repeat(3)

#=>returnsanEnumeratorwhencalledwithoutablock

enum.first(4)#=>[1,1,1,2]

enum.size#=>42

obj="a"

other=obj.dup

obj==other#=>true

Theeql?methodreturnstrueifobjandotherrefertothesamehashkey.ThisisusedbyHashtotestmembersforequality.ForobjectsofclassObject,eql?issynonymouswith==.Subclassesnormallycontinuethistraditionbyaliasingeql?totheir

overridden==method,butthereareexceptions.Numerictypes,forexample,performtypeconversionacross==,butnotacrosseql?,so:

1==1.0#=>true

1.eql?1.0#=>false

Addstoobjtheinstancemethodsfromeachmodulegivenasaparameter.

moduleMod

defhello

"HellofromMod.\n"

classKlass

defhello

"HellofromKlass.\n"

k=Klass.new

k.hello#=>"HellofromKlass.\n"

k.extend(Mod)#=>#<Klass:0x401b3bc8>

k.hello#=>"HellofromMod.\n"

Preventsfurthermodificationstoobj.ARuntimeErrorwillberaisedifmodificationisattempted.Thereisnowaytounfreezeafrozenobject.SeealsoObject#frozen?.

Thismethodreturnsself.

a=["a","b","c"]

a.freeze

a<<"z"

extend(module,...)→obj

freeze→obj

produces:

prog.rb:3:in`<<':can'tmodifyfrozenArray(RuntimeError)

fromprog.rb:3

Objectsofthefollowingclassesarealwaysfrozen:Fixnum,Bignum,Float,Symbol.

Returnsthefreezestatusofobj.

a=["a","b","c"]

a.freeze#=>["a","b","c"]

a.frozen?#=>true

GeneratesaFixnumhashvalueforthisobject.Thisfunctionmusthavethepropertythata.eql?(b)impliesa.hash==b.hash.

Thehashvalueisusedalongwitheql?bytheHashclasstodetermineiftwoobjectsreferencethesamehashkey.AnyhashvaluethatexceedsthecapacityofaFixnumwillbetruncatedbeforebeingused.

ThehashvalueforanobjectmaynotbeidenticalacrossinvocationsorimplementationsofRuby.IfyouneedastableidentifieracrossRubyinvocationsandimplementationsyouwillneedtogenerateonewithacustommethod.

Returnsastringcontainingahuman-readablerepresentationofobj.Thedefaultinspectshowstheobject'sclassname,anencodingoftheobjectid,andalistoftheinstancevariablesandtheirvalues(by

frozen?→trueorfalse

hash→fixnum

inspect→string

callinginspectoneachofthem).Userdefinedclassesshouldoverridethismethodtoprovideabetterrepresentationofobj.Whenoverridingthismethod,itshouldreturnastringwhoseencodingiscompatiblewiththedefaultexternalencoding.

[1,2,3..4,'five'].inspect#=>"[1,2,3..4,\"five\"]"

Time.new.inspect#=>"2008-03-0819:43:39+0900"

classFoo

Foo.new.inspect#=>"#<Foo:0x0300c868>"

classBar

definitialize

@bar=1

Bar.new.inspect#=>"#<Bar:0x0300c868@bar=1>"

Returnstrueifobjisaninstanceofthegivenclass.SeealsoObject#kind_of?.

classA;end

classB<A;end

classC<B;end

b=B.new

b.instance_of?A#=>false

b.instance_of?B#=>true

b.instance_of?C#=>false

Returnstrueifthegiveninstancevariableisdefined

instance_of?(class)→trueorfalse

instance_variable_defined?(symbol)→trueorfalseinstance_variable_defined?(string)→trueorfalse

inobj.Stringargumentsareconvertedtosymbols.

classFred

definitialize(p1,p2)

@a,@b=p1,p2

fred=Fred.new('cat',99)

fred.instance_variable_defined?(:@a)#=>true

fred.instance_variable_defined?("@b")#=>true

fred.instance_variable_defined?("@c")#=>false

Returnsthevalueofthegiveninstancevariable,orniliftheinstancevariableisnotset.The@partofthevariablenameshouldbeincludedforregularinstancevariables.ThrowsaNameErrorexceptionifthesuppliedsymbolisnotvalidasaninstancevariablename.Stringargumentsareconvertedtosymbols.

classFred

@a,@b=p1,p2

fred.instance_variable_get(:@a)#=>"cat"

fred.instance_variable_get("@b")#=>99

Setstheinstancevariablenamedbysymboltothegivenobject,therebyfrustratingtheeffortsoftheclass'sauthortoattempttoprovideproperencapsulation.Thevariabledoesnothavetoexistpriortothiscall.Iftheinstancevariablenameis

instance_variable_get(symbol)→objinstance_variable_get(string)→obj

instance_variable_set(symbol,obj)→objinstance_variable_set(string,obj)→obj

passedasastring,thatstringisconvertedtoasymbol.

classFred

@a,@b=p1,p2

fred.instance_variable_set(:@a,'dog')#=>"dog"

fred.instance_variable_set(:@c,'cat')#=>"cat"

fred.inspect#=>"#<Fred:0x401b3da8@a=\"dog\",@b=99,@c=\"cat\">"

Returnsanarrayofinstancevariablenamesforthereceiver.Notethatsimplydefininganaccessordoesnotcreatethecorrespondinginstancevariable.

classFred

attr_accessor:a1

definitialize

Fred.new.instance_variables#=>[:@iv]

Returnstrueifclassistheclassofobj,orifclassisoneofthesuperclassesofobjormodulesincludedinobj.

moduleM;end

classA

includeM

classB<A;end

classC<B;end

instance_variables→array

is_a?(class)→trueorfalsekind_of?(class)→trueorfalse

b=B.new

b.is_a?A#=>true

b.is_a?B#=>true

b.is_a?C#=>false

b.is_a?M#=>true

b.kind_of?A#=>true

b.kind_of?B#=>true

b.kind_of?C#=>false

b.kind_of?M#=>true

Returnsobj.

string='mystring'#=>"mystring"

string.itself.object_id==string.object_id#=>true

Returnstrueifclassistheclassofobj,orifclassisoneofthesuperclassesofobjormodulesincludedinobj.

moduleM;end

classA

includeM

classB<A;end

classC<B;end

b=B.new

b.is_a?A#=>true

b.is_a?B#=>true

b.is_a?C#=>false

b.is_a?M#=>true

b.kind_of?A#=>true

b.kind_of?B#=>true

b.kind_of?C#=>false

b.kind_of?M#=>true

itself→an_object

is_a?(class)→trueorfalsekind_of?(class)→trueorfalse

Looksupthenamedmethodasareceiverinobj,returningaMethodobject(orraisingNameError).TheMethodobjectactsasaclosureinobj'sobjectinstance,soinstancevariablesandthevalueofselfremainavailable.

classDemo

definitialize(n)

defhello()

"Hello,@iv=#{@iv}"

k=Demo.new(99)

m=k.method(:hello)

m.call#=>"Hello,@iv=99"

l=Demo.new('Fred')

m=l.method("hello")

m.call#=>"Hello,@iv=Fred"

Returnsalistofthenamesofpublicandprotectedmethodsofobj.Thiswillincludeallthemethodsaccessibleinobj'sancestors.Iftheoptionalparameterisfalse,itreturnsanarrayofobj<i>'spublicandprotectedsingletonmethods,thearraywillnotincludemethodsinmodulesincludedin<i>obj.

classKlass

defklass_method()

k=Klass.new

k.methods[0..9]#=>[:klass_method,:nil?,:===,

#:==~,:!,:eql?

method(sym)→method

methods(regular=true)→array

#:hash,:<=>,:class,:singleton_class]

k.methods.length#=>56

k.methods(false)#=>[]

defk.singleton_method;end

k.methods(false)#=>[:singleton_method]

moduleM123;defm123;endend

k.extendM123

k.methods(false)#=>[:singleton_method]

Onlytheobjectnilrespondstruetonil?.

Object.new.nil?#=>false

nil.nil?#=>true

Returnsanintegeridentifierforobj.

Thesamenumberwillbereturnedonallcallstoobject_idforagivenobject,andnotwoactiveobjectswillshareanid.

Note:thatsomeobjectsofbuiltinclassesarereusedforoptimization.Thisisthecaseforimmediatevaluesandfrozenstringliterals.

Immediatevaluesarenotpassedbyreferencebutarepassedbyvalue:nil,true,false,Fixnums,Symbols,andsomeFloats.

Object.new.object_id==Object.new.object_id#=>false

(21*2).object_id==(21*2).object_id#=>true

"hello".object_id=="hello".object_id#=>false

"hi".freeze.object_id=="hi".freeze.object_id#=>true

nil?→trueorfalse

__id__→integerobject_id→integer

Returnsthelistofprivatemethodsaccessibletoobj.Iftheallparameterissettofalse,onlythosemethodsinthereceiverwillbelisted.

Returnsthelistofprotectedmethodsaccessibletoobj.Iftheallparameterissettofalse,onlythosemethodsinthereceiverwillbelisted.

Similartomethod,searchespublicmethodonly.

Returnsthelistofpublicmethodsaccessibletoobj.Iftheallparameterissettofalse,onlythosemethodsinthereceiverwillbelisted.

Invokesthemethodidentifiedbysymbol,passingitanyargumentsspecified.Unlikesend,#public_sendcallspublicmethodsonly.Whenthemethodisidentifiedbyastring,thestringisconvertedtoasymbol.

1.public_send(:puts,"hello")#causesNoMethodError

Removesthenamedinstancevariablefromobj,returningthatvariable'svalue.

private_methods(all=true)→array

protected_methods(all=true)→array

public_method(sym)→method

public_methods(all=true)→array

public_send(symbol[,args...])→objpublic_send(string[,args...])→obj

remove_instance_variable(symbol)→obj

classDummy

attr_reader:var

definitialize

@var=99

defremove

remove_instance_variable(:@var)

d=Dummy.new

d.var#=>99

d.remove#=>99

d.var#=>nil

Returnstrueifobjrespondstothegivenmethod.Privateandprotectedmethodsareincludedinthesearchonlyiftheoptionalsecondparameterevaluatestotrue.

Ifthemethodisnotimplemented,asProcess.forkonWindows,File.lchmodonGNU/Linux,etc.,falseisreturned.

Ifthemethodisnotdefined,respond_to_missing?methodiscalledandtheresultisreturned.

Whenthemethodnameparameterisgivenasastring,thestringisconvertedtoasymbol.

DONOTUSETHISDIRECTLY.

respond_to?(symbol,include_all=false)→trueorfalserespond_to?(string,include_all=false)→trueorfalse

respond_to_missing?(symbol,include_all)→trueorfalserespond_to_missing?(string,include_all)→trueorfalse

Hookmethodtoreturnwhethertheobjcanrespondtoidmethodornot.

Whenthemethodnameparameterisgivenasastring,thestringisconvertedtoasymbol.

Seerespond_to?,andtheexampleofBasicObject.

Invokesthemethodidentifiedbysymbol,passingitanyargumentsspecified.Youcanuse__send__ifthenamesendclasheswithanexistingmethodinobj.Whenthemethodisidentifiedbyastring,thestringisconvertedtoasymbol.

classKlass

defhello(*args)

"Hello"+args.join('')

k=Klass.new

k.send:hello,"gentle","readers"#=>"Hellogentlereaders"

Returnsthesingletonclassofobj.Thismethodcreatesanewsingletonclassifobjdoesnothaveone.

Ifobjisnil,true,orfalse,itreturnsNilClass,TrueClass,orFalseClass,respectively.IfobjisaFixnumoraSymbol,itraisesaTypeError.

Object.new.singleton_class#=>#<Class:#<Object:0xb7ce1e24>>

String.singleton_class#=>#<Class:String>

nil.singleton_class#=>NilClass

send(symbol[,args...])→obj__send__(symbol[,args...])→objsend(string[,args...])→obj__send__(string[,args...])→obj

singleton_class→class

Similartomethod,searchessingletonmethodonly.

classDemo

definitialize(n)

defhello()

"Hello,@iv=#{@iv}"

k=Demo.new(99)

defk.hi

"Hi,@iv=#{@iv}"

m=k.singleton_method(:hi)

m.call#=>"Hi,@iv=99"

m=k.singleton_method(:hello)#=>NameError

Returnsanarrayofthenamesofsingletonmethodsforobj.Iftheoptionalallparameteristrue,thelistwillincludemethodsinmodulesincludedinobj.Onlypublicandprotectedsingletonmethodsarereturned.

moduleOther

defthree()end

classSingle

defSingle.four()end

a=Single.new

defa.one()

class<<a

singleton_method(sym)→method

singleton_methods(all=true)→array

includeOther

deftwo()

Single.singleton_methods#=>[:four]

a.singleton_methods(false)#=>[:two,:one]

a.singleton_methods#=>[:two,:one,:three]

Marktheobjectastainted.

Objectsthataremarkedastaintedwillberestrictedfromvariousbuilt-inmethods.Thisistopreventinsecuredata,suchascommand-lineargumentsorstringsreadfromKernel#gets,frominadvertentlycompromisingtheuser'ssystem.

Tocheckwhetheranobjectistainted,usetainted?.

Youshouldonlyuntaintataintedobjectifyourcodehasinspecteditanddeterminedthatitissafe.Todosouseuntaint.

In$SAFElevel3,allnewlycreatedobjectsaretaintedandyoucan'tuntaintobjects.

Returnstrueiftheobjectistainted.

Seetaintformoreinformation.

Yieldsselftotheblock,andthenreturnsself.Theprimarypurposeofthismethodisto“tapinto”amethodchain,inordertoperformoperationsonintermediateresultswithinthechain.

taint→obj

tainted?→trueorfalse

tap{|x|...}→obj

(1..10).tap{|x|puts"original:#{x.inspect}"

.to_a.tap{|x|puts"array:#{x.inspect}"

.select{|x|x%2==0}.tap{|x|puts"evens:#{x.inspect}"

.map{|x|x*x}.tap{|x|puts"squares:#{x.inspect}"

CreatesanewEnumeratorwhichwillenumeratebycallingmethodonobj,passingargsifany.

Ifablockisgiven,itwillbeusedtocalculatethesizeoftheenumeratorwithouttheneedtoiterateit(seeEnumerator#size).

Examplesstr="xyz"

enum=str.enum_for(:each_byte)

enum.each{|b|putsb}

#=>120

#=>121

#=>122

#protectanarrayfrombeingmodifiedbysome_method

a=[1,2,3]

some_method(a.to_enum)

Itistypicaltocall#to_enumwhendefiningmethodsforagenericEnumerable,incasenoblockispassed.

Hereissuchanexample,withparameterpassingandasizingblock:

to_enum(method=:each,*args)→enumenum_for(method=:each,*args)→enumto_enum(method=:each,*args){|*args|block}→enumenum_for(method=:each,*args){|*args|block}→enum

moduleEnumerable

#agenericmethodtorepeatthevaluesofanyenumerable

defrepeat(n)

raiseArgumentError,"#{n}isnegative!"ifn<0

unlessblock_given?

returnto_enum(__method__,n)do#__method__is:repeathere

sz=size#Callsizeandmultiplybyn...

sz*nifsz#butreturnnilifsizeitselfisnil

eachdo|*val|

n.times{yield*val}

%[helloworld].repeat(2){|w|putsw}

#=>Prints'hello','hello','world','world'

enum=(1..14).repeat(3)

#=>returnsanEnumeratorwhencalledwithoutablock

enum.first(4)#=>[1,1,1,2]

enum.size#=>42

Returnsastringrepresentingobj.Thedefaultto_sprintstheobject'sclassandanencodingoftheobjectid.Asaspecialcase,thetop-levelobjectthatistheinitialexecutioncontextofRubyprogramsreturns“main''.

Deprecatedmethodthatisequivalenttountaint.

Removesthetaintedmarkfromtheobject.

Seetaintformoreinformation.

to_s→string

trust→obj

untaint→obj

Deprecatedmethodthatisequivalenttotaint.

Deprecatedmethodthatisequivalenttotainted?.

untrust→obj

untrusted?→trueorfalse

moduleObjectSpaceTheObjectSpacemodulecontainsanumberofroutinesthatinteractwiththegarbagecollectionfacilityandallowyoutotraversealllivingobjectswithaniterator.

ObjectSpacealsoprovidessupportforobjectfinalizers,procsthatwillbecalledwhenaspecificobjectisabouttobedestroyedbygarbagecollection.

ObjectSpace.define_finalizer(a,proc{|id|puts"Finalizeroneon#{id}"

ObjectSpace.define_finalizer(b,proc{|id|puts"Finalizertwoon#{id}"

produces:

Finalizertwoon537763470

Finalizeroneon537763480

InFilesgc.c

PublicClassMethods

Convertsanobjectidtoareferencetotheobject.Maynotbecalledonanobjectidpassedasaparametertoafinalizer.

s="Iamastring"#=>"Iamastring"

r=ObjectSpace._id2ref(s.object_id)#=>"Iamastring"

r==s#=>true

Countsobjectsforeachtype.

Itreturnsahash,suchas:

:TOTAL=>10000,

:FREE=>3011,

:T_OBJECT=>6,

:T_CLASS=>404,

Thecontentsofthereturnedhashareimplementationspecific.Itmaybechangedinfuture.

Iftheoptionalargumentresult_hashisgiven,itisoverwrittenandreturned.Thisisintendedtoavoidprobeeffect.

AddsaProcasafinalizer,tobecalledafterobjwasdestroyed.

_id2ref(object_id)→an_object

count_objects([result_hash])→hash

define_finalizer(obj,aProc=proc())

each_object([module]){|obj|...}→fixnumeach_object([module])→an_enumerator

Callstheblockonceforeachliving,nonimmediateobjectinthisRubyprocess.Ifmoduleisspecified,callstheblockforonlythoseclassesormodulesthatmatch(orareasubclassof)module.Returnsthenumberofobjectsfound.Immediateobjects(Fixnums,Symbolstrue,false,andnil)areneverreturned.Intheexamplebelow,each_objectreturnsboththenumberswedefinedandseveralconstantsdefinedintheMathmodule.

a=102.7

b=95#Won'tbereturned

c=12345678987654321

count=ObjectSpace.each_object(Numeric){|x|px}

puts"Totalcount:#{count}"

produces:

12345678987654321

2.71828182845905

3.14159265358979

2.22044604925031e-16

1.7976931348623157e+308

2.2250738585072e-308

Totalcount:7

Removesallfinalizersforobj.

undefine_finalizer(obj)

classObjectSpace::WeakMapAnObjectSpace::WeakMapobjectholdsreferencestoanyobjects,butthoseobjectscangetgarbagecollected.

ThisclassismostlyusedinternallybyWeakRef,pleaseuselib/weakref.rbforthepublicinterface.

InFilesgc.c

ParentObject

Retrievesaweaklyreferencedobjectwiththegivenkey

[](p1)

Createsaweakreferencefromthegivenkeytothegivenvalue

Iteratesoverkeysandobjectsinaweaklyreferencedobject

Returnstrueifkeyisregistered

Iteratesoverkeysandobjectsinaweaklyreferenced

[]=(p1,p2)

each()

each_key()

each_pair()

each_value()

include?(p1)

inspect()

key?(p1)

keys()

object

Returnstrueifkeyisregistered

Iteratesovervaluesandobjectsinaweaklyreferencedobject

length()

member?(p1)

size()

values()

classProcProcobjectsareblocksofcodethathavebeenboundtoasetoflocalvariables.Oncebound,thecodemaybecalledindifferentcontextsandstillaccessthosevariables.

defgen_times(factor)

returnProc.new{|n|n*factor}

times3=gen_times(3)

times5=gen_times(5)

times3.call(12)#=>36

times5.call(5)#=>25

times3.call(times5.call(4))#=>60

InFilesproc.c

ParentObject

PublicClassMethods

CreatesanewProcobject,boundtothecurrent

new{|...|block}→a_procnew→a_proc

context.Proc::newmaybecalledwithoutablockonlywithinamethodwithanattachedblock,inwhichcasethatblockisconvertedtotheProcobject.

defproc_from

Proc.new

proc=proc_from{"hello"}

proc.call#=>"hello"

Invokestheblockwithobjastheproc'sparameterlike#call.Itistoallowaprocobjecttobeatargetofwhenclauseinacasestatement.

Invokestheblock,settingtheblock'sparameterstothevaluesinparamsusingsomethingclosetomethodcallingsemantics.Generatesawarningifmultiplevaluesarepassedtoaprocthatexpectsjustone(previouslythissilentlyconvertedtheparameterstoanarray).Notethatprc.()invokesprc.call()withtheparametersgiven.It'sasyntaxsugartohide“call”.

Forprocscreatedusinglambdaor->()anerrorisgeneratedifthewrongnumberofparametersarepassedtoaProcwithmultipleparameters.ForprocscreatedusingProc.neworKernel.proc,extraparametersaresilentlydiscarded.

proc===obj→result_of_proc

call(params,...)→objprc[params,...]→obj(params,...)→obj

Returnsthevalueofthelastexpressionevaluatedintheblock.SeealsoProc#yield.

a_proc=Proc.new{|a,*b|b.collect{|i|i*a}}

a_proc.call(9,1,2,3)#=>[9,18,27]

a_proc[9,1,2,3]#=>[9,18,27]

a_proc=lambda{|a,b|a}

a_proc.call(1,2,3)

produces:

prog.rb:4:in`blockin<main>':wrongnumberofarguments(3for2)(ArgumentError)

fromprog.rb:5:in`call'

fromprog.rb:5:in`<main>'

Returnsthenumberofmandatoryarguments.Iftheblockisdeclaredtotakenoarguments,returns0.Iftheblockisknowntotakeexactlynarguments,returnsn.Iftheblockhasoptionalarguments,returns-n-1,wherenisthenumberofmandatoryarguments,withtheexceptionforblocksthatarenotlambdasandhaveonlyafinitenumberofoptionalarguments;inthislattercase,returnsn.Keywordsargumentswillconsideredasasingleadditionalargument,thatargumentbeingmandatoryifanykeywordargumentismandatory.Aprocwithnoargumentdeclarationsisthesameasablockdeclaring||asitsarguments.

proc{}.arity#=>0

proc{||}.arity#=>0

proc{|a|}.arity#=>1

proc{|a,b|}.arity#=>2

proc{|a,b,c|}.arity#=>3

proc{|*a|}.arity#=>-1

proc{|a,*b|}.arity#=>-2

proc{|a,*b,c|}.arity#=>-3

proc{|x:,y:,z:0|}.arity#=>1

proc{|*a,x:,y:0|}.arity#=>-2

arity→fixnum

proc{|x=0|}.arity#=>0

lambda{|x=0|}.arity#=>-1

proc{|x=0,y|}.arity#=>1

lambda{|x=0,y|}.arity#=>-2

proc{|x=0,y=0|}.arity#=>0

lambda{|x=0,y=0|}.arity#=>-1

proc{|x,y=0|}.arity#=>1

lambda{|x,y=0|}.arity#=>-2

proc{|(x,y),z=0|}.arity#=>1

lambda{|(x,y),z=0|}.arity#=>-2

proc{|a,x:0,y:0|}.arity#=>1

lambda{|a,x:0,y:0|}.arity#=>-2

Returnsthebindingassociatedwithprc.NotethatKernel#evalacceptseitheraProcoraBindingobjectasitssecondparameter.

deffred(param)

proc{}

b=fred(99)

eval("param",b.binding)#=>99

Invokestheblock,settingtheblock'sparameterstothevaluesinparamsusingsomethingclosetomethodcallingsemantics.Generatesawarningifmultiplevaluesarepassedtoaprocthatexpectsjustone(previouslythissilentlyconvertedtheparameterstoanarray).Notethatprc.()invokesprc.call()withtheparametersgiven.It'sasyntaxsugartohide“call”.

Forprocscreatedusinglambdaor->()anerroris

binding→binding

generatedifthewrongnumberofparametersarepassedtoaProcwithmultipleparameters.ForprocscreatedusingProc.neworKernel.proc,extraparametersaresilentlydiscarded.

a_proc.call(9,1,2,3)#=>[9,18,27]

a_proc[9,1,2,3]#=>[9,18,27]

a_proc.call(1,2,3)

produces:

Returnsacurriedproc.Iftheoptionalarityargumentisgiven,itdeterminesthenumberofarguments.Acurriedprocreceivessomearguments.Ifasufficientnumberofargumentsaresupplied,itpassesthesuppliedargumentstotheoriginalprocandreturnstheresult.Otherwise,returnsanothercurriedprocthattakestherestofarguments.

b=proc{|x,y,z|(x||0)+(y||0)+(z||0)}

pb.curry[1][2][3]#=>6

pb.curry[1,2][3,4]#=>6

pb.curry(5)[1][2][3][4][5]#=>6

pb.curry(5)[1,2][3,4][5]#=>6

pb.curry(1)[1]#=>1

b=proc{|x,y,z,*w|(x||0)+(y||0)+(z||0)+w.inject

pb.curry[1][2][3]#=>6

curry→a_proccurry(arity)→a_proc

pb.curry[1,2][3,4]#=>10

pb.curry(5)[1][2][3][4][5]#=>15

pb.curry(5)[1,2][3,4][5]#=>15

pb.curry(1)[1]#=>1

b=lambda{|x,y,z|(x||0)+(y||0)+(z||0)}

pb.curry[1][2][3]#=>6

pb.curry[1,2][3,4]#=>wrongnumberofarguments(4for3)

pb.curry(5)#=>wrongnumberofarguments(5for3)

b=lambda{|x,y,z,*w|(x||0)+(y||0)+(z||0)+w

pb.curry[1][2][3]#=>6

pb.curry[1,2][3,4]#=>10

pb.curry(5)[1][2][3][4][5]#=>15

pb.curry(5)[1,2][3,4][5]#=>15

b=proc{:foo}

pb.curry[]#=>:foo

Returnsahashvaluecorrespondingtoprocbody.

SeealsoObject#hash.

Aliasfor:to_s

ReturnstrueforaProcobjectforwhichargumenthandlingisrigid.Suchprocsaretypicallygeneratedbylambda.

AProcobjectgeneratedbyprocignoresextraarguments.

proc{|a,b|[a,b]}.call(1,2,3)#=>[1,2]

hash→integer

inspect()

lambda?→trueorfalse

Itprovidesnilformissingarguments.

proc{|a,b|[a,b]}.call(1)#=>[1,nil]

Itexpandsasinglearrayargument.

proc{|a,b|[a,b]}.call([1,2])#=>[1,2]

AProcobjectgeneratedbylambdadoesn'thavesuchtricks.

lambda{|a,b|[a,b]}.call(1,2,3)#=>ArgumentError

lambda{|a,b|[a,b]}.call(1)#=>ArgumentError

lambda{|a,b|[a,b]}.call([1,2])#=>ArgumentError

#lambda?isapredicateforthetricks.Itreturnstrueifnotricksapply.

lambda{}.lambda?#=>true

proc{}.lambda?#=>false

::newisthesameasproc.

Proc.new{}.lambda?#=>false

lambda,procand::newpreservethetricksofaProcobjectgivenby&argument.

lambda(&lambda{}).lambda?#=>true

proc(&lambda{}).lambda?#=>true

Proc.new(&lambda{}).lambda?#=>true

lambda(&proc{}).lambda?#=>false

proc(&proc{}).lambda?#=>false

Proc.new(&proc{}).lambda?#=>false

AProcobjectgeneratedby&argumenthasthetricks

defn(&b)b.lambda?end

n{}#=>false

The&argumentpreservesthetricksifaProcobject

isgivenby&argument.

n(&lambda{})#=>true

n(&proc{})#=>false

n(&Proc.new{})#=>false

AProcobjectconvertedfromamethodhasnotricks.

defm()end

method(:m).to_proc.lambda?#=>true

n(&method(:m))#=>true

n(&method(:m).to_proc)#=>true

define_methodistreatedthesameasmethoddefinition.Thedefinedmethodhasnotricks.

classC

define_method(:d){}

C.new.d(1,2)#=>ArgumentError

C.new.method(:d).to_proc.lambda?#=>true

define_methodalwaysdefinesamethodwithoutthetricks,evenifanon-lambdaProcobjectisgiven.Thisistheonlyexceptionforwhichthetricksarenotpreserved.

classC

define_method(:e,&proc{})

C.new.e(1,2)#=>ArgumentError

C.new.method(:e).to_proc.lambda?#=>true

Thisexceptioninsuresthatmethodsneverhavetricksandmakesiteasytohavewrapperstodefinemethodsthatbehaveasusual.

classC

defself.def2(name,&body)

define_method(name,&body)

def2(:f){}

C.new.f(1,2)#=>ArgumentError

Thewrapperdef2definesamethodwhichhasnotricks.

Returnstheparameterinformationofthisproc.

prc=lambda{|x,y=42,*other|}

prc.parameters#=>[[:req,:x],[:opt,:y],[:rest,:other]]

ReturnstheRubysourcefilenameandlinenumbercontainingthisprocornilifthisprocwasnotdefinedinRuby(i.e.native)

PartoftheprotocolforconvertingobjectstoProcobjects.InstancesofclassProcsimplyreturnthemselves.

Returnstheuniqueidentifierforthisproc,alongwithanindicationofwheretheprocwasdefined.

Invokestheblock,settingtheblock'sparameterstothevaluesinparamsusingsomethingcloseto

parameters→array

to_proc→proc

to_s→string

methodcallingsemantics.Generatesawarningifmultiplevaluesarepassedtoaprocthatexpectsjustone(previouslythissilentlyconvertedtheparameterstoanarray).Notethatprc.()invokesprc.call()withtheparametersgiven.It'sasyntaxsugartohide“call”.

Forprocscreatedusinglambdaor->()anerrorisgeneratedifthewrongnumberofparametersarepassedtoaProcwithmultipleparameters.ForprocscreatedusingProc.neworKernel.proc,extraparametersaresilentlydiscarded.

a_proc.call(9,1,2,3)#=>[9,18,27]

a_proc[9,1,2,3]#=>[9,18,27]

a_proc.call(1,2,3)

produces:

moduleProcess

InFilesprocess.cruby.c

Constants

CLOCK_BOOTTIME

CLOCK_BOOTTIME_ALARM

CLOCK_MONOTONIC

CLOCK_MONOTONIC_COARSE

CLOCK_MONOTONIC_FAST

CLOCK_MONOTONIC_PRECISE

CLOCK_MONOTONIC_RAW

CLOCK_PROCESS_CPUTIME_ID

CLOCK_PROF

CLOCK_REALTIME

CLOCK_REALTIME_ALARM

CLOCK_REALTIME_COARSE

CLOCK_REALTIME_FAST

CLOCK_REALTIME_PRECISE

CLOCK_SECOND

CLOCK_THREAD_CPUTIME_ID

CLOCK_UPTIME

CLOCK_UPTIME_FAST

CLOCK_UPTIME_PRECISE

CLOCK_VIRTUAL

PRIO_PGRP

see::setpriority

PRIO_PROCESS

see::setpriority

PRIO_USER

see::setpriority

RLIMIT_AS

Maximumsizeoftheprocess'svirtualmemory(addressspace)inbytes.

seethesystemgetrlimit(2)manualfordetails.

RLIMIT_CORE

Maximumsizeofthecorefile.

RLIMIT_CPU

CPUtimelimitinseconds.

RLIMIT_DATA

Maximumsizeoftheprocess'sdatasegment.

RLIMIT_FSIZE

Maximumsizeoffilesthattheprocessmaycreate.

RLIMIT_MEMLOCK

MaximumnumberofbytesofmemorythatmaybelockedintoRAM.

RLIMIT_MSGQUEUE

SpecifiesthelimitonthenumberofbytesthatcanbeallocatedforPOSIXmessagequeuesfortherealuserIDofthecallingprocess.

RLIMIT_NICE

Specifiesaceilingtowhichtheprocess'snicevaluecanberaised.

RLIMIT_NOFILE

Specifiesavalueonegreaterthanthemaximumfiledescriptornumberthatcanbeopenedbythisprocess.

RLIMIT_NPROC

ThemaximumnumberofprocessesthatcanbecreatedfortherealuserIDofthecallingprocess.

RLIMIT_RSS

Specifiesthelimit(inpages)oftheprocess'sresidentset.

RLIMIT_RTPRIO

Specifiesaceilingonthereal-timeprioritythatmaybesetforthisprocess.

RLIMIT_RTTIME

SpecifieslimitonCPUtimethisprocessscheduledunderareal-timeschedulingpolicycanconsume.

RLIMIT_SBSIZE

Maximumsizeofthesocketbuffer.

RLIMIT_SIGPENDING

SpecifiesalimitonthenumberofsignalsthatmaybequeuedfortherealuserIDofthecallingprocess.

RLIMIT_STACK

Maximumsizeofthestack,inbytes.

RLIM_INFINITY

see::setrlimit

RLIM_SAVED_CUR

see::setrlimit

RLIM_SAVED_MAX

see::setrlimit

WNOHANG

see::wait

WUNTRACED

see::wait

PublicClassMethods

Terminateexecutionimmediately,effectivelyby

abortKernel::abort([msg])Process::abort([msg])

callingKernel.exit(false).Ifmsgisgiven,itiswrittentoSTDERRpriortoterminating.

Returnsthenameofthescriptbeingexecuted.Thevalueisnotaffectedbyassigninganewvalueto$0.

ThismethodfirstappearedinRuby2.1toserveasaglobalvariablefreemeanstogetthescriptname.

ReturnsthetimeresolutionreturnedbyPOSIX::clock_getres()function.

clock_idspecifiesakindofclock.SeethedocumentofProcess.clock_gettimefordetails.

clock_idcanbeasymbolasProcess.clock_gettime.Howevertheresultmaynotbeaccurate.Forexample,+::clock_getres(:GETTIMEOFDAY_BASED_CLOCK_REALTIME)+returns1.0e-06whichmeans1microsecond,butactualresolutioncanbemorecoarse.

Ifthegivenclock_idisnotsupported,Errno::EINVALisraised.

unitspecifiesatypeofthereturnvalue.Process.clock_getresacceptsunitasProcess.clock_gettime.Thedefaultvalue,:float_second,isalsosameasProcess.clock_gettime.

Process.clock_getresalsoaccepts:hertzasunit.:hertzmeansathereciprocalof:float_second.

:hertzcanbeusedtoobtaintheexactvalueoftheclocktickspersecondfortimes()functionand

argv0→frozen_string

clock_getres(clock_id[,unit])→number

CLOCKS_PER_SECforclock()function.

+::clock_getres(:TIMES_BASED_CLOCK_PROCESS_CPUTIME_ID,:hertz)+returnstheclocktickspersecond.

+::clock_getres(:CLOCK_BASED_CLOCK_PROCESS_CPUTIME_ID,:hertz)+returnsCLOCKS_PER_SEC.

pProcess.clock_getres(Process::CLOCK_MONOTONIC)

#=>1.0e-09

ReturnsatimereturnedbyPOSIX::clock_gettime()function.

pProcess.clock_gettime(Process::CLOCK_MONOTONIC)

#=>896053.968060096

clock_idspecifiesakindofclock.ItisspecifedasaconstantwhichbeginswithProcess::CLOCK_suchasProcess::CLOCK_REALTIMEandProcess::CLOCK_MONOTONIC.

ThesupportedconstantsdependsonOSandversion.Rubyprovidesfollowingtypesofclock_idifavailable.

CLOCK_REALTIMESUSv2to4,Linux2.5.63,FreeBSD3.0,NetBSD2.0,OpenBSD2.1

CLOCK_MONOTONICSUSv3to4,Linux2.5.63,FreeBSD3.0,NetBSD2.0,OpenBSD3.4

CLOCK_PROCESS_CPUTIME_IDSUSv3to4,Linux2.5.63,OpenBSD5.4

clock_gettime(clock_id[,unit])→number

CLOCK_THREAD_CPUTIME_IDSUSv3to4,Linux2.5.63,FreeBSD7.1,OpenBSD5.4

CLOCK_VIRTUALFreeBSD3.0,OpenBSD2.1

CLOCK_PROFFreeBSD3.0,OpenBSD2.1

CLOCK_REALTIME_FASTFreeBSD8.1

CLOCK_REALTIME_PRECISEFreeBSD8.1

CLOCK_REALTIME_COARSELinux2.6.32

CLOCK_REALTIME_ALARMLinux3.0

CLOCK_MONOTONIC_FASTFreeBSD8.1

CLOCK_MONOTONIC_PRECISEFreeBSD8.1

CLOCK_MONOTONIC_COARSELinux2.6.32

CLOCK_MONOTONIC_RAWLinux2.6.28

CLOCK_BOOTTIMELinux2.6.39

CLOCK_BOOTTIME_ALARMLinux3.0

CLOCK_UPTIMEFreeBSD7.0,OpenBSD5.5

CLOCK_UPTIME_FASTFreeBSD8.1

CLOCK_UPTIME_PRECISEFreeBSD8.1

CLOCK_SECONDFreeBSD8.1

NotethatSUSstandsforSingleUnixSpecification.SUScontainsPOSIXand::clock_gettimeisdefinedinthePOSIXpart.SUSdefinesCLOCK_REALTIMEmandatorybutCLOCK_MONOTONIC,CLOCK_PROCESS_CPUTIME_IDandCLOCK_THREAD_CPUTIME_IDareoptional.

Also,severalsymbolsareacceptedasclock_id.Thereareemulationsfor::clock_gettime().

Forexample,Process::CLOCK_REALTIMEisdefinedas:GETTIMEOFDAY_BASED_CLOCK_REALTIMEwhen::clock_gettime()isnotavailable.

EmulationsforCLOCK_REALTIME:

:GETTIMEOFDAY_BASED_CLOCK_REALTIMEUsegettimeofday()definedbySUS.(SUSv4obsoletedit,though.)The

resolutionis1microsecond.

:TIME_BASED_CLOCK_REALTIMEUsetime()definedbyISOC.Theresolutionis1second.

EmulationsforCLOCK_MONOTONIC:

:MACH_ABSOLUTE_TIME_BASED_CLOCK_MONOTONICUsemach_absolute_time(),availableonDarwin.TheresolutionisCPUdependent.

:TIMES_BASED_CLOCK_MONOTONICUsetheresultvalueoftimes()definedbyPOSIX.POSIXdefinesitas“times()shallreturntheelapsedrealtime,inclockticks,sinceanarbitrarypointinthepast(forexample,systemstart-uptime)”.Forexample,GNU/Linuxreturnsavaluebasedonjiffiesanditismonotonic.However,4.4BSDusesgettimeofday()anditisnotmonotonic.(FreeBSDuses::clock_gettime(CLOCK_MONOTONIC)instead,though.)Theresolutionistheclocktick.“getconfCLK_TCK”commandshowstheclocktickspersecond.(TheclocktickspersecondisdefinedbyHZmacroinoldersystems.)Ifitis100andclock_tis32bitsintegertype,theresolutionis10millisecondandcannotrepresentover497days.

EmulationsforCLOCK_PROCESS_CPUTIME_ID:

:GETRUSAGE_BASED_CLOCK_PROCESS_CPUTIME_IDUsegetrusage()definedbySUS.getrusage()isusedwithRUSAGE_SELFtoobtainthetimeonlyforthecallingprocess

(excludingthetimeforchildprocesses).Theresultisadditionofusertime(ru_utime)andsystemtime(ru_stime).Theresolutionis1microsecond.

:TIMES_BASED_CLOCK_PROCESS_CPUTIME_IDUsetimes()definedbyPOSIX.Theresultisadditionofusertime(tms_utime)andsystemtime(tms_stime).tms_cutimeandtms_cstimeareignoredtoexcludethetimeforchildprocesses.Theresolutionistheclocktick.“getconfCLK_TCK”commandshowstheclocktickspersecond.(TheclocktickspersecondisdefinedbyHZmacroinoldersystems.)Ifitis100,theresolutionis10millisecond.

:CLOCK_BASED_CLOCK_PROCESS_CPUTIME_IDUseclock()definedbyISOC.Theresolutionis1/CLOCKS_PER_SEC.CLOCKS_PER_SECistheC-levelmacrodefinedbytime.h.SUSdefinesCLOCKS_PER_SECis1000000.Non-Unixsystemsmaydefineitadifferentvalue,though.IfCLOCKS_PER_SECis1000000asSUS,theresolutionis1microsecond.IfCLOCKS_PER_SECis1000000andclock_tis32bitsintegertype,itcannotrepresentover72minutes.

Ifthegivenclock_idisnotsupported,Errno::EINVALisraised.

unitspecifiesatypeofthereturnvalue.

:float_secondnumberofsecondsasafloat(default)

:float_millisecondnumberofmillisecondsasafloat

:float_microsecondnumberofmicrosecondsasafloat

:secondnumberofsecondsasaninteger

:millisecondnumberofmillisecondsasaninteger

:microsecondnumberofmicrosecondsasaninteger

:nanosecondnumberofnanosecondsasaninteger

Theunderlyingfunction,::clock_gettime(),returnsanumberofnanoseconds.Floatobject(IEEE754double)isnotenoughtorepresentthereturnvalueforCLOCK_REALTIME.Iftheexactnanosecondsvalueisrequired,use:nanosecondsastheunit.

Theorigin(zero)ofthereturnedvaluevaries.Forexample,systemstartuptime,processstartuptime,theEpoch,etc.

TheorigininCLOCK_REALTIMEisdefinedastheEpoch(1970-01-0100:00:00UTC).Butsomesystemscountleapsecondsandothersdoesn't.Sotheresultcanbeinterpreteddifferentlyacrosssystems.Time.nowisrecommendedoverCLOCK_REALTIME.

Detachtheprocessfromcontrollingterminalandruninthebackgroundassystemdaemon.Unlesstheargumentnochdiristrue(i.e.nonfalse),itchangesthecurrentworkingdirectorytotheroot(“/”).Unlesstheargumentnocloseistrue,daemon()willredirectstandardinput,standardoutputandstandarderrorto/dev/null.Returnzeroonsuccess,orraiseoneofErrno::*.

Someoperatingsystemsretainthestatusofterminatedchildprocessesuntiltheparentcollectsthatstatus(normallyusingsomevariantofwait().Iftheparentnevercollectsthisstatus,thechildstaysaroundasazombieprocess.Process::detachpreventsthisbysettingupaseparateRubythreadwhosesolejobistoreapthestatusoftheprocesspidwhenitterminates.Usedetachonlywhenyoudonotintenttoexplicitlywaitforthechildtoterminate.

Thewaitingthreadreturnstheexitstatusofthedetachedprocesswhenitterminates,soyoucanuseThread#jointoknowtheresult.IfspecifiedpidisnotavalidchildprocessID,thethreadreturnsnilimmediately.

Thewaitingthreadhaspidmethodwhichreturnsthepid.

Inthisfirstexample,wedon'treapthefirstchildprocess,soitappearsasazombieintheprocessstatusdisplay.

p1=fork{sleep0.1}

p2=fork{sleep0.2}

daemon()→0daemon(nochdir=nil,noclose=nil)→0

detach(pid)→thread

Process.waitpid(p2)

sleep2

system("ps-hopid,state-p#{p1}")

produces:

27389Z

Inthenextexample,Process::detachisusedtoreapthechildautomatically.

p1=fork{sleep0.1}

p2=fork{sleep0.2}

Process.detach(p1)

Process.waitpid(p2)

sleep2

system("ps-hopid,state-p#{p1}")

(producesnooutput)

ReturnstheeffectivegroupIDforthisprocess.Notavailableonallplatforms.

Process.egid#=>500

SetstheeffectivegroupIDforthisprocess.Notavailableonallplatforms.

ReturnstheeffectiveuserIDforthisprocess.

egid→fixnumProcess::GID.eid→fixnumProcess::Sys.geteid→fixnum

egid=fixnum→fixnum

euid→fixnumProcess::UID.eid→fixnumProcess::Sys.geteuid→fixnum

Process.euid#=>501

SetstheeffectiveuserIDforthisprocess.Notavailableonallplatforms.

Replacesthecurrentprocessbyrunningthegivenexternalcommand,whichcantakeoneofthefollowingforms:

exec(commandline)

commandlinestringwhichispassedtothestandardshell

exec(cmdname,arg1,...)

commandnameandoneormorearguments(noshell)

exec([cmdname,argv0],arg1,...)

commandname,argvandzeroormorearguments(noshell)

Inthefirstform,thestringistakenasacommandlinethatissubjecttoshellexpansionbeforebeingexecuted.

Thestandardshellalwaysmeans"/bin/sh"onUnix-likesystems,sameasENV["RUBYSHELL"](orENV["COMSPEC"]onWindowsNTseries),andsimilar.

Ifthestringfromthefirstform(exec("command"))followsthesesimplerules:

nometacharacters

noshellreservedwordandnospecialbuilt-in

euid=user

exec([env,]command...[,options])

Rubyinvokesthecommanddirectlywithoutshell

Youcanforceshellinvocationbyadding“;”tothestring(because“;”isametacharacter).

Notethatthisbehaviorisobservablebypidobtained(returnvalueofspawn()andIO#pidforIO.popen)isthepidoftheinvokedcommand,notshell.

Inthesecondform(exec("command1","arg1",...)),thefirstistakenasacommandnameandtherestarepassedasparameterstocommandwithnoshellexpansion.

Inthethirdform(exec(["command","argv0"],"arg1",...)),startingatwo-elementarrayatthebeginningofthecommand,thefirstelementisthecommandtobeexecuted,andthesecondargumentisusedastheargv[0]value,whichmayshowupinprocesslistings.

Inordertoexecutethecommand,oneoftheexec(2)systemcallsareused,sotherunningcommandmayinheritsomeoftheenvironmentoftheoriginalprogram(includingopenfiledescriptors).

Thisbehaviorismodifiedbythegivenenvandoptionsparameters.See::spawnfordetails.

Ifthecommandfailstoexecute(typicallyErrno::ENOENTwhenitwasnotfound)aSystemCallErrorexceptionisraised.

Thismethodmodifiesprocessattributesaccordingtogivenoptionsbeforeexec(2)systemcall.See::spawnformoredetailsaboutthegivenoptions.

Themodifiedattributesmayberetainedwhenexec(2)systemcallfails.

Forexample,hardresourcelimitsarenotrestorable.

Considertocreateachildprocessusing::spawnorKernel#systemifthisisnotacceptable.

exec"echo*"#echoeslistoffilesincurrentdirectory

#nevergethere

exec"echo","*"#echoesanasterisk

#nevergethere

InitiatestheterminationoftheRubyscriptbyraisingtheSystemExitexception.Thisexceptionmaybecaught.Theoptionalparameterisusedtoreturnastatuscodetotheinvokingenvironment.trueandFALSEofstatusmeanssuccessandfailurerespectively.Theinterpretationofotherintegervaluesaresystemdependent.

puts"nevergethere"

rescueSystemExit

puts"rescuedaSystemExitexception"

puts"afterbeginblock"

produces:

rescuedaSystemExitexception

afterbeginblock

Justpriortotermination,Rubyexecutesanyat_exitfunctions(seeKernel::at_exit)andrunsanyobjectfinalizers(seeObjectSpace.define_finalizer).

exit(status=true)Kernel::exit(status=true)Process::exit(status=true)

at_exit{puts"at_exitfunction"}

ObjectSpace.define_finalizer("string",proc{puts"infinalizer"})

produces:

at_exitfunction

infinalizer

Exitstheprocessimmediately.Noexithandlersarerun.statusisreturnedtotheunderlyingsystemastheexitstatus.

Process.exit!(true)

Createsasubprocess.Ifablockisspecified,thatblockisruninthesubprocess,andthesubprocessterminateswithastatusofzero.Otherwise,theforkcallreturnstwice,onceintheparent,returningtheprocessIDofthechild,andonceinthechild,returningnil.ThechildprocesscanexitusingKernel.exit!toavoidrunninganyat_exitfunctions.TheparentprocessshoulduseProcess.waittocollecttheterminationstatusesofitschildrenoruseProcess.detachtoregisterdisinterestintheirstatus;otherwise,theoperatingsystemmayaccumulatezombieprocesses.

Thethreadcallingforkistheonlythreadinthecreatedchildprocess.forkdoesn'tcopyotherthreads.

Ifforkisnotusable,Process.respond_to?(:fork)

exit!(status=false)

fork[{block}]→fixnumornilfork[{block}]→fixnumornil

returnsfalse.

Notethatfork(2)isnotavailableonsomeplatformslikeWindowsandNetBSD4.Thereforeyoushouldusespawn()insteadoffork().

ReturnstheprocessgroupIDforthegivenprocessid.Notavailableonallplatforms.

Process.getpgid(Process.ppid())#=>25527

ReturnstheprocessgroupIDforthisprocess.Notavailableonallplatforms.

Process.getpgid(0)#=>25527

Process.getpgrp#=>25527

Getstheschedulingpriorityforspecifiedprocess,processgroup,oruser.kindindicatesthekindofentitytofind:oneofProcess::PRIO_PGRP,Process::PRIO_USER,orProcess::PRIO_PROCESS.integerisanidindicatingtheparticularprocess,processgroup,oruser(anidof0meanscurrent).Lowerprioritiesaremorefavorableforscheduling.Notavailableonallplatforms.

Process.getpriority(Process::PRIO_USER,0)#=>19

Process.getpriority(Process::PRIO_PROCESS,0)#=>19

Getstheresourcelimitoftheprocess.cur_limit

getpgid(pid)→integer

getpgrp→integer

getpriority(kind,integer)→fixnum

getrlimit(resource)→[cur_limit,max_limit]

meanscurrent(soft)limitandmax_limitmeansmaximum(hard)limit.

resourceindicatesthekindofresourcetolimit.Itisspecifiedasasymbolsuchas:CORE,astringsuchas"CORE"oraconstantsuchasProcess::RLIMIT_CORE.See::setrlimitfordetails.

cur_limitandmax_limitmaybeProcess::RLIM_INFINITY,Process::RLIM_SAVED_MAXorProcess::RLIM_SAVED_CUR.See::setrlimitandthesystemgetrlimit(2)manualfordetails.

ReturnsthesessionIDforforthegivenprocessid.Ifnotgive,returncurrentprocesssid.Notavailableonallplatforms.

Process.getsid()#=>27422

Process.getsid(0)#=>27422

Process.getsid(Process.pid())#=>27422

Returnsthe(real)groupIDforthisprocess.

Process.gid#=>500

SetsthegroupIDforthisprocess.

getsid()→integergetsid(pid)→integer

gid→fixnumProcess::GID.rid→fixnumProcess::Sys.getgid→fixnum

gid=fixnum→fixnum

groups→array

GetanArrayofthegidsofgroupsinthesupplementalgroupaccesslistforthisprocess.

Process.groups#=>[27,6,10,11]

SetthesupplementalgroupaccesslisttothegivenArrayofgroupIDs.

Process.groups#=>[0,1,2,3,4,6,10,11,20,26,27]

Process.groups=[27,6,10,11]#=>[27,6,10,11]

Initializesthesupplementalgroupaccesslistbyreadingthesystemgroupdatabaseandusingallgroupsofwhichthegivenuserisamember.Thegroupwiththespecifiedgidisalsoaddedtothelist.ReturnstheresultingArrayofthegidsofallthegroupsinthesupplementarygroupaccesslist.Notavailableonallplatforms.

Process.groups#=>[0,1,2,3,4,6,10,11,20,26,27]

Process.initgroups("mgranger",30)#=>[30,6,10,11]

Sendsthegivensignaltothespecifiedprocessid(s)ifpidispositive.IfpidiszerosignalissenttoallprocesseswhosegroupIDisequaltothegroupIDoftheprocess.signalmaybeanintegersignalnumberoraPOSIXsignalname(eitherwithorwithoutaSIGprefix).Ifsignalisnegative(orstartswithaminussign),killsprocessgroupsinsteadofprocesses.Not

groups=array→array

initgroups(username,gid)→array

kill(signal,pid,...)→fixnum

allsignalsareavailableonallplatforms.ThekeysandvaluesofSignal.listareknownsignalnamesandnumbers,respectively.

pid=forkdo

Signal.trap("HUP"){puts"Ouch!";exit}

#...dosomework...

Process.kill("HUP",pid)

Process.wait

produces:

Ifsignalisanintegerbutwrongforsignal,Errno::EINVALorRangeErrorwillberaised.OtherwiseunlesssignalisaStringoraSymbol,andaknownsignalname,ArgumentErrorwillberaised.

Also,Errno::ESRCHorRangeErrorforinvalidpid,Errno::EPERMwhenfailedbecauseofnoprivilege,willberaised.Inthesecases,signalsmayhavebeensenttoprecedingprocesses.

Returnsthemaximumnumberofgidsallowedinthesupplementalgroupaccesslist.

Process.maxgroups#=>32

Setsthemaximumnumberofgidsallowedinthesupplementalgroupaccesslist.

maxgroups→fixnum

maxgroups=fixnum→fixnum

pid→fixnum

Returnstheprocessidofthisprocess.Notavailableonallplatforms.

Process.pid#=>27415

Returnstheprocessidoftheparentofthisprocess.ReturnsuntrustworthyvalueonWin32/64.Notavailableonallplatforms.

puts"Iam#{Process.pid}"

Process.fork{puts"Dadis#{Process.ppid}"}

produces:

Iam27417

Dadis27417

SetstheprocessgroupIDofpid(0indicatesthisprocess)tointeger.Notavailableonallplatforms.

Equivalenttosetpgid(0,0).Notavailableonallplatforms.

SeeProcess#getpriority.

Process.setpriority(Process::PRIO_USER,0,19)#=>0

Process.setpriority(Process::PRIO_PROCESS,0,19)#=>0

Process.getpriority(Process::PRIO_USER,0)#=>19

Process.getpriority(Process::PRIO_PROCESS,0)#=>19

ppid→fixnum

setpgid(pid,integer)→0

setpgrp→0

setpriority(kind,integer,priority)→0

Setstheprocesstitlethatappearsontheps(1)command.Notnecessarilyeffectiveonallplatforms.Noexceptionwillberaisedregardlessoftheresult,norwillNotImplementedErrorberaisedeveniftheplatformdoesnotsupportthefeature.

Callingthismethoddoesnotaffectthevalueof$0.

Process.setproctitle('myapp:worker#%d'%worker_id)

ThismethodfirstappearedinRuby2.1toserveasaglobalvariablefreemeanstochangetheprocesstitle.

Setstheresourcelimitoftheprocess.cur_limitmeanscurrent(soft)limitandmax_limitmeansmaximum(hard)limit.

Ifmax_limitisnotgiven,cur_limitisused.

resourceindicatesthekindofresourcetolimit.Itshouldbeasymbolsuchas:CORE,astringsuchas"CORE"oraconstantsuchasProcess::RLIMIT_CORE.TheavailableresourcesareOSdependent.Rubymaysupportfollowingresources.

AStotalavailablememory(bytes)(SUSv3,NetBSD,FreeBSD,OpenBSDbut4.4BSD-Lite)

COREcoresize(bytes)(SUSv3)

setproctitle(string)→string

setrlimit(resource,cur_limit,max_limit)→nilsetrlimit(resource,cur_limit)→nil

CPUCPUtime(seconds)(SUSv3)

DATAdatasegment(bytes)(SUSv3)

FSIZEfilesize(bytes)(SUSv3)

MEMLOCKtotalsizeformlock(2)(bytes)(4.4BSD,GNU/Linux)

MSGQUEUEallocationforPOSIXmessagequeues(bytes)(GNU/Linux)

NICEceilingonprocess'snice(2)value(number)(GNU/Linux)

NOFILEfiledescriptors(number)(SUSv3)

NPROCnumberofprocessesfortheuser(number)(4.4BSD,GNU/Linux)

RSSresidentmemorysize(bytes)(4.2BSD,GNU/Linux)

RTPRIO

ceilingontheprocess'sreal-timepriority(number)(GNU/Linux)

RTTIMECPUtimeforreal-timeprocess(us)(GNU/Linux)

SBSIZEallsocketbuffers(bytes)(NetBSD,FreeBSD)

SIGPENDINGnumberofqueuedsignalsallowed(signals)(GNU/Linux)

STACKstacksize(bytes)(SUSv3)

cur_limitandmax_limitmaybe:INFINITY,"INFINITY"orProcess::RLIM_INFINITY,whichmeansthattheresourceisnotlimited.TheymaybeProcess::RLIM_SAVED_MAX,Process::RLIM_SAVED_CURandcorrespondingsymbolsandstringstoo.Seesystemsetrlimit(2)manualfordetails.

Thefollowingexampleraisesthesoftlimitofcoresizetothehardlimittotrytomakecoredumppossible.

Process.setrlimit(:CORE,Process.getrlimit(:CORE)[1])

Establishesthisprocessasanewsessionandprocessgroupleader,withnocontrollingtty.Returnsthesessionid.Notavailableonallplatforms.

setsid→fixnum

Process.setsid#=>27422

spawnexecutesspecifiedcommandandreturnitspid.

pid=spawn("tarxfruby-2.0.0-p195.tar.bz2")

Process.waitpid

pid=spawn(RbConfig.ruby,"-eputs'Hello,world!'")

Process.waitpid

ThismethodissimilartoKernel#systembutitdoesn'twaitforthecommandtofinish.

TheparentprocessshoulduseProcess.waittocollecttheterminationstatusofitschildoruseProcess.detachtoregisterdisinterestintheirstatus;otherwise,theoperatingsystemmayaccumulatezombieprocesses.

spawnhasbunchofoptionstospecifyprocessattributes:

env:hash

name=>val:settheenvironmentvariable

name=>nil:unsettheenvironmentvariable

command...:

commandline:commandlinestringwhich

cmdname,arg1,...:commandnameandoneor

[cmdname,argv0],arg1,...:commandname,argv[0]

options:hash

clearingenvironmentvariables:

:unsetenv_others=>true:clearenvironmentvariables

:unsetenv_others=>false:don'tclear(default)

processgroup:

:pgroup=>trueor0:makeanewprocessgroup

:pgroup=>pgid:jointospecifiedprocessgroup

:pgroup=>nil:don'tchangetheprocessgroup

spawn([env,]command...[,options])→pidspawn([env,]command...[,options])→pid

createnewprocessgroup:Windowsonly

:new_pgroup=>true:thenewprocessistheroot

:new_pgroup=>false:don'tcreateanewprocessgroup(default)

resourcelimit:resourcenameiscore,cpu,data,etc.SeeProcess.setrlimit.

:rlimit_resourcename=>limit

:rlimit_resourcename=>[cur_limit,max_limit]

umask:

:umask=>int

redirection:

FD:singlefiledescriptorinchildprocess

[FD,FD,...]:multiplefiledescriptorinchildprocess

value:

FD:redirecttothefiledescriptorinparentprocess

string:redirecttofilewithopen(string,"r"or"w")

[string]:redirecttofilewithopen(string,File::RDONLY)

[string,open_mode]:redirecttofilewithopen(string,open_mode,0644)

[string,open_mode,perm]:redirecttofilewithopen(string,open_mode,perm)

[:child,FD]:redirecttotheredirectedfiledescriptor

:close:closethefiledescriptorinchildprocess

FDisoneoffollows

:in:thefiledescriptor0whichisthestandardinput

:out:thefiledescriptor1whichisthestandardoutput

:err:thefiledescriptor2whichisthestandarderror

integer:thefiledescriptorofspecifiedtheinteger

io:thefiledescriptorspecifiedasio.fileno

filedescriptorinheritance:closenon-redirectednon-standardfds(3,4,5,...)ornot

:close_others=>true:don'tinherit

currentdirectory:

:chdir=>str

The'cmdname,arg1,...'formdoesnotusetheshell

ondifferentOSes,differentthingsareprovidedas

commands.Anexampleofthisis'echo',whichisabuilt

onWindows,butisanormalprogramonLinuxandMac

Thismeansthat%xProcess.spawn'echo','%Path%'`will

thecontentsofthe%x%Path%`environmentvariableon

but%xProcess.spawn'echo','$PATH'`printstheliteral

Ifahashisgivenasenv,theenvironmentisupdatedbyenvbeforeexec(2)inthechildprocess.Ifapairinenvhasnilasthevalue,thevariableisdeleted.

#setFOOasBARandunsetBAZ.

pid=spawn({"FOO"=>"BAR","BAZ"=>nil},command)

Ifahashisgivenasoptions,itspecifiesprocessgroup,createnewprocessgroup,resourcelimit,currentdirectory,umaskandredirectsforthechildprocess.Also,itcanbespecifiedtoclearenvironmentvariables.

The:unsetenv_otherskeyinoptionsspecifiestoclearenvironmentvariables,otherthanspecifiedbyenv.

pid=spawn(command,:unsetenv_others=>true)#noenvironmentvariable

pid=spawn({"FOO"=>"BAR"},command,:unsetenv_others=

The:pgroupkeyinoptionsspecifiesaprocessgroup.Thecorrespondingvalueshouldbetrue,zeroorpositiveinteger.trueandzeromeanstheprocessshouldbeaprocessleaderofanewprocessgroup.Othervaluesspecifiesaprocessgrouptobebelongs.

pid=spawn(command,:pgroup=>true)#processleader

pid=spawn(command,:pgroup=>10)#belongstotheprocessgroup10

The:new_pgroupkeyinoptionsspecifiestopassCREATE_NEW_PROCESS_GROUPflagtoCreateProcessW()thatisWindowsAPI.ThisoptionisonlyforWindows.truemeansthenewprocessistherootprocessofthenewprocessgroup.ThenewprocesshasCTRL+Cdisabled.ThisflagisnecessaryforProcess.kill(:SIGINT,pid)onthesubprocess.:new_pgroupisfalsebydefault.

pid=spawn(command,:new_pgroup=>true)#newprocessgroup

pid=spawn(command,:new_pgroup=>false)#sameprocessgroup

The:rlimit_fookeyspecifiesaresourcelimit.foo

shouldbeoneofresourcetypessuchascore.Thecorrespondingvalueshouldbeanintegeroranarraywhichhaveoneortwointegers:sameascur_limitandmax_limitargumentsfor::setrlimit.

cur,max=Process.getrlimit(:CORE)

pid=spawn(command,:rlimit_core=>[0,max])#disablecoretemporary.

pid=spawn(command,:rlimit_core=>max)#enablecoredump

pid=spawn(command,:rlimit_core=>0)#neverdumpcore.

The:umaskkeyinoptionsspecifiestheumask.

pid=spawn(command,:umask=>077)

The:in,:out,:err,afixnum,anIOandanarraykeyspecifiesaredirection.Theredirectionmapsafiledescriptorinthechildprocess.

Forexample,stderrcanbemergedintostdoutasfollows:

pid=spawn(command,:err=>:out)

pid=spawn(command,2=>1)

pid=spawn(command,STDERR=>:out)

pid=spawn(command,STDERR=>STDOUT)

Thehashkeysspecifiesafiledescriptorinthechildprocessstartedbyspawn.:err,2andSTDERRspecifiesthestandarderrorstream(stderr).

Thehashvaluesspecifiesafiledescriptorintheparentprocesswhichinvokesspawn.:out,1andSTDOUTspecifiesthestandardoutputstream(stdout).

Intheaboveexample,thestandardoutputinthechildprocessisnotspecified.Soitisinheritedfromtheparentprocess.

Thestandardinputstream(stdin)canbespecifiedby:in,0andSTDIN.

Afilenamecanbespecifiedasahashvalue.

pid=spawn(command,:in=>"/dev/null")#readmode

pid=spawn(command,:out=>"/dev/null")#writemode

pid=spawn(command,:err=>"log")#writemode

pid=spawn(command,[:out,:err]=>"/dev/null")#writemode

pid=spawn(command,3=>"/dev/null")#readmode

Forstdoutandstderr(andcombinationofthem),itisopenedinwritemode.Otherwisereadmodeisused.

Forspecifyingflagsandpermissionoffilecreationexplicitly,anarrayisusedinstead.

pid=spawn(command,:in=>["file"])#readmodeisassumed

pid=spawn(command,:in=>["file","r"])

pid=spawn(command,:out=>["log","w"])#0644assumed

pid=spawn(command,:out=>["log","w",0600])

pid=spawn(command,:out=>["log",File::WRONLY|File::

Thearrayspecifiesafilename,flagsandpermission.Theflagscanbeastringoraninteger.Iftheflagsisomittedornil,File::RDONLYisassumed.Thepermissionshouldbeaninteger.Ifthepermissionisomittedornil,0644isassumed.

IfanarrayofIOsandintegersarespecifiedasahashkey,alltheelementsareredirected.

pid=spawn(command,[:out,:err]=>["log","w"])

Anotherwaytomergemultiplefiledescriptorsis[:child,fd].[:child,fd]meansthefiledescriptorinthechildprocess.Thisisdifferentfromfd.Forexample,:err=>:outmeansredirectingchildstderrtoparentstdout.But:err=>[:child,:out]meansredirectingchildstderrtochildstdout.Theydifferifstdoutisredirectedinthechildprocessasfollows.

pid=spawn(command,:out=>["log","w"],:err=>[:child

[:child,:out]canbeusedtomergestderrintostdoutinIO.popen.Inthiscase,IO.popenredirectsstdouttoapipeinthechildprocessand[:child,:out]referstheredirectedstdout.

io=IO.popen(["sh","-c","echoout;echoerr>&2",:

pio.read#=>"out\nerr\n"

The:chdirkeyinoptionsspecifiesthecurrentdirectory.

pid=spawn(command,:chdir=>"/var/tmp")

spawnclosesallnon-standardunspecifieddescriptorsbydefault.The“standard”descriptorsare0,1and2.Thisbehaviorisspecifiedby:close_othersoption.:close_othersdoesn'taffectthestandarddescriptorswhichareclosedonlyif:closeisspecifiedexplicitly.

pid=spawn(command,:close_others=>true)#close3,4,5,...(default)

pid=spawn(command,:close_others=>false)#don'tclose3,4,5,...

:close_othersistruebydefaultforspawnandIO.popen.

Notethatfdswhichclose-on-execflagisalreadysetareclosedregardlessof:close_othersoption.

SoIO.pipeandspawncanbeusedasIO.popen.

#similartor=IO.popen(command)

r,w=IO.pipe

pid=spawn(command,:out=>w)#r,wisclosedinthechildprocess.

w.close

:closeisspecifiedasahashvaluetocloseafdindividually.

f=open(foo)

system(command,f=>:close)#don'tinheritf.

Ifafiledescriptorneedtobeinherited,io=>iocanbeused.

#valgrindhas--log-fdoptionforlogdestination.

#log_w=>log_windicateslog_w.filenoinheritstochildprocess.

log_r,log_w=IO.pipe

pid=spawn("valgrind","--log-fd=#{log_w.fileno}","echo"

log_w.close

plog_r.read

Itisalsopossibletoexchangefiledescriptors.

pid=spawn(command,:out=>:err,:err=>:out)

Thehashkeysspecifyfiledescriptorsinthechildprocess.Thehashvaluesspecifiesfiledescriptorsintheparentprocess.Sotheabovespecifiesexchangingstdoutandstderr.Internally,spawnusesanextrafiledescriptortoresolvesuchcyclicfiledescriptormapping.

ReturnsaTmsstructure(seeProcess::Tms)thatcontainsuserandsystemCPUtimesforthisprocess,andalsoforchildrenprocesses.

t=Process.times

[t.utime,t.stime,t.cutime,t.cstime]#=>[0.0,0.02,0.00,0.00]

times→aProcessTms

Returnsthe(real)userIDofthisprocess.

Process.uid#=>501

Setsthe(user)userIDforthisprocess.Notavailableonallplatforms.

Waitsforachildprocesstoexit,returnsitsprocessid,andsets$?toaProcess::Statusobjectcontaininginformationonthatprocess.Whichchilditwaitsondependsonthevalueofpid:

>0WaitsforthechildwhoseprocessIDequalspid.

0WaitsforanychildwhoseprocessgroupIDequalsthatofthecallingprocess.

-1Waitsforanychildprocess(thedefaultifnopidisgiven).

<-1WaitsforanychildwhoseprocessgroupIDequalstheabsolutevalueofpid.

TheflagsargumentmaybealogicaloroftheflagvaluesProcess::WNOHANG(donotblockifnochild

uid→fixnumProcess::UID.rid→fixnumProcess::Sys.getuid→fixnum

uid=user→numeric

wait()→fixnumwait(pid=-1,flags=0)→fixnumwaitpid(pid=-1,flags=0)→fixnum

available)orProcess::WUNTRACED(returnstoppedchildrenthathaven'tbeenreported).Notallflagsareavailableonallplatforms,butaflagvalueofzerowillworkonallplatforms.

CallingthismethodraisesaSystemCallErroriftherearenochildprocesses.Notavailableonallplatforms.

includeProcess

fork{exit99}#=>27429

wait#=>27429

$?.exitstatus#=>99

pid=fork{sleep3}#=>27440

Time.now#=>2008-03-0819:56:16+0900

waitpid(pid,Process::WNOHANG)#=>nil

Time.now#=>2008-03-0819:56:16+0900

waitpid(pid,0)#=>27440

Time.now#=>2008-03-0819:56:19+0900

Waitsforachildprocesstoexit(see::waitpidforexactsemantics)andreturnsanarraycontainingtheprocessidandtheexitstatus(aProcess::Statusobject)ofthatchild.RaisesaSystemCallErroriftherearenochildprocesses.

Process.fork{exit99}#=>27437

pid,status=Process.wait2

pid#=>27437

status.exitstatus#=>99

Waitsforallchildren,returninganarrayofpid/statuspairs(wherestatusisaProcess::Statusobject).

fork{sleep0.2;exit2}#=>27432

wait2(pid=-1,flags=0)→[pid,status]waitpid2(pid=-1,flags=0)→[pid,status]

waitall→[[pid1,status1],...]

fork{sleep0.1;exit1}#=>27433

fork{exit0}#=>27434

pProcess.waitall

produces:

[[30982,#<Process::Status:pid30982exit0>],

[30979,#<Process::Status:pid30979exit1>],

[30976,#<Process::Status:pid30976exit2>]]

Waitsforachildprocesstoexit,returnsitsprocessid,andsets$?toaProcess::Statusobjectcontaininginformationonthatprocess.Whichchilditwaitsondependsonthevalueofpid:

>0WaitsforthechildwhoseprocessIDequalspid.

0WaitsforanychildwhoseprocessgroupIDequalsthatofthecallingprocess.

-1Waitsforanychildprocess(thedefaultifnopidisgiven).

<-1WaitsforanychildwhoseprocessgroupIDequalstheabsolutevalueofpid.

TheflagsargumentmaybealogicaloroftheflagvaluesProcess::WNOHANG(donotblockifnochildavailable)orProcess::WUNTRACED(returnstoppedchildrenthathaven'tbeenreported).Notallflagsareavailableonallplatforms,butaflagvalueofzerowillworkonallplatforms.

wait()→fixnumwait(pid=-1,flags=0)→fixnumwaitpid(pid=-1,flags=0)→fixnum

CallingthismethodraisesaSystemCallErroriftherearenochildprocesses.Notavailableonallplatforms.

includeProcess

wait#=>27429

$?.exitstatus#=>99

pid=fork{sleep3}#=>27440

Time.now#=>2008-03-0819:56:16+0900

waitpid(pid,Process::WNOHANG)#=>nil

Time.now#=>2008-03-0819:56:16+0900

waitpid(pid,0)#=>27440

Time.now#=>2008-03-0819:56:19+0900

Waitsforachildprocesstoexit(see::waitpidforexactsemantics)andreturnsanarraycontainingtheprocessidandtheexitstatus(aProcess::Statusobject)ofthatchild.RaisesaSystemCallErroriftherearenochildprocesses.

Process.fork{exit99}#=>27437

pid,status=Process.wait2

pid#=>27437

status.exitstatus#=>99

wait2(pid=-1,flags=0)→[pid,status]waitpid2(pid=-1,flags=0)→[pid,status]

moduleProcess::GIDTheProcess::GIDmodulecontainsacollectionofmodulefunctionswhichcanbeusedtoportablyget,set,andswitchthecurrentprocess'sreal,effective,andsavedgroupIDs.

InFilesprocess.c

PublicClassMethods

Changethecurrentprocess'srealandeffectivegroupIDtothatspecifiedbygroup.ReturnsthenewgroupID.Notavailableonallplatforms.

[Process.gid,Process.egid]#=>[0,0]

Process::GID.change_privilege(33)#=>33

Process.egid#=>500

Process::GID.change_privilege(group)→fixnum

GetthegroupIDbythename.Ifthegroupisnotfound,ArgumentErrorwillberaised.

Process::GID.from_name("wheel")#=>0

Process::GID.from_name("nosuchgroup")#=>can'tfindgroupfornosuchgroup(ArgumentError)

SettheeffectivegroupID,andifpossible,thesavedgroupIDoftheprocesstothegivengroup.ReturnstheneweffectivegroupID.Notavailableonallplatforms.

Process::GID.grant_privilege(31)#=>33

ExchangerealandeffectivegroupIDsandreturntheneweffectivegroupID.Notavailableonallplatforms.

Process::GID.re_exchange#=>0

ReturnstrueiftherealandeffectivegroupIDsofaprocessmaybeexchangedonthecurrentplatform.

Process::GID.from_name(name)→gid

Process::GID.grant_privilege(group)→fixnumProcess::GID.eid=group→fixnum

Process::GID.re_exchange→fixnum

Process::GID.re_exchangeable?→trueorfalse

Process.gid#=>500

ReturnstrueifthecurrentplatformhassavedgroupIDfunctionality.

SwitchtheeffectiveandrealgroupIDsofthecurrentprocess.Ifablockisgiven,thegroupIDswillbeswitchedbackaftertheblockisexecuted.ReturnstheneweffectivegroupIDifcalledwithoutablock,andthereturnvalueoftheblockifoneisgiven.

Process::GID.sid_available?→trueorfalse

Process::GID.switch→fixnumProcess::GID.switch{||block}→object

classProcess::StatusProcess::Statusencapsulatestheinformationonthestatusofarunningorterminatedsystemprocess.Thebuilt-invariable$?iseitherniloraProcess::Statusobject.

Process.wait#=>26557

$?.class#=>Process::Status

$?.to_i#=>25344

$?>>8#=>99

$?.stopped?#=>false

$?.exited?#=>true

$?.exitstatus#=>99

Posixsystemsrecordinformationonprocessesusinga16-bitinteger.Thelowerbitsrecordtheprocessstatus(stopped,exited,signaled)andtheupperbitspossiblycontainadditionalinformation(forexampletheprogram'sreturncodeinthecaseofexitedprocesses).PreRuby1.8,thesebitswereexposeddirectlytotheRubyprogram.RubynowencapsulatestheseinaProcess::Statusobject.Tomaximizecompatibility,however,theseobjectsretainabit-orientedinterface.Inthedescriptionsthatfollow,whenwetalkabouttheintegervalueofstat,we'rereferringtothis16bitvalue.

InFiles

process.c

ParentObject

LogicalANDofthebitsinstatwithnum.

fork{exit0x37}

Process.wait

sprintf('%04x',$?.to_i)#=>"3700"

sprintf('%04x',$?&0x1e00)#=>"1600"

Returnstrueiftheintegervalueofstatequalsother.

Shiftthebitsinstatrightnumplaces.

$?.to_i#=>25344

$?>>8#=>99

Returnstrueifstatgeneratedacoredumpwhenitterminated.Notavailableonallplatforms.

stat&num→fixnum

stat==other→trueorfalse

stat>>num→fixnum

coredump?→trueorfalse

exited?→trueorfalse

Returnstrueifstatexitednormally(forexampleusinganexit()callorfinishingtheprogram).

Returnstheleastsignificanteightbitsofthereturncodeofstat.Onlyavailableifexited?istrue.

fork{}#=>26572

$?.exited?#=>true

$?.exitstatus#=>0

$?.exited?#=>true

$?.exitstatus#=>99

Overridetheinspectionmethod.

system("false")

p$?.inspect#=>"#<Process::Status:pid12861exit1>"

ReturnstheprocessIDthatthisstatusobjectrepresents.

fork{exit}#=>26569

$?.pid#=>26569

Returnstrueifstatterminatedbecauseofanuncaughtsignal.

exitstatus→fixnumornil

inspect→string

pid→fixnum

signaled?→trueorfalse

Returnstrueifthisprocessisstopped.ThisisonlyreturnedifthecorrespondingwaitcallhadtheWUNTRACEDflagset.

Returnsthenumberofthesignalthatcausedstattostop(ornilifselfisnotstopped).

Returnstrueifstatissuccessful,falseifnot.Returnsnilifexited?isnottrue.

Returnsthenumberofthesignalthatcausedstattoterminate(ornilifselfwasnotterminatedbyanuncaughtsignal).

ReturnsthebitsinstatasaFixnum.Pokingaroundinthesebitsisplatformdependent.

fork{exit0xab}#=>26566

sprintf('%04x',$?.to_i)#=>"ab00"

Showpidandexitstatusasastring.

system("false")

p$?.to_s#=>"pid12766exit1"

stopped?→trueorfalse

stopsig→fixnumornil

success?→true,falseornil

termsig→fixnumornil

to_i→fixnumto_int→fixnum

to_s→string

moduleProcess::SysTheProcess::SysmodulecontainsUIDandGIDfunctionswhichprovidedirectbindingstothesystemcallsofthesamenamesinsteadofthemore-portableversionsofthesamefunctionalityfoundintheProcess,Process::UID,andProcess::GIDmodules.

InFilesprocess.c

PublicClassMethods

Process.egid#=>500

Process.euid#=>501

Process.gid#=>500

Process.uid#=>501

Returnstrueiftheprocesswascreatedasaresultofanexecve(2)systemcallwhichhadeitherofthesetuidorsetgidbitsset(andextraprivilegesweregivenasaresult)orifithaschangedanyofitsreal,effectiveorsaveduserorgroupIDssinceitbeganexecution.

SettheeffectivegroupIDofthecallingprocesstogroup.Notavailableonallplatforms.

SettheeffectiveuserIDofthecallingprocesstouser.Notavailableonallplatforms.

uid→fixnumProcess::UID.rid→fixnumProcess::Sys.getuid→fixnum

Process::Sys.issetugid→trueorfalse

Process::Sys.setegid(group)→nil

Process::Sys.seteuid(user)→nil

Process::Sys.setgid(group)→nil

SetthegroupIDofthecurrentprocesstogroup.Notavailableonallplatforms.

Setsthe(group)realand/oreffectivegroupIDsofthecurrentprocesstoridandeid,respectively.Avalueof-1foreithermeanstoleavethatIDunchanged.Notavailableonallplatforms.

Setsthe(group)real,effective,andsaveduserIDsofthecurrentprocesstorid,eid,andsidrespectively.Avalueof-1foranyvaluemeanstoleavethatIDunchanged.Notavailableonallplatforms.

Setsthe(user)real,effective,andsaveduserIDsofthecurrentprocesstorid,eid,andsidrespectively.Avalueof-1foranyvaluemeanstoleavethatIDunchanged.Notavailableonallplatforms.

Setsthe(user)realand/oreffectiveuserIDsofthecurrentprocesstoridandeid,respectively.Avalueof-1foreithermeanstoleavethatIDunchanged.Notavailableonallplatforms.

SettherealgroupIDofthecallingprocesstogroup.Notavailableonallplatforms.

Process::Sys.setregid(rid,eid)→nil

Process::Sys.setresgid(rid,eid,sid)→nil

Process::Sys.setresuid(rid,eid,sid)→nil

Process::Sys.setreuid(rid,eid)→nil

Process::Sys.setrgid(group)→nil

SettherealuserIDofthecallingprocesstouser.Notavailableonallplatforms.

SettheuserIDofthecurrentprocesstouser.Notavailableonallplatforms.

Process::Sys.setruid(user)→nil

Process::Sys.setuid(user)→nil

moduleProcess::UIDTheProcess::UIDmodulecontainsacollectionofmodulefunctionswhichcanbeusedtoportablyget,set,andswitchthecurrentprocess'sreal,effective,andsaveduserIDs.

InFilesprocess.c

PublicClassMethods

Changethecurrentprocess'srealandeffectiveuserIDtothatspecifiedbyuser.ReturnsthenewuserID.Notavailableonallplatforms.

[Process.uid,Process.euid]#=>[0,0]

Process::UID.change_privilege(31)#=>31

Process.euid#=>501

Process::UID.change_privilege(user)→fixnum

GettheuserIDbythename.Iftheuserisnotfound,ArgumentErrorwillberaised.

Process::UID.from_name("root")#=>0

Process::UID.from_name("nosuchuser")#=>can'tfinduserfornosuchuser(ArgumentError)

SettheeffectiveuserID,andifpossible,thesaveduserIDoftheprocesstothegivenuser.ReturnstheneweffectiveuserID.Notavailableonallplatforms.

Process::UID.grant_privilege(31)#=>31

ExchangerealandeffectiveuserIDsandreturntheneweffectiveuserID.Notavailableonallplatforms.

Process::UID.re_exchange#=>0

ReturnstrueiftherealandeffectiveuserIDsofaprocessmaybeexchangedonthecurrentplatform.

Process::UID.from_name(name)→uid

Process::UID.grant_privilege(user)→fixnumProcess::UID.eid=user→fixnum

Process::UID.re_exchange→fixnum

Process::UID.re_exchangeable?→trueorfalse

uid→fixnumProcess::UID.rid→fixnum

Process.uid#=>501

ReturnstrueifthecurrentplatformhassaveduserIDfunctionality.

SwitchtheeffectiveandrealuserIDsofthecurrentprocess.Ifablockisgiven,theuserIDswillbeswitchedbackaftertheblockisexecuted.ReturnstheneweffectiveuserIDifcalledwithoutablock,andthereturnvalueoftheblockifoneisgiven.

Process::Sys.getuid→fixnum

Process::UID.sid_available?→trueorfalse

Process::UID.switch→fixnumProcess::UID.switch{||block}→object

classProcess::Waiter

InFilesprocess.c

ParentThread

classRandomRandomprovidesaninterfacetoRuby'spseudo-randomnumbergenerator,orPRNG.ThePRNGproducesadeterministicsequenceofbitswhichapproximatetruerandomness.Thesequencemayberepresentedbyintegers,floats,orbinarystrings.

Thegeneratormaybeinitializedwitheitherasystem-generatedoruser-suppliedseedvaluebyusing::srand.

Theclassmethod#randprovidesthebasefunctionalityofKernel#randalongwithbetterhandlingoffloatingpointvalues.ThesearebothinterfacestoRandom::DEFAULT,theRubysystemPRNG.

::newwillcreateanewPRNGwithastateindependentofRandom::DEFAULT,allowingmultiplegeneratorswithdifferentseedvaluesorsequencepositionstoexistsimultaneously.Randomobjectscanbemarshaled,allowingsequencestobesavedandresumed.

PRNGsarecurrentlyimplementedasamodifiedMersenneTwisterwithaperiodof2**19937-1.

InFiles

random.c

ParentObject

Constants

DEFAULT

DirectaccesstoRuby'sPseudorandomnumbergenerator(PRNG).

PublicClassMethods

CreatesanewPRNGusingseedtosettheinitialstate.Ifseedisomitted,thegeneratorisinitializedwith::new_seed.

See::srandformoreinformationontheuseofseedvalues.

Returnsanarbitraryseedvalue.Thisisusedby::newwhennoseedvalueisspecifiedasanargument.

Random.new_seed#=>115032730400174366788466674494640623225

new(seed=Random.new_seed)→prng

new_seed→integer

rand→float

AliasofRandom::DEFAULT.rand.

Seedsthesystempseudo-randomnumbergenerator,Random::DEFAULT,withnumber.Thepreviousseedvalueisreturned.

Ifnumberisomitted,seedsthegeneratorusingasourceofentropyprovidedbytheoperatingsystem,ifavailable(/dev/urandomonUnixsystemsortheRSAcryptographicprovideronWindows),whichisthencombinedwiththetime,theprocessid,andasequencenumber.

srandmaybeusedtoensurerepeatablesequencesofpseudo-randomnumbersbetweendifferentrunsoftheprogram.Bysettingtheseedtoaknownvalue,programscanbemadedeterministicduringtesting.

srand1234#=>268519324636777531569100071560086917274

[rand,rand]#=>[0.1915194503788923,0.6221087710398319]

[rand(10),rand(1000)]#=>[4,664]

srand1234#=>1234

[rand,rand]#=>[0.1915194503788923,0.6221087710398319]

Returnstrueifthetwogeneratorshavethesameinternalstate,otherwisefalse.Equivalentgeneratorswillreturnthesamesequenceofpseudo-randomnumbers.Twogeneratorswillgenerallyhavethesamestateonlyiftheywereinitializedwiththesame

rand(max)→number

srand(number=Random.new_seed)→old_seed

prng1==prng2→trueorfalse

Random.new==Random.new#=>false

Random.new(1234)==Random.new(1234)#=>true

andhavethesameinvocationhistory.

prng1=Random.new(1234)

prng1==prng2#=>true

prng1.rand#=>0.1915194503788923

prng1==prng2#=>false

prng2.rand#=>0.1915194503788923

prng1==prng2#=>true

Returnsarandombinarystringcontainingsizebytes.

random_string=Random.new.bytes(10)#=>"\xD7:R\xAB?\x83\xCE\xFAkO"

random_string.size#=>10

WhenmaxisanInteger,randreturnsarandomintegergreaterthanorequaltozeroandlessthanmax.UnlikeKernel#rand,whenmaxisanegativeintegerorzero,randraisesanArgumentError.

prng=Random.new

prng.rand(100)#=>42

WhenmaxisaFloat,randreturnsarandomfloatingpointnumberbetween0.0andmax,including0.0andexcludingmax.

prng.rand(1.5)#=>1.4600282860034115

bytes(size)→a_string

rand→floatrand(max)→number

WhenmaxisaRange,randreturnsarandomnumberwhererange.member?(number)==true.

prng.rand(5..9)#=>oneof[5,6,7,8,9]

prng.rand(5...9)#=>oneof[5,6,7,8]

prng.rand(5.0..9.0)#=>between5.0and9.0,including9.0

prng.rand(5.0...9.0)#=>between5.0and9.0,excluding9.0

Boththebeginningandendingvaluesoftherangemustrespondtosubtract(-)andadd(+)methods,orrandwillraiseanArgumentError.

Returnstheseedvalueusedtoinitializethegenerator.Thismaybeusedtoinitializeanothergeneratorwiththesamestateatalatertime,causingittoproducethesamesequenceofnumbers.

prng1.seed#=>1234

prng1.rand(100)#=>47

prng2=Random.new(prng1.seed)

prng2.rand(100)#=>47

seed→integer

classRangeARangerepresentsaninterval—asetofvalueswithabeginningandanend.Rangesmaybeconstructedusingthes..eands...eliterals,orwith::new.Rangesconstructedusing..runfromthebeginningtotheendinclusively.Thosecreatedusing...excludetheendvalue.Whenusedasaniterator,rangesreturneachvalueinthesequence.

(-1..-5).to_a#=>[]

(-5..-1).to_a#=>[-5,-4,-3,-2,-1]

('a'..'e').to_a#=>["a","b","c","d","e"]

('a'...'e').to_a#=>["a","b","c","d"]

CustomObjectsinRanges

Rangescanbeconstructedusinganyobjectsthatcanbecomparedusingthe<=>operator.Methodsthattreattherangeasasequence(eachandmethodsinheritedfromEnumerable)expectthebeginobjecttoimplementasuccmethodtoreturnthenextobjectinsequence.Thestepandinclude?methodsrequirethebeginobjecttoimplementsuccortobenumeric.

IntheXsclassbelowboth<=>andsuccareimplementedsoXscanbeusedtoconstructranges.NotethattheComparablemoduleisincludedsothe==methodisdefinedintermsof<=>.

classXs#representastringof'x's

includeComparable

attr:length

definitialize(n)

@length=n

defsucc

Xs.new(@length+1)

def<=>(other)

@length<=>other.length

defto_s

sprintf"%2d#{inspect}",@length

definspect

'x'*@length

AnexampleofusingXstoconstructarange:

r=Xs.new(3)..Xs.new(6)#=>xxx..xxxxxx

r.to_a#=>[xxx,xxxx,xxxxx,xxxxxx]

r.member?(Xs.new(5))#=>true

InFilesrange.c

ParentObject

PublicClassMethods

Constructsarangeusingthegivenbeginandend.Iftheexclude_endparameterisomittedorisfalse,therngwillincludetheendobject;otherwise,itwillbeexcluded.

new(begin,end,exclude_end=false)→rng

ReturnstrueonlyifobjisaRange,hasequivalentbeginandenditems(bycomparingthemwith==),andhasthesameexclude_end?settingastherange.

(0..2)==(0..2)#=>true

(0..2)==Range.new(0,2)#=>true

(0..2)==(0...2)#=>false

Returnstrueifobjisanelementoftherange,falseotherwise.Conveniently,===isthecomparisonoperatorusedbycasestatements.

case79

when1..50thenprint"low\n"

when51..75thenprint"medium\n"

when76..100thenprint"high\n"

produces:

Returnstheobjectthatdefinesthebeginningoftherange.

(1..10).begin#=>1

Byusingbinarysearch,findsavalueinrangewhichmeetsthegivenconditioninO(logn)wherenisthesizeoftherange.

rng==obj→trueorfalse

rng===obj→trueorfalse

begin→obj

bsearch{|obj|block}→value

Youcanusethismethodintwousecases:afind-minimummodeandafind-anymode.Ineithercase,theelementsoftherangemustbemonotone(orsorted)withrespecttotheblock.

Infind-minimummode(thisisagoodchoicefortypicalusecase),theblockmustreturntrueorfalse,andtheremustbeavaluexsothat:

theblockreturnsfalseforanyvaluewhichislessthanx,and

theblockreturnstrueforanyvaluewhichisgreaterthanorequaltox.

Ifxiswithintherange,thismethodreturnsthevaluex.Otherwise,itreturnsnil.

ary=[0,4,7,10,12]

(0...ary.size).bsearch{|i|ary[i]>=4}#=>1

(0...ary.size).bsearch{|i|ary[i]>=100}#=>nil

(0.0...Float::INFINITY).bsearch{|x|Math.log(x)>=0}

Infind-anymode(thisbehaveslikelibc'sbsearch(3)),theblockmustreturnanumber,andtheremustbetwovaluesxandy(x<=y)sothat:

theblockreturnsapositivenumberforvifv<x,

theblockreturnszeroforvifx<=v<y,and

theblockreturnsanegativenumberforvify<=v.

Thismethodreturnsanyvaluewhichiswithintheintersectionofthegivenrangeandx…y(ifany).Ifthereisnovaluethatsatisfiesthecondition,itreturnsnil.

ary=[0,100,100,100,200]

(0..4).bsearch{|i|100-ary[i]}#=>1,2or3

(0..4).bsearch{|i|300-ary[i]}#=>nil

(0..4).bsearch{|i|50-ary[i]}#=>nil

Youmustnotmixthetwomodesatatime;theblockmustalwaysreturneithertrue/false,oralwaysreturnanumber.Itisundefinedwhichvalueisactuallypickedupateachiteration.

Returnstrueifobjisbetweenthebeginandendoftherange.

Thistestsbegin<=obj<=endwhenexclude_end?isfalseandbegin<=obj<endwhenexclude_end?istrue.

("a".."z").cover?("c")#=>true

("a".."z").cover?("5")#=>false

("a".."z").cover?("cc")#=>true

Iteratesovertheelementsofrange,passingeachinturntotheblock.

Theeachmethodcanonlybeusedifthebeginobjectoftherangesupportsthesuccmethod.ATypeErrorisraisediftheobjectdoesnothavesuccmethoddefined(likeFloat).

(10..15).each{|n|printn,''}

#prints:101112131415

cover?(obj)→trueorfalse

each{|i|block}→rngeach→an_enumerator

(2.5..5).each{|n|printn,''}

#raises:TypeError:can'titeratefromFloat

Returnstheobjectthatdefinestheendoftherange.

(1..10).end#=>10

(1...10).end#=>10

ReturnstrueonlyifobjisaRange,hasequivalentbeginandenditems(bycomparingthemwitheql?),andhasthesameexclude_end?settingastherange.

(0..2).eql?(0..2)#=>true

(0..2).eql?(Range.new(0,2))#=>true

(0..2).eql?(0...2)#=>false

Returnstrueiftherangeexcludesitsendvalue.

(1..5).exclude_end?#=>false

(1...5).exclude_end?#=>true

Returnsthefirstobjectintherange,oranarrayofthefirstnelements.

(10..20).first#=>10

(10..20).first(3)#=>[10,11,12]

end→obj

exclude_end?→trueorfalse

first→objfirst(n)→an_array

Computeahash-codeforthisrange.Tworangeswithequalbeginandendpoints(usingeql?),andthesameexclude_end?valuewillgeneratethesamehash-code.

SeealsoObject#hash.

Returnstrueifobjisanelementoftherange,falseotherwise.Ifbeginandendarenumeric,comparisonisdoneaccordingtothemagnitudeofthevalues.

("a".."z").include?("g")#=>true

("a".."z").include?("A")#=>false

("a".."z").include?("cc")#=>false

Convertthisrangeobjecttoaprintableform(usinginspecttoconvertthebeginandendobjects).

Returnsthelastobjectintherange,oranarrayofthelastnelements.

Notethatwithnoargumentslastwillreturntheobjectthatdefinestheendoftherangeevenifexclude_end?istrue.

(10..20).last#=>20

(10...20).last#=>20

(10..20).last(3)#=>[18,19,20]

(10...20).last(3)#=>[17,18,19]

hash→fixnum

member?(obj)→trueorfalseinclude?(obj)→trueorfalse

inspect→string

last→objlast(n)→an_array

Returnsthemaximumvalueintherange.Returnsnilifthebeginvalueoftherangelargerthantheendvalue.

Canbegivenanoptionalblocktooverridethedefaultcomparisonmethoda<=>b.

(10..20).max#=>20

Returnstrueifobjisanelementoftherange,falseotherwise.Ifbeginandendarenumeric,comparisonisdoneaccordingtothemagnitudeofthevalues.

("a".."z").include?("g")#=>true

("a".."z").include?("A")#=>false

("a".."z").include?("cc")#=>false

Returnstheminimumvalueintherange.Returnsnilifthebeginvalueoftherangeislargerthantheendvalue.

Canbegivenanoptionalblocktooverridethedefaultcomparisonmethoda<=>b.

max→objmax{|a,b|block}→objmax(n)→objmax(n){|a,b|block}→obj

member?(obj)→trueorfalseinclude?(obj)→trueorfalse

min→objmin{|a,b|block}→objmin(n)→arraymin(n){|a,b|block}→array

(10..20).min#=>10

Returnsthenumberofelementsintherange.BoththebeginandtheendoftheRangemustbeNumeric,otherwisenilisreturned.

(10..20).size#=>11

('a'..'z').size#=>nil

(-Float::INFINITY..Float::INFINITY).size#=>Infinity

Iteratesovertherange,passingeachnthelementtotheblock.Ifbeginandendarenumeric,nisaddedforeachiteration.Otherwisestepinvokessucctoiteratethroughrangeelements.

range=Xs.new(1)..Xs.new(10)

range.step(2){|x|putsx}

range.step(3){|x|putsx}

produces:

5xxxxx

7xxxxxxx

9xxxxxxxxx

7xxxxxxx

10xxxxxxxxxx

size→num

step(n=1){|obj|block}→rngstep(n=1)→an_enumerator

SeeRangeforthedefinitionofclassXs.

Convertthisrangeobjecttoaprintableform(usingto_stoconvertthebeginandendobjects).

to_s→string

classRangeErrorRaisedwhenagivennumericalvalueisoutofrange.

[1,2,3].drop(1<<100)

raisestheexception:

RangeError:bignumtoobigtoconvertinto`long'

InFileserror.c

ParentStandardError

classRationalArationalnumbercanberepresentedasapairedintegernumber;a/b(b>0).Whereaisnumeratorandbisdenominator.Integeraequalsrationala/1mathematically.

Inruby,youcancreaterationalobjectwithRational,#to_r,rationalizemethodorsuffixingrtoaliteral.Thereturnvalueswillbeirreducible.

Rational(1)#=>(1/1)

Rational(2,3)#=>(2/3)

Rational(4,-6)#=>(-2/3)

3.to_r#=>(3/1)

2/3r#=>(2/3)

Youcanalsocreaterationalobjectfromfloating-pointnumbersorstrings.

Rational(0.3)#=>(5404319552844595/18014398509481984)

Rational('0.3')#=>(3/10)

Rational('2/3')#=>(2/3)

0.3.to_r#=>(5404319552844595/18014398509481984)

'0.3'.to_r#=>(3/10)

'2/3'.to_r#=>(2/3)

0.3.rationalize#=>(3/10)

Arationalobjectisanexactnumber,whichhelpsyoutowriteprogramwithoutanyroundingerrors.

10.times.inject(0){|t,|t+0.1}#=>0.9999999999999999

10.times.inject(0){|t,|t+Rational('0.1')}#=>(1/1)

However,whenanexpressionhasinexactfactor(numericalvalueoroperation),willproduceaninexactresult.

Rational(10)/3#=>(10/3)

Rational(10)/3.0#=>3.3333333333333335

Rational(-8)**Rational(1,3)

#=>(1.0000000000000002+1.7320508075688772i)

InFilesrational.c

ParentNumeric

Performsmultiplication.

Rational(2,3)*Rational(2,3)#=>(4/9)

Rational(900)*Rational(1)#=>(900/1)

Rational(-2,9)*Rational(-9,2)#=>(1/1)

Rational(9,8)*4#=>(9/2)

Rational(20,9)*9.8#=>21.77777777777778

rat*numeric→numeric

Performsexponentiation.

Rational(2)**Rational(3)#=>(8/1)

Rational(10)**-2#=>(1/100)

Rational(10)**-2.0#=>0.01

Rational(-4)**Rational(1,2)#=>(1.2246063538223773e-16+2.0i)

Rational(1,2)**0#=>(1/1)

Rational(1,2)**0.0#=>1.0

Performsaddition.

Rational(2,3)+Rational(2,3)#=>(4/3)

Rational(900)+Rational(1)#=>(900/1)

Rational(-2,9)+Rational(-9,2)#=>(-85/18)

Rational(9,8)+4#=>(41/8)

Rational(20,9)+9.8#=>12.022222222222222

Performssubtraction.

Rational(2,3)-Rational(2,3)#=>(0/1)

Rational(900)-Rational(1)#=>(899/1)

Rational(-2,9)-Rational(-9,2)#=>(77/18)

Rational(9,8)-4#=>(23/8)

Rational(20,9)-9.8#=>-7.577777777777778

Performsdivision.

Rational(2,3)/Rational(2,3)#=>(1/1)

Rational(900)/Rational(1)#=>(900/1)

Rational(-2,9)/Rational(-9,2)#=>(4/81)

Rational(9,8)/4#=>(9/32)

rat**numeric→numeric

rat+numeric→numeric

rat-numeric→numeric

rat/numeric→numericquo(numeric)→numeric

Rational(20,9)/9.8#=>0.22675736961451246

Performscomparisonandreturns-1,0,or+1.

Rational(2,3)<=>Rational(2,3)#=>0

Rational(5)<=>5#=>0

Rational(2,3)<=>Rational(1,3)#=>1

Rational(1,3)<=>1#=>-1

Rational(1,3)<=>0.3#=>1

Returnstrueifratequalsobjectnumerically.

Rational(2,3)==Rational(2,3)#=>true

Rational(5)==5#=>true

Rational(0)==0.0#=>true

Rational('1/3')==0.33#=>false

Rational('1/2')=='1/2'#=>false

Returnsthetruncatedvalue(towardpositiveinfinity).

Rational(3).ceil#=>3

Rational(2,3).ceil#=>1

Rational(-3,2).ceil#=>-1

decimal-123.456

^^^^^^

precision-3-2-10+1+2

'%f'%Rational('-123.456').ceil(+1)#=>"-123.400000"

'%f'%Rational('-123.456').ceil(-1)#=>"-120.000000"

rational<=>numeric→-1,0,+1ornil

rat==object→trueorfalse

ceil→integerceil(precision=0)→rational

Returnsthedenominator(alwayspositive).

Rational(7).denominator#=>1

Rational(7,1).denominator#=>1

Rational(9,-4).denominator#=>4

Rational(-2,-10).denominator#=>5

rat.numerator.gcd(rat.denominator)#=>1

Performsdivisionandreturnsthevalueasafloat.

Rational(2,3).fdiv(1)#=>0.6666666666666666

Rational(2,3).fdiv(0.5)#=>1.3333333333333333

Rational(2).fdiv(3)#=>0.6666666666666666

Returnsthetruncatedvalue(towardnegativeinfinity).

Rational(3).floor#=>3

Rational(2,3).floor#=>0

Rational(-3,2).floor#=>-1

decimal-123.456

^^^^^^

'%f'%Rational('-123.456').floor(+1)#=>"-123.500000"

'%f'%Rational('-123.456').floor(-1)#=>"-130.000000"

Returnsthevalueasastringforinspection.

Rational(2).inspect#=>"(2/1)"

Rational(-8,6).inspect#=>"(-4/3)"

Rational('1/2').inspect#=>"(1/2)"

floor→integerfloor(precision=0)→rational

inspect→string

Rational(7).numerator#=>7

Rational(7,1).numerator#=>7

Rational(9,-4).numerator#=>-9

Rational(-2,-10).numerator#=>1

Performsdivision.

Rational(2,3)/Rational(2,3)#=>(1/1)

Rational(900)/Rational(1)#=>(900/1)

Rational(-2,9)/Rational(-9,2)#=>(4/81)

Rational(9,8)/4#=>(9/32)

Rational(20,9)/9.8#=>0.22675736961451246

Returnsasimplerapproximationofthevalueiftheoptionalargumentepsisgiven(rat-|eps|<=result<=rat+|eps|),selfotherwise.

r=Rational(5033165,16777216)

r.rationalize#=>(5033165/16777216)

r.rationalize(Rational('0.01'))#=>(3/10)

r.rationalize(Rational('0.1'))#=>(1/3)

Returnsthetruncatedvalue(towardthenearestinteger;0.5=>1;-0.5=>-1).

numerator→integer

rat/numeric→numericquo(numeric)→numeric

rationalize→selfrationalize(eps)→rational

round→integerround(precision=0)→rational

Rational(3).round#=>3

Rational(2,3).round#=>1

Rational(-3,2).round#=>-2

decimal-123.456

^^^^^^

'%f'%Rational('-123.456').round(+1)#=>"-123.500000"

'%f'%Rational('-123.456').round(-1)#=>"-120.000000"

Returnthevalueasafloat.

Rational(2).to_f#=>2.0

Rational(9,4).to_f#=>2.25

Rational(-3,4).to_f#=>-0.75

Rational(20,3).to_f#=>6.666666666666667

Returnsthetruncatedvalueasaninteger.

Equivalentto

rat.truncate.

Rational(2,3).to_i#=>0

Rational(3).to_i#=>3

Rational(300.6).to_i#=>300

Rational(98,71).to_i#=>1

Rational(-30,2).to_i#=>-15

Returnsself.

Rational(2).to_r#=>(2/1)

Rational(-8,6).to_r#=>(-4/3)

to_f→float

to_i→integer

to_r→self

Returnsthevalueasastring.

Rational(2).to_s#=>"2/1"

Rational(-8,6).to_s#=>"-4/3"

Rational('1/2').to_s#=>"1/2"

Returnsthetruncatedvalue(towardzero).

Rational(3).truncate#=>3

Rational(2,3).truncate#=>0

Rational(-3,2).truncate#=>-1

decimal-123.456

^^^^^^

'%f'%Rational('-123.456').truncate(+1)#=>"-123.400000"

'%f'%Rational('-123.456').truncate(-1)#=>"-120.000000"

to_s→string

truncate→integertruncate(precision=0)→rational

classRational::compatible

InFilesrational.c

ParentObject

classRegexpARegexpholdsaregularexpression,usedtomatchapatternagainststrings.Regexpsarecreatedusingthe/.../and%r{...}literals,andbytheRegexp::newconstructor.

Regularexpressions(regexps)arepatternswhichdescribethecontentsofastring.They'reusedfortestingwhetherastringcontainsagivenpattern,orextractingtheportionsthatmatch.Theyarecreatedwiththe/pat/and%r{pat}literalsortheRegexp.newconstructor.

Aregexpisusuallydelimitedwithforwardslashes(/).Forexample:

/hay/=~'haystack'#=>0

/y/.match('haystack')#=>#<MatchData"y">

Ifastringcontainsthepatternitissaidtomatch.Aliteralstringmatchesitself.

Here'haystack'doesnotcontainthepattern'needle',soitdoesn'tmatch:

/needle/.match('haystack')#=>nil

Here'haystack'containsthepattern'hay',soitmatches:

/hay/.match('haystack')#=>#<MatchData"hay">

Specifically,/st/requiresthatthestringcontainsthelettersfollowedbythelettert,soitmatcheshaystack,also.

=~and#match

Patternmatchingmaybeachievedbyusing=~operatoror#matchmethod.

=~operator

=~isRuby'sbasicpattern-matchingoperator.Whenoneoperandisaregularexpressionandtheotherisastringthentheregularexpressionisusedasapatterntomatchagainstthestring.(ThisoperatorisequivalentlydefinedbyRegexpandStringsotheorderofStringandRegexpdonotmatter.Otherclassesmayhavedifferentimplementationsof=~.)Ifamatchisfound,theoperatorreturnsindexoffirstmatchinstring,otherwiseitreturnsnil.

/hay/=~'haystack'#=>0

'haystack'=~/hay/#=>0

/a/=~'haystack'#=>1

/u/=~'haystack'#=>nil

Using=~operatorwithaStringandRegexpthe$~globalvariableissetafterasuccessfulmatch.$~holdsaMatchDataobject.::last_matchisequivalentto$~.

#matchmethod

ThematchmethodreturnsaMatchDataobject:

/st/.match('haystack')#=>#<MatchData"st">

MetacharactersandEscapes

Thefollowingaremetacharacters(,),[,],{,},.,?,+,*.Theyhaveaspecificmeaningwhenappearinginapattern.Tomatchthemliterallytheymustbebackslash-escaped.Tomatchabackslashliterallybackslash-escapethat:<tt>\\</tt>.

/1\+2=3\?/.match('Does1+2=3?')#=>#<MatchData"1+2=3?">

Patternsbehavelikedouble-quotedstringssocancontainthesamebackslashescapes.

/\s\u{67714eac90fd}/.match("Goto東京都")#=>#<MatchData"東京都">

ArbitraryRubyexpressionscanbeembeddedintopatternswiththe#{...}construct.

place="東京都"/#{place}/.match("Goto東京都")#=>#<MatchData"東京都">

CharacterClasses

Acharacterclassisdelimitedwithsquarebrackets([,])andlistscharactersthatmayappearatthatpointinthematch./[ab]/meansaorb,asopposedto/ab/whichmeansafollowedbyb.

/W[aeiou]rd/.match("Word")#=>#<MatchData"Word">

Withinacharacterclassthehyphen(-)isametacharacterdenotinganinclusiverangeofcharacters.[abcd]isequivalentto[a-d].Arangecanbefollowedbyanotherrange,so[abcdwxyz]isequivalentto[a-dw-z].Theorderinwhichrangesorindividualcharactersappearinsideacharacterclassisirrelevant.

/[0-9a-f]/.match('9f')#=>#<MatchData"9">

/[9f]/.match('9f')#=>#<MatchData"9">

Ifthefirstcharacterofacharacterclassisacaret(^)theclassisinverted:itmatchesanycharacterexceptthosenamed.

/[^a-eg-z]/.match('f')#=>#<MatchData"f">

Acharacterclassmaycontainanothercharacterclass.Byitselfthisisn'tusefulbecause[a-z[0-9]]describesthesamesetas[a-z0-9].

However,characterclassesalsosupportthe&&operatorwhichperformssetintersectiononitsarguments.Thetwocanbecombinedasfollows:

/[a-w&&[^c-g]z]/#([a-w]AND([^c-g]ORz))

Thisisequivalentto:

/[abh-w]/

Thefollowingmetacharactersalsobehavelikecharacterclasses:

/./-Anycharacterexceptanewline././m-Anycharacter(themmodifierenablesmultilinemode)/\w/-Awordcharacter([a-zA-Z0-9_])/\W/-Anon-wordcharacter([^a-zA-Z0-9_]).PleasetakealookatBug#4044ifusing/\W/withthe/imodifier./\d/-Adigitcharacter([0-9])/\D/-Anon-digitcharacter([^0-9])/\h/-Ahexdigitcharacter([0-9a-fA-F])/\H/-Anon-hexdigitcharacter([^0-9a-fA-F])/\s/-Awhitespacecharacter:/[\t\r\n\f]//\S/-Anon-whitespacecharacter:/[^\t\r\n\f]/

POSIXbracketexpressionsarealsosimilartocharacterclasses.Theyprovideaportablealternativetotheabove,withtheaddedbenefitthattheyencompassnon-ASCIIcharacters.Forinstance,/\d/matchesonlytheASCIIdecimaldigits(0-9);whereas/[[:digit:]]/matchesanycharacterintheUnicodeNdcategory.

/[[:alnum:]]/-Alphabeticandnumericcharacter/[[:alpha:]]/-Alphabeticcharacter/[[:blank:]]/-Spaceortab/[[:cntrl:]]/-Controlcharacter/[[:digit:]]/-Digit/[[:graph:]]/-Non-blankcharacter(excludesspaces,controlcharacters,andsimilar)/[[:lower:]]/-Lowercasealphabeticalcharacter/[[:print:]]/-Like[:graph:],butincludesthespacecharacter/[[:punct:]]/-Punctuationcharacter/[[:space:]]/-Whitespacecharacter([:blank:],newline,carriagereturn,etc.)/[[:upper:]]/-Uppercasealphabetical/[[:xdigit:]]/-Digitallowedinahexadecimalnumber(i.e.,0-9a-fA-F)

Rubyalsosupportsthefollowingnon-POSIXcharacterclasses:

/[[:word:]]/-AcharacterinoneofthefollowingUnicodegeneralcategoriesLetter,Mark,Number,Connector_Punctuation/[[:ascii:]]/-AcharacterintheASCIIcharacterset

#U+06F2is"EXTENDEDARABIC-INDICDIGITTWO"

/[[:digit:]]/.match("\u06F2")#=>#<MatchData"\u{06F2}">

/[[:upper:]][[:lower:]]/.match("Hello")#=>#<MatchData"He">

/[[:xdigit:]][[:xdigit:]]/.match("A6")#=>#<MatchData"A6">

Repetition

Theconstructsdescribedsofarmatchasinglecharacter.Theycanbefollowedbyarepetitionmetacharactertospecifyhowmanytimestheyneedtooccur.Suchmetacharactersarecalledquantifiers.

*-Zeroormoretimes+-Oneormoretimes?-Zerooronetimes(optional){n}-Exactlyntimes{n,}-normoretimes{,m}-morlesstimes{n,m}-Atleastnandatmostmtimes

Atleastoneuppercasecharacter('H'),atleastonelowercasecharacter('e'),two'l'characters,thenone'o':

"Hello".match(/[[:upper:]]+[[:lower:]]+l{2}o/)#=>#<MatchData"Hello">

Repetitionisgreedybydefault:asmanyoccurrencesaspossiblearematchedwhilestillallowingtheoverallmatchtosucceed.Bycontrast,lazymatchingmakestheminimalamountofmatchesnecessaryforoverallsuccess.Agreedymetacharactercanbemadelazybyfollowingitwith?.

Bothpatternsbelowmatchthestring.Thefirstusesagreedyquantifierso'.+'matches'<a><b>';thesecondusesalazyquantifierso'.+?'matches'<a>':

/<.+>/.match("<a><b>")#=>#<MatchData"<a><b>">

/<.+?>/.match("<a><b>")#=>#<MatchData"<a>">

Aquantifierfollowedby+matchespossessively:onceithasmatcheditdoesnotbacktrack.Theybehavelikegreedyquantifiers,buthavingmatchedtheyrefuseto“giveup”theirmatchevenifthisjeopardisestheoverallmatch.

Capturing

Parenthesescanbeusedforcapturing.Thetextenclosedbythen<sup>th</sup>groupofparenthesescanbesubsequentlyreferredtowithn.Withinapatternusethebackreference\n;outsideofthepatternuseMatchData[n].

'at'iscapturedbythefirstgroupofparentheses,thenreferredtolaterwith\1:

/[csh](..)[csh]\1in/.match("Thecatsatinthehat"

#=>#<MatchData"catsatin"1:"at">

#matchreturnsaMatchDataobjectwhichmakesthecapturedtextavailablewithits#[]method:

/[csh](..)[csh]\1in/.match("Thecatsatinthehat"

Capturegroupscanbereferredtobynamewhendefinedwiththe(?<name>)or(?'name')constructs.

/\$(?<dollars>\d+)\.(?<cents>\d+)/.match("$3.67")

=>#<MatchData"$3.67"dollars:"3"cents:"67">

/\$(?<dollars>\d+)\.(?<cents>\d+)/.match("$3.67")[:

Namedgroupscanbebackreferencedwith\k<name>,wherenameisthegroupname.

/(?<vowel>[aeiou]).\k<vowel>.\k<vowel>/.match('ototomy'

#=>#<MatchData"ototo"vowel:"o">

Note:Aregexpcan'tusenamedbackreferencesandnumberedbackreferencessimultaneously.

Whennamedcapturegroupsareusedwithaliteralregexpontheleft-handsideofanexpressionandthe=~operator,thecapturedtextisalsoassignedtolocalvariableswithcorrespondingnames.

/\$(?<dollars>\d+)\.(?<cents>\d+)/=~"$3.67"#=>0

dollars#=>"3"

Grouping

Parenthesesalsogroupthetermstheyenclose,allowingthemtobequantifiedasoneatomicwhole.

Thepatternbelowmatchesavowelfollowedby2wordcharacters:

/[aeiou]\w{2}/.match("Caenorhabditiselegans")#=>#<MatchData"aen">

Whereasthefollowingpatternmatchesavowelfollowedbyawordcharacter,twice,i.e.[aeiou]\w[aeiou]\w:'enor'.

/([aeiou]\w){2}/.match("Caenorhabditiselegans")

#=>#<MatchData"enor"1:"or">

The(?:…)constructprovidesgroupingwithoutcapturing.Thatis,itcombinesthetermsitcontainsintoanatomicwholewithoutcreatingabackreference.Thisbenefitsperformanceattheslightexpenseofreadability.

Thefirstgroupofparenthesescaptures'n'andthesecond'ti'.Thesecondgroupisreferredtolaterwiththebackreference\2:

/I(n)ves(ti)ga\2ons/.match("Investigations")

#=>#<MatchData"Investigations"1:"n"2:"ti">

Thefirstgroupofparenthesesisnowmadenon-capturingwith'?:',soitstillmatches'n',butdoesn'tcreatethebackreference.Thus,thebackreference\1nowrefersto'ti'.

/I(?:n)ves(ti)ga\1ons/.match("Investigations")

#=>#<MatchData"Investigations"1:"ti">

AtomicGrouping

Groupingcanbemadeatomicwith(?>pat).Thiscausesthesubexpressionpattobematchedindependentlyoftherestoftheexpressionsuchthatwhatitmatchesbecomesfixedfortheremainderofthematch,unlesstheentiresubexpressionmustbeabandonedandsubsequentlyrevisited.Inthiswaypatistreatedasanon-divisiblewhole.Atomicgroupingistypicallyusedtooptimisepatternssoastopreventtheregularexpressionenginefrombacktrackingneedlessly.

The"inthepatternbelowmatchesthefirstcharacterofthestring,then.*matchesQuote“.Thiscausestheoverallmatchtofail,sothetextmatchedby.*isbacktrackedbyoneposition,whichleavesthefinalcharacterofthestringavailabletomatch"

/".*"/.match('"Quote"')#=>#<MatchData"\"Quote\"">

If.*isgroupedatomically,itrefusestobacktrackQuote“,eventhoughthismeansthattheoverallmatchfails

/"(?>.*)"/.match('"Quote"')#=>nil

SubexpressionCalls

The\g<name>syntaxmatchestheprevioussubexpressionnamedname,whichcanbeagroupnameornumber,again.Thisdiffersfrombackreferencesinthatitre-executesthegroupratherthansimplytryingtore-matchthesametext.

Thispatternmatchesa(characterandassignsittotheparengroup,triestocallthattheparensub-expressionagainbutfails,thenmatchesaliteral):

/\A(?<paren>$\g<paren>*$)*\z/=~'()'

/\A(?<paren>$\g<paren>*$)*\z/=~'(())'#=>0

1. Matchesatthebeginningofthestring,i.e.beforethefirstcharacter.

2. Entersanamedcapturegroupcalledparen3. Matchesaliteral(,thefirstcharacterinthe

string

4. Callstheparengroupagain,i.e.recursesbacktothesecondstep

5. Re-enterstheparengroup6. Matchesaliteral(,thesecondcharacterinthe

string7. Trytocallparenathirdtime,butfailbecause

doingsowouldpreventanoverallsuccessfulmatch

8. Matchaliteral),thethirdcharacterinthestring.Markstheendofthesecondrecursivecall

9. Matchaliteral),thefourthcharacterinthestring

10. Matchtheendofthestring

Alternation

Theverticalbarmetacharacter(|)combinestwoexpressionsintoasingleonethatmatcheseitheroftheexpressions.Eachexpressionisanalternative.

/\w(and|or)\w/.match("Feliformia")#=>#<MatchData"form"1:"or">

/\w(and|or)\w/.match("furandi")#=>#<MatchData"randi"1:"and">

/\w(and|or)\w/.match("dissemblance")#=>nil

CharacterProperties

The\p{}constructmatchescharacterswiththenamedproperty,muchlikePOSIXbracketclasses.

/\p{Alnum}/-Alphabeticandnumericcharacter/\p{Alpha}/-Alphabeticcharacter/\p{Blank}/-Spaceortab/\p{Cntrl}/-Controlcharacter/\p{Digit}/-Digit/\p{Graph}/-Non-blankcharacter(excludesspaces,controlcharacters,andsimilar)/\p{Lower}/-Lowercasealphabeticalcharacter/\p{Print}/-Like\p{Graph},butincludesthespacecharacter/\p{Punct}/-Punctuationcharacter/\p{Space}/-Whitespacecharacter([:blank:],newline,carriagereturn,etc.)/\p{Upper}/-Uppercasealphabetical/\p{XDigit}/-Digitallowedinahexadecimalnumber(i.e.,0-9a-fA-F)/\p{Word}/-AmemberofoneofthefollowingUnicodegeneralcategoryLetter,Mark,Number,Connector_Punctuation

/\p{ASCII}/-AcharacterintheASCIIcharacterset/\p{Any}/-AnyUnicodecharacter(includingunassignedcharacters)/\p{Assigned}/-Anassignedcharacter

AUnicodecharacter'sGeneralCategoryvaluecanalsobematchedwith\p{Ab}whereAbisthecategory'sabbreviationasdescribedbelow:

/\p{L}/-'Letter'/\p{Ll}/-'Letter:Lowercase'/\p{Lm}/-'Letter:Mark'/\p{Lo}/-'Letter:Other'/\p{Lt}/-'Letter:Titlecase'/\p{Lu}/-'Letter:Uppercase/\p{Lo}/-'Letter:Other'/\p{M}/-'Mark'/\p{Mn}/-'Mark:Nonspacing'/\p{Mc}/-'Mark:SpacingCombining'/\p{Me}/-'Mark:Enclosing'/\p{N}/-'Number'/\p{Nd}/-'Number:DecimalDigit'/\p{Nl}/-'Number:Letter'/\p{No}/-'Number:Other'/\p{P}/-'Punctuation'/\p{Pc}/-'Punctuation:Connector'

/\p{Pd}/-'Punctuation:Dash'/\p{Ps}/-'Punctuation:Open'/\p{Pe}/-'Punctuation:Close'/\p{Pi}/-'Punctuation:InitialQuote'/\p{Pf}/-'Punctuation:FinalQuote'/\p{Po}/-'Punctuation:Other'/\p{S}/-'Symbol'/\p{Sm}/-'Symbol:Math'/\p{Sc}/-'Symbol:Currency'/\p{Sc}/-'Symbol:Currency'/\p{Sk}/-'Symbol:Modifier'/\p{So}/-'Symbol:Other'/\p{Z}/-'Separator'/\p{Zs}/-'Separator:Space'/\p{Zl}/-'Separator:Line'/\p{Zp}/-'Separator:Paragraph'/\p{C}/-'Other'/\p{Cc}/-'Other:Control'/\p{Cf}/-'Other:Format'/\p{Cn}/-'Other:NotAssigned'/\p{Co}/-'Other:PrivateUse'/\p{Cs}/-'Other:Surrogate'

Lastly,\p{}matchesacharacter'sUnicodescript.Thefollowingscriptsaresupported:Arabic,Armenian,Balinese,Bengali,Bopomofo,Braille,Buginese,Buhid,Canadian_Aboriginal,

Carian,Cham,Cherokee,Common,Coptic,Cuneiform,Cypriot,Cyrillic,Deseret,Devanagari,Ethiopic,Georgian,Glagolitic,Gothic,Greek,Gujarati,Gurmukhi,Han,Hangul,Hanunoo,Hebrew,Hiragana,Inherited,Kannada,Katakana,Kayah_Li,Kharoshthi,Khmer,Lao,Latin,Lepcha,Limbu,Linear_B,Lycian,Lydian,Malayalam,Mongolian,Myanmar,New_Tai_Lue,Nko,Ogham,Ol_Chiki,Old_Italic,Old_Persian,Oriya,Osmanya,Phags_Pa,Phoenician,Rejang,Runic,Saurashtra,Shavian,Sinhala,Sundanese,Syloti_Nagri,Syriac,Tagalog,Tagbanwa,Tai_Le,Tamil,Telugu,Thaana,Thai,Tibetan,Tifinagh,Ugaritic,Vai,andYi.

UnicodecodepointU+06E9isnamed“ARABICPLACEOFSAJDAH”andbelongstotheArabicscript:

/\p{Arabic}/.match("\u06E9")#=>#<MatchData"\u06E9">

Allcharacterpropertiescanbeinvertedbyprefixingtheirnamewithacaret(^).

Letter'A'isnotintheUnicodeLl(Letter;Lowercase)category,sothismatchsucceeds:

/\p{^Ll}/.match("A")#=>#<MatchData"A">

Anchors

Anchorsaremetacharacterthatmatchthezero-widthpositionsbetweencharacters,anchoringthematchtoaspecificposition.

^-Matchesbeginningofline$-Matchesendofline\A-Matchesbeginningofstring.\Z-Matchesendofstring.Ifstringendswithanewline,itmatchesjustbeforenewline\z-Matchesendofstring\G-Matchespointwherelastmatchfinished\b-Matcheswordboundarieswhenoutsidebrackets;backspace(0x08)wheninsidebrackets\B-Matchesnon-wordboundaries(?=pat)-Positivelookaheadassertion:ensuresthatthefollowingcharactersmatchpat,butdoesn'tincludethosecharactersinthematchedtext(?!pat)-Negativelookaheadassertion:ensuresthatthefollowingcharactersdonotmatchpat,butdoesn'tincludethosecharactersinthematchedtext(?<=pat)-Positivelookbehindassertion:ensuresthattheprecedingcharactersmatch

pat,butdoesn'tincludethosecharactersinthematchedtext(?<!pat)-Negativelookbehindassertion:ensuresthattheprecedingcharactersdonotmatchpat,butdoesn'tincludethosecharactersinthematchedtext

Ifapatternisn'tanchoreditcanbeginatanypointinthestring:

/real/.match("surrealist")#=>#<MatchData"real">

Anchoringthepatterntothebeginningofthestringforcesthematchtostartthere.'real'doesn'toccuratthebeginningofthestring,sonowthematchfails:

/\Areal/.match("surrealist")#=>nil

Thematchbelowfailsbecausealthough'Demand'contains'and',thepatterndoesnotoccuratawordboundary.

/\band/.match("Demand")

Whereasinthefollowingexample'and'hasbeenanchoredtoanon-wordboundarysoinsteadofmatchingthefirst'and'itmatchesfromthefourthletterof'demand'instead:

/\Band.+/.match("Supplyanddemandcurve")#=>#<MatchData"andcurve">

Thepatternbelowusespositivelookaheadandpositivelookbehindtomatchtextappearingintagswithoutincludingthetagsinthematch:

/(?<=<b>)\w+(?=<\/b>)/.match("Fortunefavoursthe<b>bold</b>"

#=>#<MatchData"bold">

Options

Theenddelimiterforaregexpcanbefollowedbyoneormoresingle-letteroptionswhichcontrolhowthepatterncanmatch.

/pat/i-Ignorecase/pat/m-Treatanewlineasacharactermatchedby./pat/x-Ignorewhitespaceandcommentsinthepattern/pat/o-Perform#{}interpolationonlyonce

i,m,andxcanalsobeappliedonthesubexpressionlevelwiththe(?on-off)construct,whichenablesoptionson,anddisablesoptionsofffortheexpressionenclosedbytheparentheses.

/a(?i:b)c/.match('aBc')#=>#<MatchData"aBc">

/a(?i:b)c/.match('abc')#=>#<MatchData"abc">

OptionsmayalsobeusedwithRegexp.new:

Regexp.new("abc",Regexp::IGNORECASE)

Regexp.new("abc",Regexp::MULTILINE)

Regexp.new("abc#Comment",Regexp::EXTENDED)

Regexp.new("abc",Regexp::IGNORECASE|Regexp::MULTILINE

Free-SpacingModeandComments

Asmentionedabove,thexoptionenablesfree-spacingmode.Literalwhitespaceinsidethepatternisignored,andtheoctothorpe(#)characterintroducesacommentuntiltheendoftheline.Thisallowsthecomponentsofthepatterntobeorganizedinapotentiallymorereadablefashion.

Acontrivedpatterntomatchanumberwithoptionaldecimalplaces:

float_pat=/\A

[[:digit:]]+#1ormoredigitsbeforethedecimalpoint

(\.#Decimalpoint

[[:digit:]]+#1ormoredigitsafterthedecimalpoint

)?#Thedecimalpointandfollowingdigitsareoptional

float_pat.match('3.14')#=>#<MatchData"3.14"1:".14">

Thereareanumberofstrategiesformatchingwhitespace:

Useapatternsuchas\sor\p{Space}.Useescapedwhitespacesuchas\,i.e.aspaceprecededbyabackslash.Useacharacterclasssuchas[].

Commentscanbeincludedinanon-xpatternwiththe(?#comment)construct,where

commentisarbitrarytextignoredbytheregexpengine.

Encoding

Regularexpressionsareassumedtousethesourceencoding.Thiscanbeoverriddenwithoneofthefollowingmodifiers.

/pat/u-UTF-8/pat/e-EUC-JP/pat/s-Windows-31J/pat/n-ASCII-8BIT

Aregexpcanbematchedagainstastringwhentheyeithershareanencoding,ortheregexp'sencodingisUS-ASCIIandthestring'sencodingisASCII-compatible.

IfamatchbetweenincompatibleencodingsisattemptedanEncoding::CompatibilityErrorexceptionisraised.

TheRegexp#fixed_encoding?predicateindicateswhethertheregexphasafixedencoding,thatisoneincompatiblewithASCII.Aregexp'sencodingcanbeexplicitlyfixedbysupplyingRegexp::FIXEDENCODINGasthesecondargumentofRegexp.new:

r=Regexp.new("a".force_encoding("iso-8859-1"),Regexp

r=~"a\u3042"

#=>Encoding::CompatibilityError:incompatibleencodingregexpmatch

(ISO-8859-1regexpwithUTF-8string)

Specialglobalvariables

Patternmatchingsetssomeglobalvariables:

$~isequivalentto::last_match;$&containsthecompletematchedtext;$`containsstringbeforematch;$'containsstringaftermatch;$1,$2andsooncontaintextmatchingfirst,second,etccapturegroup;$+containslastcapturegroup.

Example:

m=/s(\w{2}).*(c)/.match('haystack')#=>#<MatchData"stac"1:"ta"2:"c">

$~#=>#<MatchData"stac"1:"ta"2:"c">

Regexp.last_match#=>#<MatchData"stac"1:"ta"2:"c">

$&#=>"stac"

#sameasm[0]

$`#=>"hay"

#sameasm.pre_match

$'#=>"k"

#sameasm.post_match

$1#=>"ta"

#sameasm[1]

$2#=>"c"

#sameasm[2]

$3#=>nil

#nothirdgroupinpattern

$+#=>"c"

#sameasm[-1]

Theseglobalvariablesarethread-localandmethod-localvariables.

Performance

Certainpathologicalcombinationsofconstructscanleadtoabysmallybadperformance.

Considerastringof25as,ad,4as,andac.

s='a'*25+'d'+'a'*4+'c'

#=>"aaaaaaaaaaaaaaaaaaaaaaaaadaaaac"

Thefollowingpatternsmatchinstantlyasyouwouldexpect:

/(b|a)/=~s#=>0

/(b|a+)/=~s#=>0

/(b|a+)*/=~s#=>0

However,thefollowingpatterntakesappreciablylonger:

/(b|a+)*c/=~s#=>26

Thishappensbecauseanatomintheregexpisquantifiedbybothanimmediate+andanenclosing*withnothingtodifferentiatewhichisincontrolofanyparticularcharacter.Thenondeterminismthatresultsproducessuper-linearperformance.(ConsultMasteringRegularExpressions(3rded.),pp222,byJefferyFriedl,foranin-depthanalysis).Thisparticularcasecanbefixedbyuseofatomicgrouping,which

preventstheunnecessarybacktracking:

(start=Time.now)&&/(b|a+)*c/=~s&&(Time.now

#=>24.702736882

(start=Time.now)&&/(?>b|a+)*c/=~s&&(Time.

#=>0.000166571

Asimilarcaseistypifiedbythefollowingexample,whichtakesapproximately60secondstoexecuteforme:

Matchastringof29asagainstapatternof29optionalasfollowedby29mandatoryas:

Regexp.new('a?'*29+'a'*29)=~'a'*29

The29optionalasmatchthestring,butthispreventsthe29mandatoryasthatfollowfrommatching.Rubymustthenbacktrackrepeatedlysoastosatisfyasmanyoftheoptionalmatchesasitcanwhilestillmatchingthemandatory29.Itisplaintousthatnoneoftheoptionalmatchescansucceed,butthisfactunfortunatelyeludesRuby.

Thebestwaytoimproveperformanceistosignificantlyreducetheamountofbacktrackingneeded.Forthiscase,insteadofindividuallymatching29optionalas,arangeofoptionalascanbematchedallatoncewitha{0,29}:

Regexp.new('a{0,29}'+'a'*29)=~'a'*29

InFilesre.c

ParentObject

Constants

EXTENDED

see#optionsand::new

FIXEDENCODING

see#optionsand::new

IGNORECASE

see#optionsand::new

MULTILINE

see#optionsand::new

NOENCODING

see#optionsand::new

PublicClassMethods

SynonymforRegexp.newcompile(*args)

Escapesanycharactersthatwouldhavespecialmeaninginaregularexpression.Returnsanewescapedstring,orselfifnocharactersareescaped.Foranystring,Regexp.new(Regexp.escape(str))=~strwillbetrue.

Regexp.escape('\*?{}.')#=>\\\*\?\{\}\.

ThefirstformreturnstheMatchDataobjectgeneratedbythelastsuccessfulpatternmatch.Equivalenttoreadingthespecialglobalvariable$~(seeSpecialglobalvariablesinRegexpfordetails).

ThesecondformreturnsthenthfieldinthisMatchDataobject.ncanbeastringorsymboltoreferenceanamedcapture.

Notethatthe::last_matchislocaltothethreadandmethodscopeofthemethodthatdidthepatternmatch.

/c(.)t/=~'cat'#=>0

Regexp.last_match#=>#<MatchData"cat"1:"a">

Regexp.last_match(0)#=>"cat"

Regexp.last_match(1)#=>"a"

Regexp.last_match(2)#=>nil

/(?<lhs>\w+)\s*=\s*(?<rhs>\w+)/=~"var=val"

Regexp.last_match#=>#<MatchData"var=val"lhs:"var"rhs:"val">

Regexp.last_match(:lhs)#=>"var"

Regexp.last_match(:rhs)#=>"val"

escape(str)→stringquote(str)→string

last_match→matchdatalast_match(n)→str

new(string,[options[,kcode]])→regexp

Constructsanewregularexpressionfrompattern,whichcanbeeitheraStringoraRegexp(inwhichcasethatregexp'soptionsarepropagated),andnewoptionsmaynotbespecified(achangeasofRuby1.8).

IfoptionsisaFixnum,itshouldbeoneormoreoftheconstantsRegexp::EXTENDED,Regexp::IGNORECASE,andRegexp::MULTILINE,or-edtogether.Otherwise,ifoptionsisnotnilorfalse,theregexpwillbecaseinsensitive.

Whenthekcodeparameteris`n'or`N'setstheregexpnoencoding.Itmeansthattheregexpisforbinarystrings.

r1=Regexp.new('^a-z+:\s+\w+')#=>/^a-z+:\s+\w+/

r2=Regexp.new('cat',true)#=>/cat/i

r3=Regexp.new(r2)#=>/cat/i

r4=Regexp.new('dog',Regexp::EXTENDED|Regexp::IGNORECASE

Escapesanycharactersthatwouldhavespecialmeaninginaregularexpression.Returnsanewescapedstring,orselfifnocharactersareescaped.Foranystring,Regexp.new(Regexp.escape(str))=~strwillbetrue.

Regexp.escape('\*?{}.')#=>\\\*\?\{\}\.

new(regexp)→regexpcompile(string,[options[,kcode]])→regexpcompile(regexp)→regexp

escape(str)→stringquote(str)→string

try_convert(obj)→reornil

TrytoconvertobjintoaRegexp,usingto_regexpmethod.Returnsconvertedregexpornilifobjcannotbeconvertedforanyreason.

Regexp.try_convert(/re/)#=>/re/

Regexp.try_convert("re")#=>nil

o=Object.new

Regexp.try_convert(o)#=>nil

defo.to_regexp()/foo/end

Regexp.try_convert(o)#=>/foo/

ReturnaRegexpobjectthatistheunionofthegivenpatterns,i.e.,willmatchanyofitsparts.ThepatternscanbeRegexpobjects,inwhichcasetheiroptionswillbepreserved,orStrings.Ifnopatternsaregiven,returns/(?!)/.Thebehaviorisunspecifiedifanygivenpatterncontainscapture.

Regexp.union#=>/(?!)/

Regexp.union("penzance")#=>/penzance/

Regexp.union("a+b*c")#=>/a\+b\*c/

Regexp.union("skiing","sledding")#=>/skiing|sledding/

Regexp.union(["skiing","sledding"])#=>/skiing|sledding/

Regexp.union(/dogs/,/cats/)#=>/(?-mix:dogs)|(?i-mx:cats)/

Note:theargumentsfor::unionwilltrytobeconvertedintoaregularexpressionliteralviato_regexp.

union(pat1,pat2,...)→new_regexpunion(pats_ary)→new_regexp

rxp==other_rxp→trueorfalseeql?(other_rxp)→trueorfalse

Equality—Tworegexpsareequaliftheirpatternsareidentical,theyhavethesamecharactersetcode,andtheircasefold?valuesarethesame.

/abc/==/abc/#=>false

CaseEquality—Usedincasestatements.

a="HELLO"

when/^[a-z]*$/;print"Lowercase\n"

when/^[A-Z]*$/;print"Uppercase\n"

else;print"Mixedcase\n"

#=>"Uppercase"

Followingaregularexpressionliteralwiththe#===operatorallowsyoutocompareagainstaString.

/^[a-z]*$/==="HELLO"#=>false

/^[A-Z]*$/==="HELLO"#=>true

Match—Matchesrxpagainststr.

/at/=~"inputdata"#=>7

/ax/=~"inputdata"#=>nil

If=~isusedwitharegexpliteralwithnamedcaptures,capturedstrings(ornil)isassignedtolocalvariablesnamedbythecapturenames.

/(?<lhs>\w+)\s*=\s*(?<rhs>\w+)/=~"x=y"

plhs#=>"x"

prhs#=>"y"

rxp===str→trueorfalse

rxp=~str→integerornil

Ifitisnotmatched,nilisassignedforthevariables.

/(?<lhs>\w+)\s*=\s*(?<rhs>\w+)/=~"x="

plhs#=>nil

prhs#=>nil

ThisassignmentisimplementedintheRubyparser.Theparserdetects'regexp-literal=~expression'fortheassignment.Theregexpmustbealiteralwithoutinterpolationandplacedatlefthandside.

Theassignmentdoesnotoccuriftheregexpisnotaliteral.

re=/(?<lhs>\w+)\s*=\s*(?<rhs>\w+)/

re=~"x=y"

plhs#undefinedlocalvariable

prhs#undefinedlocalvariable

Aregexpinterpolation,#{},alsodisablestheassignment.

rhs_pat=/(?<rhs>\w+)/

/(?<lhs>\w+)\s*=\s*#{rhs_pat}/=~"x=y"

plhs#undefinedlocalvariable

Theassignmentdoesnotoccuriftheregexpisplacedattherighthandside.

"x=y"=~/(?<lhs>\w+)\s*=\s*(?<rhs>\w+)/

plhs,rhs#undefinedlocalvariable

Returnsthevalueofthecase-insensitiveflag.

/a/.casefold?#=>false

/a/.casefold?#=>true

/(?i:a)/.casefold?#=>false

casefold?→trueorfalse

encoding→encoding

ReturnstheEncodingobjectthatrepresentstheencodingofobj.

Equality—Tworegexpsareequaliftheirpatternsareidentical,theyhavethesamecharactersetcode,andtheircasefold?valuesarethesame.

/abc/==/abc/#=>false

ReturnsfalseifrxpisapplicabletoastringwithanyASCIIcompatibleencoding.Returnstrueotherwise.

r.fixed_encoding?#=>false

r=~"\u{6666}a"#=>2

r=~"\xa1\xa2a".force_encoding("euc-jp")#=>2

r=~"abc".force_encoding("euc-jp")#=>0

r.fixed_encoding?#=>true

r.encoding#=>#<Encoding:UTF-8>

r=~"\u{6666}a"#=>2

r=~"\xa1\xa2".force_encoding("euc-jp")#=>ArgumentError

r=~"abc".force_encoding("euc-jp")#=>0

r=/\u{6666}/

r.fixed_encoding?#=>true

r.encoding#=>#<Encoding:UTF-8>

r=~"\u{6666}a"#=>0

r=~"\xa1\xa2".force_encoding("euc-jp")#=>ArgumentError

r=~"abc".force_encoding("euc-jp")#=>nil

rxp==other_rxp→trueorfalseeql?(other_rxp)→trueorfalse

fixed_encoding?→trueorfalse

Produceahashbasedonthetextandoptionsofthisregularexpression.

SeealsoObject#hash.

Produceanicelyformattedstring-versionofrxp.Perhapssurprisingly,#inspectactuallyproducesthemorenaturalversionofthestringthan#to_s.

/ab+c/x.inspect#=>"/ab+c/ix"

ReturnsaMatchDataobjectdescribingthematch,orniliftherewasnomatch.Thisisequivalenttoretrievingthevalueofthespecialvariable$~followinganormalmatch.Ifthesecondparameterispresent,itspecifiesthepositioninthestringtobeginthesearch.

/(.)(.)(.)/.match("abc")[2]#=>"b"

/(.)(.)/.match("abc",1)[2]#=>"c"

Ifablockisgiven,invoketheblockwithMatchDataifmatchsucceed,sothatyoucanwrite

pat.match(str){|m|...}

insteadof

ifm=pat.match(str)

Thereturnvalueisavaluefromblockexecutionin

hash→fixnum

inspect→string

match(str)→matchdataornilmatch(str,pos)→matchdataornil

thiscase.

Returnsahashrepresentinginformationaboutnamedcapturesofrxp.

Akeyofthehashisanameofthenamedcaptures.Avalueofthehashisanarraywhichislistofindexesofcorrespondingnamedcaptures.

/(?<foo>.)(?<bar>.)/.named_captures

#=>{"foo"=>[1],"bar"=>[2]}

/(?<foo>.)(?<foo>.)/.named_captures

#=>{"foo"=>[1,2]}

Iftherearenonamedcaptures,anemptyhashisreturned.

/(.)(.)/.named_captures

Returnsalistofnamesofcapturesasanarrayofstrings.

/(?<foo>.)(?<bar>.)(?<baz>.)/.names

#=>["foo","bar","baz"]

/(?<foo>.)(?<foo>.)/.names

#=>["foo"]

/(.)(.)/.names

ReturnsthesetofbitscorrespondingtotheoptionsusedwhencreatingthisRegexp(seeRegexp::newfor

named_captures→hash

names→[name1,name2,...]

options→fixnum

details.Notethatadditionalbitsmaybesetinthereturnedoptions:theseareusedinternallybytheregularexpressioncode.TheseextrabitsareignorediftheoptionsarepassedtoRegexp::new.

Regexp::IGNORECASE#=>1

Regexp::EXTENDED#=>2

Regexp::MULTILINE#=>4

/cat/.options#=>0

/cat/x.options#=>3

Regexp.new('cat',true).options#=>1

/\xa1\xa2/.options#=>16

r=/cat/x

Regexp.new(r.source,r.options)#=>/cat/ix

Returnstheoriginalstringofthepattern.

/ab+c/x.source#=>"ab+c"

Notethatescapesequencesareretainedasis.

/\x20\+/.source#=>"\\x20\\+"

Returnsastringcontainingtheregularexpressionanditsoptions(usingthe(?opts:source)notation.ThisstringcanbefedbackintoRegexp::newtoaregularexpressionwiththesamesemanticsastheoriginal.(However,Regexp#==maynotreturntruewhencomparingthetwo,asthesourceoftheregularexpressionitselfmaydiffer,astheexampleshows).Regexp#inspectproducesagenerallymorereadableversionofrxp.

r1=/ab+c/x#=>/ab+c/ix

source→str

to_s→str

s1=r1.to_s#=>"(?ix-m:ab+c)"

r2=Regexp.new(s1)#=>/(?ix-m:ab+c)/

r1==r2#=>false

r1.source#=>"ab+c"

r2.source#=>"(?ix-m:ab+c)"

Match—Matchesrxpagainstthecontentsof$_.Equivalenttorxp=~$_.

$_="inputdata"

~/at/#=>7

~rxp→integerornil

classRegexpErrorRaisedwhengivenaninvalidregexpexpression.

Regexp.new("?")

raisestheexception:

RegexpError:targetofrepeatoperatorisnotspecified:/?/

InFilesre.c

ParentStandardError

classRipper

InFilesparse.c

ParentObject

Constants

Version

versionofRipper

PublicClassMethods

CreateanewRipperobject.srcmustbeaString,anIO,oranObjectwhichhasgetsmethod.

Thismethoddoesnotstartsparsing.Seealso#parseand#parse.

new(src,filename="(ripper)",lineno=1)→ripper

Returncolumnnumberofcurrentparsingline.Thisnumberstartsfrom0.

Returnencodingofthesource.

Returntrueifparsedsourceendedby+__END__+.

Returntrueifparsedsourcehaserrors.

Returncurrentparsingfilename.

Returnlinenumberofcurrentparsingline.Thisnumberstartsfrom1.

Startparsingandreturnsthevalueoftherootaction.

Getyydebug.

Setyydebug.

ripper#column→Integer

ripper#encoding→encoding

ripper#end_seen?→Boolean

ripper#error?→Boolean

ripper#filename→String

ripper#lineno→Integer

ripper#parse

yydebug→trueorfalse

yydebug=flag

classRubyVM::RubyVM

InFilesiseq.cvm.c

ParentObject

Constants

DEFAULT_PARAMS

DEFAULT_PARAMSThisconstantvariableshowsVM'sdefaultparameters.NotethatchangingthesevaluesdoesnotaffectVMexecution.Specificationisnotstableandyoushouldnotdependonthisvalue.Ofcourse,thisconstantisMRIspecific.

INSTRUCTION_NAMES

OPTS,whichshowsvmbuildoptions

PublicClassMethods

ReturnsaHashcontainingimplementation-dependentcountersinsidetheVM.

Thishashincludesinformationaboutmethod/constantcacheserials:

:global_method_state=>251,

:global_constant_state=>481,

:class_serial=>9029

Thecontentsofthehashareimplementationspecificandmaybechangedinthefuture.

stat→Hashstat(hsh)→hshstat(Symbol)→Numeric

classRubyVM::Env::RubyVM::Env

InFilesiseq.c

ParentObject

classRubyVM::InstructionSequenceTheInstructionSequenceclassrepresentsacompiledsequenceofinstructionsfortheRubyVirtualMachine.

Withit,youcangetahandletotheinstructionsthatmakeupamethodoraproc,compilestringsofRubycodedowntoVMinstructions,anddisassembleinstructionsequencestostringsforeasyinspection.ItismostlyusefulifyouwanttolearnhowtheRubyVMworks,butitalsoletsyoucontrolvarioussettingsfortheRubyiseqcompiler.

YoucanfindthesourcefortheVMinstructionsininsns.defintheRubysource.

TheinstructionsequenceresultswillalmostcertainlychangeasRubychanges,soexampleoutputinthisdocumentationmaybedifferentfromwhatyousee.

InFilesiseq.c

Parent

Object

PublicClassMethods

Takessource,aStringofRubycodeandcompilesittoanInstructionSequence.

Optionallytakesfile,path,andlinewhichdescribethefilename,absolutepathandfirstlinenumberoftherubycodeinsourcewhicharemetadataattachedtothereturnediseq.

options,whichcanbetrue,falseoraHash,isusedtomodifythedefaultbehavioroftheRubyiseqcompiler.

Fordetailsregardingvalidcompileoptionssee::compile_option=.

RubyVM::InstructionSequence.compile("a=1+2")

#=><RubyVM::InstructionSequence:<compiled>@<compiled>>

Takesfile,aStringwiththelocationofaRubysourcefile,reads,parsesandcompilesthefile,andreturnsiseq,thecompiledInstructionSequencewithsourcelocationmetadataset.

Optionallytakesoptions,whichcanbetrue,falseoraHash,tomodifythedefaultbehavioroftheRubyiseqcompiler.

compile(source[,file[,path[,line[,options]]]])→iseqnew(source[,file[,path[,line[,options]]]])→iseq

compile_file(file[,options])→iseq

#/tmp/hello.rb

puts"Hello,world!"

#elsewhere

RubyVM::InstructionSequence.compile_file("/tmp/hello.rb"

#=><RubyVM::InstructionSequence:<main>@/tmp/hello.rb>

ReturnsahashofdefaultoptionsusedbytheRubyiseqcompiler.

Fordetails,see::compile_option=.

SetsthedefaultvaluesforvariousoptimizationsintheRubyiseqcompiler.

Possiblevaluesforoptionsincludetrue,whichenablesalloptions,falsewhichdisablesalloptions,andnilwhichleavesalloptionsunchanged.

YoucanalsopassaHashofoptionsthatyouwanttochange,anyoptionsnotpresentinthehashwillbeleftunchanged.

Possibleoptionnames(whicharekeysinoptions)whichcanbesettotrueorfalseinclude:

:inline_const_cache

:instructions_unification

:operands_unification

:peephole_optimization

:specialized_instruction

compile_option→options

compile_option=options

:stack_caching

:tailcall_optimization

:trace_instruction

Additionally,:debug_levelcanbesettoaninteger.

Thesedefaultoptionscanbeoverwrittenforasinglerunoftheiseqcompilerbypassinganyoftheabovevaluesastheoptionsparameterto::new,::compileand::compile_file.

Takesbody,aMethodorProcobject,andreturnsaStringwiththehumanreadableinstructionsforbody.

ForaMethodobject:

#/tmp/method.rb

defhello

puts"hello,world"

putsRubyVM::InstructionSequence.disasm(method(:hello))

Produces:

==disasm:<RubyVM::InstructionSequence:hello@/tmp/method.rb>============

0000trace8(1)

0002trace1(2)

0004putself

0005putstring"hello,world"

0007send:puts,1,nil,8,<ic:0>

0013trace16(3)

0015leave(2)

ForaProc:

#/tmp/proc.rb

p=proc{num=1+2}

disasm(body)→strdisassemble(body)→str

putsRubyVM::InstructionSequence.disasm(p)

Produces:

==disasm:<RubyVM::InstructionSequence:blockin<main>@/tmp/proc.rb>===

==catchtable

|catchtype:redost:0000ed:0012sp:0000cont:0000

|catchtype:nextst:0000ed:0012sp:0000cont:0012

|------------------------------------------------------------------------

localtable(size:2,argc:0[opts:0,rest:-1,post:0,block:-1]s1)

[2]num

0000trace1(1)

0002putobject1

0004putobject2

0006opt_plus<ic:1>

0008dup

0009setlocalnum,0

0012leave

Takesbody,aMethodorProcobject,andreturnsaStringwiththehumanreadableinstructionsforbody.

ForaMethodobject:

#/tmp/method.rb

defhello

puts"hello,world"

putsRubyVM::InstructionSequence.disasm(method(:hello))

Produces:

==disasm:<RubyVM::InstructionSequence:hello@/tmp/method.rb>============

0000trace8(1)

0002trace1(2)

0004putself

0005putstring"hello,world"

0007send:puts,1,nil,8,<ic:0>

0013trace16(3)

disasm(body)→strdisassemble(body)→str

0015leave(2)

ForaProc:

#/tmp/proc.rb

p=proc{num=1+2}

putsRubyVM::InstructionSequence.disasm(p)

Produces:

==disasm:<RubyVM::InstructionSequence:blockin<main>@/tmp/proc.rb>===

==catchtable

|catchtype:redost:0000ed:0012sp:0000cont:0000

|catchtype:nextst:0000ed:0012sp:0000cont:0012

|------------------------------------------------------------------------

localtable(size:2,argc:0[opts:0,rest:-1,post:0,block:-1]s1)

[2]num

0000trace1(1)

0002putobject1

0004putobject2

0006opt_plus<ic:1>

0008dup

0009setlocalnum,0

0012leave

Takessource,aStringofRubycodeandcompilesittoanInstructionSequence.

Optionallytakesfile,path,andlinewhichdescribethefilename,absolutepathandfirstlinenumberoftherubycodeinsourcewhicharemetadataattachedtothereturnediseq.

options,whichcanbetrue,falseoraHash,isusedtomodifythedefaultbehavioroftheRubyiseq

compile(source[,file[,path[,line[,options]]]])→iseqnew(source[,file[,path[,line[,options]]]])→iseq

compiler.

RubyVM::InstructionSequence.compile("a=1+2")

Returnstheinstructionsequencecontainingthegivenprocormethod.

Forexample,usingirb:

#aproc

>p=proc{num=1+2}

>RubyVM::InstructionSequence.of(p)

>#=><RubyVM::InstructionSequence:blockinirb_binding@(irb)>

#foramethod

>deffoo(bar);putsbar;end

>RubyVM::InstructionSequence.of(method(:foo))

>#=><RubyVM::InstructionSequence:foo@(irb)>

Using::compile_file:

#/tmp/iseq_of.rb

defhello

puts"hello,world"

$a_global_proc=proc{str='a'+'b'}

#inirb

>require'/tmp/iseq_of.rb'

#firstthemethodhello

>RubyVM::InstructionSequence.of(method(:hello))

>#=>#<RubyVM::InstructionSequence:0x007fb73d7cb1d0>

#thentheglobalproc

>RubyVM::InstructionSequence.of($a_global_proc)

of(p1)

>#=>#<RubyVM::InstructionSequence:0x007fb73d7caf78>

Returnstheabsolutepathofthisinstructionsequence.

niliftheiseqwasevaluatedfromastring.

Forexample,using::compile_file:

#/tmp/method.rb

defhello

puts"hello,world"

#inirb

>iseq=RubyVM::InstructionSequence.compile_file('/tmp/method.rb'

>iseq.absolute_path#=>/tmp/method.rb

Returnsthebaselabelofthisinstructionsequence.

iseq=RubyVM::InstructionSequence.compile('num=1+2'

iseq.base_label

#=>"<compiled>"

#/tmp/method.rb

defhello

puts"hello,world"

absolute_path()

base_label()

#inirb

>iseq.base_label#=><main>

ReturnstheinstructionsequenceasaStringinhumanreadableform.

putsRubyVM::InstructionSequence.compile('1+2').disasm

Produces:

==disasm:<RubyVM::InstructionSequence:<compiled>@<compiled>>==========

0000trace1(1)

0002putobject1

0004putobject2

0006opt_plus<ic:1>

0008leave

ReturnstheinstructionsequenceasaStringinhumanreadableform.

putsRubyVM::InstructionSequence.compile('1+2').disasm

Produces:

==disasm:<RubyVM::InstructionSequence:<compiled>@<compiled>>==========

0000trace1(1)

0002putobject1

0004putobject2

0006opt_plus<ic:1>

0008leave

disasm→strdisassemble→str

Evaluatestheinstructionsequenceandreturnstheresult.

RubyVM::InstructionSequence.compile("1+2").eval#=>3

Returnsthenumberofthefirstsourcelinewheretheinstructionsequencewasloadedfrom.

iseq.first_lineno

Returnsahuman-readablestringrepresentationofthisinstructionsequence,includingthelabelandpath.

Returnsthelabelofthisinstructionsequence.

<main>ifit'satthetoplevel,<compiled>ifitwasevaluatedfromastring.

iseq.label

#=>"<compiled>"

eval→obj

first_lineno()

inspect()

label()

#/tmp/method.rb

defhello

puts"hello,world"

#inirb

>iseq.label#=><main>

ExperimentalMRIspecificfeature,onlyavailableasClevelapi.Returnsallspecified_lineevents.

ExperimentalMRIspecificfeature,onlyavailableasClevelapi.Setaspecified_lineeventatthegivenlineposition,ifthesetparameteristrue.

Thismethodisusefulforbuildingadebuggerbreakpointataspecificline.

ATypeErrorisraisedifsetisnotboolean.

IfposisanegativeintegeraTypeErrorexceptionisraised.

Returnsthepathofthisinstructionsequence.

<compiled>iftheiseqwasevaluatedfromastring.

line_trace_all()

line_trace_specify(p1,p2)

path()

iseq.path

#=>"<compiled>"

#/tmp/method.rb

defhello

puts"hello,world"

#inirb

>iseq.path#=>/tmp/method.rb

ReturnsanArraywith14elementsrepresentingtheinstructionsequencewiththefollowingdata:

magicAstringidentifyingthedataformat.AlwaysYARVInstructionSequence/SimpleDataFormat.

major_versionThemajorversionoftheinstructionsequence.

minor_versionTheminorversionoftheinstructionsequence.

format_typeAnumberidentifyingthedataformat.Always1.

to_a→ary

miscAhashcontaining:

:arg_size

thetotalnumberofargumentstakenbythemethodortheblock(0ifiseqdoesn'trepresentamethodorblock)

:local_size

thenumberoflocalvariables+1

:stack_max

usedincalculatingthestackdepthatwhichaSystemStackErroristhrown.

labelThenameofthecontext(block,method,class,module,etc.)thatthisinstructionsequencebelongsto.

<main>ifit'satthetoplevel,<compiled>ifitwasevaluatedfromastring.

pathTherelativepathtotheRubyfilewheretheinstructionsequencewasloadedfrom.

<compiled>iftheiseqwasevaluatedfromastring.

absolute_pathTheabsolutepathtotheRubyfilewheretheinstructionsequencewasloadedfrom.

niliftheiseqwasevaluatedfromastring.

first_linenoThenumberofthefirstsourcelinewheretheinstructionsequencewasloadedfrom.

typeThetypeoftheinstructionsequence.

Validvaluesare:top,:method,:block,:class,:rescue,:ensure,:eval,:main,and:defined_guard.

localsAnarraycontainingthenamesofallargumentsandlocalvariablesassymbols.

paramsAnHashobjectcontainingparameterinformation.

Moreinfoaboutthesevaluescanbefoundinvm_core.h.

catch_tableAlistofexceptionsandcontrolflowoperators(rescue,next,redo,break,etc.).

bytecodeAnarrayofarrayscontainingtheinstructionnamesandoperandsthatmakeupthebodyoftheinstructionsequence.

NotethatthisformatisMRIspecificandversiondependent.

classRuntimeErrorAgenericerrorclassraisedwhenaninvalidoperationisattempted.

[1,2,3].freeze<<4

raisestheexception:

RuntimeError:can'tmodifyfrozenArray

Kernel#raisewillraiseaRuntimeErrorifnoExceptionclassisspecified.

raise"ouch"

raisestheexception:

RuntimeError:ouch

InFileserror.c

ParentStandardError

classScriptErrorScriptErroristhesuperclassforerrorsraisedwhenascriptcannotbeexecutedbecauseofaLoadError,NotImplementedErrororaSyntaxError.NotethesetypeofScriptErrorsarenotStandardErrorandwillnotberescuedunlessitisspecifiedexplicitly(oritsancestorException).

InFileserror.c

ParentException

classSecurityErrorRaisedwhenattemptingapotentialunsafeoperation,typicallywhenthe$SAFElevelisraisedabove0.

foo="bar"

proc=Proc.newdo

$SAFE=3

foo.untaint

proc.call

raisestheexception:

SecurityError:Insecure:Insecureoperation`untaint'atlevel3

InFileserror.c

ParentException

moduleSignalManyoperatingsystemsallowsignalstobesenttorunningprocesses.Somesignalshaveadefinedeffectontheprocess,whileothersmaybetrappedatthecodelevelandactedupon.Forexample,yourprocessmaytraptheUSR1signalanduseittotoggledebugging,andmayuseTERMtoinitiateacontrolledshutdown.

pid=forkdo

Signal.trap("USR1")do

$debug=!$debug

puts"Debugnow:#$debug"

Signal.trap("TERM")do

puts"Terminating..."

shutdown()

#...dosomework...

Process.detach(pid)

#Controllingprogram:

Process.kill("USR1",pid)

Process.kill("TERM",pid)

produces:

Debugnow:true

Debugnow:false

Terminating...

Thelistofavailablesignalnamesandtheirinterpretationissystemdependent.Signaldeliverysemanticsmayalsovarybetweensystems;inparticularsignaldeliverymaynotalwaysbereliable.

InFilessignal.c

PublicClassMethods

Returnsalistofsignalnamesmappedtothecorrespondingunderlyingsignalnumbers.

Signal.list#=>{"EXIT"=>0,"HUP"=>1,"INT"=>2,"QUIT"=>3,"ILL"=>4,"TRAP"=>5,"IOT"=>6,"ABRT"=>6,"FPE"=>8,"KILL"=>9,"BUS"=>7,"SEGV"=>11,"SYS"=>31,"PIPE"=>13,"ALRM"=>14,"TERM"=>15,"URG"=>23,"STOP"=>19,"TSTP"=>20,"CONT"=>18,"CHLD"=>17,"CLD"=>17,"TTIN"=>21,"TTOU"=>22,"IO"=>29,"XCPU"=>24,"XFSZ"=>25,"VTALRM"=>26,"PROF"=>27,"WINCH"=>28,"USR1"=>10,"USR2"=>12,"PWR"=>30,"POLL"=>29}

convertsignalnumbertosignalname

Signal.trap("INT"){|signo|putsSignal.signame(signo

Process.kill("INT",0)

produces:

list→a_hash

signame(signo)→string

trap(signal,command)→obj

Specifiesthehandlingofsignals.Thefirstparameterisasignalname(astringsuchas“SIGALRM'',“SIGUSR1'',andsoon)orasignalnumber.Thecharacters“SIG''maybeomittedfromthesignalname.Thecommandorblockspecifiescodetoberunwhenthesignalisraised.Ifthecommandisthestring“IGNORE''or“SIG_IGN'',thesignalwillbeignored.Ifthecommandis“DEFAULT''or“SIG_DFL'',theRuby'sdefaulthandlerwillbeinvoked.Ifthecommandis“EXIT'',thescriptwillbeterminatedbythesignal.Ifthecommandis“SYSTEM_DEFAULT'',theoperatingsystem'sdefaulthandlerwillbeinvoked.Otherwise,thegivencommandorblockwillberun.Thespecialsignalname“EXIT''orsignalnumberzerowillbeinvokedjustpriortoprogramtermination.trapreturnstheprevioushandlerforthegivensignal.

Signal.trap(0,proc{puts"Terminating:#{$$}"})

Signal.trap("CLD"){puts"Childdied"}

fork&&Process.wait

produces:

Terminating:27461

Childdied

Terminating:27460

trap(signal){||block}→obj

classSignalExceptionRaisedwhenasignalisreceived.

Process.kill('HUP',Process.pid)

sleep#waitforreceivertohandlesignalsentbyProcess.kill

rescueSignalException=>e

puts"receivedException#{e}"

produces:

receivedExceptionSIGHUP

InFileserror.csignal.c

ParentException

PublicClassMethods

new(sig_name)→signal_exceptionnew(sig_number[,name])→signal_exception

ConstructanewSignalExceptionobject.sig_nameshouldbeaknownsignalname.

Returnsasignalnumber.

signo→num

classStandardErrorThemoststandarderrortypesaresubclassesofStandardError.ArescueclausewithoutanexplicitExceptionclasswillrescueallStandardErrors(andonlythose).

deffoo

raise"Oups"

foorescue"Hello"#=>"Hello"

Ontheotherhand:

require'does/not/exist'rescue"Hi"

raisestheexception:

LoadError:nosuchfiletoload--does/not/exist

InFileserror.c

ParentException

classStopIterationRaisedtostoptheiteration,inparticularbyEnumerator#next.ItisrescuedbyKernel#loop.

loopdo

puts"Hello"

raiseStopIteration

puts"World"

puts"Done!"

produces:

InFilesenumerator.c

ParentIndexError

Returnsthereturnvalueoftheiterator.

o=Object.new

result→value

defo.each

yield1

yield2

yield3

e=o.to_enum

putse.next#=>1

putse.next#=>2

putse.next#=>3

e.next

rescueStopIteration=>ex

putsex.result#=>100

classStringAStringobjectholdsandmanipulatesanarbitrarysequenceofbytes,typicallyrepresentingcharacters.StringobjectsmaybecreatedusingString::neworasliterals.

Becauseofaliasingissues,usersofstringsshouldbeawareofthemethodsthatmodifythecontentsofaStringobject.Typically,methodswithnamesendingin“!''modifytheirreceiver,whilethosewithouta“!''returnanewString.However,thereareexceptions,suchasString#[]=.

InFilescomplex.cpack.crational.cstring.ctranscode.c

ParentObject

PublicClassMethods

Returnsanewstringobjectcontainingacopyofstr.

TrytoconvertobjintoaString,using#to_strmethod.Returnsconvertedstringornilifobjcannotbeconvertedforanyreason.

String.try_convert("str")#=>"str"

String.try_convert(/re/)#=>nil

Format—Usesstrasaformatspecification,andreturnstheresultofapplyingittoarg.Iftheformatspecificationcontainsmorethanonesubstitution,thenargmustbeanArrayorHashcontainingthevaluestobesubstituted.SeeKernel::sprintffordetailsoftheformatstring.

"%05d"%123#=>"00123"

"%-5s:%08x"%["ID",self.object_id]#=>"ID:200e14d6"

"foo=%{foo}"%{:foo=>'bar'}#=>"foo=bar"

Copy—ReturnsanewStringcontainingintegercopiesofthereceiver.integermustbegreaterthanorequalto0.

new(str="")→new_str

try_convert(obj)→stringornil

str%arg→new_str

str*integer→new_str

"Ho!"*3#=>"Ho!Ho!Ho!"

"Ho!"*0#=>""

Concatenation—ReturnsanewStringcontainingother_strconcatenatedtostr.

"Hellofrom"+self.to_s#=>"Hellofrommain"

Append—Concatenatesthegivenobjecttostr.IftheobjectisaInteger,itisconsideredasacodepoint,andisconvertedtoacharacterbeforeconcatenation.

a="hello"

a<<"world"#=>"helloworld"

a.concat(33)#=>"helloworld!"

Comparison—Returns-1,0,+1ornildependingonwhetherstringislessthan,equalto,orgreaterthanother_string.

Ifthestringsareofdifferentlengths,andthestringsareequalwhencompareduptotheshortestlength,thenthelongerstringisconsideredgreaterthantheshorterone.

<=>isthebasisforthemethods<,<=,>,>=,and

str+other_str→new_str

str<<integer→strconcat(integer)→strstr<<obj→strconcat(obj)→str

string<=>other_string→-1,0,+1ornil

between?,includedfrommoduleComparable.ThemethodString#==doesnotuseComparable#==.

"abcdef"<=>"abcde"#=>1

"abcdef"<=>"abcdef"#=>0

"abcdef"<=>"abcdefg"#=>-1

"abcdef"<=>"ABCDEF"#=>1

EqualityReturnswhetherstr==obj,similartoObject#==.

IfobjisnotaninstanceofStringbutrespondstoto_str,thenthetwostringsarecomparedusingcaseequalityObject#===.

Otherwise,returnssimilarlyto#eql?,comparinglengthandcontent.

EqualityReturnswhetherstr==obj,similartoObject#==.

IfobjisnotaninstanceofStringbutrespondstoto_str,thenthetwostringsarecomparedusingcaseequalityObject#===.

Otherwise,returnssimilarlyto#eql?,comparinglengthandcontent.

str==obj→trueorfalsestr===obj→trueorfalse

str=~obj→fixnumornil

Match—IfobjisaRegexp,useitasapatterntomatchagainststr,andreturnsthepositionthematchstarts,ornilifthereisnomatch.Otherwise,invokesobj.=~,passingstrasanargument.Thedefault=~inObjectreturnsnil.

Note:str=~regexpisnotthesameasregexp=~str.Stringscapturedfromnamedcapturegroupsareassignedtolocalvariablesonlyinthesecondcase.

"cato'9tails"=~/\d/#=>7

"cato'9tails"=~9#=>nil

ElementReference—Ifpassedasingleindex,returnsasubstringofonecharacteratthatindex.Ifpassedastartindexandalength,returnsasubstringcontaininglengthcharactersstartingattheindex.Ifpassedarange,itsbeginningandendareinterpretedasoffsetsdelimitingthesubstringtobereturned.

Inthesethreecases,ifanindexisnegative,itis

str[index]→new_strornilstr[start,length]→new_strornilstr[range]→new_strornilstr[regexp]→new_strornilstr[regexp,capture]→new_strornilstr[match_str]→new_strornilslice(index)→new_strornilslice(start,length)→new_strornilslice(range)→new_strornilslice(regexp)→new_strornilslice(regexp,capture)→new_strornilslice(match_str)→new_strornil

countedfromtheendofthestring.Forthestartandrangecasesthestartingindexisjustbeforeacharacterandanindexmatchingthestring'ssize.Additionally,anemptystringisreturnedwhenthestartingindexforacharacterrangeisattheendofthestring.

Returnsniliftheinitialindexfallsoutsidethestringorthelengthisnegative.

IfaRegexpissupplied,thematchingportionofthestringisreturned.Ifacapturefollowstheregularexpression,whichmaybeacapturegroupindexorname,followstheregularexpressionthatcomponentoftheMatchDataisreturnedinstead.

Ifamatch_strisgiven,thatstringisreturnedifitoccursinthestring.

Returnsniliftheregularexpressiondoesnotmatchorthematchstringcannotbefound.

a="hellothere"

a[1]#=>"e"

a[2,3]#=>"llo"

a[2..3]#=>"ll"

a[-3,2]#=>"er"

a[7..-2]#=>"her"

a[-4..-2]#=>"her"

a[-2..-4]#=>""

a[11,0]#=>""

a[11]#=>nil

a[12,0]#=>nil

a[12..-1]#=>nil

a[/[aeiou](.)\1/]#=>"ell"

a[/[aeiou](.)\1/,0]#=>"ell"

a[/[aeiou](.)\1/,1]#=>"l"

a[/[aeiou](.)\1/,2]#=>nil

a[/(?<vowel>[aeiou])(?<non_vowel>[^aeiou])/,"non_vowel"

a[/(?<vowel>[aeiou])(?<non_vowel>[^aeiou])/,"vowel"]

a["lo"]#=>"lo"

a["bye"]#=>nil

ElementAssignment—Replacessomeorallofthecontentofstr.TheportionofthestringaffectedisdeterminedusingthesamecriteriaasString#[].Ifthereplacementstringisnotthesamelengthasthetextitisreplacing,thestringwillbeadjustedaccordingly.Iftheregularexpressionorstringisusedastheindexdoesn'tmatchapositioninthestring,IndexErrorisraised.Iftheregularexpressionformisused,theoptionalsecondFixnumallowsyoutospecifywhichportionofthematchtoreplace(effectivelyusingtheMatchDataindexingrules.TheformsthattakeaFixnumwillraiseanIndexErrorifthevalueisoutofrange;theRangeformwillraiseaRangeError,andtheRegexpandStringwillraiseanIndexErroronnegativematch.

ReturnstrueforastringwhichhasonlyASCIIcharacters.

"abc".force_encoding("UTF-8").ascii_only?#=>true

str[fixnum]=new_strstr[fixnum,fixnum]=new_strstr[range]=aStringstr[regexp]=new_strstr[regexp,fixnum]=new_strstr[regexp,name]=new_strstr[other_str]=new_str

ascii_only?→trueorfalse

"abc\u{6666}".force_encoding("UTF-8").ascii_only?#=>false

ReturnsacopiedstringwhoseencodingisASCII-8BIT.

Returnsanarrayofbytesinstr.Thisisashorthandforstr.each_byte.to_a.

Ifablockisgiven,whichisadeprecatedform,worksthesameaseach_byte.

Returnsthelengthofstrinbytes.

"\x80\u3042".bytesize#=>4

"hello".bytesize#=>5

ByteReference—IfpassedasingleFixnum,returnsasubstringofonebyteatthatposition.IfpassedtwoFixnumobjects,returnsasubstringstartingattheoffsetgivenbythefirst,andalengthgivenbythesecond.IfgivenaRange,asubstringcontainingbytesatoffsetsgivenbytherangeisreturned.Inallthreecases,ifanoffsetisnegative,itiscountedfromtheendofstr.Returnsniliftheinitialoffsetfallsoutsidethestring,thelengthisnegative,orthebeginningoftherangeisgreaterthantheend.Theencodingof

b→str

bytes→an_array

bytesize→integer

byteslice(fixnum)→new_strornilbyteslice(fixnum,fixnum)→new_strornilbyteslice(range)→new_strornil

theresultedstringkeepsoriginalencoding.

"hello".byteslice(1)#=>"e"

"hello".byteslice(-1)#=>"o"

"hello".byteslice(1,2)#=>"el"

"\x80\u3042".byteslice(1,3)#=>"\u3042"

"\x03\u3042\xff".byteslice(1..3)#=>"\u3042"

Returnsacopyofstrwiththefirstcharacterconvertedtouppercaseandtheremaindertolowercase.Note:caseconversioniseffectiveonlyinASCIIregion.

"hello".capitalize#=>"Hello"

"HELLO".capitalize#=>"Hello"

"123ABC".capitalize#=>"123abc"

Modifiesstrbyconvertingthefirstcharactertouppercaseandtheremaindertolowercase.Returnsnilifnochangesaremade.Note:caseconversioniseffectiveonlyinASCIIregion.

a="hello"

a.capitalize!#=>"Hello"

a#=>"Hello"

a.capitalize!#=>nil

Case-insensitiveversionofString#<=>.

"abcdef".casecmp("abcde")#=>1

"aBcDeF".casecmp("abcdef")#=>0

"abcdef".casecmp("abcdefg")#=>-1

"abcdef".casecmp("ABCDEF")#=>0

capitalize→new_str

capitalize!→strornil

casecmp(other_str)→-1,0,+1ornil

Centersstrinwidth.Ifwidthisgreaterthanthelengthofstr,returnsanewStringoflengthwidthwithstrcenteredandpaddedwithpadstr;otherwise,returnsstr.

"hello".center(4)#=>"hello"

"hello".center(20)#=>"hello"

"hello".center(20,'123')#=>"1231231hello12312312"

Returnsanarrayofcharactersinstr.Thisisashorthandforstr.each_char.to_a.

Ifablockisgiven,whichisadeprecatedform,worksthesameaseach_char.

ReturnsanewStringwiththegivenrecordseparatorremovedfromtheendofstr(ifpresent).If$/hasnotbeenchangedfromthedefaultRubyrecordseparator,thenchompalsoremovescarriagereturncharacters(thatisitwillremove\n,\r,and\r\n).If$/isanemptystring,itwillremovealltrailingnewlinesfromthestring.

"hello".chomp#=>"hello"

"hello\n".chomp#=>"hello"

"hello\r\n".chomp#=>"hello"

"hello\n\r".chomp#=>"hello\n"

"hello\r".chomp#=>"hello"

"hello\nthere".chomp#=>"hello\nthere"

"hello".chomp("llo")#=>"he"

"hello\r\n\r\n".chomp('')#=>"hello"

"hello\r\n\r\r\n".chomp('')#=>"hello\r\n\r"

center(width,padstr='')→new_str

chars→an_array

chomp(separator=$/)→new_str

ModifiesstrinplaceasdescribedforString#chomp,returningstr,ornilifnomodificationsweremade.

ReturnsanewStringwiththelastcharacterremoved.Ifthestringendswith\r\n,bothcharactersareremoved.Applyingchoptoanemptystringreturnsanemptystring.String#chompisoftenasaferalternative,asitleavesthestringunchangedifitdoesn'tendinarecordseparator.

"string\r\n".chop#=>"string"

"string\n\r".chop#=>"string\n"

"string\n".chop#=>"string"

"string".chop#=>"strin"

"x".chop.chop#=>""

ProcessesstrasforString#chop,returningstr,ornilifstristheemptystring.SeealsoString#chomp!.

Returnsaone-characterstringatthebeginningofthestring.

a="abcde"

a.chr#=>"a"

Makesstringempty.

a="abcde"

chomp!(separator=$/)→strornil

chop→new_str

chop!→strornil

chr→string

clear→string

a.clear#=>""

ReturnsanarrayoftheIntegerordinalsofthecharactersinstr.Thisisashorthandforstr.each_codepoint.to_a.

Ifablockisgiven,whichisadeprecatedform,worksthesameaseach_codepoint.

Append—Concatenatesthegivenobjecttostr.IftheobjectisaInteger,itisconsideredasacodepoint,andisconvertedtoacharacterbeforeconcatenation.

a="hello"

a<<"world"#=>"helloworld"

a.concat(33)#=>"helloworld!"

Eachother_strparameterdefinesasetofcharacterstocount.Theintersectionofthesesetsdefinesthecharacterstocountinstr.Anyother_strthatstartswithacaret^isnegated.Thesequencec1-c2meansallcharactersbetweenc1andc2.Thebackslashcharacter\</code>canbeusedtoescape<code>^or-andisotherwiseignoredunlessitappearsattheendofasequenceortheendofaother_str.

a="helloworld"

a.count"lo"#=>5

codepoints→an_array

str<<integer→strconcat(integer)→strstr<<obj→strconcat(obj)→str

count([other_str]+)→fixnum

a.count"lo","o"#=>2

a.count"hello","^l"#=>4

a.count"ej-m"#=>4

"hello^world".count"\\^aeiou"#=>4

"hello-world".count"a\\-eo"#=>4

c="helloworld\\r\\n"

c.count"\\"#=>2

c.count"\\A"#=>0

c.count"X-\\w"#=>3

Appliesaone-waycryptographichashtostrbyinvokingthestandardlibraryfunctioncrypt(3)withthegivensaltstring.Whiletheformatandtheresultaresystemandimplementationdependent,usingasaltmatchingtheregularexpression\A[a-zA-Z0-9./]{2}shouldbevalidandsafeonanyplatform,inwhichonlythefirsttwocharactersaresignificant.

Thismethodisforuseinsystemspecificscripts,soifyouwantacross-platformhashfunctionconsiderusingDigestorOpenSSLinstead.

Returnsacopyofstrwithallcharactersintheintersectionofitsargumentsdeleted.UsesthesamerulesforbuildingthesetofcharactersasString#count.

"hello".delete"l","lo"#=>"heo"

"hello".delete"lo"#=>"he"

"hello".delete"aeiou","^e"#=>"hell"

"hello".delete"ej-m"#=>"ho"

crypt(salt_str)→new_str

delete([other_str]+)→new_str

delete!([other_str]+)→strornil

Performsadeleteoperationinplace,returningstr,ornilifstrwasnotmodified.

Returnsacopyofstrwithalluppercaselettersreplacedwiththeirlowercasecounterparts.Theoperationislocaleinsensitive—onlycharacters“A''to“Z''areaffected.Note:casereplacementiseffectiveonlyinASCIIregion.

"hEllO".downcase#=>"hello"

Downcasesthecontentsofstr,returningnilifnochangesweremade.Note:casereplacementiseffectiveonlyinASCIIregion.

Producesaversionofstrwithallnon-printingcharactersreplacedby\nnnnotationandallspecialcharactersescaped.

"hello\n''".dump#=>"\"hello\\n''\"

Passeseachbyteinstrtothegivenblock,orreturnsanenumeratorifnoblockisgiven.

"hello".each_byte{|c|printc,''}

produces:

104101108108111

downcase→new_str

downcase!→strornil

dump→new_str

each_byte{|fixnum|block}→streach_byte→an_enumerator

Passeseachcharacterinstrtothegivenblock,orreturnsanenumeratorifnoblockisgiven.

"hello".each_char{|c|printc,''}

produces:

PassestheIntegerordinalofeachcharacterinstr,alsoknownasacodepointwhenappliedtoUnicodestringstothegivenblock.

"hello\u0639".each_codepoint{|c|printc,''}

produces:

1041011081081111593

Splitsstrusingthesuppliedparameterastherecordseparator($/bydefault),passingeachsubstringinturntothesuppliedblock.Ifazero-lengthrecordseparatorissupplied,thestringissplitintoparagraphsdelimitedbymultiplesuccessive

each_char{|cstr|block}→streach_char→an_enumerator

each_codepoint{|integer|block}→streach_codepoint→an_enumerator

each_line(separator=$/){|substr|block}→streach_line(separator=$/)→an_enumerator

newlines.

print"Exampleone\n"

"hello\nworld".each_line{|s|ps}

print"Exampletwo\n"

"hello\nworld".each_line('l'){|s|ps}

print"Examplethree\n"

"hello\n\n\nworld".each_line(''){|s|ps}

produces:

Exampleone

"hello\n"

"world"

Exampletwo

"o\nworl"

Examplethree

"hello\n\n\n"

"world"

Returnstrueifstrhasalengthofzero.

"hello".empty?#=>false

"".empty?#=>false

"".empty?#=>true

Thefirstformreturnsacopyofstrtranscodedtoencodingencoding.Thesecondformreturnsacopy

encode(encoding[,options])→strencode(dst_encoding,src_encoding[,options])→strencode([options])→str

ofstrtranscodedfromsrc_encodingtodst_encoding.ThelastformreturnsacopyofstrtranscodedtoEncoding.default_internal.

Bydefault,thefirstandsecondformraiseEncoding::UndefinedConversionErrorforcharactersthatareundefinedinthedestinationencoding,andEncoding::InvalidByteSequenceErrorforinvalidbytesequencesinthesourceencoding.Thelastformbydefaultdoesnotraiseexceptionsbutusesreplacementstrings.

TheoptionsHashgivesdetailsforconversionandcanhavethefollowingkeys:

:invalidIfthevalueis:replace,encodereplacesinvalidbytesequencesinstrwiththereplacementcharacter.ThedefaultistoraisetheEncoding::InvalidByteSequenceErrorexception

:undefIfthevalueis:replace,encodereplacescharacterswhichareundefinedinthedestinationencodingwiththereplacementcharacter.ThedefaultistoraisetheEncoding::UndefinedConversionError.

:replaceSetsthereplacementstringtothegivenvalue.Thedefaultreplacementstringis“uFFFD”forUnicodeencodingforms,and“?”otherwise.

:fallbackSetsthereplacementstringbythegivenobjectforundefinedcharacter.TheobjectshouldbeaHash,aProc,aMethod,oranobjectwhichhas[]method.Itskeyisanundefinedcharacterencodedinthesourceencodingofcurrenttranscoder.Its

valuecanbeanyencodinguntilitcanbeconvertedintothedestinationencodingofthetranscoder.

:xmlThevaluemustbe:textor:attr.Ifthevalueis:textencodereplacesundefinedcharacterswiththeir(upper-casehexadecimal)numericcharacterreferences.'&','<',and'>'areconvertedto“&”,“<”,and“>”,respectively.Ifthevalueis:attr,encodealsoquotesthereplacementresult(using'“'),andreplaces'”'with“"”.

:cr_newlineReplacesLF(“n”)withCR(“r”)ifvalueistrue.

:crlf_newlineReplacesLF(“n”)withCRLF(“rn”)ifvalueistrue.

:universal_newlineReplacesCRLF(“rn”)andCR(“r”)withLF(“n”)ifvalueistrue.

Thefirstformtranscodesthecontentsofstrfromstr.encodingtoencoding.Thesecondformtranscodesthecontentsofstrfromsrc_encodingtodst_encoding.TheoptionsHashgivesdetailsforconversion.See#encodefordetails.Returnsthestringevenifnochangesweremade.

ReturnstheEncodingobjectthatrepresentstheencodingofobj.

encode!(encoding[,options])→strencode!(dst_encoding,src_encoding[,options])→str

encoding→encoding

Returnstrueifstrendswithoneofthesuffixesgiven.

Twostringsareequaliftheyhavethesamelengthandcontent.

Changestheencodingtoencodingandreturnsself.

returnstheindexthbyteasaninteger.

Returnsacopyofstrwiththealloccurrencesofpatternsubstitutedforthesecondargument.ThepatternistypicallyaRegexp;ifgivenasaString,anyregularexpressionmetacharactersitcontainswillbeinterpretedliterally,e.g.'\\d'willmatchabacklashfollowedby'd',insteadofadigit.

IfreplacementisaStringitwillbesubstitutedforthematchedtext.Itmaycontainback-referencestothepattern'scapturegroupsoftheform\\d,wheredisagroupnumber,or\\k<n>,wherenisagroupname.Ifitisadouble-quotedstring,bothback-referencesmustbeprecededbyanadditionalbackslash.

end_with?([suffixes]+)→trueorfalse

force_encoding(encoding)→str

getbyte(index)→0..255

gsub(pattern,replacement)→new_strgsub(pattern,hash)→new_strgsub(pattern){|match|block}→new_strgsub(pattern)→enumerator

However,withinreplacementthespecialmatchvariables,suchas$&,willnotrefertothecurrentmatch.

IfthesecondargumentisaHash,andthematchedtextisoneofitskeys,thecorrespondingvalueisthereplacementstring.

Intheblockform,thecurrentmatchstringispassedinasaparameter,andvariablessuchas$1,$2,$`,$&,and$'willbesetappropriately.Thevaluereturnedbytheblockwillbesubstitutedforthematchoneachcall.

Theresultinheritsanytaintingintheoriginalstringoranysuppliedreplacementstring.

Whenneitherablocknorasecondargumentissupplied,anEnumeratorisreturned.

"hello".gsub(/[aeiou]/,'*')#=>"h*ll*"

"hello".gsub(/([aeiou])/,'<\1>')#=>"h<e>ll<o>"

"hello".gsub(/./){|s|s.ord.to_s+''}#=>"104101108108111"

"hello".gsub(/(?<foo>[aeiou])/,'{\k<foo>}')#=>"h{e}ll{o}"

'hello'.gsub(/[eo]/,'e'=>3,'o'=>'*')#=>"h3ll*"

PerformsthesubstitutionsofString#gsubinplace,returningstr,ornilifnosubstitutionswereperformed.Ifnoblockandnoreplacementisgiven,anenumeratorisreturnedinstead.

Returnahashbasedonthestring'slength,contentandencoding.

gsub!(pattern,replacement)→strornilgsub!(pattern){|match|block}→strornilgsub!(pattern)→an_enumerator

hash→fixnum

SeealsoObject#hash.

Treatsleadingcharactersfromstrasastringofhexadecimaldigits(withanoptionalsignandanoptional0x)andreturnsthecorrespondingnumber.Zeroisreturnedonerror.

"0x0a".hex#=>10

"-1234".hex#=>-4660

"0".hex#=>0

"wombat".hex#=>0

Returnstrueifstrcontainsthegivenstringorcharacter.

"hello".include?"lo"#=>true

"hello".include?"ol"#=>false

"hello".include?h#=>true

Returnstheindexofthefirstoccurrenceofthegivensubstringorpattern(regexp)instr.Returnsnilifnotfound.Ifthesecondparameterispresent,itspecifiesthepositioninthestringtobeginthesearch.

"hello".index('e')#=>1

"hello".index('lo')#=>3

"hello".index('a')#=>nil

"hello".index(e)#=>1

"hello".index(/[aeiou]/,-3)#=>4

hex→integer

include?other_str→trueorfalse

index(substring[,offset])→fixnumornilindex(regexp[,offset])→fixnumornil

replace(other_str)→str

Replacesthecontentsandtaintednessofstrwiththecorrespondingvaluesinother_str.

s="hello"#=>"hello"

s.replace"world"#=>"world"

Insertsother_strbeforethecharacteratthegivenindex,modifyingstr.Negativeindicescountfromtheendofthestring,andinsertafterthegivencharacter.TheintentisinsertaStringsothatitstartsatthegivenindex.

"abcd".insert(0,'X')#=>"Xabcd"

"abcd".insert(3,'X')#=>"abcXd"

"abcd".insert(4,'X')#=>"abcdX"

"abcd".insert(-3,'X')#=>"abXcd"

"abcd".insert(-1,'X')#=>"abcdX"

Returnsaprintableversionofstr,surroundedbyquotemarks,withspecialcharactersescaped.

str="hello"

str[3]="\b"

str.inspect#=>"\"hel\\bo\""

ReturnstheSymbolcorrespondingtostr,creatingthesymbolifitdidnotpreviouslyexist.SeeSymbol#id2name.

"Koala".intern#=>:Koala

s='cat'.to_sym#=>:cat

s==:cat#=>true

s='@cat'.to_sym#=>:@cat

insert(index,other_str)→str

inspect→string

intern→symbolto_sym→symbol

s==:@cat#=>true

Thiscanalsobeusedtocreatesymbolsthatcannotberepresentedusingthe:xxxnotation.

'catanddog'.to_sym#=>:"catanddog"

Returnsthecharacterlengthofstr.

Returnsanarrayoflinesinstrsplitusingthesuppliedrecordseparator($/bydefault).Thisisashorthandforstr.each_line(separator).to_a.

Ifablockisgiven,whichisadeprecatedform,worksthesameaseach_line.

Ifintegerisgreaterthanthelengthofstr,returnsanewStringoflengthintegerwithstrleftjustifiedandpaddedwithpadstr;otherwise,returnsstr.

"hello".ljust(4)#=>"hello"

"hello".ljust(20)#=>"hello"

"hello".ljust(20,'1234')#=>"hello123412341234123"

Returnsacopyofstrwithleadingwhitespaceremoved.SeealsoString#rstripandString#strip.

"hello".lstrip#=>"hello"

lines(separator=$/)→an_array

ljust(integer,padstr='')→new_str

lstrip→new_str

Removesleadingwhitespacefromstr,returningnilifnochangewasmade.SeealsoString#rstrip!andString#strip!.

"hello".lstrip#=>"hello"

"hello".lstrip!#=>nil

ConvertspatterntoaRegexp(ifitisn'talreadyone),theninvokesitsmatchmethodonstr.Ifthesecondparameterispresent,itspecifiesthepositioninthestringtobeginthesearch.

'hello'.match('(.)\1')#=>#<MatchData"ll"1:"l">

'hello'.match('(.)\1')[0]#=>"ll"

'hello'.match(/(.)\1/)[0]#=>"ll"

'hello'.match('xx')#=>nil

Ifablockisgiven,invoketheblockwithMatchDataifmatchsucceed,sothatyoucanwrite

str.match(pat){|m|...}

insteadof

ifm=str.match(pat)

Thereturnvalueisavaluefromblockexecutioninthiscase.

lstrip!→selfornil

match(pattern)→matchdataornilmatch(pattern,pos)→matchdataornil

succ→new_strnext→new_str

Returnsthesuccessortostr.Thesuccessoriscalculatedbyincrementingcharactersstartingfromtherightmostalphanumeric(ortherightmostcharacteriftherearenoalphanumerics)inthestring.Incrementingadigitalwaysresultsinanotherdigit,andincrementingaletterresultsinanotherletterofthesamecase.Incrementingnonalphanumericsusestheunderlyingcharacterset'scollatingsequence.

Iftheincrementgeneratesa“carry,''thecharactertotheleftofitisincremented.Thisprocessrepeatsuntilthereisnocarry,addinganadditionalcharacterifnecessary.

"abcd".succ#=>"abce"

"THX1138".succ#=>"THX1139"

"<<koala>>".succ#=>"<<koalb>>"

"1999zzz".succ#=>"2000aaa"

"ZZZ9999".succ#=>"AAAA0000"

"***".succ#=>"**+"

EquivalenttoString#succ,butmodifiesthereceiverinplace.

Treatsleadingcharactersofstrasastringofoctaldigits(withanoptionalsign)andreturnsthecorrespondingnumber.Returns0iftheconversionfails.

"123".oct#=>83

"-377".oct#=>-255

"bad".oct#=>0

"0377bad".oct#=>255

succ!→strnext!→str

oct→integer

ReturntheIntegerordinalofaone-characterstring.

"a".ord#=>97

Searchesseporpattern(regexp)inthestringandreturnsthepartbeforeit,thematch,andthepartafterit.Ifitisnotfound,returnstwoemptystringsandstr.

"hello".partition("l")#=>["he","l","lo"]

"hello".partition("x")#=>["hello","",""]

"hello".partition(/.l/)#=>["h","el","lo"]

Prepend—Prependthegivenstringtostr.

a="world"

a.prepend("hello")#=>"helloworld"

a#=>"helloworld"

Replacesthecontentsandtaintednessofstrwiththecorrespondingvaluesinother_str.

s="hello"#=>"hello"

s.replace"world"#=>"world"

Returnsanewstringwiththecharactersfromstrinreverseorder.

ord→integer

partition(sep)→[head,sep,tail]partition(regexp)→[head,match,tail]

prepend(other_str)→str

replace(other_str)→str

reverse→new_str

"stressed".reverse#=>"desserts"

Reversesstrinplace.

Returnstheindexofthelastoccurrenceofthegivensubstringorpattern(regexp)instr.Returnsnilifnotfound.Ifthesecondparameterispresent,itspecifiesthepositioninthestringtoendthesearch—charactersbeyondthispointwillnotbeconsidered.

"hello".rindex('e')#=>1

"hello".rindex('l')#=>3

"hello".rindex('a')#=>nil

"hello".rindex(e)#=>1

"hello".rindex(/[aeiou]/,-2)#=>1

Ifintegerisgreaterthanthelengthofstr,returnsanewStringoflengthintegerwithstrrightjustifiedandpaddedwithpadstr;otherwise,returnsstr.

"hello".rjust(4)#=>"hello"

"hello".rjust(20)#=>"hello"

"hello".rjust(20,'1234')#=>"123412341234123hello"

Searchesseporpattern(regexp)inthestringfromtheendofthestring,andreturnsthepartbeforeit,thematch,andthepartafterit.Ifitisnotfound,

reverse!→str

rindex(substring[,fixnum])→fixnumornilrindex(regexp[,fixnum])→fixnumornil

rjust(integer,padstr='')→new_str

rpartition(sep)→[head,sep,tail]rpartition(regexp)→[head,match,tail]

returnstwoemptystringsandstr.

"hello".rpartition("l")#=>["hel","l","o"]

"hello".rpartition("x")#=>["","","hello"]

"hello".rpartition(/.l/)#=>["he","ll","o"]

Returnsacopyofstrwithtrailingwhitespaceremoved.SeealsoString#lstripandString#strip.

"hello".rstrip#=>"hello"

Removestrailingwhitespacefromstr,returningnilifnochangewasmade.SeealsoString#lstrip!andString#strip!.

"hello".rstrip#=>"hello"

"hello".rstrip!#=>nil

Bothformsiteratethroughstr,matchingthepattern(whichmaybeaRegexporaString).Foreachmatch,aresultisgeneratedandeitheraddedtotheresultarrayorpassedtotheblock.Ifthepatterncontainsnogroups,eachindividualresultconsistsofthematchedstring,$&.Ifthepatterncontainsgroups,eachindividualresultisitselfanarraycontainingoneentrypergroup.

a="cruelworld"

a.scan(/\w+/)#=>["cruel","world"]

a.scan(/.../)#=>["cru","el","wor"]

rstrip→new_str

rstrip!→selfornil

scan(pattern)→arrayscan(pattern){|match,...|block}→str

a.scan(/(...)/)#=>[["cru"],["el"],["wor"]]

a.scan(/(..)(..)/)#=>[["cr","ue"],["l","wo"]]

Andtheblockform:

a.scan(/\w+/){|w|print"<<#{w}>>"}

print"\n"

a.scan(/(.)(.)/){|x,y|printy,x}

print"\n"

produces:

<<cruel>><<world>>

rceulowlr

Ifthestringisinvalidbytesequencethenreplaceinvalidbyteswithgivenreplacementcharacter,elsereturnsself.Ifblockisgiven,replaceinvalidbyteswithreturnedvalueoftheblock.

"abc\u3042\x81".scrub#=>"abc\u3042\uFFFD"

"abc\u3042\x81".scrub("*")#=>"abc\u3042*"

"abc\u3042\xE3\x80".scrub{|bytes|'<'+bytes.unpack('H*'

Ifthestringisinvalidbytesequencethenreplaceinvalidbyteswithgivenreplacementcharacter,elsereturnsself.Ifblockisgiven,replaceinvalidbyteswithreturnedvalueoftheblock.

"abc\u3042\x81".scrub!#=>"abc\u3042\uFFFD"

"abc\u3042\x81".scrub!("*")#=>"abc\u3042*"

scrub→new_strscrub(repl)→new_strscrub{|bytes|}→new_str

scrub!→strscrub!(repl)→strscrub!{|bytes|}→str

"abc\u3042\xE3\x80".scrub!{|bytes|'<'+bytes.unpack('H*'

modifiestheindexthbyteasinteger.

Returnsthecharacterlengthofstr.

ElementReference—Ifpassedasingleindex,returnsasubstringofonecharacteratthatindex.Ifpassedastartindexandalength,returnsasubstringcontaininglengthcharactersstartingattheindex.Ifpassedarange,itsbeginningandendareinterpretedasoffsetsdelimitingthesubstringtobereturned.

Inthesethreecases,ifanindexisnegative,itiscountedfromtheendofthestring.Forthestartand

setbyte(index,integer)→integer

str[index]→new_strornilstr[start,length]→new_strornilstr[range]→new_strornilstr[regexp]→new_strornilstr[regexp,capture]→new_strornilstr[match_str]→new_strornilslice(index)→new_strornilslice(start,length)→new_strornilslice(range)→new_strornilslice(regexp)→new_strornilslice(regexp,capture)→new_strornilslice(match_str)→new_strornil

rangecasesthestartingindexisjustbeforeacharacterandanindexmatchingthestring'ssize.Additionally,anemptystringisreturnedwhenthestartingindexforacharacterrangeisattheendofthestring.

Returnsniliftheinitialindexfallsoutsidethestringorthelengthisnegative.

IfaRegexpissupplied,thematchingportionofthestringisreturned.Ifacapturefollowstheregularexpression,whichmaybeacapturegroupindexorname,followstheregularexpressionthatcomponentoftheMatchDataisreturnedinstead.

Ifamatch_strisgiven,thatstringisreturnedifitoccursinthestring.

Returnsniliftheregularexpressiondoesnotmatchorthematchstringcannotbefound.

a="hellothere"

a[1]#=>"e"

a[2,3]#=>"llo"

a[2..3]#=>"ll"

a[-3,2]#=>"er"

a[7..-2]#=>"her"

a[-4..-2]#=>"her"

a[-2..-4]#=>""

a[11,0]#=>""

a[11]#=>nil

a[12,0]#=>nil

a[12..-1]#=>nil

a[/[aeiou](.)\1/]#=>"ell"

a[/[aeiou](.)\1/,0]#=>"ell"

a[/[aeiou](.)\1/,1]#=>"l"

a[/[aeiou](.)\1/,2]#=>nil

a[/(?<vowel>[aeiou])(?<non_vowel>[^aeiou])/,"non_vowel"

a[/(?<vowel>[aeiou])(?<non_vowel>[^aeiou])/,"vowel"]

a["lo"]#=>"lo"

a["bye"]#=>nil

Deletesthespecifiedportionfromstr,andreturnstheportiondeleted.

string="thisisastring"

string.slice!(2)#=>"i"

string.slice!(3..6)#=>"is"

string.slice!(/s.*t/)#=>"sast"

string.slice!("r")#=>"r"

string#=>"thing"

Dividesstrintosubstringsbasedonadelimiter,returninganarrayofthesesubstrings.

IfpatternisaString,thenitscontentsareusedasthedelimiterwhensplittingstr.Ifpatternisasinglespace,strissplitonwhitespace,withleadingwhitespaceandrunsofcontiguouswhitespacecharactersignored.

IfpatternisaRegexp,strisdividedwherethepatternmatches.Wheneverthepatternmatchesazero-lengthstring,strissplitintoindividualcharacters.Ifpatterncontainsgroups,therespectivematcheswillbereturnedinthearrayaswell.

Ifpatternisomitted,thevalueof$;isused.If$;isnil(whichisthedefault),strissplitonwhitespaceas

slice!(fixnum)→new_strornilslice!(fixnum,fixnum)→new_strornilslice!(range)→new_strornilslice!(regexp)→new_strornilslice!(other_str)→new_strornil

split(pattern=$;,[limit])→anArray

if`'werespecified.

Ifthelimitparameterisomitted,trailingnullfieldsaresuppressed.Iflimitisapositivenumber,atmostthatnumberoffieldswillbereturned(iflimitis1,theentirestringisreturnedastheonlyentryinanarray).Ifnegative,thereisnolimittothenumberoffieldsreturned,andtrailingnullfieldsarenotsuppressed.

WhentheinputstrisemptyanemptyArrayisreturnedasthestringisconsideredtohavenofieldstosplit.

"now'sthetime".split#=>["now's","the","time"]

"now'sthetime".split('')#=>["now's","the","time"]

"now'sthetime".split(//)#=>["","now's","","the","time"]

"1,2.34,56,7".split(%r{,\s*})#=>["1","2.34","56","7"]

"hello".split(//)#=>["h","e","l","l","o"]

"hello".split(//,3)#=>["h","e","llo"]

"himom".split(%r{\s*})#=>["h","i","m","o","m"]

"mellowyellow".split("ello")#=>["m","wy","w"]

"1,2,,3,4,,".split(',')#=>["1","2","","3","4"]

"1,2,,3,4,,".split(',',4)#=>["1","2","","3,4,,"]

"1,2,,3,4,,".split(',',-4)#=>["1","2","","3","4","",""]

"".split(',',-1)#=>[]

Buildsasetofcharactersfromtheother_strparameter(s)usingtheproceduredescribedforString#count.Returnsanewstringwhererunsofthesamecharacterthatoccurinthissetarereplacedbyasinglecharacter.Ifnoargumentsaregiven,allrunsofidenticalcharactersarereplacedbyasinglecharacter.

"yellowmoon".squeeze#=>"yelowmon"

"nowisthe".squeeze("")#=>"nowisthe"

"puttersshootballs".squeeze("m-z")#=>"putersshotballs"

squeeze([other_str]*)→new_str

Squeezesstrinplace,returningeitherstr,ornilifnochangesweremade.

Returnstrueifstrstartswithoneoftheprefixesgiven.

"hello".start_with?("hell")#=>true

#returnstrueifoneoftheprefixesmatches.

"hello".start_with?("heaven","hell")#=>true

"hello".start_with?("heaven","paradise")#=>false

Returnsacopyofstrwithleadingandtrailingwhitespaceremoved.

"hello".strip#=>"hello"

"\tgoodbye\r\n".strip#=>"goodbye"

Removesleadingandtrailingwhitespacefromstr.Returnsnilifstrwasnotaltered.

Returnsacopyofstrwiththefirstoccurrenceofpatternreplacedbythesecondargument.ThepatternistypicallyaRegexp;ifgivenasaString,any

squeeze!([other_str]*)→strornil

start_with?([prefixes]+)→trueorfalse

strip→new_str

strip!→strornil

sub(pattern,replacement)→new_strsub(pattern,hash)→new_strsub(pattern){|match|block}→new_str

regularexpressionmetacharactersitcontainswillbeinterpretedliterally,e.g.'\\d'willmatchabacklashfollowedby'd',insteadofadigit.

IfreplacementisaStringitwillbesubstitutedforthematchedtext.Itmaycontainback-referencestothepattern'scapturegroupsoftheform"\d",wheredisagroupnumber,or"\k<n>",wherenisagroupname.Ifitisadouble-quotedstring,bothback-referencesmustbeprecededbyanadditionalbackslash.However,withinreplacementthespecialmatchvariables,suchas&$,willnotrefertothecurrentmatch.IfreplacementisaStringthatlookslikeapattern'scapturegroupbutisactaullynotapatterncapturegroupe.g."\'",thenitwillhavetobeprecededbytwobackslasheslikeso"\\'".

IfthesecondargumentisaHash,andthematchedtextisoneofitskeys,thecorrespondingvalueisthereplacementstring.

Intheblockform,thecurrentmatchstringispassedinasaparameter,andvariablessuchas$1,$2,$`,$&,and$'willbesetappropriately.Thevaluereturnedbytheblockwillbesubstitutedforthematchoneachcall.

Theresultinheritsanytaintingintheoriginalstringoranysuppliedreplacementstring.

"hello".sub(/[aeiou]/,'*')#=>"h*llo"

"hello".sub(/([aeiou])/,'<\1>')#=>"h<e>llo"

"hello".sub(/./){|s|s.ord.to_s+''}#=>"104ello"

"hello".sub(/(?<foo>[aeiou])/,'*\k<foo>*')#=>"h*e*llo"

'IsSHELLyourpreferredshell?'.sub(/[[:upper:]]{2,}/

#=>"Is/bin/bashyourpreferredshell?"

sub!(pattern,replacement)→strornil

Performsthesamesubstitutionas#subin-place.

Returnsstrifasubstitutionwasperformedornilifnosubstitutionwasperformed.

Returnsthesuccessortostr.Thesuccessoriscalculatedbyincrementingcharactersstartingfromtherightmostalphanumeric(ortherightmostcharacteriftherearenoalphanumerics)inthestring.Incrementingadigitalwaysresultsinanotherdigit,andincrementingaletterresultsinanotherletterofthesamecase.Incrementingnonalphanumericsusestheunderlyingcharacterset'scollatingsequence.

Iftheincrementgeneratesa“carry,''thecharactertotheleftofitisincremented.Thisprocessrepeatsuntilthereisnocarry,addinganadditionalcharacterifnecessary.

"abcd".succ#=>"abce"

"THX1138".succ#=>"THX1139"

"<<koala>>".succ#=>"<<koalb>>"

"1999zzz".succ#=>"2000aaa"

"ZZZ9999".succ#=>"AAAA0000"

"***".succ#=>"**+"

EquivalenttoString#succ,butmodifiesthereceiverinplace.

Returnsabasicn-bitchecksumofthecharactersin

sub!(pattern){|match|block}→strornil

succ→new_strnext→new_str

succ!→strnext!→str

sum(n=16)→integer

str,wherenistheoptionalFixnumparameter,defaultingto16.Theresultissimplythesumofthebinaryvalueofeachbyteinstrmodulo2**n-1.Thisisnotaparticularlygoodchecksum.

Returnsacopyofstrwithuppercasealphabeticcharactersconvertedtolowercaseandlowercasecharactersconvertedtouppercase.Note:caseconversioniseffectiveonlyinASCIIregion.

"Hello".swapcase#=>"hELLO"

"cYbEr_PuNk11".swapcase#=>"CyBeR_pUnK11"

EquivalenttoString#swapcase,butmodifiesthereceiverinplace,returningstr,ornilifnochangesweremade.Note:caseconversioniseffectiveonlyinASCIIregion.

Returnsacomplexwhichdenotesthestringform.Theparserignoresleadingwhitespacesandtrailinggarbage.Anydigitsequencescanbeseparatedbyanunderscore.Returnszerofornullorgarbagestring.

'9'.to_c#=>(9+0i)

'2.5'.to_c#=>(2.5+0i)

'2.5/1'.to_c#=>((5/2)+0i)

'-3/2'.to_c#=>((-3/2)+0i)

'-i'.to_c#=>(0-1i)

'45i'.to_c#=>(0+45i)

'3-4i'.to_c#=>(3-4i)

'-4e2-4e-2i'.to_c#=>(-400.0-0.04i)

'-0.0-0.0i'.to_c#=>(-0.0-0.0i)

'1/2+3/4i'.to_c#=>((1/2)+(3/4)*i)

swapcase→new_str

swapcase!→strornil

to_c→complex

'ruby'.to_c#=>(0+0i)

SeeKernel.Complex.

Returnstheresultofinterpretingleadingcharactersinstrasafloatingpointnumber.Extraneouscharacterspasttheendofavalidnumberareignored.Ifthereisnotavalidnumberatthestartofstr,0.0isreturned.Thismethodneverraisesanexception.

"123.45e1".to_f#=>1234.5

"45.67degrees".to_f#=>45.67

"thx1138".to_f#=>0.0

Returnstheresultofinterpretingleadingcharactersinstrasanintegerbasebase(between2and36).Extraneouscharacterspasttheendofavalidnumberareignored.Ifthereisnotavalidnumberatthestartofstr,0isreturned.Thismethodneverraisesanexceptionwhenbaseisvalid.

"12345".to_i#=>12345

"99redballoons".to_i#=>99

"0a".to_i#=>0

"0a".to_i(16)#=>10

"hello".to_i#=>0

"1100101".to_i(2)#=>101

"1100101".to_i(8)#=>294977

"1100101".to_i(10)#=>1100101

"1100101".to_i(16)#=>17826049

Returnsarationalwhichdenotesthestringform.Theparserignoresleadingwhitespacesandtrailing

to_f→float

to_i(base=10)→integer

to_r→rational

garbage.Anydigitsequencescanbeseparatedbyanunderscore.Returnszerofornullorgarbagestring.

NOTE:'0.3'.#to_risn'tthesameas0.3.to_r.Theformerisequivalentto'3/10'.#to_r,butthelatterisn'tso.

'2'.to_r#=>(2/1)

'300/2'.to_r#=>(150/1)

'-9.2'.to_r#=>(-46/5)

'-9.2e2'.to_r#=>(-920/1)

'1_234_567'.to_r#=>(1234567/1)

'21june09'.to_r#=>(21/1)

'21/06/09'.to_r#=>(7/2)

'bwv1079'.to_r#=>(0/1)

SeeKernel.Rational.

Returnsthereceiver.

ReturnstheSymbolcorrespondingtostr,creatingthesymbolifitdidnotpreviouslyexist.SeeSymbol#id2name.

"Koala".intern#=>:Koala

s='cat'.to_sym#=>:cat

s==:cat#=>true

s='@cat'.to_sym#=>:@cat

s==:@cat#=>true

to_s→strto_str→str

intern→symbolto_sym→symbol

Thiscanalsobeusedtocreatesymbolsthatcannotberepresentedusingthe:xxxnotation.

'catanddog'.to_sym#=>:"catanddog"

Returnsacopyofstrwiththecharactersinfrom_strreplacedbythecorrespondingcharactersinto_str.Ifto_strisshorterthanfrom_str,itispaddedwithitslastcharacterinordertomaintainthecorrespondence.

"hello".tr('el','ip')#=>"hippo"

"hello".tr('aeiou','*')#=>"h*ll*"

"hello".tr('aeiou','AA*')#=>"hAll*"

Bothstringsmayusethec1-c2notationtodenoterangesofcharacters,andfrom_strmaystartwitha^,whichdenotesallcharactersexceptthoselisted.

"hello".tr('a-y','b-z')#=>"ifmmp"

"hello".tr('^aeiou','*')#=>"*e**o"

Thebackslashcharacter</code>canbeusedtoescape<code>^or-andisotherwiseignoredunlessitappearsattheendofarangeortheendofthefrom_strorto_str:

"hello^world".tr("\\^aeiou","*")#=>"h*ll**w*rld"

"hello-world".tr("a\\-eo","*")#=>"h*ll**w*rld"

"hello\r\nworld".tr("\r","")#=>"hello\nworld"

"hello\r\nworld".tr("\\r","")#=>"hello\r\nwold"

"hello\r\nworld".tr("\\\r","")#=>"hello\nworld"

"X['\\b']".tr("X\\","")#=>"['b']"

"X['\\b']".tr("X-\\]","")#=>"'b'"

tr(from_str,to_str)→new_str

Translatesstrinplace,usingthesamerulesasString#tr.Returnsstr,ornilifnochangesweremade.

ProcessesacopyofstrasdescribedunderString#tr,thenremovesduplicatecharactersinregionsthatwereaffectedbythetranslation.

"hello".tr_s('l','r')#=>"hero"

"hello".tr_s('el','*')#=>"h*o"

"hello".tr_s('el','hx')#=>"hhxo"

PerformsString#tr_sprocessingonstrinplace,returningstr,ornilifnochangesweremade.

Decodesstr(whichmaycontainbinarydata)accordingtotheformatstring,returninganarrayofeachvalueextracted.Theformatstringconsistsofasequenceofsingle-characterdirectives,summarizedinthetableattheendofthisentry.Eachdirectivemaybefollowedbyanumber,indicatingthenumberoftimestorepeatwiththisdirective.Anasterisk(“*'')willuseupallremainingelements.ThedirectivessSiIlLmayeachbefollowedbyanunderscore(“_'')orexclamationmark(“!'')tousetheunderlyingplatform'snativesizeforthespecifiedtype;otherwise,itusesaplatform-independentconsistentsize.Spacesareignoredintheformatstring.SeealsoArray#pack.

tr!(from_str,to_str)→strornil

tr_s(from_str,to_str)→new_str

tr_s!(from_str,to_str)→strornil

unpack(format)→anArray

"abc\00\\00aabc\00\\00"".unpack('A6Z6')#=>["abc","abc"]

"abc\00\\00"".unpack('a3a3')#=>["abc","\000\000"]

"abc\00aabc\00"".unpack('Z*Z*')#=>["abc","abc"]

"aa".unpack('b8B8')#=>["10000110","01100001"]

"aaa".unpack('h2H2c')#=>["16","61",97]

"\xfe\xff\xfe\xff".unpack('sS')#=>[-2,65534]

"now=20is".unpack('M*')#=>["nowis"]

"whole".unpack('xax2aX2aX1aX2a')#=>["h","e","l","l","o"]

ThistablesummarizesthevariousformatsandtheRubyclassesreturnedbyeach.

Integer||

Directive|Returns|Meaning

-----------------------------------------------------------------

C|Integer|8-bitunsigned(unsignedchar)

S|Integer|16-bitunsigned,nativeendian(uint16_t)

L|Integer|32-bitunsigned,nativeendian(uint32_t)

Q|Integer|64-bitunsigned,nativeendian(uint64_t)

c|Integer|8-bitsigned(signedchar)

s|Integer|16-bitsigned,nativeendian(int16_t)

l|Integer|32-bitsigned,nativeendian(int32_t)

q|Integer|64-bitsigned,nativeendian(int64_t)

S_,S!|Integer|unsignedshort,nativeendian

I,I_,I!|Integer|unsignedint,nativeendian

L_,L!|Integer|unsignedlong,nativeendian

Q_,Q!|Integer|unsignedlonglong,nativeendian(ArgumentError

||(Q_andQ!isavailablesinceRuby2.1.)

s_,s!|Integer|signedshort,nativeendian

i,i_,i!|Integer|signedint,nativeendian

l_,l!|Integer|signedlong,nativeendian

q_,q!|Integer|signedlonglong,nativeendian(ArgumentError

||(q_andq!isavailablesinceRuby2.1.)

S>L>Q>|Integer|sameasthedirectiveswithout">"except

s>l>q>||bigendian

S!>I!>||(availablesinceRuby1.9.3)

L!>Q!>||"S>"issameas"n"

s!>i!>||"L>"issameas"N"

l!>q!>||

S<L<Q<|Integer|sameasthedirectiveswithout"<"except

s<l<q<||littleendian

S!<I!<||(availablesinceRuby1.9.3)

L!<Q!<||"S<"issameas"v"

s!<i!<||"L<"issameas"V"

l!<q!<||

n|Integer|16-bitunsigned,network(big-endian)byteorder

N|Integer|32-bitunsigned,network(big-endian)byteorder

v|Integer|16-bitunsigned,VAX(little-endian)byteorder

V|Integer|32-bitunsigned,VAX(little-endian)byteorder

U|Integer|UTF-8character

w|Integer|BER-compressedinteger(seeArray.pack)

Float||

-----------------------------------------------------------------

D,d|Float|double-precision,nativeformat

F,f|Float|single-precision,nativeformat

E|Float|double-precision,little-endianbyteorder

e|Float|single-precision,little-endianbyteorder

G|Float|double-precision,network(big-endian)byteorder

g|Float|single-precision,network(big-endian)byteorder

String||

-----------------------------------------------------------------

A|String|arbitrarybinarystring(removetrailingnullsandASCIIspaces)

a|String|arbitrarybinarystring

Z|String|null-terminatedstring

B|String|bitstring(MSBfirst)

b|String|bitstring(LSBfirst)

H|String|hexstring(highnibblefirst)

h|String|hexstring(lownibblefirst)

u|String|UU-encodedstring

M|String|quoted-printable,MIMEencoding(seeRFC2045)

m|String|base64encodedstring(RFC2045)(default)

||base64encodedstring(RFC4648)iffollowedby0

P|String|pointertoastructure(fixed-lengthstring)

p|String|pointertoanull-terminatedstring

Misc.||

-----------------------------------------------------------------

@|---|skiptotheoffsetgivenbythelengthargument

X|---|skipbackwardonebyte

x|---|skipforwardonebyte

Returnsacopyofstrwithalllowercaselettersreplacedwiththeiruppercasecounterparts.Theoperationislocaleinsensitive—onlycharacters“a''to“z''areaffected.Note:casereplacementiseffectiveonlyinASCIIregion.

"hEllO".upcase#=>"HELLO"

Upcasesthecontentsofstr,returningnilifnochangesweremade.Note:casereplacementiseffectiveonlyinASCIIregion.

Iteratesthroughsuccessivevalues,startingatstrandendingatother_strinclusive,passingeachvalueinturntotheblock.TheString#succmethodisusedtogenerateeachvalue.Ifoptionalsecondargumentexclusiveisomittedorisfalse,thelastvaluewillbeincluded;otherwiseitwillbeexcluded.

"a8".upto("b6"){|s|prints,''}

forsin"a8".."b6"

prints,''

upcase→new_str

upcase!→strornil

upto(other_str,exclusive=false){|s|block}→strupto(other_str,exclusive=false)→an_enumerator

produces:

a8a9b0b1b2b3b4b5b6

Ifstrandother_strcontainsonlyasciinumericcharacters,botharerecognizedasdecimalnumbers.Inaddition,thewidthofstring(e.g.leadingzeros)ishandledappropriately.

"9".upto("11").to_a#=>["9","10","11"]

"25".upto("5").to_a#=>[]

"07".upto("11").to_a#=>["07","08","09","10","11"]

Returnstrueforastringwhichencodedcorrectly.

"\xc2\xa1".force_encoding("UTF-8").valid_encoding?#=>true

"\xc2".force_encoding("UTF-8").valid_encoding?#=>false

"\x80".force_encoding("UTF-8").valid_encoding?#=>false

valid_encoding?→trueorfalse

classStruct

InFilesprocess.cstruct.c

ParentObject

Constants

PublicClassMethods

ThefirsttwoformsareusedtocreateanewStruct

new([class_name][,member_name]+>)→StructClassnew([class_name][,member_name]+>){|StructClass|block}→StructClassnew(value,...)→objStructClass[value,...]→obj

subclassclass_namethatcancontainavalueforeachmember_name.ThissubclasscanbeusedtocreateinstancesofthestructurelikeanyotherClass.

Iftheclass_nameisomittedananonymousstructureclasswillbecreated.Otherwise,thenameofthisstructwillappearasaconstantinclassStruct,soitmustbeuniqueforallStructsinthesystemandmuststartwithacapitalletter.Assigningastructureclasstoaconstantalsogivestheclassthenameoftheconstant.

#CreateastructurewithanameunderStruct

Struct.new("Customer",:name,:address)

#=>Struct::Customer

Struct::Customer.new("Dave","123Main")

#=>#<structStruct::Customername="Dave",address="123Main">

IfablockisgivenitwillbeevaluatedinthecontextofStructClass,passingthecreatedclassasaparameter:

Customer=Struct.new(:name,:address)do

defgreeting

"Hello#{name}!"

Customer.new("Dave","123Main").greeting#=>"HelloDave!"

Thisistherecommendedwaytocustomizeastruct.Subclassingananonymousstructcreatesanextraanonymousclassthatwillneverbeused.

Thelasttwoformscreateanewinstanceofastructsubclass.Thenumberofvalueparametersmustbelessthanorequaltothenumberofattributesdefinedforthestructure.Unsetparametersdefaulttonil.PassingmoreparametersthannumberofattributeswillraiseanArgumentError.

#Createastructurenamedbyitsconstant

Customer=Struct.new(:name,:address)

#=>Customer

Customer.new("Dave","123Main")

#=>#<structCustomername="Dave",address="123Main">

Equality—Returnstrueifotherhasthesamestructsubclassandhasequalmembervalues(accordingtoObject#==).

Customer=Struct.new(:name,:address,:zip)

joe=Customer.new("JoeSmith","123Maple,AnytownNC"

joejr=Customer.new("JoeSmith","123Maple,AnytownNC"

jane=Customer.new("JaneDoe","456Elm,AnytownNC"

joe==joejr#=>true

joe==jane#=>false

AttributeReference—Returnsthevalueofthegivenstructmemberorthememberatthegivenindex.RaisesNameErrorifthememberdoesnotexistandIndexErroriftheindexisoutofrange.

joe["name"]#=>"JoeSmith"

joe[:name]#=>"JoeSmith"

joe[0]#=>"JoeSmith"

struct==other→trueorfalse

struct[member]→anObjectstruct[index]→anObject

AttributeAssignment—Setsthevalueofthegivenstructmemberorthememberatthegivenindex.RaisesNameErrorifthenamedoesnotexistandIndexErroriftheindexisoutofrange.

joe["name"]="Luke"

joe[:zip]="90210"

joe.name#=>"Luke"

joe.zip#=>"90210"

Yieldsthevalueofeachstructmemberinorder.Ifnoblockisgivenanenumeratorisreturned.

joe.each{|x|puts(x)}

Produces:

JoeSmith

123Maple,AnytownNC

Yieldsthenameandvalueofeachstructmemberinorder.Ifnoblockisgivenanenumeratorisreturned.

struct[name]=obj→objstruct[index]=obj→obj

each{|obj|block}→structeach→an_enumerator

each_pair{|sym,obj|block}→structeach_pair→an_enumerator

joe.each_pair{|name,value|puts("#{name}=>#{value}"

Produces:

name=>JoeSmith

address=>123Maple,AnytownNC

zip=>12345

Hashequality—otherandstructrefertothesamehashkeyiftheyhavethesamestructsubclassandhaveequalmembervalues(accordingtoObject#eql?).

Returnsahashvaluebasedonthisstruct'scontents(seeObject#hash).

SeealsoObject#hash.

Describethecontentsofthisstructinastring.

Alsoaliasedas:to_s

Returnsthenumberofstructmembers.

joe.length#=>3

hash→fixnum

Returnsthestructmembersasanarrayofsymbols:

joe.members#=>[:name,:address,:zip]

YieldseachmembervaluefromthestructtotheblockandreturnsanArraycontainingthemembervaluesfromthestructforwhichthegivenblockreturnsatruevalue(equivalenttoEnumerable#select).

Lots=Struct.new(:a,:b,:c,:d,:e,:f)

l=Lots.new(11,22,33,44,55,66)

l.select{|v|(v%2).zero?}#=>[22,44,66]

Returnsthenumberofstructmembers.

joe.length#=>3

ReturnsthevaluesforthisstructasanArray.

members→array

select{|i|block}→arrayselect→an_enumerator

to_a→arrayvalues→array

joe.to_a[1]#=>"123Maple,AnytownNC"

ReturnsaHashcontainingthenamesandvaluesforthestruct'smembers.

joe.to_h[:address]#=>"123Maple,AnytownNC"

Aliasfor:inspect

ReturnsthevaluesforthisstructasanArray.

joe.to_a[1]#=>"123Maple,AnytownNC"

ReturnsthestructmembervaluesforeachselectorasanArray.AselectormaybeeitheranIntegeroffsetoraRangeofoffsets(asinArray#values_at).

joe.values_at0,2#=>["JoeSmith",12345]

to_h→hash

to_s()

to_a→arrayvalues→array

values_at(selector,...)→an_array

classSymbolSymbolobjectsrepresentnamesandsomestringsinsidetheRubyinterpreter.Theyaregeneratedusingthe:nameand:"string"literalssyntax,andbythevariousto_symmethods.ThesameSymbolobjectwillbecreatedforagivennameorstringforthedurationofaprogram'sexecution,regardlessofthecontextormeaningofthatname.ThusifFredisaconstantinonecontext,amethodinanother,andaclassinathird,theSymbol:Fredwillbethesameobjectinallthreecontexts.

moduleOne

classFred

$f1=:Fred

moduleTwo

Fred=1

$f2=:Fred

defFred()

$f3=:Fred

$f1.object_id#=>2514190

$f2.object_id#=>2514190

$f3.object_id#=>2514190

InFilesstring.c

ParentObject

PublicClassMethods

ReturnsanarrayofallthesymbolscurrentlyinRuby'ssymboltable.

Symbol.all_symbols.size#=>903

Symbol.all_symbols[1,20]#=>[:floor,:ARGV,:Binding,:symlink,

:chown,:EOFError,:$;

:LOCK_SH,:"setuid?",:

:default_proc,:compact

:Tms,:getwd,:$=,:ThreadGroup

:wait2,:$>]

Comparessymbolwithother_symbolaftercallingto_soneachofthesymbols.Returns-1,0,+1ornildependingonwhethersymbolislessthan,equalto,orgreaterthanother_symbol.

+nil+isreturnedifthetwovaluesareincomparable.

SeeString#<=>formoreinformation.

all_symbols→array

symbol<=>other_symbol→-1,0,+1ornil

Equality—Ifsymandobjareexactlythesamesymbol,returnstrue.

Returnssym.to_s=~obj.

Returnssym.to_s[].

Sameassym.to_s.capitalize.intern.

Case-insensitiveversionofSymbol#<=>.

Sameassym.to_s.downcase.intern.

Returnsthatsymis:“”ornot.

sym==obj→trueorfalse

sym=~obj→fixnumornilmatch(obj)→fixnumornil

sym[idx]→charsym[b,n]→stringslice(idx)→charslice(b,n)→string

capitalize→symbol

casecmp(other)→-1,0,+1ornil

downcase→symbol

ReturnstheEncodingobjectthatrepresentstheencodingofsym.

Returnsthenameorstringcorrespondingtosym.

:fred.id2name#=>"fred"

Returnstherepresentationofsymasasymbolliteral.

:fred.inspect#=>":fred"

Ingeneral,to_symreturnstheSymbolcorrespondingtoanobject.Assymisalreadyasymbol,selfisreturnedinthiscase.

Sameassym.to_s.length.

Returnssym.to_s=~obj.

encoding→encoding

id2name→stringto_s→string

inspect→string

to_sym→symintern→sym

sym=~obj→fixnumornilmatch(obj)→fixnumornil

Sameassym.to_s.succ.intern.

Sameassym.to_s.length.

Returnssym.to_s[].

Sameassym.to_s.succ.intern.

Sameassym.to_s.swapcase.intern.

ReturnsaProcobjectwhichrespondtothegivenmethodbysym.

(1..3).collect(&:to_s)#=>["1","2","3"]

Returnsthenameorstringcorrespondingtosym.

:fred.id2name#=>"fred"

sym[idx]→charsym[b,n]→stringslice(idx)→charslice(b,n)→string

swapcase→symbol

to_proc

id2name→stringto_s→string

Ingeneral,to_symreturnstheSymbolcorrespondingtoanobject.Assymisalreadyasymbol,selfisreturnedinthiscase.

Sameassym.to_s.upcase.intern.

to_sym→symintern→sym

upcase→symbol

classSyntaxErrorRaisedwhenencounteringRubycodewithaninvalidsyntax.

eval("1+1=2")

raisestheexception:

SyntaxError:(eval):1:syntaxerror,unexpected'=',expecting$end

InFileserror.c

ParentScriptError

classSystemCallErrorSystemCallErroristhebaseclassforalllow-levelplatform-dependenterrors.

TheerrorsavailableonthecurrentplatformaresubclassesofSystemCallErrorandaredefinedintheErrnomodule.

File.open("does/not/exist")

raisestheexception:

Errno::ENOENT:Nosuchfileordirectory-does/not/exist

InFileserror.c

ParentStandardError

PublicClassMethods

ReturntrueifthereceiverisagenericSystemCallError,oriftheerrornumbersselfand

system_call_error===other→trueorfalse

otherarethesame.

Iferrnocorrespondstoaknownsystemerrorcode,constructstheappropriateErrnoclassforthaterror,otherwiseconstructsagenericSystemCallErrorobject.Theerrornumberissubsequentlyavailableviatheerrnomethod.

ReturnthisSystemCallError'serrornumber.

new(msg,errno)→system_call_error_subclass

errno→fixnum

classSystemExitRaisedbyexittoinitiatetheterminationofthescript.

InFileserror.c

ParentException

PublicClassMethods

CreateanewSystemExitexceptionwiththegivenstatusandmessage.Statusistrue,false,oraninteger.Ifstatusisnotgiven,trueisused.

Returnthestatusvalueassociatedwiththissystemexit.

new→system_exitnew(status)→system_exitnew(status,msg)→system_exitnew(msg)→system_exit

status→fixnum

Returnstrueifexitingsuccessful,falseifnot.

success?→trueorfalse

classSystemStackErrorRaisedincaseofastackoverflow.

defme_myself_and_i

me_myself_and_i

raisestheexception:

SystemStackError:stackleveltoodeep

InFilesproc.c

ParentException

classThreadThreadsaretheRubyimplementationforaconcurrentprogrammingmodel.

ProgramsthatrequiremultiplethreadsofexecutionareaperfectcandidateforRuby'sThreadclass.

Forexample,wecancreateanewthreadseparatefromthemainthread'sexecutionusing::new.

thr=Thread.new{puts"Whatsthebigdeal"}

Thenweareabletopausetheexecutionofthemainthreadandallowournewthreadtofinish,usingjoin:

thr.join#=>"Whatsthebigdeal"

Ifwedon'tcallthr.joinbeforethemainthreadterminates,thenallotherthreadsincludingthrwillbekilled.

Alternatively,youcanuseanarrayforhandlingmultiplethreadsatonce,likeinthefollowingexample:

threads=[]

threads<<Thread.new{puts"Whatsthebigdeal"}

threads<<Thread.new{3.times{puts"Threadsarefun!"}}

Aftercreatingafewthreadswewaitforthemalltofinishconsecutively.

threads.each{|thr|thr.join}

Threadinitialization

Inordertocreatenewthreads,Rubyprovides::new,::start,and::fork.Ablockmustbeprovidedwitheachofthesemethods,otherwiseaThreadErrorwillberaised.

WhensubclassingtheThreadclass,theinitializemethodofyoursubclasswillbeignoredby::startand::fork.Otherwise,besuretocallsuperinyourinitializemethod.

Threadtermination

Forterminatingthreads,Rubyprovidesavarietyofwaystodothis.

Theclassmethod::kill,ismeanttoexitagiventhread:

thr=Thread.new{...}

Thread.kill(thr)#sendsexit()tothr

Alternatively,youcanusetheinstancemethod

exit,oranyofitsaliaseskillorterminate.

thr.exit

Threadstatus

Rubyprovidesafewinstancemethodsforqueryingthestateofagiventhread.Togetastringwiththecurrentthread'sstateusestatus

thr=Thread.new{sleep}

thr.status#=>"sleep"

thr.exit

thr.status#=>false

Youcanalsousealive?totellifthethreadisrunningorsleeping,andstop?ifthethreadisdeadorsleeping.

Threadvariablesandscope

Sincethreadsarecreatedwithblocks,thesamerulesapplytootherRubyblocksforvariablescope.Anylocalvariablescreatedwithinthisblockareaccessibletoonlythisthread.

Fiber-localvs.Thread-local

EachfiberhasitsownbucketforThread#[]storage.Whenyousetanewfiber-localitisonlyaccessiblewithinthisFiber.Toillustrate:

Thread.new{

Thread.current[:foo]="bar"

Fiber.new{

pThread.current[:foo]#=>nil

}.resume

}.join

Thisexampleuses#[]forgettingand#[]=forsettingfiber-locals,youcanalsousekeystolistthefiber-localsforagiventhreadandkey?tocheckifafiber-localexists.

Whenitcomestothread-locals,theyareaccessiblewithintheentirescopeofthethread.Giventhefollowingexample:

Thread.new{

Thread.current.thread_variable_set(:foo,1)

pThread.current.thread_variable_get(:foo)#=>1

Fiber.new{

Thread.current.thread_variable_set(:foo,2)

}.resume

}.join

Youcanseethatthethread-local:foocarriedoverintothefiberandwaschangedto2bytheendofthethread.

Thisexamplemakesuseofthread_variable_settocreatenewthread-locals,andthread_variable_gettoreferencethem.

Thereisalsothread_variablestolistallthread-locals,andthread_variable?tocheckifagiven

thread-localexists.

Exceptionhandling

Anythreadcanraiseanexceptionusingtheraiseinstancemethod,whichoperatessimilarlytoKernel#raise.

However,it'simportanttonotethatanexceptionthatoccursinanythreadexceptthemainthreaddependsonabort_on_exception.Thisoptionisfalsebydefault,meaningthatanyunhandledexceptionwillcausethethreadtoterminatesilentlywhenwaitedonbyeitherjoinorvalue.Youcanchangethisdefaultbyeitherabort_on_exception=trueorsetting$::DEBUGtotrue.

Withtheadditionoftheclassmethod::handle_interrupt,youcannowhandleexceptionsasynchronouslywiththreads.

Scheduling

Rubyprovidesafewwaystosupportschedulingthreadsinyourprogram.

Thefirstwayisbyusingtheclassmethod::stop,toputthecurrentrunningthreadtosleepandscheduletheexecutionofanotherthread.

Onceathreadisasleep,youcanusetheinstancemethodwakeuptomarkyourthreadas

eligibleforscheduling.

Youcanalsotry::pass,whichattemptstopassexecutiontoanotherthreadbutisdependentontheOSwhetherarunningthreadwillswitchornot.Thesamegoesforpriority,whichletsyouhinttothethreadschedulerwhichthreadsyouwanttotakeprecedencewhenpassingexecution.ThismethodisalsodependentontheOSandmaybeignoredonsomeplatforms.

InFilesthread.cvm.cvm_trace.c

ParentObject

PublicClassMethods

Returnsthethreaddebuglevel.AvailableonlyifcompiledwithTHREAD_DEBUG=-1.

Setsthethreaddebuglevel.AvailableonlyifcompiledwithTHREAD_DEBUG=-1.

DEBUG→num

DEBUG=num

Returnsthestatusoftheglobal“abortonexception''condition.

Thedefaultisfalse.

Whensettotrue,allthreadswillabort(theprocesswillexit(0))ifanexceptionisraisedinanythread.

Canalsobespecifiedbytheglobal$::DEBUGflagorcommandlineoption-d.

Seealso::abort_on_exception=.

Thereisalsoaninstancelevelmethodtosetthisforaspecificthread,seeabort_on_exception.

Whensettotrue,allthreadswillabortifanexceptionisraised.Returnsthenewstate.

Thread.abort_on_exception=true

t1=Thread.newdo

puts"Innewthread"

raise"Exceptionfromthread"

sleep(1)

puts"notreached"

Thiswillproduce:

Innewthread

prog.rb:4:Exceptionfromthread(RuntimeError)

fromprog.rb:2:in`initialize'

fromprog.rb:2:in`new'

fromprog.rb:2

Seealso::abort_on_exception.

Thereisalsoaninstancelevelmethodtosetthisforaspecificthread,seeabort_on_exception=.

abort_on_exception→trueorfalse

abort_on_exception=boolean→trueorfalse

Returnsthecurrentlyexecutingthread.

Thread.current#=>#<Thread:0x401bdf4crun>

Terminatesthecurrentlyrunningthreadandschedulesanotherthreadtoberun.

Ifthisthreadisalreadymarkedtobekilled,::exitreturnstheThread.

Ifthisisthemainthread,orthelastthread,exittheprocess.

Basicallythesameas::new.However,ifclassThreadissubclassed,thencallingstartinthatsubclasswillnotinvokethesubclass'sinitializemethod.

Changesasynchronousinterrupttiming.

interruptmeansasynchronouseventandcorrespondingprocedureby#raise,#kill,signaltrap(notsupportedyet)andmainthreadtermination(ifmainthreadterminates,thenallotherthreadwillbekilled).

ThegivenhashhaspairslikeExceptionClass=>:TimingSymbol.WheretheExceptionClassisthe

current→thread

exit→thread

start([args]*){|args|block}→threadfork([args]*){|args|block}→thread

handle_interrupt(hash){...}→resultoftheblock

interrupthandledbythegivenblock.TheTimingSymbolcanbeoneofthefollowingsymbols:

:immediate

Invokeinterruptsimmediately.

:on_blocking

InvokeinterruptswhileBlockingOperation.

:never

Neverinvokeallinterrupts.

BlockingOperationmeansthattheoperationwillblockthecallingthread,suchasreadandwrite.OnCRubyimplementation,BlockingOperationisanyoperationexecutedwithoutGVL.

Maskedasynchronousinterruptsaredelayeduntiltheyareenabled.Thismethodissimilartosigprocmask(3).

NOTEAsynchronousinterruptsaredifficulttouse.

Ifyouneedtocommunicatebetweenthreads,pleaseconsidertouseanotherwaysuchasQueue.

Orusethemwithdeepunderstandingaboutthismethod.

UsageInthisexample,wecanguardfrom#raiseexceptions.

Usingthe:neverTimingSymboltheRuntimeErrorexceptionwillalwaysbeignoredinthefirstblockofthemainthread.Inthesecond::handle_interruptblockwecanpurposefullyhandleRuntimeErrorexceptions.

th=Thread.newdo

Thread.handle_interrupt(RuntimeError=>:never){

#Youcanwriteresourceallocationcodesafely.

Thread.handle_interrupt(RuntimeError=>:immediate

ensure

#Youcanwriteresourcedeallocationcodesafely.

Thread.pass

th.raise"stop"

WhileweareignoringtheRuntimeErrorexception,it'ssafetowriteourresourceallocationcode.Then,theensureblockiswherewecansafelydeallocateyourresources.

GuardingfromTimeout::ErrorInthenextexample,wewillguardfromtheTimeout::Errorexception.ThiswillhelppreventfromleakingresourceswhenTimeout::Errorexceptionsoccurduringnormalensureclause.ForthisexampleweusethehelpofthestandardlibraryTimeout,fromlib/timeout.rb

require'timeout'

Thread.handle_interrupt(Timeout::Error=>:never){

timeout(10){

#Timeout::Errordoesn'toccurhere

Thread.handle_interrupt(Timeout::Error=>:on_blocking

#possibletobekilledbyTimeout::Error

#whileblockingoperation

#Timeout::Errordoesn'toccurhere

Inthefirstpartofthetimeoutblock,wecanrelyonTimeout::Errorbeingignored.ThenintheTimeout::Error=>:on_blockingblock,anyoperationthatwillblockthecallingthreadissusceptibletoaTimeout::Errorexceptionbeingraised.

StackcontrolsettingsIt'spossibletostackmultiplelevelsof::handle_interruptblocksinordertocontrolmorethanoneExceptionClassandTimingSymbolatatime.

Thread.handle_interrupt(FooError=>:never){

Thread.handle_interrupt(BarError=>:never){

#FooErrorandBarErrorareprohibited.

InheritancewithExceptionClassAllexceptionsinheritedfromtheExceptionClassparameterwillbeconsidered.

Thread.handle_interrupt(Exception=>:never){

#allexceptionsinheritedfromExceptionareprohibited.

Causesthegiventhreadtoexit,seealso::exit.

count=0

a=Thread.new{loop{count+=1}}

sleep(0.1)#=>0

Thread.kill(a)#=>#<Thread:0x401b3d30dead>

count#=>93947

a.alive?#=>false

kill(thread)→thread

list→array

ReturnsanarrayofThreadobjectsforallthreadsthatareeitherrunnableorstopped.

Thread.new{sleep(200)}

Thread.new{1000000.times{|i|i*i}}

Thread.new{Thread.stop}

Thread.list.each{|t|pt}

Thiswillproduce:

#<Thread:0x401b3e84sleep>

#<Thread:0x401b3f38run>

#<Thread:0x401b3fb0sleep>

#<Thread:0x401bdf4crun>

Returnsthemainthread.

Createsanewthreadexecutingthegivenblock.

Anyargsgivento::newwillbepassedtotheblock:

arr=[]

a,b,c=1,2,3

Thread.new(a,b,c){|d,e,f|arr<<d<<e<<f}.join

arr#=>[1,2,3]

AThreadErrorexceptionisraisedif::newiscalledwithoutablock.

Ifyou'regoingtosubclassThread,besuretocallsuperinyourinitializemethod,otherwiseaThreadErrorwillberaised.

main→thread

new{...}→threadnew(*args,&proc)→threadnew(*args){|args|...}→thread

pass→nil

Givethethreadschedulerahinttopassexecutiontoanotherthread.Arunningthreadmayormaynotswitch,itdependsonOSandprocessor.

Returnswhetherornottheasynchronousqueueisempty.

Since::handle_interruptcanbeusedtodeferasynchronousevents,thismethodcanbeusedtodetermineifthereareanydeferredevents.

Ifyoufindthismethodreturnstrue,thenyoumayfinish:neverblocks.

Forexample,thefollowingmethodprocessesdeferredasynchronouseventsimmediately.

defThread.kick_interrupt_immediately

Thread.handle_interrupt(Object=>:immediate){

Thread.pass

Iferrorisgiven,thencheckonlyforerrortypedeferredevents.

Usageth=Thread.new{

Thread.handle_interrupt(RuntimeError=>:on_blocking

whiletrue

#reachsafepointtoinvokeinterrupt

ifThread.pending_interrupt?

Thread.handle_interrupt(Object=>:immediate){}

pending_interrupt?(error=nil)→true/false

th.raise#stopthread

Thisexamplecanalsobewrittenasthefollowing,whichyoushouldusetoavoidasynchronousinterrupts.

flag=true

th=Thread.new{

Thread.handle_interrupt(RuntimeError=>:on_blocking

whiletrue

#reachsafepointtoinvokeinterrupt

breakifflag==false

flag=false#stopthread

Basicallythesameas::new.However,ifclassThreadissubclassed,thencallingstartinthatsubclasswillnotinvokethesubclass'sinitializemethod.

Stopsexecutionofthecurrentthread,puttingitintoa“sleep''state,andschedulesexecutionofanotherthread.

a=Thread.new{print"a";Thread.stop;print"c"}

sleep0.1whilea.status!='sleep'

print"b"

a.join

start([args]*){|args|block}→threadfork([args]*){|args|block}→thread

stop→nil

#=>"abc"

AttributeReference—Returnsthevalueofafiber-localvariable(currentthread'srootfiberifnotexplicitlyinsideaFiber),usingeitherasymbolorastringname.Ifthespecifiedvariabledoesnotexist,returnsnil.

Thread.new{Thread.current["name"]="A"},

Thread.new{Thread.current[:name]="B"},

Thread.new{Thread.current["name"]="C"}

].eachdo|th|

th.join

puts"#{th.inspect}:#{th[:name]}"

Thiswillproduce:

#<Thread:0x00000002a54220dead>:A

#<Thread:0x00000002a541a8dead>:B

#<Thread:0x00000002a54130dead>:C

Thread#[]andThread#[]=arenotthread-localbutfiber-local.ThisconfusiondidnotexistinRuby1.8becausefibersareonlyavailablesinceRuby1.9.Ruby1.9choosesthatthemethodsbehavesfiber-localtosavefollowingidiomfordynamicscope.

defmeth(newvalue)

oldvalue=Thread.current[:name]

Thread.current[:name]=newvalue

ensure

Thread.current[:name]=oldvalue

thr[sym]→objornil

Theidiommaynotworkasdynamicscopeifthemethodsarethread-localandagivenblockswitchesfiber.

f=Fiber.new{

meth(1){

Fiber.yield

meth(2){

f.resume

pThread.current[:name]

#=>niliffiber-local

#=>2ifthread-local(Thevalue2isleakedtooutsideofmethmethod.)

Forthread-localvariables,pleaseseethread_variable_getandthread_variable_set.

AttributeAssignment—Setsorcreatesthevalueofafiber-localvariable,usingeitherasymbolorastring.

SeealsoThread#[].

Forthread-localvariables,pleaseseethread_variable_setandthread_variable_get.

Returnsthestatusofthethread-local“abortonexception''conditionforthisthr.

Thedefaultisfalse.

Seealsoabort_on_exception=.

Thereisalsoaclasslevelmethodtosetthisforall

thr[sym]=obj→obj

abort_on_exception→trueorfalse

threads,see::abort_on_exception.

Whensettotrue,allthreads(includingthemainprogram)willabortifanexceptionisraisedinthisthr.

Theprocesswilleffectivelyexit(0).

Seealsoabort_on_exception.

Thereisalsoaclasslevelmethodtosetthisforallthreads,see::abort_on_exception=.

Addsprocasahandlerfortracing.

See#set_trace_funcandKernel#set_trace_func.

Returnstrueifthrisrunningorsleeping.

thr=Thread.new{}

thr.join#=>#<Thread:0x401b3fb0dead>

Thread.current.alive?#=>true

thr.alive?#=>false

Seealsostop?andstatus.

Returnsthecurrentbacktraceofthetargetthread.

Returnstheexecutionstackforthetargetthread—an

abort_on_exception=boolean→trueorfalse

add_trace_func(proc)→proc

alive?→trueorfalse

backtrace→array

backtrace_locations(*args)→arrayornil

arraycontainingbacktracelocationobjects.

SeeThread::Backtrace::Locationformoreinformation.

ThismethodbehavessimilarlytoKernel#caller_locationsexceptitappliestoaspecificthread.

Terminatesthrandschedulesanotherthreadtoberun.

Ifthisthreadisalreadymarkedtobekilled,exitreturnstheThread.

Ifthisisthemainthread,orthelastthread,exitstheprocess.

ReturnstheThreadGroupwhichcontainsthegiventhread,orreturnsnilifthrisnotamemberofanygroup.

Thread.main.group#=>#<ThreadGroup:0x4029d914>

Dumpthename,id,andstatusofthrtoastring.

Thecallingthreadwillsuspendexecutionandrunthis

exit→thrornilkill→thrornilterminate→thrornil

group→thgrpornil

inspect→string

join→thrjoin(limit)→thr

Doesnotreturnuntilthrexitsoruntilthegivenlimitsecondshavepassed.

Ifthetimelimitexpires,nilwillbereturned,otherwisethrisreturned.

Anythreadsnotjoinedwillbekilledwhenthemainprogramexits.

Ifthrhadpreviouslyraisedanexceptionandthe::abort_on_exceptionor$::DEBUGflagsarenotset,(sotheexceptionhasnotyetbeenprocessed),itwillbeprocessedatthistime.

a=Thread.new{print"a";sleep(10);print"b";print

x=Thread.new{print"x";Thread.pass;print"y";print

x.join#Letthreadxfinish,threadawillbekilledonexit.

#=>"axyz"

Thefollowingexampleillustratesthelimitparameter.

y=Thread.new{4.times{sleep0.1;puts'tick...'}}

puts"Waiting"untily.join(0.15)

Thiswillproduce:

tick...

Waiting

tick...

Waiting

tick...

Returnstrueifthegivenstring(orsymbol)existsasafiber-localvariable.

key?(sym)→trueorfalse

me=Thread.current

me[:oliver]="a"

me.key?(:oliver)#=>true

me.key?(:stanley)#=>false

Returnsanarrayofthenamesofthefiber-localvariables(asSymbols).

thr=Thread.newdo

Thread.current[:cat]='meow'

Thread.current["dog"]='woof'

thr.join#=>#<Thread:0x401b3f10dead>

thr.keys#=>[:dog,:cat]

Returnswhetherornottheasynchronousqueueisemptyforthetargetthread.

Iferrorisgiven,thencheckonlyforerrortypedeferredevents.

See::pending_interrupt?formoreinformation.

keys→array

pending_interrupt?(error=nil)→true/false

Returnsthepriorityofthr.Defaultisinheritedfromthecurrentthreadwhichcreatingthenewthread,orzerofortheinitialmainthread;higher-prioritythreadwillrunmorefrequentlythanlower-prioritythreads(butlower-prioritythreadscanalsorun).

ThisisjusthintforRubythreadscheduler.Itmaybeignoredonsomeplatform.

Thread.current.priority#=>0

Setsthepriorityofthrtointeger.Higher-prioritythreadswillrunmorefrequentlythanlower-prioritythreads(butlower-prioritythreadscanalsorun).

ThisisjusthintforRubythreadscheduler.Itmaybeignoredonsomeplatform.

count1=count2=0

a=Thread.newdo

loop{count1+=1}

a.priority=-1

b=Thread.newdo

loop{count2+=1}

b.priority=-2

sleep1#=>1

count1#=>622504

count2#=>5832

Raisesanexceptionfromthegiventhread.Thecaller

priority→integer

priority=integer→thr

raiseraise(string)raise(exception[,string[,array]])

doesnothavetobethr.SeeKernel#raiseformoreinformation.

Thread.abort_on_exception=true

a=Thread.new{sleep(200)}

a.raise("Gotcha")

Thiswillproduce:

prog.rb:3:Gotcha(RuntimeError)

fromprog.rb:2:in`initialize'

fromprog.rb:2:in`new'

fromprog.rb:2

Wakesupthr,makingiteligibleforscheduling.

a=Thread.new{puts"a";Thread.stop;puts"c"}

sleep0.1whilea.status!='sleep'

puts"Gothere"

a.join

Thiswillproduce:

Gothere

Seealsotheinstancemethodwakeup.

Returnsthesafelevelineffectforthr.Settingthread-localsafelevelscanhelpwhenimplementingsandboxeswhichruninsecurecode.

thr=Thread.new{$SAFE=3;sleep}

Thread.current.safe_level#=>0

thr.safe_level#=>3

run→thr

safe_level→integer

Establishesproconthrasthehandlerfortracing,ordisablestracingiftheparameterisnil.

SeeKernel#set_trace_func.

Returnsthestatusofthr.

"sleep"

ReturnedifthisthreadissleepingorwaitingonI/O

Whenthisthreadisexecuting

"aborting"

Ifthisthreadisaborting

Whenthisthreadisterminatednormally

Ifterminatedwithanexception.

a=Thread.new{raise("dienow")}

b=Thread.new{Thread.stop}

c=Thread.new{Thread.exit}

d=Thread.new{sleep}

d.kill#=>#<Thread:0x401b3678aborting>

a.status#=>nil

b.status#=>"sleep"

c.status#=>false

d.status#=>"aborting"

Thread.current.status#=>"run"

set_trace_func(proc)→procset_trace_func(nil)→nil

status→string,falseornil

Seealsotheinstancemethodsalive?andstop?

Returnstrueifthrisdeadorsleeping.

a=Thread.new{Thread.stop}

b=Thread.current

a.stop?#=>true

b.stop?#=>false

Seealsoalive?andstatus.

Returnstrueifthegivenstring(orsymbol)existsasathread-localvariable.

me=Thread.current

me.thread_variable_set(:oliver,"a")

me.thread_variable?(:oliver)#=>true

me.thread_variable?(:stanley)#=>false

Notethatthesearenotfiberlocalvariables.PleaseseeThread#[]and#thread_variable_getformoredetails.

stop?→trueorfalse

thread_variable?(key)→trueorfalse

Returnsthevalueofathreadlocalvariablethathasbeenset.Notethatthesearedifferentthanfiberlocalvalues.Forfiberlocalvalues,pleaseseeThread#[]andThread#[]=.

Threadlocalvaluesarecarriedalongwiththreads,anddonotrespectfibers.Forexample:

Thread.new{

Thread.current.thread_variable_set("foo","bar")#setathreadlocal

Thread.current["foo"]="bar"#setafiberlocal

Fiber.new{

Fiber.yield[

Thread.current.thread_variable_get("foo"),#getthethreadlocal

Thread.current["foo"],#getthefiberlocal

}.resume

}.join.value#=>['bar',nil]

Thevalue“bar”isreturnedforthethreadlocal,wherenilisreturnedforthefiberlocal.Thefiberisexecutedinthesamethread,sothethreadlocalvaluesareavailable.

Setsathreadlocalwithkeytovalue.Notethatthesearelocaltothreads,andnottofibers.Pleasesee#thread_variable_getandThread#[]formoreinformation.

Returnsanarrayofthenamesofthethread-localvariables(asSymbols).

thr=Thread.newdo

Thread.current.thread_variable_set(:cat,'meow')

thread_variable_get(key)→objornil

thread_variable_set(key,value)

thread_variables→array

Thread.current.thread_variable_set("dog",'woof')

thr.join#=>#<Thread:0x401b3f10dead>

thr.thread_variables#=>[:dog,:cat]

Notethatthesearenotfiberlocalvariables.PleaseseeThread#[]and#thread_variable_getformoredetails.

Waitsforthrtocomplete,usingjoin,andreturnsitsvalueorraisestheexceptionwhichterminatedthethread.

a=Thread.new{2+2}

a.value#=>4

b=Thread.new{raise'somethingwentwrong'}

b.value#=>RuntimeError:somethingwentwrong

Marksagiventhreadaseligibleforscheduling,howeveritmaystillremainblockedonI/O.

Note:Thisdoesnotinvokethescheduler,seerunformoreinformation.

c=Thread.new{Thread.stop;puts"hey!"}

sleep0.1whilec.status!='sleep'

c.wakeup

c.join

#=>"hey!"

value→obj

wakeup→thr

classThreadErrorRaisedwhenaninvalidoperationisattemptedonathread.

Forexample,whennootherthreadhasbeenstarted:

Thread.stop

Thiswillraisesthefollowingexception:

ThreadError:stoppingonlythread

note:usesleeptostopforever

InFilesthread.c

ParentStandardError

classThreadGroupThreadGroupprovidesameansofkeepingtrackofanumberofthreadsasagroup.

AgivenThreadobjectcanonlybelongtooneThreadGroupatatime;addingathreadtoanewgroupwillremoveitfromanypreviousgroup.

Newlycreatedthreadsbelongtothesamegroupasthethreadfromwhichtheywerecreated.

InFilesthread.c

ParentObject

Constants

Default

ThedefaultThreadGroupcreatedwhenRubystarts;allThreadsbelongtoitbydefault.

Addsthegiventhreadtothisgroup,removingitfromanyothergrouptowhichitmayhavepreviouslybeenamember.

puts"Initialgroupis#{ThreadGroup::Default.list}"

tg=ThreadGroup.new

t1=Thread.new{sleep}

t2=Thread.new{sleep}

puts"t1is#{t1}"

puts"t2is#{t2}"

tg.add(t1)

puts"Initialgroupnow#{ThreadGroup::Default.list}"

puts"tggroupnow#{tg.list}"

Thiswillproduce:

Initialgroupis#<Thread:0x401bdf4c>

t1is#<Thread:0x401b3c90>

t2is#<Thread:0x401b3c18>

Initialgroupnow#<Thread:0x401b3c18>#<Thread:0x401bdf4c>

tggroupnow#<Thread:0x401b3c90>

PreventsthreadsfrombeingaddedtoorremovedfromthereceivingThreadGroup.

NewthreadscanstillbestartedinanenclosedThreadGroup.

ThreadGroup::Default.enclose#=>#<ThreadGroup:0x4029d914>

thr=Thread::new{Thread.stop}#=>#<Thread:0x402a7210sleep>

tg=ThreadGroup::new#=>#<ThreadGroup:0x402752d4>

tg.addthr

#=>ThreadError:can'tmovefromtheenclosedthreadgroup

add(thread)→thgrp

enclose→thgrp

enclosed?→trueorfalse

Returnstrueifthethgrpisenclosed.Seealso#enclose.

ReturnsanarrayofallexistingThreadobjectsthatbelongtothisgroup.

ThreadGroup::Default.list#=>[#<Thread:0x401bdf4crun>]

list→array

classTimeTimeisanabstractionofdatesandtimes.TimeisstoredinternallyasthenumberofsecondswithfractionsincetheEpoch,January1,197000:00UTC.AlsoseethelibrarymoduleDate.TheTimeclasstreatsGMT(GreenwichMeanTime)andUTC(CoordinatedUniversalTime)asequivalent.GMTistheolderwayofreferringtothesebaselinetimesbutpersistsinthenamesofcallsonPOSIXsystems.

Alltimesmayhavefraction.Beawareofthisfactwhencomparingtimeswitheachother–timesthatareapparentlyequalwhendisplayedmaybedifferentwhencompared.

SinceRuby1.9.2,Timeimplementationusesasigned63bitinteger,BignumorRational.TheintegerisanumberofnanosecondssincetheEpochwhichcanrepresent1823-11-12to2116-02-20.WhenBignumorRationalisused(before1823,after2116,undernanosecond),Timeworkssloweraswhenintegerisused.

ExamplesAlloftheseexamplesweredoneusingtheESTtimezonewhichisGMT-5.

CreatinganewTimeinstance

YoucancreateanewinstanceofTimewith::new.Thiswillusethecurrentsystemtime.::nowisanaliasforthis.Youcanalsopasspartsofthetimeto::newsuchasyear,month,minute,etc.Whenyouwanttoconstructatimethiswayyoumustpassatleastayear.IfyoupasstheyearwithnothingelsetimewilldefaulttoJanuary1ofthatyearat00:00:00withthecurrentsystemtimezone.Herearesomeexamples:

Time.new(2002)#=>2002-01-0100:00:00-0500

Time.new(2002,10)#=>2002-10-0100:00:00-0500

Time.new(2002,10,31)#=>2002-10-3100:00:00-0500

Time.new(2002,10,31,2,2,2,"+02:00")#=>2002-10-3102:02:02+0200

Youcanalsousegm,localandutctoinferGMT,localandUTCtimezonesinsteadofusingthecurrentsystemsetting.

Youcanalsocreateanewtimeusing::atwhichtakesthenumberofseconds(orfractionofseconds)sincetheUnixEpoch.

Time.at(628232400)#=>1989-11-2800:00:00-0500

WorkingwithaninstanceofTime

OnceyouhaveaninstanceofTimethereisamultitudeofthingsyoucandowithit.Belowaresomeexamples.Forallofthefollowingexamples,wewillworkontheassumptionthatyouhavedonethefollowing:

t=Time.new(1993,02,24,12,0,0,"+09:00")

Wasthatamonday?

t.monday?#=>false

Whatyearwasthatagain?

t.year#=>1993

Wasisdaylightsavingsatthetime?

t.dst?#=>false

What'sthedayayearlater?

t+(60*60*24*365)#=>1994-02-2412:00:00+0900

HowmanysecondswasthatsincetheUnixEpoch?

t.to_i#=>730522800

Youcanalsodostandardfunctionslikecomparetwotimes.

t1=Time.new(2010)

t2=Time.new(2011)

t1==t2#=>false

t1==t1#=>true

t1<t2#=>true

t1>t2#=>false

Time.new(2010,10,31).between?(t1,t2)#=>true

InFilestime.c

ParentObject

PublicClassMethods

at(time)→timeat(seconds_with_frac)→timeat(seconds,microseconds_with_frac)→

CreatesanewTimeobjectwiththevaluegivenbytime,thegivennumberofseconds_with_frac,orsecondsandmicroseconds_with_fracsincetheEpoch.seconds_with_fracandmicroseconds_with_fraccanbeanInteger,Float,Rational,orotherNumeric.non-portablefeatureallowstheoffsettobenegativeonsomesystems.

Ifanumericargumentisgiven,theresultisinlocaltime.

Time.at(0)#=>1969-12-3118:00:00-0600

Time.at(Time.at(0))#=>1969-12-3118:00:00-0600

Time.at(946702800)#=>1999-12-3123:00:00-0600

Time.at(-284061600)#=>1960-12-3100:00:00-0600

Time.at(946684800.2).usec#=>200000

Time.at(946684800,123456.789).nsec#=>123456789

utc(year)→timeutc(year,month)→timeutc(year,month,day)→timeutc(year,month,day,hour)→timeutc(year,month,day,hour,min)→timeutc(year,month,day,hour,min,sec_with_frac)→timeutc(year,month,day,hour,min,sec,usec_with_frac)→timeutc(sec,min,hour,day,month,year,dummy,dummy,dummy,dummy)→timegm(year)→timegm(year,month)→timegm(year,month,day)→timegm(year,month,day,hour)→time

CreatesaTimeobjectbasedongivenvalues,interpretedasUTC(GMT).Theyearmustbespecified.Othervaluesdefaulttotheminimumvalueforthatfield(andmaybeniloromitted).Monthsmaybespecifiedbynumbersfrom1to12,orbythethree-letterEnglishmonthnames.Hoursarespecifiedona24-hourclock(0..23).RaisesanArgumentErrorifanyvaluesareoutofrange.Willalsoaccepttenargumentsintheorderoutputby#to_a.

sec_with_fracandusec_with_fraccanhaveafractionalpart.

Time.utc(2000,"jan",1,20,15,1)#=>2000-01-0120:15:01UTC

Time.gm(2000,"jan",1,20,15,1)#=>2000-01-0120:15:01UTC

gm(year,month,day,hour,min)→timegm(year,month,day,hour,min,sec_with_frac)→timegm(year,month,day,hour,min,sec,usec_with_frac)→timegm(sec,min,hour,day,month,year,dummy,dummy,dummy,dummy)→time

local(year)→timelocal(year,month)→timelocal(year,month,day)→timelocal(year,month,day,hour)→timelocal(year,month,day,hour,min)→timelocal(year,month,day,hour,min,sec_with_frac)→timelocal(year,month,day,hour,min,sec,usec_with_frac)→time

Sameas::gm,butinterpretsthevaluesinthelocaltimezone.

Time.local(2000,"jan",1,20,15,1)#=>2000-01-0120:15:01-0600

local(sec,min,hour,day,month,year,dummy,dummy,isdst,dummy)→timemktime(year)→timemktime(year,month)→timemktime(year,month,day)→timemktime(year,month,day,hour)→timemktime(year,month,day,hour,min)→timemktime(year,month,day,hour,min,sec_with_frac)→timemktime(year,month,day,hour,min,sec,usec_with_frac)→timemktime(sec,min,hour,day,month,year,dummy,dummy,isdst,dummy)→time

local(year)→timelocal(year,month)→timelocal(year,month,day)→timelocal(year,month,day,hour)→timelocal(year,month,day,hour,min)→timelocal(year,month,day,hour,min,sec_with_frac)→timelocal(year,month,day,hour,min,sec,usec_with_frac)→timelocal(sec,min,hour,day,month,year,dummy,dummy,isdst,dummy)→timemktime(year)→timemktime(year,month)→time

Sameas::gm,butinterpretsthevaluesinthelocaltimezone.

Time.local(2000,"jan",1,20,15,1)#=>2000-01-0120:15:01-0600

ReturnsaTimeobject.

Itisinitializedtothecurrentsystemtimeifnoargumentisgiven.

Note:Thenewobjectwillusetheresolutionavailableonyoursystemclock,andmayincludefractionalseconds.

Ifoneormoreargumentsspecified,thetimeisinitializedtothespecifiedtime.

secmayhavefractionifitisarational.

utc_offsetistheoffsetfromUTC.Itcanbeastringsuchas“+09:00”oranumberofsecondssuchas32400.

a=Time.new#=>2007-11-1907:50:02-0600

b=Time.new#=>2007-11-1907:50:02-0600

mktime(year,month,day)→timemktime(year,month,day,hour)→timemktime(year,month,day,hour,min)→timemktime(year,month,day,hour,min,sec_with_frac)→timemktime(year,month,day,hour,min,sec,usec_with_frac)→timemktime(sec,min,hour,day,month,year,dummy,dummy,isdst,dummy)→time

new→timenew(year,month=nil,day=nil,hour=nil,min=nil,sec=nil,utc_offset=nil)→time

a==b#=>false

"%.6f"%a.to_f#=>"1195480202.282373"

"%.6f"%b.to_f#=>"1195480202.283415"

Time.new(2008,6,21,13,30,0,"+09:00")#=>2008-06-2113:30:00+0900

#AtripforRubyConf2007

t1=Time.new(2007,11,1,15,25,0,"+09:00")#JST(Narita)

t2=Time.new(2007,11,1,12,5,0,"-05:00")#CDT(Minneapolis)

t3=Time.new(2007,11,1,13,25,0,"-05:00")#CDT(Minneapolis)

t4=Time.new(2007,11,1,16,53,0,"-04:00")#EDT(Charlotte)

t5=Time.new(2007,11,5,9,24,0,"-05:00")#EST(Charlotte)

t6=Time.new(2007,11,5,11,21,0,"-05:00")#EST(Detroit)

t7=Time.new(2007,11,5,13,45,0,"-05:00")#EST(Detroit)

t8=Time.new(2007,11,6,17,10,0,"+09:00")#JST(Narita)

p((t2-t1)/3600.0)#=>10.666666666666666

p((t4-t3)/3600.0)#=>2.466666666666667

p((t6-t5)/3600.0)#=>1.95

p((t8-t7)/3600.0)#=>13.416666666666666

CreatesanewTimeobjectforthecurrenttime.Thisissameas::newwithoutarguments.

Time.now#=>2009-06-2412:39:54+0900

now→time

utc(year)→timeutc(year,month)→timeutc(year,month,day)→timeutc(year,month,day,hour)→timeutc(year,month,day,hour,min)→timeutc(year,month,day,hour,min,sec_with_frac)→timeutc(year,month,day,hour,min,sec,usec_with_frac)→timeutc(sec,min,hour,day,month,year,dummy,

CreatesaTimeobjectbasedongivenvalues,interpretedasUTC(GMT).Theyearmustbespecified.Othervaluesdefaulttotheminimumvalueforthatfield(andmaybeniloromitted).Monthsmaybespecifiedbynumbersfrom1to12,orbythethree-letterEnglishmonthnames.Hoursarespecifiedona24-hourclock(0..23).RaisesanArgumentErrorifanyvaluesareoutofrange.Willalsoaccepttenargumentsintheorderoutputby#to_a.

sec_with_fracandusec_with_fraccanhaveafractionalpart.

Time.utc(2000,"jan",1,20,15,1)#=>2000-01-0120:15:01UTC

Time.gm(2000,"jan",1,20,15,1)#=>2000-01-0120:15:01UTC

Addition—Addssomenumberofseconds(possibly

dummy,dummy,dummy)→timegm(year)→timegm(year,month)→timegm(year,month,day)→timegm(year,month,day,hour)→timegm(year,month,day,hour,min)→timegm(year,month,day,hour,min,sec_with_frac)→timegm(year,month,day,hour,min,sec,usec_with_frac)→timegm(sec,min,hour,day,month,year,dummy,dummy,dummy,dummy)→time

time+numeric→time

fractional)totimeandreturnsthatvalueasanewTimeobject.

t=Time.now#=>2007-11-1908:22:21-0600

t+(60*60*24)#=>2007-11-2008:22:21-0600

Difference—ReturnsanewTimeobjectthatrepresentsthedifferencebetweentimeandother_time,orsubtractsthegivennumberofsecondsinnumericfromtime.

t=Time.now#=>2007-11-1908:23:10-0600

t2=t+2592000#=>2007-12-1908:23:10-0600

t2-t#=>2592000.0

t2-2592000#=>2007-11-1908:23:10-0600

Comparison—Comparestimewithother_time.

-1,0,+1ornildependingonwhethertimeislessthan,equalto,orgreaterthanother_time.

t=Time.now#=>2007-11-1908:12:12-0600

t2=t+2592000#=>2007-12-1908:12:12-0600

t<=>t2#=>-1

t2<=>t#=>1

t=Time.now#=>2007-11-1908:13:38-0600

t2=t+0.1#=>2007-11-1908:13:38-0600

t.nsec#=>98222999

t2.nsec#=>198222999

t<=>t2#=>-1

t2<=>t#=>1

t<=>t#=>0

time-other_time→floattime-numeric→time

time<=>other_time→-1,0,+1ornil

Returnsacanonicalstringrepresentationoftime.

Time.now.asctime#=>"WedApr908:56:032003"

Returnsacanonicalstringrepresentationoftime.

Time.now.asctime#=>"WedApr908:56:032003"

Returnsthedayofthemonth(1..n)fortime.

t=Time.now#=>2007-11-1908:27:03-0600

t.day#=>19

t.mday#=>19

ReturnstrueiftimeoccursduringDaylightSavingTimeinitstimezone.

#CST6CDT:

Time.local(2000,1,1).zone#=>"CST"

Time.local(2000,1,1).isdst#=>false

Time.local(2000,1,1).dst?#=>false

Time.local(2000,7,1).zone#=>"CDT"

Time.local(2000,7,1).isdst#=>true

Time.local(2000,7,1).dst?#=>true

asctime→stringctime→string

day→fixnummday→fixnum

isdst→trueorfalsedst?→trueorfalse

#Asia/Tokyo:

Time.local(2000,1,1).zone#=>"JST"

Returnstrueiftimeandother_timearebothTimeobjectswiththesamesecondsandfractionalseconds.

ReturnstrueiftimerepresentsFriday.

t=Time.local(1987,12,18)#=>1987-12-1800:00:00-0600

t.friday?#=>true

ReturnsanewTimeobjectrepresentingtimeinUTC.

t=Time.local(2000,1,1,20,15,1)#=>2000-01-0120:15:01-0600

t.gmt?#=>false

y=t.getgm#=>2000-01-0202:15:01UTC

y.gmt?#=>true

t==y#=>true

ReturnsanewTimeobjectrepresentingtimeinlocaltime(usingthelocaltimezoneineffectforthis

eql?(other_time)

friday?→trueorfalse

getgm→new_timegetutc→new_time

getlocal→new_timegetlocal(utc_offset)→new_time

process).

Ifutc_offsetisgiven,itisusedinsteadofthelocaltime.

t=Time.utc(2000,1,1,20,15,1)#=>2000-01-0120:15:01UTC

t.utc?#=>true

l=t.getlocal#=>2000-01-0114:15:01-0600

l.utc?#=>false

t==l#=>true

j=t.getlocal("+09:00")#=>2000-01-0205:15:01+0900

j.utc?#=>false

t==j#=>true

ReturnsanewTimeobjectrepresentingtimeinUTC.

t=Time.local(2000,1,1,20,15,1)#=>2000-01-0120:15:01-0600

t.gmt?#=>false

y=t.getgm#=>2000-01-0202:15:01UTC

y.gmt?#=>true

t==y#=>true

ReturnstrueiftimerepresentsatimeinUTC(GMT).

t=Time.now#=>2007-11-1908:15:23-0600

t.utc?#=>false

t=Time.gm(2000,"jan",1,20,15,1)#=>2000-01-0120:15:01UTC

t.utc?#=>true

t=Time.now#=>2007-11-1908:16:03-0600

t.gmt?#=>false

t=Time.gm(2000,1,1,20,15,1)#=>2000-01-0120:15:01UTC

t.gmt?#=>true

getgm→new_timegetutc→new_time

utc?→trueorfalsegmt?→trueorfalse

ReturnstheoffsetinsecondsbetweenthetimezoneoftimeandUTC.

t=Time.gm(2000,1,1,20,15,1)#=>2000-01-0120:15:01UTC

t.gmt_offset#=>0

l=t.getlocal#=>2000-01-0114:15:01-0600

l.gmt_offset#=>-21600

ConvertstimetoUTC(GMT),modifyingthereceiver.

t=Time.now#=>2007-11-1908:18:31-0600

t.gmt?#=>false

t.gmtime#=>2007-11-1914:18:31UTC

t.gmt?#=>true

t=Time.now#=>2007-11-1908:18:51-0600

t.utc?#=>false

t.utc#=>2007-11-1914:18:51UTC

t.utc?#=>true

t=Time.gm(2000,1,1,20,15,1)#=>2000-01-0120:15:01UTC

t.gmt_offset#=>0

l=t.getlocal#=>2000-01-0114:15:01-0600

gmt_offset→fixnumgmtoff→fixnumutc_offset→fixnum

gmtime→timeutc→time

ReturnsahashcodeforthisTimeobject.

SeealsoObject#hash.

Returnsthehouroftheday(0..23)fortime.

t=Time.now#=>2007-11-1908:26:20-0600

t.hour#=>8

Returnsastringrepresentingtime.Equivalenttocallingstrftimewiththeappropriateformatstring.

t=Time.now

t.to_s=>"2012-11-1018:16:12+0100"

t.strftime"%Y-%m-%d%H:%M:%S%z"=>"2012-11-1018:16:12+0100"

t.utc.to_s=>"2012-11-1017:16:12UTC"

t.strftime"%Y-%m-%d%H:%M:%SUTC"=>"2012-11-1017:16:12UTC"

ReturnstrueiftimeoccursduringDaylightSavingTimeinitstimezone.

#CST6CDT:

Time.local(2000,1,1).zone#=>"CST"

Time.local(2000,7,1).zone#=>"CDT"

Time.local(2000,7,1).isdst#=>true

hash→fixnum

hour→fixnum

isdst→trueorfalsedst?→trueorfalse

Time.local(2000,7,1).dst?#=>true

#Asia/Tokyo:

Convertstimetolocaltime(usingthelocaltimezoneineffectforthisprocess)modifyingthereceiver.

Ifutc_offsetisgiven,itisusedinsteadofthelocaltime.

t=Time.utc(2000,"jan",1,20,15,1)#=>2000-01-0120:15:01UTC

t.utc?#=>true

t.localtime#=>2000-01-0114:15:01-0600

t.utc?#=>false

t.localtime("+09:00")#=>2000-01-0205:15:01+0900

t.utc?#=>false

Returnsthedayofthemonth(1..n)fortime.

t=Time.now#=>2007-11-1908:27:03-0600

t.day#=>19

t.mday#=>19

Returnstheminuteofthehour(0..59)fortime.

localtime→timelocaltime(utc_offset)→time

day→fixnummday→fixnum

min→fixnum

t=Time.now#=>2007-11-1908:25:51-0600

t.min#=>25

Returnsthemonthoftheyear(1..12)fortime.

t=Time.now#=>2007-11-1908:27:30-0600

t.mon#=>11

t.month#=>11

ReturnstrueiftimerepresentsMonday.

t=Time.local(2003,8,4)#=>2003-08-0400:00:00-0500

pt.monday?#=>true

Returnsthemonthoftheyear(1..12)fortime.

t=Time.now#=>2007-11-1908:27:30-0600

t.mon#=>11

t.month#=>11

Returnsthenumberofnanosecondsfortime.

t=Time.now#=>2007-11-1715:18:03+0900

"%10.9f"%t.to_f#=>"1195280283.536151409"

t.nsec#=>536151406

Thelowestdigitsofto_fandnsecaredifferent

mon→fixnummonth→fixnum

monday?→trueorfalse

mon→fixnummonth→fixnum

nsec→inttv_nsec→int

becauseIEEE754doubleisnotaccurateenoughtorepresenttheexactnumberofnanosecondssincetheEpoch.

Themoreaccuratevalueisreturnedbynsec.

Roundssubsecondstoagivenprecisionindecimaldigits(0digitsbydefault).ItreturnsanewTimeobject.ndigitsshouldbezeroorpositiveinteger.

require'time'

t=Time.utc(2010,3,30,5,43,"25.123456789".to_r)

pt.iso8601(10)#=>"2010-03-30T05:43:25.1234567890Z"

pt.round.iso8601(10)#=>"2010-03-30T05:43:25.0000000000Z"

pt.round(0).iso8601(10)#=>"2010-03-30T05:43:25.0000000000Z"

pt.round(1).iso8601(10)#=>"2010-03-30T05:43:25.1000000000Z"

pt.round(2).iso8601(10)#=>"2010-03-30T05:43:25.1200000000Z"

pt.round(3).iso8601(10)#=>"2010-03-30T05:43:25.1230000000Z"

pt.round(4).iso8601(10)#=>"2010-03-30T05:43:25.1235000000Z"

pt.round(5).iso8601(10)#=>"2010-03-30T05:43:25.1234600000Z"

pt.round(6).iso8601(10)#=>"2010-03-30T05:43:25.1234570000Z"

pt.round(7).iso8601(10)#=>"2010-03-30T05:43:25.1234568000Z"

pt.round(8).iso8601(10)#=>"2010-03-30T05:43:25.1234567900Z"

pt.round(9).iso8601(10)#=>"2010-03-30T05:43:25.1234567890Z"

pt.round(10).iso8601(10)#=>"2010-03-30T05:43:25.1234567890Z"

t=Time.utc(1999,12,31,23,59,59)

p((t+0.4).round.iso8601(3))#=>"1999-12-31T23:59:59.000Z"

p((t+0.49).round.iso8601(3))#=>"1999-12-31T23:59:59.000Z"

p((t+0.5).round.iso8601(3))#=>"2000-01-01T00:00:00.000Z"

p((t+1.4).round.iso8601(3))#=>"2000-01-01T00:00:00.000Z"

p((t+1.49).round.iso8601(3))#=>"2000-01-01T00:00:00.000Z"

p((t+1.5).round.iso8601(3))#=>"2000-01-01T00:00:01.000Z"

t=Time.utc(1999,12,31,23,59,59)

p(t+0.123456789).round(4).iso8601(6)#=>"1999-12-31T23:59:59.123500Z"

round([ndigits])→new_time

saturday?→trueorfalse

ReturnstrueiftimerepresentsSaturday.

t=Time.local(2006,6,10)#=>2006-06-1000:00:00-0500

t.saturday?#=>true

Returnsthesecondoftheminute(0..60)fortime.

Note:Secondsrangefromzeroto60toallowthesystemtoinjectleapseconds.Seeen.wikipedia.org/wiki/Leap_secondforfurtherdetails.

t=Time.now#=>2007-11-1908:25:02-0600

t.sec#=>2

Formatstimeaccordingtothedirectivesinthegivenformatstring.

Thedirectivesbeginwithapercent(%)character.Anytextnotlistedasadirectivewillbepassedthroughtotheoutputstring.

Thedirectiveconsistsofapercent(%)character,zeroormoreflags,optionalminimumfieldwidth,optionalmodifierandaconversionspecifierasfollows:

%<flags><width><modifier><conversion>

Flags:

-don'tpadanumericaloutput

_usespacesforpadding

0usezerosforpadding

^upcasetheresultstring

#changecase

:usecolonsfor%z

sec→fixnum

strftime(string)→string

Theminimumfieldwidthspecifiestheminimumwidth.

Themodifiersare“E”and“O”.Theyareignored.

Formatdirectives:

Date(Year,Month,Day):

%Y-Yearwithcenturyifprovided,willpadresultatleast4digits.

-0001,0000,1995,2009,14292,etc.

%C-year/100(roundeddownsuchas20in2009)

%y-year%100(00..99)

%m-Monthoftheyear,zero-padded(01..12)

%_mblank-padded(1..12)

%-mno-padded(1..12)

%B-Thefullmonthname(``January'')

%^Buppercased(``JANUARY'')

%b-Theabbreviatedmonthname(``Jan'')

%^buppercased(``JAN'')

%h-Equivalentto%b

%d-Dayofthemonth,zero-padded(01..31)

%-dno-padded(1..31)

%e-Dayofthemonth,blank-padded(1..31)

%j-Dayoftheyear(001..366)

Time(Hour,Minute,Second,Subsecond):

%H-Houroftheday,24-hourclock,zero-padded(00..23)

%k-Houroftheday,24-hourclock,blank-padded(0..23)

%I-Houroftheday,12-hourclock,zero-padded(01..12)

%l-Houroftheday,12-hourclock,blank-padded(1..12)

%P-Meridianindicator,lowercase(``am''or``pm'')

%p-Meridianindicator,uppercase(``AM''or``PM'')

%M-Minuteofthehour(00..59)

%S-Secondoftheminute(00..60)

%L-Millisecondofthesecond(000..999)

Thedigitsundermillisecondaretruncatedtonotproduce1000.

%N-Fractionalsecondsdigits,defaultis9digits(nanosecond)

%3Nmillisecond(3digits)

%6Nmicrosecond(6digits)

%9Nnanosecond(9digits)

%12Npicosecond(12digits)

%15Nfemtosecond(15digits)

%18Nattosecond(18digits)

%21Nzeptosecond(21digits)

%24Nyoctosecond(24digits)

Thedigitsunderthespecifiedlengtharetruncatedtoavoid

carryup.

Timezone:

%z-TimezoneashourandminuteoffsetfromUTC(e.g.+0900)

%:z-hourandminuteoffsetfromUTCwithacolon(e.g.+09:00)

%::z-hour,minuteandsecondoffsetfromUTC(e.g.+09:00:00)

%Z-Abbreviatedtimezonenameorsimilarinformation.(OSdependent)

Weekday:

%A-Thefullweekdayname(``Sunday'')

%^Auppercased(``SUNDAY'')

%a-Theabbreviatedname(``Sun'')

%^auppercased(``SUN'')

%u-Dayoftheweek(Mondayis1,1..7)

%w-Dayoftheweek(Sundayis0,0..6)

ISO8601week-basedyearandweeknumber:

ThefirstweekofYYYYstartswithaMondayandincludesYYYY-01-04.

Thedaysintheyearbeforethefirstweekareinthelastweekof

thepreviousyear.

%G-Theweek-basedyear

%g-Thelast2digitsoftheweek-basedyear(00..99)

%V-Weeknumberoftheweek-basedyear(01..53)

Weeknumber:

ThefirstweekofYYYYthatstartswithaSundayorMonday(accordingto%U

or%W).Thedaysintheyearbeforethefirstweekareinweek0.

%U-Weeknumberoftheyear.TheweekstartswithSunday.(00..53)

%W-Weeknumberoftheyear.TheweekstartswithMonday.(00..53)

SecondssincetheEpoch:

%s-Numberofsecondssince1970-01-0100:00:00UTC.

Literalstring:

%n-Newlinecharacter(\n)

%t-Tabcharacter(\t)

%%-Literal``%''character

Combination:

%c-dateandtime(%a%b%e%T%Y)

%D-Date(%m/%d/%y)

%F-TheISO8601dateformat(%Y-%m-%d)

%v-VMSdate(%e-%^b-%4Y)

%x-Sameas%D

%X-Sameas%T

%r-12-hourtime(%I:%M:%S%p)

%R-24-hourtime(%H:%M)

%T-24-hourtime(%H:%M:%S)

Thismethodissimilartostrftime()functiondefinedinISOCandPOSIX.

WhilealldirectivesarelocaleindependentsinceRuby1.9,%Zisplatformdependent.So,theresultmaydifferevenifthesameformatstringisusedinothersystemssuchasC.

%zisrecommendedover%Z.%Zdoesn'tidentifythetimezone.Forexample,“CST”isusedatAmerica/Chicago(-06:00),America/Havana(-05:00),Asia/Harbin(+08:00),Australia/Darwin(+09:30)andAustralia/Adelaide(+10:30).Also,%Zishighlydependentontheoperatingsystem.Forexample,itmaygenerateanonASCIIstringonJapaneseWindows.i.e.theresultcanbedifferentto“JST”.Sothenumerictimezoneoffset,%z,isrecommended.

Examples:

t=Time.new(2007,11,19,8,37,48,"-06:00")#=>2007-11-1908:37:48-0600

t.strftime("Printedon%m/%d/%Y")#=>"Printedon11/19/2007"

t.strftime("at%I:%M%p")#=>"at08:37AM"

VariousISO8601formats:

%Y%m%d=>20071119Calendardate(basic)

%F=>2007-11-19Calendardate(extended)

%Y-%m=>2007-11Calendardate,reducedaccuracy,specificmonth

%Y=>2007Calendardate,reducedaccuracy,specificyear

%C=>20Calendardate,reducedaccuracy,specificcentury

%Y%j=>2007323Ordinaldate(basic)

%Y-%j=>2007-323Ordinaldate(extended)

%GW%V%u=>2007W471Weekdate(basic)

%G-W%V-%u=>2007-W47-1Weekdate(extended)

%GW%V=>2007W47Weekdate,reducedaccuracy,specificweek(basic)

%G-W%V=>2007-W47Weekdate,reducedaccuracy,specificweek(extended)

%H%M%S=>083748Localtime(basic)

%T=>08:37:48Localtime(extended)

%H%M=>0837Localtime,reducedaccuracy,specificminute(basic)

%H:%M=>08:37Localtime,reducedaccuracy,specificminute(extended)

%H=>08Localtime,reducedaccuracy,specifichour

%H%M%S,%L=>083748,000Localtimewithdecimalfraction,commaasdecimalsign(basic)

%T,%L=>08:37:48,000Localtimewithdecimalfraction,commaasdecimalsign(extended)

%H%M%S.%L=>083748.000Localtimewithdecimalfraction,fullstopasdecimalsign(basic)

%T.%L=>08:37:48.000Localtimewithdecimalfraction,fullstopasdecimalsign(extended)

%H%M%S%z=>083748-0600LocaltimeandthedifferencefromUTC(basic)

%T%:z=>08:37:48-06:00LocaltimeandthedifferencefromUTC(extended)

%Y%m%dT%H%M%S%z=>20071119T083748-0600Dateandtimeofdayforcalendardate(basic)

%FT%T%:z=>2007-11-19T08:37:48-06:00Dateandtimeofdayforcalendardate(extended)

%Y%jT%H%M%S%z=>2007323T083748-0600Dateandtimeofdayforordinaldate(basic)

%Y-%jT%T%:z=>2007-323T08:37:48-06:00Dateandtimeofdayforordinaldate(extended)

%GW%V%uT%H%M%S%z=>2007W471T083748-0600Dateandtimeofdayforweekdate(basic)

%G-W%V-%uT%T%:z=>2007-W47-1T08:37:48-06:00Dateandtimeofdayforweekdate(extended)

%Y%m%dT%H%M=>20071119T0837Calendardateandlocaltime(basic)

%FT%R=>2007-11-19T08:37Calendardateandlocaltime(extended)

%Y%jT%H%MZ=>2007323T0837ZOrdinaldateandUTCofday(basic)

%Y-%jT%RZ=>2007-323T08:37ZOrdinaldateandUTCofday(extended)

%GW%V%uT%H%M%z=>2007W471T0837-0600WeekdateandlocaltimeanddifferencefromUTC(basic)

%G-W%V-%uT%R%:z=>2007-W47-1T08:37-06:00WeekdateandlocaltimeanddifferencefromUTC(extended)

Returnsthefractionfortime.

Thereturnvaluecanbearationalnumber.

t=Time.now#=>2009-03-2622:33:12+0900

"%10.9f"%t.to_f#=>"1238074392.940563917"

t.subsec#=>(94056401/100000000)

Thelowestdigitsofto_fandsubsecaredifferentbecauseIEEE754doubleisnotaccurateenoughtorepresenttherationalnumber.

Themoreaccuratevalueisreturnedbysubsec.

subsec→number

ReturnsanewTimeobject,onesecondlaterthantime.#succisobsoletesince1.9.2fortimeisnotadiscretevalue.

t=Time.now#=>2007-11-1908:23:57-0600

t.succ#=>2007-11-1908:23:58-0600

Useinsteadtime+1

t+1#=>2007-11-1908:23:58-0600

ReturnstrueiftimerepresentsSunday.

t=Time.local(1990,4,1)#=>1990-04-0100:00:00-0600

t.sunday?#=>true

ReturnstrueiftimerepresentsThursday.

t=Time.local(1995,12,21)#=>1995-12-2100:00:00-0600

pt.thursday?#=>true

Returnsaten-elementarrayofvaluesfortime:

[sec,min,hour,day,month,year,wday,yday,isdst,zone]

Seetheindividualmethodsforanexplanationofthevalidrangesofeachvalue.Thetenelementscanbepasseddirectlyto::utcor::localtocreateanewTime

succ→new_time

sunday?→trueorfalse

thursday?→trueorfalse

to_a→array

object.

t=Time.now#=>2007-11-1908:36:01-0600

now=t.to_a#=>[1,36,8,19,11,2007,1,323,false,"CST"]

ReturnsthevalueoftimeasafloatingpointnumberofsecondssincetheEpoch.

t=Time.now

"%10.5f"%t.to_f#=>"1270968744.77658"

t.to_i#=>1270968744

NotethatIEEE754doubleisnotaccurateenoughtorepresentthenumberofnanosecondssincetheEpoch.

ReturnsthevalueoftimeasanintegernumberofsecondssincetheEpoch.

t=Time.now

"%10.5f"%t.to_f#=>"1270968656.89607"

t.to_i#=>1270968656

ReturnsthevalueoftimeasarationalnumberofsecondssincetheEpoch.

t=Time.now

pt.to_r#=>(1270968792716287611/1000000000)

ThismethodsisintendedtobeusedtogetanaccuratevaluerepresentingthenanosecondssincetheEpoch.Youcanusethismethodtoconverttime

to_f→float

to_i→inttv_sec→int

to_r→a_rational

toanotherEpoch.

Returnsastringrepresentingtime.Equivalenttocallingstrftimewiththeappropriateformatstring.

t=Time.now

t.to_s=>"2012-11-1018:16:12+0100"

t.strftime"%Y-%m-%d%H:%M:%S%z"=>"2012-11-1018:16:12+0100"

t.utc.to_s=>"2012-11-1017:16:12UTC"

t.strftime"%Y-%m-%d%H:%M:%SUTC"=>"2012-11-1017:16:12UTC"

ReturnstrueiftimerepresentsTuesday.

t=Time.local(1991,2,19)#=>1991-02-1900:00:00-0600

pt.tuesday?#=>true

Returnsthenumberofnanosecondsfortime.

t=Time.now#=>2007-11-1715:18:03+0900

"%10.9f"%t.to_f#=>"1195280283.536151409"

t.nsec#=>536151406

Thelowestdigitsofto_fandnsecaredifferentbecauseIEEE754doubleisnotaccurateenoughtorepresenttheexactnumberofnanosecondssincetheEpoch.

Themoreaccuratevalueisreturnedbynsec.

tuesday?→trueorfalse

nsec→inttv_nsec→int

ReturnsthevalueoftimeasanintegernumberofsecondssincetheEpoch.

t=Time.now

"%10.5f"%t.to_f#=>"1270968656.89607"

t.to_i#=>1270968656

Returnsthenumberofmicrosecondsfortime.

t=Time.now#=>2007-11-1908:03:26-0600

"%10.6f"%t.to_f#=>"1195481006.775195"

t.usec#=>775195

Returnsthenumberofmicrosecondsfortime.

t=Time.now#=>2007-11-1908:03:26-0600

"%10.6f"%t.to_f#=>"1195481006.775195"

t.usec#=>775195

ConvertstimetoUTC(GMT),modifyingthereceiver.

t=Time.now#=>2007-11-1908:18:31-0600

t.gmt?#=>false

t.gmtime#=>2007-11-1914:18:31UTC

t.gmt?#=>true

t=Time.now#=>2007-11-1908:18:51-0600

to_i→inttv_sec→int

usec→inttv_usec→int

gmtime→timeutc→time

t.utc?#=>false

t.utc#=>2007-11-1914:18:51UTC

t.utc?#=>true

ReturnstrueiftimerepresentsatimeinUTC(GMT).

t=Time.now#=>2007-11-1908:15:23-0600

t.utc?#=>false

t=Time.gm(2000,"jan",1,20,15,1)#=>2000-01-0120:15:01UTC

t.utc?#=>true

t=Time.now#=>2007-11-1908:16:03-0600

t.gmt?#=>false

t=Time.gm(2000,1,1,20,15,1)#=>2000-01-0120:15:01UTC

t.gmt?#=>true

t=Time.gm(2000,1,1,20,15,1)#=>2000-01-0120:15:01UTC

t.gmt_offset#=>0

l=t.getlocal#=>2000-01-0114:15:01-0600

Returnsanintegerrepresentingthedayoftheweek,0..6,withSunday==0.

t=Time.now#=>2007-11-2002:35:35-0600

t.wday#=>2

t.sunday?#=>false

utc?→trueorfalsegmt?→trueorfalse

wday→fixnum

t.monday?#=>false

t.tuesday?#=>true

t.wednesday?#=>false

t.thursday?#=>false

t.friday?#=>false

t.saturday?#=>false

ReturnstrueiftimerepresentsWednesday.

t=Time.local(1993,2,24)#=>1993-02-2400:00:00-0600

pt.wednesday?#=>true

Returnsanintegerrepresentingthedayoftheyear,1..366.

t=Time.now#=>2007-11-1908:32:31-0600

t.yday#=>323

Returnstheyearfortime(includingthecentury).

t=Time.now#=>2007-11-1908:27:51-0600

t.year#=>2007

Returnsthenameofthetimezoneusedfortime.AsofRuby1.8,returns“UTC''ratherthan“GMT''forUTCtimes.

t=Time.gm(2000,"jan",1,20,15,1)

t.zone#=>"UTC"

t=Time.local(2000,"jan",1,20,15,1)

t.zone#=>"CST"

wednesday?→trueorfalse

yday→fixnum

year→fixnum

zone→string

classTracePointAclassthatprovidesthefunctionalityofKernel#set_trace_funcinaniceObject-OrientedAPI.

Example

WecanuseTracePointtogatherinformationspecificallyforexceptions:

trace=TracePoint.new(:raise)do|tp|

p[tp.lineno,tp.event,tp.raised_exception]

#=>#<TracePoint:disabled>

trace.enable

#=>false

#=>[5,:raise,#<ZeroDivisionError:dividedby0>]

Events

Ifyoudon'tspecifythetypeofeventsyouwanttolistenfor,TracePointwillincludeallavailableevents.

Notedonotdependoncurrenteventset,asthislistissubjecttochange.Instead,itisrecommendedyouspecifythetypeofeventsyouwanttouse.

Tofilterwhatistraced,youcanpassanyofthefollowingasevents:

executecodeonanewline

:class

startaclassormoduledefinition

finishaclassormoduledefinition

callaRubymethod

:return

returnfromaRubymethod

:c_call

callaC-languageroutine

:c_return

returnfromaC-languageroutine

:raise

raiseanexception

:b_call

eventhookatblockentry

:b_return

eventhookatblockending

:thread_begin

eventhookatthreadbeginning

:thread_end

eventhookatthreadending

InFilesvm_trace.c

ParentObject

PublicClassMethods

ReturnsanewTracePointobject,notenabledbydefault.

Next,inordertoactivatethetrace,youmustuse#enable

trace=TracePoint.new(:call)do|tp|

p[tp.lineno,tp.defined_class,tp.method_id,tp.event

#=>#<TracePoint:disabled>

trace.enable

#=>false

puts"Hello,TracePoint!"

#[48,IRB::Notifier::AbstractNotifier,:printf,:call]

Whenyouwanttodeactivatethetrace,youmustuse#disable

trace.disable

SeeEventsatTracePointforpossibleeventsandmoreinformation.

Ablockmustbegiven,otherwiseaThreadErrorisraised.

Ifthetracemethodisn'tincludedinthegiveneventsfilter,aRuntimeErrorisraised.

TracePoint.trace(:line)do|tp|

ptp.raised_exception

#=>RuntimeError:'raised_exception'notsupportedbythisevent

Ifthetracemethodiscalledoutsideblock,aRuntimeErrorisraised.

new(*events){|obj|block}→obj

TracePoint.trace(:line)do|tp|

$tp=tp

$tp.line#=>accessfromoutside(RuntimeError)

Accessfromotherthreadsisalsoforbidden.

ReturnsinternalinformationofTracePoint.

Thecontentsofthereturnedvalueareimplementationspecific.Itmaybechangedinfuture.

ThismethodisonlyfordebuggingTracePointitself.

Aconveniencemethodfor::new,thatactivatesthetraceautomatically.

trace=TracePoint.trace(:call){|tp|[tp.lineno,tp.

#=>#<TracePoint:enabled>

trace.enabled?#=>true

Returnthegeneratedbindingobjectfromevent

Returnclassormoduleofthemethodbeingcalled.

classC;deffoo;end;end

ptp.defined_class#=>C

stat→obj

trace(*events){|obj|block}→obj

binding()

defined_class()

end.enabledo

C.new.foo

Ifmethodisdefinedbyamodule,thenthatmoduleisreturned.

moduleM;deffoo;end;end

classC;includeM;end;

ptp.defined_class#=>M

end.enabledo

C.new.foo

Note:defined_classreturnssingletonclass.6thblockparameterofKernel#set_trace_funcpassesoriginalclassofattachedbysingletonclass.

ThisisadifferencebetweenKernel#set_trace_funcandTracePoint.

classC;defself.foo;end;end

ptp.defined_class#=>#<Class:C>

end.enabledo

Deactivatesthetrace

Returntrueiftracewasenabled.Returnfalseiftracewasdisabled.

trace.disable#=>false(previousstatus)

trace.enabled?#=>false

trace.disable#=>false

disable→trueorfalsedisable{block}→obj

Ifablockisgiven,thetracewillonlybedisablewithinthescopeoftheblock.

trace.enabled?

#=>true

trace.disabledo

trace.enabled?

#onlydisabledforthisblock

trace.enabled?

#=>true

Note:Youcannotaccesseventhookswithintheblock.

trace.disable{ptp.lineno}

#=>RuntimeError:accessfromoutside

Activatesthetrace

Returntrueiftracewasenabled.Returnfalseiftracewasdisabled.

trace.enabled?#=>false

trace.enable#=>false(previousstate)

#traceisenabled

trace.enable#=>true(previousstate)

#traceisstillenabled

Ifablockisgiven,thetracewillonlybeenabledwithinthescopeoftheblock.

trace.enabled?

#=>false

trace.enabledo

trace.enabled?

#onlyenabledforthisblock

enable→trueorfalseenable{block}→obj

trace.enabled?

#=>false

Note:Youcannotaccesseventhookswithintheblock.

trace.enable{ptp.lineno}

#=>RuntimeError:accessfromoutside

Thecurrentstatusofthetrace

Typeofevent

SeeEventsatTracePointformoreinformation.

Returnastringcontainingahuman-readableTracePointstatus.

Linenumberoftheevent

Returnthenameofthemethodbeingcalled

Pathofthefilebeingrun

enabled?→trueorfalse

event()

inspect→string

lineno()

method_id()

path()

raised_exception()

Valuefromexceptionraisedonthe:raiseevent

Returnvaluefrom:return,c_return,andb_returnevent

Returnthetraceobjectduringevent

Sameas#binding:

trace.binding.eval('self')

return_value()

self()

classTrueClassTheglobalvaluetrueistheonlyinstanceofclassTrueClassandrepresentsalogicallytruevalueinbooleanexpressions.Theclassprovidesoperatorsallowingtruetobeusedinlogicalexpressions.

InFilesobject.c

ParentObject

And—Returnsfalseifobjisnilorfalse,trueotherwise.

ExclusiveOr—Returnstrueifobjisnilorfalse,falseotherwise.

Aliasfor:to_s

true&obj→trueorfalse

true^obj→!obj

inspect()

Thestringrepresentationoftrueis“true”.

Or—Returnstrue.Asobjisanargumenttoamethodcall,itisalwaysevaluated;thereisnoshort-circuitevaluationinthiscase.

true|puts("or")

true||puts("logicalor")

produces:

to_s→"true"

true|obj→true

classTypeErrorRaisedwhenencounteringanobjectthatisnotoftheexpectedtype.

[1,2,3].first("two")

raisestheexception:

TypeError:noimplicitconversionofStringintoInteger

InFileserror.c

ParentStandardError

classUnboundMethodRubysupportstwoformsofobjectifiedmethods.ClassMethodisusedtorepresentmethodsthatareassociatedwithaparticularobject:thesemethodobjectsareboundtothatobject.BoundmethodobjectsforanobjectcanbecreatedusingObject#method.

Rubyalsosupportsunboundmethods;methodsobjectsthatarenotassociatedwithaparticularobject.ThesecanbecreatedeitherbycallingModule#instance_methodorbycallingunbindonaboundmethodobject.TheresultofbothoftheseisanUnboundMethodobject.

Unboundmethodscanonlybecalledaftertheyareboundtoanobject.Thatobjectmustbebeakind_of?themethod'soriginalclass.

classSquare

defarea

@side*@side

definitialize(side)

@side=side

area_un=Square.instance_method(:area)

s=Square.new(12)

area=area_un.bind(s)

area.call#=>144

Unboundmethodsareareferencetothemethodatthetimeitwasobjectified:subsequentchangestotheunderlyingclasswillnotaffecttheunboundmethod.

classTest

deftest

:original

um=Test.instance_method(:test)

classTest

deftest

:modified

t=Test.new

t.test#=>:modified

um.bind(t).call#=>:original

InFilesproc.c

ParentObject

Twomethodobjectsareequaliftheyareboundto

thesameobjectandrefertothesamemethoddefinitionandtheirownersarethesameclassormodule.

Returnsanindicationofthenumberofargumentsacceptedbyamethod.Returnsanonnegativeintegerformethodsthattakeafixednumberofarguments.ForRubymethodsthattakeavariablenumberofarguments,returns-n-1,wherenisthenumberofrequiredarguments.FormethodswritteninC,returns-1ifthecalltakesavariablenumberofarguments.

classC

defone;end

deftwo(a);end

defthree(*a);end

deffour(a,b);end

deffive(a,b,*c);end

defsix(a,b,*c,&d);end

c=C.new

c.method(:one).arity#=>0

c.method(:two).arity#=>1

c.method(:three).arity#=>-1

c.method(:four).arity#=>2

c.method(:five).arity#=>-3

c.method(:six).arity#=>-3

"cat".method(:size).arity#=>0

"cat".method(:replace).arity#=>1

"cat".method(:squeeze).arity#=>-1

"cat".method(:count).arity#=>-1

Bindumethtoobj.IfKlasswastheclassfromwhichumethwasobtained,obj.kind_of?(Klass)mustbetrue.

arity→fixnum

bind(obj)→method

classA

deftest

puts"Intest,class=#{self.class}"

classB<A

classC<B

um=B.instance_method(:test)

bm=um.bind(C.new)

bm.call

bm=um.bind(B.new)

bm.call

bm=um.bind(A.new)

bm.call

produces:

Intest,class=C

Intest,class=B

prog.rb:16:in%xbind':bindargumentmustbeaninstanceofB(TypeError)

fromprog.rb:16

Returnsacloneofthismethod.

classA

deffoo

return"bar"

m=A.new.method(:foo)

m.call#=>"bar"

n=m.clone.call#=>"bar"

Twomethodobjectsareequaliftheyareboundto

clone→new_method

thesameobjectandrefertothesamemethoddefinitionandtheirownersarethesameclassormodule.

Returnsahashvaluecorrespondingtothemethodobject.

SeealsoObject#hash.

Returnsthenameofthemethod.

Returnstheoriginalnameofthemethod.

Returnstheclassormodulethatdefinesthemethod.

Returnstheparameterinformationofthismethod.

ReturnstheRubysourcefilenameandlinenumbercontainingthismethodornilifthismethodwasnot

hash→integer

name→symbol

original_name→symbol

owner→class_or_module

parameters→array

definedinRuby(i.e.native)

ReturnsaMethodofsuperclass,whichwouldbecalledwhensuperisused.

super_method()

classUncaughtThrowErrorRaisedwhenthrowiscalledwithatagwhichdoesnothavecorrespondingcatchblock.

throw"foo","bar"

raisestheexception:

UncaughtThrowError:uncaughtthrow"foo"

InFilesvm_eval.c

ParentArgError

PublicClassMethods

Document-class:UncaughtThrowError

Raisedwhenthrowiscalledwithatagwhichdoesnothavecorrespondingcatchblock.

throw"foo","bar"

raisestheexception:

new(*args)

UncaughtThrowError:uncaughtthrow"foo"

Returnthetagobjectwhichwascalledfor.

Returnsformattedmessagewiththeinspectedtag.

Returnthereturnvaluewhichwascalledfor.

tag→obj

to_s→string

value→obj

classZeroDivisionErrorRaisedwhenattemptingtodivideanintegerby0.

#=>ZeroDivisionError:dividedby0

Notethatonlydivisionbyanexact0willraisetheexception:

42/0.0#=>Float::INFINITY

42/-0.0#=>-Float::INFINITY

0/0.0#=>NaN

InFilesnumeric.c

ParentStandardError

classfatalfatalisanExceptionthatisraisedwhenrubyhasencounteredafatalerrorandmustexit.Youarenotabletorescuefatal.

InFileserror.c

ParentException

Ruby2.2.4CoreAPIReferenceAPIReferenceThisistheAPIdocumentationfor'Ruby2.2.4CoreAPIReferenceAPIReference'.

ruby 2.2.4 core api reference api referenceruby 2.2.4 core api reference api reference this is the...

Documents

pthread api reference

rational rhapsody api reference manual - ibm€¦ ·...

pp api reference

iac api reference

vhost api reference

ev10 api reference

vocalware api reference

cps udc api reference, release 13.1 - cisco udc api...

application programmer interface (api) reference guide ·...

programming api reference guide - · pdf fileprogramming api...

api reference

api reference api version 2016-02-06 - aws … ·...

acropdf api reference

wolframalpha api reference

api reference guide

aws greengrass - api reference greengrass api reference...

amazon ses api v2 - api v2 reference · amazon ses api v2...

amazon kinesis data firehose api reference - api...

paypal api reference

api reference api version 2012-12-01