Ruby 1.9.2 リファレンスマニュアル > ライブラリ一覧 > 組み込みライブラリ > Stringクラス

class String

クラスの継承リスト: String < Comparable < Object < Kernel < BasicObject

Abstract

文字列のクラスです。 NUL 文字を含む任意のバイト列を扱うことができます。文字列の長さにはメモリ容量以外の制限はありません。

文字列は通常、文字列リテラルを使って生成します。以下に文字列リテラルの例をいくつか示します。

'str\\ing'   # シングルクオート文字列 (エスケープシーケンスがほぼ無効)
"string\n"   # ダブルクオート文字列 (エスケープシーケンスがすべて有効)
%q(str\\ing) # 「%q」文字列 (エスケープシーケンスがほぼ無効、デリミタが変えられる)
%Q(string\n) # 「%Q」文字列 (エスケープシーケンスがすべて有効、デリミタが変えられる)

# ヒアドキュメント
<<End
この行はヒアドキュメント
End

# ダブルクオートヒアドキュメント (クオートなしの場合と同じ)
<<"End"
この行はヒアドキュメント
End

# シングルクオートヒアドキュメント (一切のエスケープシーケンスが無効)
<<'End'
この行はヒアドキュメント
End

# 終端記号がインデントされたヒアドキュメント
# シングルクオート、ダブルクオートとの併用も可能
<<-End
この行はヒアドキュメント (終端記号をインデントできる)
   End

破壊的な変更

Ruby の String クラスは mutable です。つまり、オブジェクト自体を破壊的に変更できます。

「破壊的な変更」とは、あるオブジェクトの内容自体を変化させることです。例えば文字列のすべての文字を破壊的に大文字へ変更する String#upcase! メソッドの使用例を以下に示します。

a = "string"
b = a
a.upcase!
p a   # => "STRING"
p b   # => "STRING"

この例では、a に対してメソッドを呼んだにも関わらず b も変更されています。これは、変数 a と b が一つの文字列オブジェクトを指していて、 upcase! メソッドでそのオブジェクト自体が変更されたからです。

upcase! の非破壊版である String#upcase を使った例を以下に示します。こちらでは a の変更が b に波及しません。

a = "string"
b = a
a = a.upcase
p a   # => "STRING"
p b   # => "string"

一般には、破壊的「ではない」メソッドを中心に使っていくほうがバグが出にくくなります。

String クラスのメソッドには破壊的なメソッドも非破壊的なメソッドもあります。破壊的なメソッドの例としては concat, sub!, upcase! などが挙げられます。非破壊的なメソッドの例としては index, sub, upcase などが挙げられます。

同じ動作で破壊的なメソッドと非破壊的なメソッドの両方が定義されているときは、破壊的なバージョンには名前の最後に「!」が付いています。例えば upcase メソッドは非破壊的で、upcase! メソッドは破壊的です。

ただし、この命名ルールを「破壊的なメソッドにはすべて『!』が付いている」と解釈しないでください。例えば concat には「!」が付いていませんが、破壊的です。あくまでも、「『!』が付いているメソッドと付いていないメソッドの両方があるときは、『!』が付いているほうが破壊的」というだけです。「『!』が付いているならば破壊的」は常に成立しますが、逆は必ずしも成立しません。

多言語化と文字列のエンコーディング

String オブジェクトは自身のエンコーディング情報を持ちます。インスタンスメソッドはエンコーディングに従い、1バイトではなく1文字を単位として動作します。エンコーディングの変換にはメソッド String#encode を使います。

動作例: (注)一行目にmagic commentが必要です。

# vim:set fileencoding=UTF-8:
p "いろは".size      #=> 3
p "漢字"[0]          #=> "漢"
p "山本山".reverse   #=> "山本山"

s = "ruビー"
s[0..1] = "ル"
p s                  #=> "ルビー"

e = "言語".encode("EUC-JP")
u = "言語".encode("UTF-8")
p e.encoding                   #=> Encoding::EUC_JP
p u.encoding                   #=> Encoding::UTF_8

より詳しく知りたい場合は、[[unknown:m17n]] を参照してください。

文字列同士の比較・結合

文字列同士の比較・結合などでは両者のエンコーディングを意識する必要があります。例えば String#== は両者のエンコーディングが等しくバイト列表現が等しい場合にのみ true を返します。このときエンコーディングが UTF-8 であっても正規化せずに比較します。文字列の結合も同様です。異なるエンコーディング同士の文字列を結合する時は明示的にエンコーディングを変換する必要があります。

動作例: (注)一行目にmagic commentが必要です。

# vim:set fileencoding=UTF-8:
s = "いろは"
a = s.encode("EUC-JP")
b = s.encode("UTF-8")
p a == b                            #=> false

s = "合".encode("EUC-JP")
p s + "\u{4f53}".encode("EUC-JP")   #=> "合体"
p s + "\u{4f53}"                    #=> ArgumentError

ハッシュのキーの比較に使われる String#eql? は String#== の別名です。なので、ハッシュのキーに非 ASCII 文字列を使う場合には注意が必要です。

動作例: (注)一行目にmagic commentが必要です。

# encoding: UTF-8
h = {}
s = "いろは"
s.force_encoding("EUC-JP")
h[s] = 1
s.force_encoding("ASCII-8BIT")
p h[s]                             #=> nil

7bit クリーンな文字列

ASCII 互換エンコーディングをもつ 7bit クリーンな文字列はエンコーディングに関わらず ASCII として扱うことができます。例えば String#== は両者の文字エンコーディングが異なっていても true を返します。 ASCII 互換エンコーディングをもつ文字列にエンコーディングの変換なしで結合することができます。

例:

s = "abc"
a = s.encode("EUC-JP")
b = s.encode("UTF-8")
p a == b                           #=> true
p a + b                            #=> "abcabc"

ここで言う「ASCII互換エンコーディング」とは、コードポイントが同一という意味ではなくバイト列が同じことを意味します。従って UTF-16 はASCII互換ではありません。また厳密性を追求せず、おおむね互換なら互換と呼びます。よって Shift_JIS は ASCII 互換です。

バイト列を表す文字列

文字列ではない単なるバイト列も String オブジェクトで表されます。その時のエンコーディングは ASCII-8BIT です。

特異メソッド

new(string = "") -> String

string と同じ内容の新しい文字列を作成して返します。引数を省略した場合は空文字列を生成して返します。

[PARAM] string:: 文字列
[RETURN]: 引数 string と同じ内容の文字列オブジェクト

try_convert(obj) -> String | nil

obj を String に変換しようと試みます。変換には Object#to_str メソッドが使われます。変換後の文字列を返すか、何らかの理由により変換できなかった場合は nil が返されます。

[PARAM] obj:: 変換する任意のオブジェクト
[RETURN]: 変換後の文字列または nil

String.try_convert("str")     # => str
String.try_convert(/re/)      # => nil

インスタンスメソッド

self % args -> String

printf と同じ規則に従って args をフォーマットします。

args が配列であれば Kernel.#sprintf(self, *args) と同じです。それ以外の場合は Kernel.#sprintf(self, args) と同じです。

[PARAM] args:: フォーマットする値、もしくはその配列
[RETURN]: フォーマットされた文字列

例:

p "i = %d" % 10       # => "i = 10"
p "i = %x" % 10       # => "i = a"
p "i = %o" % 10       # => "i = 12"

p "i = %#d" % 10      # => "i = 10"
p "i = %#x" % 10      # => "i = 0xa"
p "i = %#o" % 10      # => "i = 012"

p "%d" % 10           # => "10"
p "%d,%o" % [10, 10]  # => "10,12"

sprintf フォーマット

Ruby の sprintf フォーマットは基本的に C 言語の sprintf(3) のものと同じです。ただし、short や long などの C 特有の型に対する修飾子がないこと、2進数の指示子(%b)が存在すること、sprintf のすべての方言をサポートしていないこと(%': 3桁区切り)などの違いがあります。

Ruby には整数の大きさに上限がないので、%b, %o, %x に負の数を与えると (左側に無限に1が続くとみなせるので) ..f のような表示をします。絶対値に符号を付けた形式で出力するためには %+x、% x のように指定します。

以下は sprintf フォーマットの書式です。[] で囲まれた部分は省略可能であることを示しています。

%[引数指定$][フラグ][幅][.精度]指示子

`%' 自身を出力するには `%%' とします。

以下それぞれの要素に関して説明します。

フラグ

フラグには #, +, ' '(スペース), -, 0 の5種類があります。

#

2進、8進、16進の指示子(b, o, x, X) ではそれぞれプレフィックスとして "0b", "0", "0x", "0X" を付加します。 C 言語とは異なり引数が 0 の場合にもプレフィックスが付加されます。

  p sprintf("%#b", 10) #=> "0b1010"
  p sprintf("%#o", 10) #=> "012"
  p sprintf("%#x", 10) #=> "0xa"
  p sprintf("%#X", 10) #=> "0XA"

浮動小数点数 (f, e, E, g, G) に対しては必ず出力に"."をつけます。

  p sprintf("%.0f", 10) #=> "10"
  p sprintf("%#.0f", 10) #=> "10."
  p sprintf("%.0e", 10) #=> "1e+01"
  p sprintf("%#.0e", 10) #=> "1.e+01"

また g, G では上記に加えて末尾の余分な0が残ります。

  p sprintf("%.05g", 10) #=> "10"
  p sprintf("%#.05g", 10) #=> "10.000"

+

出力文字列を符号付きにします。特に正の数では`+'が付加されます。数値の指示子 (d, i, b, o, x, X, u, f, e, E, g, G) に対してだけ意味を持ちます。また、特に b, o, x, X, u に対しては、負数に対して "-" を付加することを示します。

  p sprintf("%d", 1)   #=> "1"
  p sprintf("%+d", 1)  #=> "+1"

  p sprintf("%x", -1)  #=> "..f"  # ".." は無限に f が続くことを表している
  p sprintf("%+x", -1) #=> "-1"

' '(スペース)

`+' と同じですが正の符号 `+' の代わりに空白を用います。数値の指示子 (d, i, b, o, x, X, u, f, e, E, g, G) に対してだけ意味を持ちます。

  p sprintf("%d", 1)   #=> "1"
  p sprintf("%+d", 1)  #=> "+1"
  p sprintf("% d", 1)  #=> " 1"

  p sprintf("%x", -1)  #=> "..f"
  p sprintf("% x", 1)  #=> " 1"
  p sprintf("% x", -1) #=> "-1"

-

出力を左詰めにします幅の指定がなければ意味がありません。

0

出力が右詰めの場合に余った部分に空白の代わりに "0" を詰めます。

数値の指示子の一部(d, i, b, o, x, X, u, f, g, G)に対してだけ意味を持ちます(e, E には意味がない)

  p sprintf("%010d", 10)   #=> "0000000010"

`#' と一緒に指定した場合の出力は以下のようになります。

  p sprintf("%#010x", 10)  #=> "0x0000000a"
  p sprintf("%#010o", 10)  #=> "0000000012"
  p sprintf("%#010b", 10)  #=> "0b00001010"

これは、以下と同じです。

  p sprintf("%#10.8x", 10) #=> "0x0000000a"
  p sprintf("%#10.9o", 10) #=> "0000000012"
  p sprintf("%#10.8b", 10) #=> "0b00001010"

通常は、以下のようになります。

  p sprintf("%#10x", 10)   #=> "       0xa"
  p sprintf("%#10o", 10)   #=> "       012"
  p sprintf("%#10b", 10)   #=> "    0b1010"

幅

0以外の数字で始まる数字列は幅指定になります。幅は生成文字列の長さを示します。後述の精度の値によらずこの幅分だけの文字列が生成されます。

幅の指定はフラグで付与される " ", "+", "-", "0b", "0", "0x", "0X" の長さも考慮されます。

p sprintf("%+5d", 11)  #=> "  +11"
p sprintf("%+-5d", 11) #=> "+11  "
p sprintf("%+05d", 11) #=> "+0011"

幅は「最低限必要な幅」の指定になります。結果の文字列が指定した幅を超える場合は幅の指定は無効になります。

幅として `*' を指定すると幅の値を引数から得ることになります。

p sprintf("%#05x", 10)    #=> "0x00a"
p sprintf("%#0*x", 5, 10) #=> "0x00a"

精度

"." の後に続く数字列は精度を表します("." のみの場合 ".0" と同じです)。精度は整数の指示子 (d, i, b, o, x, X, u) に対しては、数値列部分の長さを意味します。

p sprintf("%10.5d", 1)  #=> "     00001"
p sprintf("%#10.5x", 1) #=> "   0x00001"
p sprintf("%+10.5x", 1) #=> "    +00001"

浮動小数点数の指示子 (f) に対しては小数部の桁数を意味します。

p sprintf("%10.5f", 1)   #=> "   1.00000"
p sprintf("%10.5f", 10)  #=> "  10.00000"

浮動小数点数の指示子 (e, E, g, G) に対しては有効桁数を意味します。

p sprintf("%10.5e", 1)   #=> "1.00000e+00"
p sprintf("%10.5e", 10)  #=> "1.00000e+01"
p sprintf("%10.5g",  10)  #=> "        10"
p sprintf("%#10.5G", 10)  #=> "    10.000"

文字列の指示子(s, p) に対しては引数の文字列のうち指定した数を超える分を切り捨てます。幅と精度を同じ値にすれば、どのような引数に対してもその長さだけの出力を行うことになります。

p sprintf("%10.2s", "foo")  #=> "        fo"

p sprintf("%5.5s", "foo")     #=> "  foo"
p sprintf("%5.5s", "foobar")  #=> "fooba"

精度として `*' を指定すると精度の値を引数から得ることになります。

p sprintf("%.5s", "foobar")    #=> "fooba"
p sprintf("%.*s", 5, "foobar") #=> "fooba"

指示子

指示子は引数の型の解釈を示します。指示子を省略することはできません。指示子には大きく分けて

文字列を表す指示子: c, s, p
整数を表す指示子: d, i, u, b, o, x, X,
浮動小数点数を表す指示子: f, g, e, E, G

があります

c

引数の数値(0～255)を文字コードとみなして対応する文字を出力します。引数が数値以外のオブジェクトの場合 to_int メソッドによる変換を試みます。引数として範囲内の一文字の文字列も受けつけます。文字そのものを出力します。

  p sprintf("%c", 97)  #=> "a"
  p sprintf("%c", 'a') #=> "a"

フラグ `-' と幅の指定だけが意味を持ちます。

s

文字列を出力します。

引数が String オブジェクトでなければ to_s メソッドにより文字列化したものを引数として扱います。

p

Object#inspect の結果を出力します。

  p sprintf("%s", /e+/)  #=> "(?-mix:e+)"
  p sprintf("%p", /e+/)  #=> "/e+/"

d

i

引数の数値を10進表現の整数として出力します。

引数が整数でなければ関数 Kernel.#Integer と同じ規則で整数に変換されます。

  p sprintf("%d", -1) #=> "-1"
  p sprintf("%d", 3.1) #=> "3"
  p sprintf("%d", '0b1010') #=> "10"

u

引数の数値を符号なし整数とみなして10進表現の整数として出力します。

  p sprintf("%u", '0b1010') #=> "10"
  p sprintf("%u", -1) #=> "-1"

b

o

x

X

整数をそれぞれ2進、8進、16進、16進(大文字)表現の文字列で出力します。

`#' フラグを指定すれば "0b", "0", "0x", "0X" を先頭に付加します。

`+', ` ' フラグがない場合、負の数には ".." が先頭(`#' フラグがあれば "0x" などの後)に付加されます。これは最上位桁の文字が無限に続くことを意味し、2の補数表現で負の数を表しています。

   p sprintf("%#b", 10)    #=> "0b1010"
   p sprintf("%#o", 10)    #=> "012"
   p sprintf("%#x", 10)    #=> "0xa"

   # 負の数に対して ".." が付加されます
   p sprintf("%#b", -1)    #=> "0b..1"
   p sprintf("%#o", -1)    #=> "0..7"
   p sprintf("%#x", -1)    #=> "0x..f"

   p sprintf("%10x", -1)   #=> "       ..f"
   p sprintf("%-10x", -1)  #=> "..f       "

   # 「精度」を指定した場合、".." は付加されません
   p sprintf("%.10x", -1)  #=> "ffffffffff"

f

e

E

g

G

f は小数点表現(xxx.xxx)で数値を出力します。

e は指数表現(x.xxxe+xx)で数値を出力します。

g は指数が -4 より小さいか精度以上の場合に e と同じ出力を、それ以外では f と同じ出力を行います。ただし、小数部の末尾の0は取り除かれます。

大文字の指示子(E, G)は出力のアルファベットを大文字にします。

  p sprintf("%f", 1.0) #=> "1.000000"
  p sprintf("%e", 1.0) #=> "1.000000e+00"
  p sprintf("%g", 1.0) #=> "1"

  p sprintf("%f", 10.1) #=> "10.100000"
  p sprintf("%e", 10.1) #=> "1.010000e+01"
  p sprintf("%g", 10.1) #=> "10.1"

  p sprintf("%g", 10 ** 6)  #=> "1e+06"
  p sprintf("%g", 10 ** -5) #=> "1e-05"

精度の省略値は 6 です。

無限大、NaN(Not a Number) に対する出力は以下のとおりです。

  p sprintf("%f",  1.0/0)  #=> "inf"
  p sprintf("%f", -1.0/0)  #=> "-inf"
  p sprintf("%f",  0.0/0)  #=> "nan"

  p sprintf("%E",  1.0/0)  #=> "INF"
  p sprintf("%E", -1.0/0)  #=> "-INF"
  p sprintf("%E",  0.0/0)  #=> "NAN"

f, e, E, g, G に関しては sprintf(3) の結果を利用しています。従って出力結果は実際にはシステムに依存することになります。

引数指定

利用頻度が低いので最後に説明します。

nth$

nth 番目の引数のフォーマットを行うことを示します。

  p sprintf("%d, %x, %o", 1, 2, 3) #=> "1, 2, 3"
  p sprintf("%3$d, %2$x, %1$o", 1, 2, 3) #=> "3, 2, 1"

  p sprintf("%1$d, %1$x, %1$o", 10) #=> "10, a, 12"

状況によってフォーマットを変えたいが引数の順序を変えたくない場合に使用します。

  case ENV['LC_TIME']
  when /^ja_JP/
    fmt = "%1$d年%2$d月%3$d日"
  else
    fmt = "%2$02d/%03$2d/%1$02d"
  end

  p sprintf(fmt, 1, 4, 22) #=> "04/22/01"

"*" の後に指定することで幅や精度を引数で指定することもできます。

  p sprintf("%5.2f", 1)              #=> " 1.00"
  p sprintf("%*.*f", 5, 2, 1)        #=> " 1.00"
  p sprintf("%1$*2$.*3$f", 1, 5, 2)  #=> " 1.00"

self * times -> String

文字列の内容を times 回だけ繰り返した新しい文字列を作成して返します。

[PARAM] times:: 整数
[RETURN]: self を times 回繰り返した新しい文字列
[EXCEPTION] ArgumentError:: 引数に負数を指定したときに発生します。

例:

p "str" * 3   # => "strstrstr"

str = "abc"
p str * 4   # => "abcabcabcabc"
p str * 0   # => ""
p str       # => "abc"  (変化なし)

self + other -> String

文字列と other を連結した新しい文字列を返します。

[PARAM] other:: 文字列
[RETURN]: self と other を連結した文字列

例:

p "str" + "ing"   # => "string"

a = "abc"
b = "def"
p a + b   # => "abcdef"
p a       # => "abc"  (変化なし)
p b       # => "def"

self << other -> self

concat(other) -> self

self に文字列 other を破壊的に連結します。 other が 0 から 255 のまでの整数である場合はその 1 バイトを末尾に追加します (つまり、整数が示す ASCII コードの文字が追加されます)。

self を返します。

[PARAM] other:: 文字列もしくは 0 から 255 までの範囲の整数

例:

str = "string"
str.concat "XXX"
p str    # => "stringXXX"

str << "YYY"
p str    # => "stringXXXYYY"

str << 56  # 文字AのASCIIコード
p str    # => "stringXXXYYYA"

self <=> other -> Integer

self と other を ASCII コード順で比較して、 self が大きい時には正の整数、等しい時には 0、小さい時には負の整数を返します。このメソッドは Comparable モジュールのメソッドを実装するために使われます。

変数 $= の値が真であるときはアルファベットの大文字小文字を無視して比較します。ただし $= 変数はいずれ廃止されることが決まっているので $= に頼るべきではありません。代わりに String#casecmp を使ってください。

other が文字列でない場合、 other.to_str と other.<=> が定義されていれば 0 - (other <=> self) の結果を返します。そうでなければ nil を返します。

[PARAM] other:: 文字列
[RETURN]: 比較結果の整数か nil

例:

p "aaa" <=> "xxx"   # => -1
p "aaa" <=> "aaa"   # => 0
p "xxx" <=> "aaa"   # => 1

p "string" <=> "stringAA"  # => -1
p "string" <=> "string"    # => 0
p "stringAA" <=> "string"  # => 1

self == other -> bool

文字列の内容が文字列 other の内容と等しいときに true を返します。等しくなければ false を返します。

このメソッドは文字列の内容を比較します。同一のオブジェクトかどうかを比較するわけではありません。つまり、"string" == str という式を実行した場合には、 str が "string" という内容の文字列でありさえすれば常に true を返します。同一のオブジェクトであるかどうかを判定したいときは Object#equal? を使ってください。

変数 $= の値が真であるときはアルファベットの大文字小文字を無視して比較します。ただし $= 変数はいずれ廃止されることが決まっているので $= に頼るべきではありません。

アルファベットの大文字小文字を無視して比較したい場合は、String#upcase, String#downcase で大文字小文字を揃えてから比較するとよいです。

[PARAM] other:: 任意のオブジェクト
[RETURN]: true か false

例:

p "string" == "string"  # => true
p "string" == "STRING"  # => false
p "string" == ""        # => false
p "" == "string"        # => false

p "string" == "str" + "ing"   # => true   (内容が同じなら true)
p "string" == "stringX".chop  # => true   (内容が同じなら true)

p "string".upcase == "String".upcase     # => true
p "string".downcase == "String".downcase # => true

[SEE_ALSO] String#<=>, String#casecmp

self =~ other -> Integer

正規表現 other とのマッチを行います。マッチが成功すればマッチした位置のインデックスを、そうでなければ nil を返します。

other が正規表現でも文字列でもない場合は other =~ self を行います。

Ruby 1.6 までは、other が文字列であった場合には other を正規表現にコンパイルして self とのマッチを実行していました。しかし Ruby 1.8 以降では other に文字列を指定すると例外 TypeError が発生します。

このメソッドが実行されると、組み込み変数 $~, $1, ... にマッチに関する情報が設定されます。

[PARAM] other:: 正規表現もしくは =~ メソッドを持つオブジェクト
[EXCEPTION] TypeError:: other が文字列であった

例:

p "string" =~ /str/   # => 0
p "string" =~ /not/   # => nil
p "abcfoo" =~ /foo/   # => 3

self[nth] -> Integer

slice(nth) -> Integer

nth 番目のバイトを整数 (文字コード) で返します。 nth が負の場合は文字列の末尾から数えます。つまり、 self.size + nth 番目のバイトを返します。

nth が範囲外を指す場合は nil を返します。

[PARAM] nth:: バイトインデックスを表す整数
[RETURN]: 文字コードを表す整数

例:

p 'bar'[2]        # => 114
p 'bar'[2] == ?r  # => true
p 'bar'[-1]       # => 114

p 'bar'[3]        # => nil
p 'bar'[-4]       # => nil

このメソッドの逆に文字コードから文字列を得るには Integer#chr を使ってください。

self[nth, len] -> String | nil

slice(nth, len) -> String | nil

nth バイト番目から長さ len バイトの部分文字列を新しく作って返します。 nth が負の場合は文字列の末尾から数えます。

nth が範囲外を指す場合は nil を返します。

[PARAM] nth:: 取得したい文字列の開始インデックス。整数
[PARAM] len:: 取得したい文字列の長さ。正の整数

例:

str0 = "bar"
p str0[2, 1]         #=> "r"
p str0[2, 0]         #=> ""
p str0[2, 100]       #=> "r"  (右側を超えても平気)
p str0[2, 1] == ?r   #=> false  (左辺は長さ1の文字列、右辺は整数の文字コード)
p str0[-1, 1]        #=> "r"
p str0[-1, 2]        #=> "r" (飽くまでも「右に向かって len バイト」)

p str0[3, 1]         #=> ""
p str0[4, 1]         #=> nil
p str0[-4, 1]        #=> nil
str1 = str0[0, 2]    # (str0の「一部」をstr1とする)
p str1               #=> "ba"
str1[0] = "XYZ"
p str1               #=> "XYZa" (str1の内容が破壊的に変更された)
p str0               #=> "bar" (str0は無傷、str1はstr0と内容を共有していない)

self[substr] -> String

slice(substr) -> String

self が substr を含む場合、一致した文字列を新しく作って返します。 substr を含まなければ nil を返します。

[PARAM] substr:: 取得したい文字列のパターン。文字列

例:

substr = "bar"
result = "foobar"[substr]
p result   # => "bar"
p substr.equal?(result)   # => false

self[regexp, nth = 0] -> String

slice(regexp, nth = 0) -> String

正規表現 regexp の nth 番目の括弧にマッチする最初の部分文字列を返します。 nth を省略したときや 0 の場合は正規表現がマッチした部分文字列全体を返します。正規表現が self にマッチしなかった場合や nth に対応する括弧がないときは nil を返します。

このメソッドを実行すると、マッチ結果に関する情報が組み込み変数 $~ に設定されます。

[PARAM] regexp:: 取得したい文字列のパターンを示す正規表現
[PARAM] nth:: 取得したい正規表現レジスタのインデックス。整数

p "foobar"[/bar/]  # => "bar"
p $~.begin(0)      # => 3

p "foobar"[/bar/]   # => "bar"
p $~.begin(0)       # => 3

p "def getcnt(line)"[ /def\s+(\w+)/, 1 ]   # => "getcnt"

self[first..last] -> String

slice(first..last) -> String

インデックス first から last までのバイトを含む新しい文字列を作成して返します。インデックスと文字列の対応については以下の対照図も参照してください。

  0   1   2   3   4   5   (インデックス)
 -6  -5  -4  -3  -2  -1   (負のインデックス)
| a | b | c | d | e | f |
|<--------->|                'abcdef'[0..2]  # => 'abc'
                |<----->|    'abcdef'[4..5]  # => 'ef'
        |<--------->|        'abcdef'[2..4]  # => 'cde'

last が文字列の長さ以上のときは (文字列の長さ - 1) を指定したものとみなされます。

first が 0 より小さいか文字列の長さより大きいとき、および first > last + 1 であるときは nil を返します。ただし first および last のどちらかまたは両方が負の数のときは一度だけ文字列の長さを足して再試行します。

[PARAM] first:

..last 取得したい文字列の範囲を示す Range オブジェクト

例:

'abcd'[ 2 ..  1] # => ""
'abcd'[ 2 ..  2] # => "c"
'abcd'[ 2 ..  3] # => "cd"
'abcd'[ 2 ..  4] # => "cd"

'abcd'[ 2 .. -1] # => "cd"   # str[f..-1] は「f 文字目から
'abcd'[ 3 .. -1] # => "d"    # 文字列の最後まで」を表す慣用句

'abcd'[ 1 ..  2] # => "bc"
'abcd'[ 2 ..  2] # =>  "c"
'abcd'[ 3 ..  2] # =>   ""
'abcd'[ 4 ..  2] # =>  nil

'abcd'[-3 ..  2] # =>  "bc"
'abcd'[-4 ..  2] # => "abc"
'abcd'[-5 ..  2] # =>  nil

self[first...last] -> String

slice(first...last) -> String

文字列先頭を 0 番目の隙間、末尾を self.length 番目の隙間として、 first 番目の隙間から last 番目の隙間までに含まれるバイト列を含んだ新しい文字列を作成して返します。

文字列と「隙間」の関係については以下の模式図を参照してください。

 0   1   2   3   4   5   6  (隙間番号)
-6  -5  -4  -3  -2  -1      (負の隙間番号)
 | a | b | c | d | e | f |
 |<--------->|                'abcdef'[0...3]  # => 'abc'
                 |<----->|    'abcdef'[4...6]  # => 'ef'
         |<--------->|        'abcdef'[2...5]  # => 'cde'

last が文字列の長さよりも大きいときは文字列の長さを指定したものとみなされます。

first が 0 より小さいか文字列の長さより大きいとき、および first > last であるときは nil を返します。ただし first と last のどちらかまたは両方が負の数であるときは一度だけ文字列の長さを足して再試行します。

[PARAM] first:

...last 取得したい文字列の範囲を示す Range オブジェクト

例:

'abcd'[ 2 ... 3] # => "c"
'abcd'[ 2 ... 4] # => "cd"
'abcd'[ 2 ... 5] # => "cd"

'abcd'[ 1 ... 2] # => "b"
'abcd'[ 2 ... 2] # => ""
'abcd'[ 3 ... 2] # => nil

'abcd'[-3 ... 2] # => "b"
'abcd'[-4 ... 2] # => "ab"
'abcd'[-5 ... 2] # => nil

self[nth] = val

nth 番目のバイトを文字列 val で置き換えます。 val が 0 から 255 の範囲の整数である場合、文字コードとみなしてその文字で置き換えます。

val を返します。

[PARAM] nth:: 置き換えたいバイトのインデックス
[PARAM] val:: 指定バイトと置き換える文字列もしくはバイト

例:

buf = "string"
buf[1] = "!!"
p buf   # => "s!!ring"

self[nth, len] = val

nth バイト番目から長さ len バイトの部分文字列を文字列 val で置き換えます。 nth が負の場合は文字列の末尾から数えます。

val を返します。

[PARAM] nth:: 置き換えたい部分文字列の開始インデックス
[PARAM] len:: 置き換えたい部分文字列の長さ
[PARAM] val:: 指定範囲の部分文字列と置き換える文字列

例:

buf = "string"
buf[1, 4] = "!!"
p buf   # => "s!!g"

self[substr] = val

文字列中の substr に一致する最初の部分文字列を文字列 val で置き換えます。

self が substr を含まない場合は例外 IndexError が発生します。

val を返します。

[PARAM] substr:: 置き換えたい部分文字列のパターンを示す文字列
[PARAM] val:: 指定範囲の部分文字列と置き換える文字列
[EXCEPTION] IndexError:: self が部分文字列 substr を含まない

例:

buf = "string"
buf["trin"] = "!!"
p buf   # => "s!!g"

buf = "string"
buf["nosuchstring"] = "!!"   # IndexError

self[regexp, nth = 0] = val

正規表現 regexp の nth 番目の括弧にマッチする最初の部分文字列を文字列 val で置き換えます。 nth を省略したときや nth が 0 の場合は、マッチした部分文字列全体を val で置き換えます。

正規表現がマッチしなければ例外 IndexError が発生します。

val を返します。

[PARAM] regexp:: 置き換えたい部分文字列のパターンを示す正規表現
[PARAM] nth:: 置き換えたい部分文字列のパターンを示す正規表現レジスタの番号
[PARAM] val:: 指定範囲の部分文字列と置き換えたい文字列

例:

buf = "string"
buf[/tr../] = "!!"
p buf   # => "s!!g"

buf = "def exec(cmd)"
buf[/def\s+(\w+)/, 1] = "preprocess"
p buf    # => "def preprocess(cmd)"

self[first..last] = val

インデックス first から last までの部分文字列を文字列 val で置き換えます。

val を返します。

[PARAM] first:

..last 置き換えたい範囲を示す Range オブジェクト

self[first...last] = val

インデックス first から last までの部分文字列を文字列 val で置き換えます。

val を返します。

[PARAM] first:

...last 置き換えたい範囲を示す Range オブジェクト

ascii_only? -> bool

文字列がASCII文字のみで構成されている場合に true を返します。さもなくば false を返します。

each_byte {|byte| ... } -> ()

bytes {|byte| ... } -> ()

each_byte -> Enumerator

bytes -> Enumerator

文字列の各バイトに対して繰り返します。

なお、バイトごとに分割した配列を得たいときは、 Ruby 1.8 までなら unpack('C*') を、 Ruby 1.9 以降は String#bytes.to_a を使ってください。

例:

"str".each_byte do |byte|
  p byte
end
    # => 115
    # => 116
    # => 114

[SEE_ALSO] String#unpack

bytesize -> Integer

文字列のバイト長を整数で返します。

例:

#coding:UTF-8
# 実行結果は文字コードによって異なります。
p "いろは".size     #=> 3
p "いろは".bytesize #=> 6

[SEE_ALSO] String#size

capitalize -> String

文字列先頭の文字を大文字に、残りを小文字に変更した文字列を返します。ただし、アルファベット以外の文字は位置に関わらず変更しません。

例:

p "foobar--".capitalize   # => "Foobar--"
p "fooBAR--".capitalize   # => "Foobar--"
p "FOOBAR--".capitalize   # => "Foobar--"

$KCODE が適切に設定されていない場合は、マルチバイト文字の一部をあやまって変換してしまう場合があります。この問題は以下のように Shift JIS エンコーディングを使う場合に発生します。

$KCODE = 'NONE'
# 文字列は Shift JIS エンコーディングで記述されている
puts "帰".capitalize   # => 蟻

また、$KCODE を設定しても、マルチバイト文字のいわゆる全角アルファベットは処理しません。

[SEE_ALSO] String#capitalize!, String#upcase, String#downcase, String#swapcase

capitalize! -> self | nil

文字列先頭の文字を大文字に、残りを小文字に変更します。ただし、アルファベット以外の文字は位置に関わらず変更しません。

[RETURN]: capitalize! は self を変更して返しますが、変更が起こらなかった場合は nil を返します。

例:

str = "foobar"
str.capitalize!
p str   # => "Foobar"

str = "fooBAR"
str.capitalize!
p str   # => "Foobar"

$KCODE = 'NONE'
# 文字列は Shift JIS エンコーディングで記述されている
puts "帰".capitalize   # => 蟻

また、$KCODE を設定しても、マルチバイト文字のいわゆる全角アルファベットは処理しません。

[SEE_ALSO] String#capitalize, String#upcase, String#downcase, String#swapcase

casecmp(other) -> Integer

String#<=> と同様に文字列の順序を比較しますが、アルファベットの大文字小文字の違いを無視します。

このメソッドの動作は組み込み変数 $= には影響されません。

[PARAM] other:: self と比較する文字列

例:

p 'a' <=> 'A'       # => 1
p 'a'.casecmp('A')  # => 0

[SEE_ALSO] String#<=>

center(width, padding = ' ') -> String

長さ width の文字列に self を中央寄せした文字列を返します。 self の長さが width より長い時には元の文字列の複製を返します。また、第 2 引数 padding を指定したときは空白文字の代わりに padding を詰めます。

[PARAM] width:: 返り値の文字列の最小の長さ
[PARAM] padding:: 長さが width になるまで self の両側に詰める文字

例:

p "foo".center(10)       # => "   foo    "
p "foo".center(9)        # => "   foo   "
p "foo".center(8)        # => "  foo   "
p "foo".center(7)        # => "  foo  "
p "foo".center(3)        # => "foo"
p "foo".center(2)        # => "foo"
p "foo".center(1)        # => "foo"
p "foo".center(10, "*")  # => "***foo****"

[SEE_ALSO] String#ljust, String#rjust

each_char {|cstr| block } -> self

chars {|cstr| block } -> self

each_char -> Enumerator

chars -> Enumerator

文字列の各文字に対して繰り返します。

たとえば、

"hello".each_char {|c| print c, ' ' }

は次のように出力されます。

h e l l o

chomp(rs = $/) -> String

self の末尾から rs で指定する改行コードを取り除いた文字列を生成し返します。ただし、rs が "\n" ($/ のデフォルト値) のときは、実行環境によらず "\r", "\r\n", "\n" のすべてを改行コードとみなして取り除きます。

rs に nil を指定した場合、このメソッドは何もしません。

rs に空文字列 ("") を指定した場合は「パラグラフモード」になり、末尾の連続する改行コードをすべて取り除きます。

例:

p "foo\n".chomp             # => "foo"
p "foo\n".chomp("\n")       # => "foo"
p "foo\r\n".chomp("\r\n")   # => "foo"

$/ = "\n"   # デフォルト値と同じ
p "foo\r".chomp    # => "foo"
p "foo\r\n".chomp  # => "foo"
p "foo\n".chomp    # => "foo"
p "foo\n\r".chomp  # => "foo\n"

chomp!(rs = $/) -> self | nil

self の末尾から rs で指定する改行コードを取り除きます。ただし rs が "\n" ($/ のデフォルト値) のときは、システムによらず "\r", "\r\n", "\n" のすべてを改行コードとみなして取り除きます。

rs に nil を指定した場合、このメソッドは何もしません。

rs に空文字列 ("") を指定した場合は「パラグラフモード」になり、末尾の連続する改行コードをすべて取り除きます。

[RETURN]: chomp! は通常 self を返しますが、取り除く改行がなかった場合は nil を返します。

例:

buf = "string\n"
buf.chomp!
p buf   # => "string"

$/ = "\n"   # デフォルトと同じ
p "foo\r".chomp    # => "foo"
p "foo\r\n".chomp  # => "foo"
p "foo\n".chomp    # => "foo"
p "foo\n\r".chomp  # => "foo\n"

chop -> String

文字列の最後の文字を取り除いた新しい文字列を生成して返します。ただし、文字列の終端が "\r\n" であればその 2 文字を取り除きます。

例:

p "string\n".chop    # => "string"
p "string\r\n".chop  # => "string"
p "string".chop      # => "strin"
p "strin".chop       # => "stri"
p "".chop            # => ""

chop! -> self | nil

文字列の最後の文字を取り除きます。ただし、終端が "\r\n" であればその 2 文字を取り除きます。

[RETURN]: chop! は self を変更して返しますが、取り除く文字がなかった場合は nil を返します。

chr -> String

self の最初の文字だけを含む文字列を返します。

[SEE_ALSO] String#ord, Integer#chr

clear -> ()

文字列の内容を削除して空にします。 self を返します。

例:

str = "abc"
str.clear
p str     # => ""

str = ""
str.clear
p str   # => ""

each_codepoint {|codepoint| block } -> self

codepoints {|codepoint| block } -> self

each_codepoint -> Enumerator

codepoints -> Enumerator

文字列の各コードポイントに対して繰り返します。

#coding:UTF-8
"hello わーるど".codepoints.to_a
# => [104, 101, 108, 108, 111, 32, 12431, 12540, 12427, 12393]

count(*chars) -> Integer

chars で指定された文字が文字列 self にいくつあるか数えます。

検索する文字を示す引数 chars の形式は tr(1) と同じです。つまり、「"a-c"」は文字 a から c を意味し、「"^0-9"」のように文字列の先頭が「^」の場合は指定文字以外を意味します。

文字「-」は文字列の両端にない場合にだけ範囲指定の意味になります。同様に、「^」も文字列の先頭にあるときだけ否定の効果を発揮します。また、「-」「^」「\」はバックスラッシュ (「\」) によりエスケープできます。

引数を複数指定した場合は、すべての引数にマッチした文字だけを数えます。

[PARAM] chars:: 出現回数を数える文字のパターン

例:

p 'abcdefg'.count('c')               # => 1
p '123456789'.count('2378')          # => 4
p '123456789'.count('2-8', '^4-6')   # => 4

# ファイルの行数を数える
n_lines = File.open("foo").read.count("\n")

# ファイルの末尾に改行コードがない場合にも対処する
buf = File.open("foo").read
n_lines = buf.count("\n")
n_lines += 1 if /[^\n]\z/ =~ buf
    # if /\n\z/ !~ buf だと空ファイルを 1 行として数えてしまうのでダメ

crypt(salt) -> String

self と salt から暗号化された文字列を生成して返します。 salt には英数字、ドット (「.」)、スラッシュ (「/」) から構成される、 2 バイト以上の文字列を指定します。

暗号化された文字列から暗号化前の文字列 (self) を求めることは一般に困難で、 self を知っている者のみが同じ暗号化された文字列を生成できます。このことから self を知っているかどうかの認証に使うことが出来ます。

salt には、以下の様になるべくランダムな文字列を選ぶべきです。他にも [ruby-list:29297] などがあります。

注意:

crypt の処理は crypt(3) の実装に依存しています。従って、crypt で処理される内容の詳細や salt の与え方については、利用環境の crypt(3) 等を見て確認してください。
crypt の結果は利用環境が異なると変わる場合があります。 crypt の結果を、異なる利用環境間で使用する場合には注意して下さい。
典型的な DES を使用した crypt(3) の場合、 self の最初の 8 バイト、salt の最初の 2 バイトだけが使用されます。

[PARAM] salt:: 文字列を暗号化するための鍵となる文字列。英数字・「.」・「/」のいずれかで構成される 2 バイト以上の文字列

例:

# パスワードの暗号化
salt = [rand(64),rand(64)].pack("C*").tr("\x00-\x3f","A-Za-z0-9./")
passwd.crypt(salt)

# UNIX のログイン認証
require 'etc'

def valid_login?(user, password)
  ent = Etc.getpwnam(user)
  passwd.crypt(ent.passwd) == ent.passwd
end

p valid_login?("taro", "password")   # => 真偽値が得られる

delete(*strs) -> String

self から strs に含まれる文字を取り除いた文字列を生成し返します。

str の形式は tr(1) と同じです。つまり、`a-c' は a から c を意味し、"^0-9" のように文字列の先頭が `^' の場合は指定文字以外を意味します。

「-」は文字列の両端にない場合にだけ範囲指定の意味になります。「^」も文字列の先頭にあるときだけ効果を発揮します。また、「-」「^」「\」はバックスラッシュ (「\」) によってエスケープできます。

なお、引数を複数指定した場合は、すべての引数にマッチする文字だけが削除されます。

[PARAM] strs:: 削除する文字列を示す文字列 (のリスト)

例:

p "123456789".delete("2378")         #=> "14569"
p "123456789".delete("2-8", "^4-6")  #=> "14569"

delete!(*strs) -> self | nil

self から strs に含まれる文字を破壊的に取り除きます。

str の形式は tr(1) と同じです。つまり、「a-c」は a から c を意味し、"^0-9" のように文字列の先頭が「^」の場合は指定文字以外を意味します。

「-」は文字列の両端にない場合にだけ範囲指定の意味になります。「^」も文字列先頭にあるときだけ否定の効果を発揮します。また、「-」「^」「\」はバックスラッシュ (「\」) によってエスケープできます。

なお、引数を複数指定した場合は、すべての引数にマッチする文字だけが削除されます。

[RETURN]: 通常は self を返しますが、何も変更が起こらなかった場合は nil を返します。
[PARAM] strs:: 削除する文字列を示す文字列 (のリスト)

例:

p "123456789".delete("2-8", "^4-6")  #=> "14569"
p "123456789".delete("2378")         #=> "14569"

downcase -> String

'A' から 'Z' までのアルファベット大文字をすべて小文字に置き換えた新しい文字列を生成し返します。アルファベット大文字以外の文字はすべてそのまま保存されます。

処理する文字列の文字コードが Shift JIS で、しかも $KCODE が適切に設定されていない場合、このメソッドはマルチバイト文字の一部も変換してしまう場合があります。逆に、$KCODE を適切に設定してもマルチバイト文字のアルファベットは処理できません。

例:

p "STRing?".downcase   # => "string?"

# -*- Coding: shift_jis -*-
$KCODE ='n'
puts "帰".downcase   # => 蟻

[SEE_ALSO] String#upcase, String#swapcase, String#capitalize

downcase! -> self | nil

文字列中の 'A' から 'Z' までのアルファベット大文字をすべて破壊的に小文字に置き換えます。アルファベット大文字以外の文字はすべてそのまま保存されます。

[RETURN]: self を変更して返します。変更が無かった場合は nil を返します。

例:

p "STRing?".downcase   # => "string?"

# -*- Coding: shift_jis -*-
$KCODE ='n'
puts "帰".downcase   # => 蟻

[SEE_ALSO] String#upcase, String#swapcase, String#capitalize

dump -> String

文字列中の非表示文字をバックスラッシュ記法に置き換えた文字列を返します。 str == eval(str.dump) となることが保証されています。

例:

# p だとさらにバックスラッシュが増えて見にくいので puts している
puts "abc\r\n\f\x00\b10\\\"".dump   # => "abc\r\n\f\000\01010\\\""

each_line(rs = $/) {|line| ... } -> ()

lines(rs = $/) {|line| ... } -> ()

each_line(rs = $/) -> Enumerator

lines(rs = $/) -> Enumerator

文字列中の各行に対して繰り返します。行の区切りは rs に指定した文字列で、そのデフォルト値は変数 $/ の値です。各 line には区切りの文字列も含みます。

rs に nil を指定すると行区切りなしとみなします。 rs に空文字列 "" を指定すると「パラグラフモード」になり、改行コードが 2 つ以上連続するところで文字列を分割します (つまり空行で分割します)。

[PARAM] rs:: 行末を示す文字列

例:

"aa\nbb\ncc\n".each_line do |line|
  p line
end
    # => "aa\n"
    # => "bb\n"
    # => "cc\n"

p "aa\nbb\ncc\n".lines.to_a   # => ["aa\n", "bb\n", "cc\n"]
p "aa\n".lines.to_a           # => ["aa\n"]
p "".lines.to_a               # => []

s = "aa\nbb\ncc\n"
p s.lines("\n").to_a #=> ["aa\n", "bb\n", "cc\n"]
p s.lines("bb").to_a #=> ["aa\nbb", "\ncc\n"]

empty? -> bool

文字列が空 (つまり長さ 0) の時、真を返します。

encode(encoding[, options]) -> String

encode(encoding, from_encoding[, options]) -> String

encode([options]) -> String

self を指定したエンコーディングに変換した文字列を作成して返します。引数を2つ与えた場合、第二引数は変換元のエンコーディングを意味します。さもなくば self のエンコーディングが使われます。無引数の場合は、Encoding.default_internal が nil でなければそれが変換先のエンコーディングになり、かつ :invalid => replace と :undef => replace が指定されたと見なされ、nil ならば変換は行われません。

[PARAM] encoding:: 変換先のエンコーディングを表す文字列か Encoding オブジェクトを指定します。
[PARAM] from_encoding:: 変換元のエンコーディングを表す文字列か Encoding オブジェクトを指定します。
[PARAM] option:: 変換オプションをハッシュで与えます。
[RETURN]: 変換された文字列

変換オプション

:invalid => nil: 変換元のエンコーディングにおいて不正なバイトがあった場合に、例外 Encoding::InvalidByteSequenceError を投げます。(デフォルト)
:invalid => :replace: 変換元のエンコーディングにおいて不正なバイトがあった場合に、不正なバイトを置換文字で置き換えます。
:undef => nil: 変換先のエンコーディングにおいて文字が定義されていない場合に、例外 Encoding::UndefinedConversionError を投げます。(デフォルト)
:undef => :replace: 変換先のエンコーディングにおいて文字が定義されていない場合に、未定義文字を置換文字で置き換えます。
:replace => string: 前述の :invalid => :replace や :undef => :replace で用いられる置換文字を指定します。デフォルトは Unicode 系のエンコーディングならば U+FFFD、それ以外では "?" です。
:xml => :text: 文字列を XML の CharData として適するように処理します。具体的には、'&'、'<'、'>'、をそれぞれ '&'、'<'、'>' に変換し、未定義文字を文字参照 (大文字16進数) に置き換えます。この出力は HTML の #PCDATA として利用することもできます。
:xml => :attr: 文字列を XML の AttValue として適するように処理します。具体的には、'&'、'<'、'>'、'"'、をそれぞれ '&'、'<'、'>'、'"' に変換し、未定義文字を文字参照 (大文字16進数) に置き換えます。この出力は HTML の属性値として利用することもできます。
:universal_newline => true: CR 改行および CRLF 改行を LF 改行に置き換えます。
:cr_newline => true: LF 改行を CR 改行に置き換えます。(CRLF は CRCR になります)
:crlf_newline => true: LF 改行を CRLF 改行に置き換えます。(CRLF は CRCRLF になります)

これ以上細かい指定を行いたい場合は、Encoding::Converter#convert を用いましょう。

例:

#coding:UTF-8
s = "いろは"
s.encode("EUC-JP")
s.encode(Encoding::UTF_8)

[SEE_ALSO] String#encode!

encode!(encoding[, options]) -> self

encode!(encoding, from_encoding[, options]) -> self

self を指定したエンコーディングに変換し、自身を置き換えます。引数を2つ与えた場合、第二引数は変換元のエンコーディングを意味します。さもなくば self のエンコーディングが使われます。変換後の self を返します。

(gsub!などと異なり)変換が行なわれなくても self を返します。

[PARAM] encoding:: 変換先のエンコーディングを表す文字列か Encoding オブジェクトを指定します。
[PARAM] from_encoding:: 変換元のエンコーディングを表す文字列か Encoding オブジェクトを指定します。
[RETURN]: 変換後のself

例:

#coding:UTF-8
s = "いろは"
s.encode!("EUC-JP")
s.encode!(Encoding::UTF_8)

[SEE_ALSO] String#encode

encoding -> Encoding

文字列のエンコーディング情報を表現した Encoding オブジェクトを返します。

[SEE_ALSO] Encoding

end_with?(str) -> bool

self の末尾が str であるとき true を返します。

[PARAM] str:: パターンを表す文字列

例:

"string".end_with?("ing")   # => true
"string".end_with?("str")   # => false

[SEE_ALSO] String#start_with?

eql?(other) -> bool

self == other と同じです。 Hash クラス内での比較に使われます。

[SEE_ALSO] Hash

force_encoding(encoding) -> self

文字列の持つエンコーディング情報を指定された encoding に変えます。

このとき実際のエンコーディングは変換されず、検査もされません。 Array#pack などで得られたバイト列のエンコーディングを指定する時に使います。

[PARAM] encoding:: 変更するエンコーディング情報を表す文字列か Encoding オブジェクトを指定します。

例:

s = [164, 164, 164, 237, 164, 207].pack("C*")
p s.encoding                                  #=> ASCII-8BIT
p s.force_encoding("EUC-JP")                  #=> "いろは"

u = [12411, 12408, 12392].pack("U*")
u.force_encoding("UTF-8")                     #=> "ほへと"

gsub(pattern, replace) -> String

文字列中で pattern にマッチする部分全てを文字列 replace で置き換えた文字列を生成し返します。

Ruby 1.6 以前では pattern が文字列の場合、その文字列を正規表現にコンパイルしていました。しかし Ruby 1.8 以降では、その文字列そのものがパターンになります。

置換文字列 replace 中の \& と \0 はマッチした部分文字列に、 \1 ... \9 は n 番目の括弧の内容に置き換えられます。置換文字列内では \`、\'、\+ も使えます。これらは $`、$'、$+ に対応します。

[PARAM] pattern:: 置き換える文字列のパターン
[PARAM] replace:: pattern で指定した文字列と置き換える文字列

例:

p 'abcdefg'.gsub(/def/, '!!')          # => "abc!!g"
p 'abcabc'.gsub(/b/, '<<\&>>')         # => "a<<b>>ca<<b>>c"
p 'xxbbxbb'.gsub(/x+(b+)/, 'X<<\1>>')  # => "X<<bb>>X<<bb>>"

注意:

第 2 引数 replace に $1 を埋め込んでも意図した結果にはなりません。この文字列が評価される時点ではまだ正規表現マッチが行われておらず、 $1 がセットされていないからです。

また、gsub では「\」が部分文字列との置き換えという特別な意味を持つため、 replace に「\」自身を入れたいときは「\」を二重にエスケープしなければなりません。

# ひとつめの括弧の内容に置き換えるときによくある間違い
p 'xbbb-xbbb'.gsub(/x(b+)/, "#{$1}")   # => "-"        # NG
p 'xbbb-xbbb'.gsub(/x(b+)/, "\1")      # => "1-1"      # NG
p 'xbbb-xbbb'.gsub(/x(b+)/, "\\1")     # => "bbb-bbb"  # OK
p 'xbbb-xbbb'.gsub(/x(b+)/, '\1')      # => "bbb-bbb"  # OK
p 'xbbb-xbbb'.gsub(/x(b+)/, '\\1')     # => "bbb-bbb"  # OK

# バックスラッシュを倍にするときによくある間違い
puts '\n'.gsub(/\\/, "\\\\")      # => \n   # NG
puts '\n'.gsub(/\\/, '\\\\')      # => \n   # NG
puts '\n'.gsub(/\\/, "\\\\\\\\")  # => \\n  # OK
puts '\n'.gsub(/\\/, '\\\\\\\\')  # => \\n  # OK

このような間違いを確実に防止し、コードの可読性を上げるには、 \& や \1 よりも下記のようにブロック付き形式の gsub を使うべきです。

p 'xbbb-xbbb'.gsub(/x(b+)/) { $1 }   # => "bbb-bbb"  # OK

puts '\n'.gsub(/\\/) { '\\\\' }      # => \\n        # OK

[SEE_ALSO] String#sub

gsub(pattern) {|matched| .... } -> String

gsub(pattern) -> Enumerator

文字列中で pattern にマッチした部分を順番にブロックに渡し、その実行結果で置き換えます。ブロックなしの場合と違い、ブロックの中からは組み込み変数 $1, $2, $3, ... を問題なく参照できます。

[PARAM] pattern:: 置き換える文字列のパターン
[RETURN]: 置換した場合は self、置換しなかった場合は nil

例:

p 'abcabc'.gsub(/[bc]/) {|s| s.upcase }  #=> "aBCaBC"
p 'abcabc'.gsub(/[bc]/) { $&.upcase }    #=> "aBCaBC"

[SEE_ALSO] String#sub

gsub(pattern, hash) -> String

文字列中の pattern にマッチした部分をキーにして hash を引いた値で置き換えます。

[PARAM] pattern:: 置き換える文字列のパターン
[PARAM] hash:: 置き換える文字列を与えるハッシュ

hash = {'b'=>'B', 'c'=>'C'}
p "abcabc".gsub(/[bc]/){hash[$&]} #=> "aBCaBC"
p "abcabc".gsub(/[bc]/, hash)     #=> "aBCaBC"

gsub!(pattern, replace) -> self | nil

文字列中で pattern にマッチする部分全てを文字列 replace に破壊的に置き換えます。

gsub! は通常 self を変更して返しますが、置換が起こらなかった場合は nil を返します。

[PARAM] pattern:: 置き換える文字列のパターン
[PARAM] replace:: pattern で指定した文字列と置き換える文字列
[RETURN]: 置換した場合は self、置換しなかった場合は nil

例:

buf = "String-String"
buf.gsub!(/in./, "!!")
p buf   # => "Str!!-Str!!"

buf = "String.String"
buf.gsub!(/in./, '<<\&>>')
p buf   # => "Str<<ing>>-Str<<ing>>"

注意:

引数 replace の中で $1 を使うことはできません。 replace は gsub メソッドの呼び出しより先に評価されるので、まだ gsub の正規表現マッチが行われておらず、 $1 がセットされていないからです。

例:

# ひとつめの括弧にマッチした部分に置き換えるときによくやる間違い
'abbbcd'.gsub!(/a(b+)/, "#{$1}")       # NG
'abbbcd'.gsub!(/a(b+)/, "\1")          # NG
'abbbcd'.gsub!(/a(b+)/, "\\1")         # OK
'abbbcd'.gsub!(/a(b+)/, '\\1')         # OK
'abbbcd'.gsub!(/a(b+)/, '\1')          # OK
'abbbcd'.gsub!(/a(b+)/) { $1 }         # OK   これがもっとも安全

[SEE_ALSO] String#sub

gsub!(pattern) {|matched| .... } -> self | nil

gsub!(pattern) -> Enumerator

文字列中で pattern にマッチする部分全てを順番にブロックに渡し、その評価結果に置き換えます。

また、ブロックなしの場合と違い、ブロックの中からは組み込み変数 $1, $2, $3, ... を問題なく参照できます。

[PARAM] pattern:: 置き換える文字列のパターン
[RETURN]: 置換した場合は self、置換しなかった場合は nil

例:

str = 'abcabc'
str.gsub!(/b/) {|s| s.upcase }
p str    #=> "aBcaBc"

str = 'abcabc'
str.gsub!(/b/) { $&.upcase }
p str    #=> "aBcaBc"

[SEE_ALSO] String#sub

gsub!(pattern, hash) -> self | nil

文字列中の pattern にマッチした部分をキーにして hash を引いた値で置き換えます。

[PARAM] pattern:: 置き換える文字列のパターン
[PARAM] hash:: 置き換える文字列を与えるハッシュ

hash = {'b'=>'B', 'c'=>'C'}
p "abcabc".gsub(/[bc]/){hash[$&]} #=> "aBCaBC"
p "abcabc".gsub(/[bc]/, hash)     #=> "aBCaBC"

hash -> Integer

self のハッシュ値を返します。 eql? で等しい文字列は、常にハッシュ値も等しくなります。

[SEE_ALSO] Hash

hex -> Integer

文字列に 16 進数で数値が表現されていると解釈して整数に変換します。接頭辞 "0x", "0X" とアンダースコアは無視されます。文字列が [_0-9a-fA-F] 以外の文字を含むときはその文字以降を無視します。

self が空文字列のときは 0 を返します。

例:

p "10".hex    # => 16
p "ff".hex    # => 255
p "0x10".hex  # => 16
p "-0x10".hex # => -16

p "xyz".hex   # => 0
p "10z".hex   # => 16
p "1_0".hex   # => 16

p "".hex      # => 0

[SEE_ALSO] String#oct, String#to_i, String#to_f, Kernel.#Integer, Kernel.#Float

このメソッドの逆に数値を文字列に変換するには Kernel.#sprintf, String#%, Integer#to_s などを使ってください。

include?(substr) -> bool

文字列中に部分文字列 substr が含まれていれば真を返します。

[PARAM] substr:: 検索する文字列

index(pattern, pos = 0) -> Integer

インデックス pos から右に向かって pattern を検索し、最初に見つかった部分文字列の左端のインデックスを返します。見つからなければ nil を返します。

引数 pattern は探索する部分文字列、正規表現、文字コードを示す 0 から 255 の整数のいずれかで指定します。

pos が負の場合、文字列の末尾から数えた位置から探索します。

[PARAM] pattern:: 探索する部分文字列、正規表現、文字コードを示す 0 から 255 の整数
[PARAM] pos:: 探索を開始するインデックス

例:

p "astrochemistry".index("str")         # => 1
p "regexpindex".index(/e.*x/, 2)        # => 3
p "character".index(?c)                 # => 0

p "foobarfoobar".index("bar", 6)        # => 9
p "foobarfoobar".index("bar", -6)       # => 9

[SEE_ALSO] String#rindex

insert(pos, other) -> ()

nth 番目の文字の直前に文字列 other を挿入します。 self[pos, 0] = other と同じ操作です。

[PARAM] pos:: 文字列を挿入するインデックス
[PARAM] other:: 挿入する文字列

例:

str = "foobaz"
str.insert(3, "bar")
p str   # => "foobarbaz"

inspect -> String

文字列オブジェクトの内容を、出力したときに人間が読みやすいような適当な形式に変換します。変換された文字列は印字可能な文字のみによって構成されます

現在の実装では、Ruby のリテラル形式を使って、文字列中の不可視文字をエスケープシーケンスに変換します。

$KCODE が設定されている場合は、そのエンコーディング内の適正なマルチバイト文字をそのまま出力します。それ以外の不可視文字はエスケープシーケンスを使って出力されます。

このメソッドは主にデバッグのために用意されています。永続化などの目的で文字列をダンプしたいときは、 String#dump を使うべきです。

例：

# p ではないことに注意
puts "string".inspect    # => "string"
puts "\t\r\n".inspect    # => "\t\r\n"

[SEE_ALSO] String#dump

intern -> Symbol

to_sym -> Symbol

文字列に対応するシンボル値 Symbol を返します。

なお、このメソッドの逆にシンボルに対応する文字列を得るには Symbol#to_s または Symbol#id2name を使います。

Ruby 1.9 以降では、シンボル文字列にナルキャラクタ("\0")、空の文字列が使用可能になりました。

例:

p "foo".intern                 # => :foo
p "foo".intern.to_s == "foo"   # => true

length -> Integer

size -> Integer

文字列の文字数を返します。バイト数を知りたいときは bytesize メソッドを使ってください。

[SEE_ALSO] String#bytesize

ljust(width, padding = ' ') -> String

長さ width の文字列に self を左詰めした文字列を返します。 self の長さが width より長い時には元の文字列の複製を返します。また、第 2 引数 padding を指定したときは空白文字の代わりに padding を詰めます。

[PARAM] width:: 返り値の文字列の最小の長さ
[PARAM] padding:: 長さが width になるまで self の右側に詰める文字

例:

p "foo".ljust(10)        # => "foo       "
p "foo".ljust(9)         # => "foo      "
p "foo".ljust(8)         # => "foo     "
p "foo".ljust(2)         # => "foo"
p "foo".ljust(1)         # => "foo"
p "foo".ljust(10, "*")   # => "foo*******"

[SEE_ALSO] String#center, String#rjust

lstrip -> String

文字列の先頭にある空白文字を全て取り除いた新しい文字列を返します。空白文字の定義は " \t\r\n\f\v" です。

例:

p "  abc\n".lstrip     #=> "abc\n"
p "\t abc\n".lstrip    #=> "abc\n"
p "abc\n".lstrip       #=> "abc\n"

[SEE_ALSO] String#strip, String#rstrip

lstrip! -> self | nil

文字列の先頭にある空白文字を全て破壊的に取り除きます。空白文字の定義は " \t\r\n\f\v" です。

lstrip! は self を変更して返します。ただし取り除く空白がなかったときは nil を返します。

例:

str = "  abc"
p str.lstrip!   # => "abc"
p str           # => "abc"

str = "abc"
p str.lstrip!   # => nil
p str           # => "abc"

match(regexp, pos = 0) -> MatchData

regexp.match(self, pos) と同じです。 regexp が文字列の場合は、正規表現にコンパイルします。詳しくは Regexp#match を参照してください。

succ -> String

next -> String

self の「次の」文字列を返します。

「次の」文字列は、対象の文字列の右端からアルファベットならアルファベット順(aの次はb, zの次はa, 大文字も同様)に、数字なら 10 進数(9 の次は 0)とみなして計算されます。

p "aa".succ        # => "ab"
p "88".succ.succ   # => "90"

"99" → "100", "AZZ" → "BAA" のような繰り上げも行われます。このとき負符号などは考慮されません。

p "99".succ   # => "100"
p "ZZ".succ   # => "AAA"
p "a9".succ   # => "b0"
p "-9".succ   # => "-10"

self にアルファベットや数字とそれ以外の文字が混在している場合、アルファベットと数字だけが「次の」文字になり、残りは保存されます。

p "1.9.9".succ # => # "2.0.0"

逆に self がアルファベットや数字をまったく含まない場合は、単純に文字コードを 1 増やします。

p ".".succ     # => "/"

さらに、self が空文字列の場合は "" を返します。このメソッドはマルチバイト文字を意識せず、単に文字列をバイト列として扱います。

なお、succ と逆の動作をするメソッドはありません。また、succ という名前の由来は successor です。

例:

p "aa".succ   # => "ab"

# 繰り上がり
p "99".succ   # => "100"
p "a9".succ   # => "b0"
p "Az".succ   # => "Ba"
p "zz".succ   # => "aaa"
p "-9".succ   # => "-10"
p "9".succ    # => "10"
p "09".succ   # => "10"

# アルファベット・数字とそれ以外の混在
p "1.9.9".succ # => # "2.0.0"

# アルファベット・数字以外のみ
p ".".succ     # => "/"
p "\0".succ    # => "\001"
p "\377".succ  # => "\001\000"

このメソッドは文字列の Range の内部で使用されます。

succ! -> String

next! -> String

self を「次の」文字列に置き換えます。「次の」文字列は、アルファベットなら 16 進数、数字なら 10 進数とみなして計算されます。「次の」文字列の計算では "99" → "100" のように繰り上げも行われます。このとき負符号などは考慮されません。

self にアルファベットや数字とそれ以外の文字が混在している場合、アルファベットと数字だけが「次の」文字になり、残りは保存されます。逆に self がアルファベットや数字をまったく含まない場合は、単純に文字コードを 1 増やします。

さらに、self が空文字列の場合は "" を返します。

このメソッドはマルチバイト文字を意識せず、単に文字列をバイト列として扱います。

なお、succ! と逆の動作をするメソッドはありません。

例:

p "aa".succ   # => "ab"

# 繰り上がり
p "99".succ   # => "100"
p "a9".succ   # => "b0"
p "Az".succ   # => "Ba"
p "zz".succ   # => "aaa"
p "-9".succ   # => "-10"
p "9".succ    # => "10"
p "09".succ   # => "10"

# アルファベット・数字とそれ以外の混在
p "1.9.9".succ # => # "2.0.0"

# アルファベット・数字以外のみ
p ".".succ     # => "/"
p "\0".succ    # => "\001"
p "\377".succ  # => "\001\000"

[SEE_ALSO] String#succ

oct -> Integer

文字列を 8 進文字列であると解釈して、整数に変換します。

例:

p "10".oct  # => 8
p "010".oct # => 8
p "8".oct   # => 0

oct は文字列の接頭辞 ("0", "0b", "0B", "0x", "0X") に応じて 8 進以外の変換も行います。

例:

p "0b10".oct  # => 2
p "10".oct    # => 8
p "010".oct   # => 8
p "0x10".oct  # => 16

整数とみなせない文字があればそこまでを変換対象とします。変換対象が空文字列であれば 0 を返します。

Ruby 1.6 では、8 進だけが符号を許す。 Ruby 1.8 以降はいずれも符号を許す

例:

p "-010".oct     # => -8
p "-0x10".oct    # => 0
p "-0b10".oct    # => 0

p "1_0_1x".oct   # => 65

[SEE_ALSO] String#hex, String#to_i, String#to_f, Kernel.#Integer, Kernel.#Float

逆に、数値を文字列に変換するにはKernel.#sprintf, String#%, Integer#to_s を使用します。

ord -> Integer

文字列の最初の文字の文字コードを整数で返します。

self が空文字列のときは例外 TypeError を発生します。

[RETURN]: 文字コードを表す整数
[EXCEPTION] TypeError:: self の長さが 0 のとき発生

例:

p "a".ord   # => 97

[SEE_ALSO] Integer#chr, String#chr

partition(sep) -> [String, String, String]

セパレータ sep が最初に登場する部分で self を 2 つに分割し、 [セパレータを含まない先頭部分, セパレータ, それ以降の部分] の 3 要素の配列を返します。

self がセパレータを含まないときは、返り値の第 2 要素と第 3 要素が空文字列になります。

[PARAM] sep:: セパレータを表す文字列か正規表現

例：

p "axaxa".partition("x")   # => ["a", "x", "axa"]
p "aaaaa".partition("x")   # => ["aaaaa", "", ""]

[SEE_ALSO] String#rpartition, String#split

replace(other) -> String

self の内容を other の内容で置き換えます。

例:

str = "foo"
str.replace "bar"
p str   # => "bar"

reverse -> String

文字列をバイト単位で左右逆転した文字列を返します。

例:

p "foobar".reverse   # => "raboof"
p "".reverse         # => ""

reverse! -> ()

文字列をバイト単位で左右逆転します。

例:

str = "foobar"
str.reverse!
p str   # => "raboof"

rindex(pattern, pos = self.size) -> Integer | nil

文字列のインデックス pos から左に向かって pattern を探索します。見つかった部分文字列の左端のインデックスを返します。見つからなければ nil を返します。

pos が負の場合は、文字列の末尾から数えた位置から探索します。

rindex と String#index とでは、探索方向だけが逆になります。完全に左右が反転した動作をするわけではありません。探索はその開始位置を右から左にずらしながら行いますが、部分文字列の照合はどちらのメソッドも左から右に向かって行います。以下の例を参照してください。

# String#index の場合
p "stringstring".index("ing", 1)    # => 3
  # ing            # ここから探索を始める
  #  ing
  #   ing          # 右にずらしていってここで見つかる

# String#rindex の場合
p "stringstring".rindex("ing", -1)  # => 9
  #           ing    # インデックス -1 のバイトから探索を始める
  #          ing
  #         ing      # 左にずらしていってここで見つかる

[PARAM] pattern:: 探索する部分文字列。文字列、正規表現、文字コードを示す 0 から 255 の整数のいずれか
[PARAM] pos:: 探索を始めるインデックス

例:

p "astrochemistry".rindex("str")        # => 10
p "character".rindex(?c)                # => 5
p "regexprindex".rindex(/e.*x/, 2)      # => 1

p "foobarfoobar".rindex("bar", 6)       # => 3
p "foobarfoobar".rindex("bar", -6)      # => 3

[SEE_ALSO] String#index

rjust(width, padding = ' ') -> String

長さ width の文字列に self を右詰めした文字列を返します。 self の長さが width より長い時には元の文字列の複製を返します。また、第 2 引数 padding を指定したときは空白文字の代わりに padding を詰めます。

[PARAM] width:: 返り値の文字列の最小の長さ
[PARAM] padding:: 長さが width になるまで self の右側に詰める文字

例:

p "foo".rjust(10)        # => "       foo"
p "foo".rjust(9)         # => "      foo"
p "foo".rjust(8)         # => "     foo"
p "foo".rjust(2)         # => "foo"
p "foo".rjust(1)         # => "foo"
p "foo".rjust(10, "*")   # => "*******foo"

[SEE_ALSO] String#center, String#ljust

rpartition(sep) -> [String, String, String]

セパレータ sep が最後に登場する部分で self を 2 つに分割し、 [最後のセパレータより前の部分, セパレータ, それ以降の部分] の 3 要素の配列を返します。

self がセパレータを含まないときは、返り値の第 2 要素と第 3 要素が空文字列になります。

[PARAM] sep:: セパレータを表す文字列か正規表現

例：

p "axaxa".partition("x")   # => ["axa", "x", "a"]
p "aaaaa".partition("x")   # => ["", "", "aaaaa"]

[SEE_ALSO] String#partition, String#split

rstrip -> String

文字列の末尾にある空白文字を全て取り除いた新しい文字列を返します。空白文字の定義は " \t\r\n\f\v\0" です。

例:

p "  abc\n".rstrip          #=> "  abc"
p "  abc \t\r\n\0".rstrip   #=> "  abc"
p "  abc".rstrip            #=> "  abc"

str = "abc\n"
p str.rstrip    #=> "abc"
p str           #=> "abc\n"  (元の文字列は変化しない)

[SEE_ALSO] String#lstrip, String#strip

rstrip! -> self | nil

文字列の末尾にある空白文字を全て破壊的に取り除きます。空白文字の定義は " \t\r\n\f\v\0" です。

例:

str = "  abc\n"
p str.rstrip!   # => "  abc"
p str           # => "  abc"

str = "  abc \r\n\t\v\0"
p str.rstrip!   # => "  abc"
p str           # => "  abc"

[SEE_ALSO] String#rstrip, String#lstrip

scan(re) -> [String] | [[String]]

self に対して正規表現 re を繰り返しマッチし、マッチした部分文字列の配列を返します。

正規表現が括弧を含む場合は、括弧で括られたパターンにマッチした部分文字列の配列の配列を返します。

例:

p "foobar".scan(/../)               # => ["fo", "ob", "ar"]
p "foobarbazfoobarbaz".scan(/ba./)  # => ["bar", "baz", "bar", "baz"]

p "foobar".scan(/(.)/)
    # => [["f"], ["o"], ["o"], ["b"], ["a"], ["r"]]

p "foobarbazfoobarbaz".scan(/(ba)(.)/)
    # => [["ba", "r"], ["ba", "z"], ["ba", "r"], ["ba", "z"]]

scan(re) {|s| ... } -> ()

正規表現 re がマッチした部分文字列をブロックに渡して実行します。正規表現 re が括弧を含む場合は、括弧で括られたパターンにマッチした文字列の配列を渡します。

Ruby 1.6 以前は re が文字列の場合、その文字列を正規表現にコンパイルしていました。 Ruby 1.8 以降は、その文字列そのものがパターンになります。

[PARAM] re:: パターン

例:

"foobarbazfoobarbaz".scan(/ba./) {|s| p s }
    # => "bar"
    #    "baz"
    #    "baz"
    #    "baz"

"foobarbazfoobarbaz".scan(/(ba)(.)/) {|s| p s }
    # => ["ba", "r"]
    #    ["ba", "z"]
    #    ["ba", "r"]
    #    ["ba", "z"]

slice!(nth) -> Integer

slice!(pos, len) -> String

slice!(substr) -> String

slice!(regexp, nth = 0) -> String

slice!(first..last) -> String

slice!(first...last) -> String

slice!(regexp, nth = 0) -> String

指定した範囲 (String#[] 参照) を文字列から取り除いたうえで取り除いた部分文字列を返します。

引数が範囲外を指す場合は nil を返します。

split(sep = $/, limit = 0) -> [String] | [[String]]

第 1 引数 sep で指定されたセパレータによって文字列を limit 個まで分割し、結果を文字列の配列で返します。

第 1 引数 sep は以下のいずれかです。

正規表現: 正規表現にマッチする部分で分割する。特に、括弧によるグルーピングがあればそのグループにマッチした文字列も結果の配列に含まれる (後述)。
文字列: その文字列自体にマッチする部分で分割する。
1 バイトの空白文字 ' ' か nil: 先頭と末尾の空白を除いたうえで、空白文字列で分割する。
空文字列 '' あるいは空文字列にマッチする正規表現: 文字列を 1 文字ずつに分割する。マルチバイト文字を認識する。

sep が正規表現で、かつその正規表現に括弧が含まれている場合には、各括弧のパターンにマッチした文字列も配列に含まれます。括弧が複数ある場合は、マッチしたものだけが配列に含まれます。

第 2 引数 limit は以下のいずれかです。

limit > 0: 最大 limit 個の文字列に分割する
limit == 0: 分割個数制限はなしで、配列末尾の空文字列を取り除く
limit < 0: 分割個数の制限はなし

[PARAM] sep:: 文字列を分割するときのセパレータのパターン
[PARAM] limit:: 分割する最大個数

例:

p "   a \t  b \n  c".split(/\s+/) # => ["", "a", "b", "c"]

p "   a \t  b \n  c".split(nil)   # => ["a", "b", "c"]
p "   a \t  b \n  c".split(' ')   # => ["a", "b", "c"]   # split(nil) と同じ
p "   a \t  b \n  c".split        # => ["a", "b", "c"]   # split(nil) と同じ

# 括弧を含む正規表現
p '1-10,20'.split(/([-,])/)   # => ["1", "-", "10", ",", "20"]

# 正規表現が空文字列にマッチする場合は 1 文字に分割
p 'hi there'.split(/\s*/).join(':')  # => "h:i:t:h:e:r:e"

# 文字列全体を 1 文字ずつに分割する例
p 'hi there'.split(//).join(':')     # => "h:i: :t:h:e:r:e"

# $KCODE を設定すればマルチバイト文字列を認識
$KCODE = "EUC"
p '文字列'.split(//).join(':')       # => "文:字:列"

# limit == 0 だと制限なく分割、配列末尾の空文字列は取り除かれる
p "a,b,c,,,".split(/,/, 0)   # => ["a", "b", "c"]

# limit 省略時は 0 と同じ (最もよく使われるパターン)
p "a,b,c,,,".split(/,/)      # => ["a", "b", "c"]

# 正の limit 使用例
p "a,b,c,d,e".split(/,/, 1)  # => ["a,b,c,d,e"]
p "a,b,c,d,e".split(/,/, 2)  # => ["a", "b,c,d,e"]
p "a,b,c,d,e".split(/,/, 3)  # => ["a", "b", "c,d,e"]
p "a,b,c,d,e".split(/,/, 4)  # => ["a", "b", "c", "d,e"]
p "a,b,c,d,e".split(/,/, 5)  # => ["a", "b", "c", "d", "e"]
p "a,b,c,d,e".split(/,/, 6)  # => ["a", "b", "c", "d", "e"]
p "a,b,c,d,e".split(/,/, 7)  # => ["a", "b", "c", "d", "e"]

# limit が負の数の場合は制限なく分割
p "a,b,c,,,".split(/,/, -1)    # => ["a", "b", "c", "", "", ""]

squeeze(*chars) -> String

chars に含まれる文字が複数並んでいたら 1 文字にまとめます。

chars の形式は tr(1) と同じです。つまり、 `a-c' は a から c を意味し、"^0-9" のように文字列の先頭が `^' の場合は指定文字以外を意味します。

`-' は文字列の両端にない場合にだけ範囲指定の意味になります。同様に、`^' もその効果は文字列の先頭にあるときだけです。また、 `-', `^', `\' はバックスラッシュ(`\')によりエスケープすることができます。

引数を 1 つも指定しない場合は、すべての連続した文字を 1 文字にまとめます。

引数を複数指定した場合は、すべての引数にマッチする文字を 1 文字にまとめます。

[PARAM] chars:: １文字にまとめる文字。

例:

p "112233445566778899".squeeze          # =>"123456789"
p "112233445566778899".squeeze("2-8")   # =>"11234567899"

# 以下の 2 つは同じ意味
p "112233445566778899".squeeze("2378")          # =>"11234455667899"
p "112233445566778899".squeeze("2-8", "^4-6")   # =>"11234455667899"

squeeze!(*chars) -> ()

chars に含まれる文字が複数並んでいたら 1 文字にまとめます。

chars の形式は tr(1) と同じです。つまり、 `a-c' は a から c を意味し、"^0-9" のように文字列の先頭が `^' の場合は指定文字以外を意味します。

引数を 1 つも指定しない場合は、すべての連続した文字を 1 文字にまとめます。

引数を複数指定した場合は、すべての引数にマッチする文字を 1 文字にまとめます。

[PARAM] chars:: １文字にまとめる文字。

例:

str = "112233445566778899"
str.squeeze!
p str    # =>"123456789"

str = "112233445566778899"
str.squeeze!("2-8")
p str    # =>"11234567899"

start_with?(str) -> bool

self の先頭が str であるとき true を返します。

[PARAM] str:: パターンを表す文字列

例:

"string".end_with?("str")   # => true
"string".end_with?("ing")   # => false

[SEE_ALSO] String#end_with?

strip -> String

文字列先頭と末尾の空白文字を全て取り除いた文字列を生成して返します。空白文字の定義は " \t\r\n\f\v" です。また、文字列右側からは "\0" も取り除きますが、左側の "\0" は取り除きません。

例:

p "  abc  \r\n".strip    #=> "abc"
p "abc\n".strip          #=> "abc"
p "  abc".strip          #=> "abc"
p "abc".strip            #=> "abc"
p "  \0  abc  \0".strip  # => "\000  abc"   # 右側のみ "\0" も取り除く

str = "\tabc\n"
p str.strip              #=> "abc"
p str                    #=> "\tabc\n" (元の文字列は変化しない)

[SEE_ALSO] String#lstrip, String#rstrip

strip! -> self | nil

先頭と末尾の空白文字を全て破壊的に取り除きます。空白文字の定義は " \t\r\n\f\v" です。また、文字列右側からは "\0" も取り除きますが、左側の "\0" は取り除きません。

strip! は、内容を変更した self を返します。ただし取り除く空白がなかったときは nil を返します。

例:

str = "  abc\r\n"
p str.strip!     #=> "abc"
p str            #=> "abc"

str = "abc"
p str.strip!     #=> nil
p str            #=> "abc"

str = "  \0  abc  \0"
str.strip!
p str            # => "\000  abc"   # 右側の "\0" のみ取り除かれる

[SEE_ALSO] String#strip, String#lstrip

sub(pattern, replace) -> String

文字列中で pattern にマッチした最初の部分を文字列 replace で置き換えた文字列を生成し返します。

[PARAM] pattern:: 置き換える文字列のパターン
[PARAM] replace:: pattern で指定した文字列と置き換える文字列

例:

p 'abcdefg'.sub(/def/, '!!')          # => "abc!!g"
p 'abcabc'.sub(/b/, '<<\&>>')         # => "a<<b>>cabc"
p 'xxbbxbb'.sub(/x+(b+)/, 'X<<\1>>')  # => "X<<bb>>xbb"

注意:

また、sub では「\」が部分文字列との置き換えという特別な意味を持つため、 replace に「\」自身を入れたいときは「\」を二重にエスケープしなければなりません。

# ひとつめの括弧の内容に置き換えるときによくある間違い
p 'xbbb-xbbb'.sub(/x(b+)/, "#{$1}")   # => "-xbbb"     # NG
p 'xbbb-xbbb'.sub(/x(b+)/, "\1")      # => "1-xbbb"    # NG
p 'xbbb-xbbb'.sub(/x(b+)/, "\\1")     # => "bbb-xbbb"  # OK
p 'xbbb-xbbb'.sub(/x(b+)/, '\1')      # => "bbb-xbbb"  # OK
p 'xbbb-xbbb'.sub(/x(b+)/, '\\1')     # => "bbb-xbbb"  # OK

# バックスラッシュを倍にするときによくある間違い
puts '\n'.sub(/\\/, "\\\\")      # => \n   # NG
puts '\n'.sub(/\\/, '\\\\')      # => \n   # NG
puts '\n'.sub(/\\/, "\\\\\\\\")  # => \\n  # OK
puts '\n'.sub(/\\/, '\\\\\\\\')  # => \\n  # OK

このような間違いを確実に防止し、コードの可読性を上げるには、 \& や \1 よりも下記のようにブロック付き形式の sub を使うべきです。

p 'xbbb-xbbb'.sub(/x(b+)/) { $1 }   # => "bbb-xbbb"  # OK

puts '\n'.sub(/\\/) { '\\\\' }      # => \\n        # OK

[SEE_ALSO] String#gsub

sub(pattern) {|matched| .... } -> String

文字列中で pattern にマッチした最初の部分をブロックに渡し、その評価結果で置き換えた新しい文字列を返します。ブロックなしの sub と違い、ブロックの中からは組み込み変数 $1, $2, $3, ... を問題なく参照できます。

[PARAM] pattern:: 置き換える文字列のパターン

例:

p 'abcabc'.sub(/b/) {|s| s.upcase }  #=> "aBcabc"
p 'abcabc'.sub(/b/) { $&.upcase }    #=> "aBcabc"

[SEE_ALSO] String#gsub

sub(pattern, hash) -> String

文字列中の pattern にマッチした部分をキーにして hash を引いた値で置き換えます。

[PARAM] pattern:: 置き換える文字列のパターン
[PARAM] hash:: 置き換える文字列を与えるハッシュ

hash = {'b'=>'B', 'c'=>'C'}
p "abcabc".sub(/[bc]/){hash[$&]} #=> "aBCabc"
p "abcabc".sub(/[bc]/, hash)     #=> "aBCabc"

sub!(pattern, replace) -> self | nil

文字列中で pattern にマッチした最初の部分を文字列 replace へ破壊的に置き換えます。

sub! は通常 self を変更して返しますが、置換が起こらなかった場合は nil を返します。

[PARAM] pattern:: 置き換える文字列のパターン
[PARAM] replace:: pattern で指定した文字列と置き換える文字列
[RETURN]: 置換した場合は self、置換しなかった場合は nil

例:

buf = "String-String"
buf.sub!(/in./, "!!")
p buf   # => "Str!!-String"

buf = "String.String"
buf.sub!(/in./, '<<\&>>')
p buf   # => "Str<<ing>>-String"

注意:

引数 replace の中で $1 を使うことはできません。 replace は sub メソッドの呼び出しより先に評価されるので、まだ sub の正規表現マッチが行われておらず、 $1 がセットされていないからです。

例:

# ひとつめの括弧にマッチした部分に置き換えるときによくやる間違い
'abbbcd'.sub!(/a(b+)/, "#{$1}")       # NG
'abbbcd'.sub!(/a(b+)/, "\1")          # NG
'abbbcd'.sub!(/a(b+)/, "\\1")         # OK
'abbbcd'.sub!(/a(b+)/, '\\1')         # OK
'abbbcd'.sub!(/a(b+)/, '\1')          # OK
'abbbcd'.sub!(/a(b+)/) { $1 }         # OK   これがもっとも安全

[SEE_ALSO] String#gsub

sub!(pattern) {|matched| .... } -> self | nil

文字列中で pattern にマッチした最初の部分をブロックに渡し、その評価結果へ破壊的に置き換えます。

また、ブロックなしの sub と違い、ブロックの中からは組み込み変数 $1, $2, $3, ... を問題なく参照できます。

[PARAM] pattern:: 置き換える文字列のパターン
[RETURN]: 置換した場合は self、置換しなかった場合は nil

例:

str = 'abcabc'
str.sub!(/b/) {|s| s.upcase }
p str    #=> "aBcabc"

str = 'abcabc'
str.sub!(/b/) { $&.upcase }
p str    #=> "aBcabc"

[SEE_ALSO] String#gsub

sub!(pattern, hash) -> String

文字列中の pattern にマッチした部分をキーにして hash を引いた値で破壊的に置き換えます。

[PARAM] pattern:: 置き換える文字列のパターン
[PARAM] hash:: 置き換える文字列を与えるハッシュ
[RETURN]: 置換した場合は self、置換しなかった場合は nil

sum(bits = 16) -> Integer

文字列の bits ビットのチェックサムを計算します。以下と同じです。

def sum(bits)
  sum = 0
  each_byte {|c| sum += c }
  return 0 if sum == 0
  sum & ((1 << bits) - 1)
end

例えば以下のコードで UNIX System V の sum(1) コマンドと同じ値が得られます。

例:

sum = 0
ARGF.each_line do |line|
  sum += line.sum
end
sum %= 65536

[PARAM] bits:: チェックサムのビット数

swapcase -> String

'A' から 'Z' までのアルファベット大文字を小文字に、 'a' から 'z' までのアルファベット小文字を大文字に変更した文字列を返します。

このメソッドはマルチバイト文字を認識しません。そのため、文字列が Shift JIS エンコーディングで、かつ $KCODE が適切に設定されていない場合、マルチバイト文字の一部も変換してしまう場合があります。逆に、$KCODE を設定してもマルチバイト文字のアルファベットは処理しません。

例:

p "ABCxyz".swapcase   # => "abcXYZ"
p "Access".swapcase   # => "aCCESS"

# -*- Coding: shift_jis -*-
$KCODE = 'n'
puts "蟻".swapcase   # => 帰

[SEE_ALSO] String#upcase, String#downcase, String#capitalize

swapcase! -> self | nil

'A' から 'Z' までのアルファベット大文字を小文字に、 'a' から 'z' までのアルファベット小文字を大文字に、破壊的に変更します。

swapcase! は self を変更して返しますが、置換が起こらなかった場合は nil を返します。

例:

str = "ABCxyz"
str.swapcase!
p str   # => "abcXYZ"

# -*- Coding: shift_jis -*-
$KCODE ='n'
puts "蟻".swapcase   # => 帰

[SEE_ALSO] String#upcase, String#downcase, String#capitalize

to_f -> Float

文字列を 10 進数表現と解釈して、浮動小数点数 Float に変換します。

浮動小数点数とみなせなくなるところまでを変換対象とします。変換対象が空文字列であれば 0.0 を返します。

例:

p "10".to_f    # => 10.0
p "10e2".to_f  # => 1000.0
p "1e-2".to_f  # => 0.01
p ".1".to_f    # => 0.1

p "nan".to_f   # => 0.0
p "INF".to_f   # => 0.0
p "-Inf".to_f  # => -0.0
p(("10" * 1000).to_f)   # => Infinity (with warning)

p "".to_f      # => 0.0
p "1_0_0".to_f # => 100.0
p " \n10".to_f # => 10.0       # 先頭の空白は無視される
p "0xa.a".to_f # => 0.0

なお、このメソッドの逆に、数値を文字列に変換するには Kernel.#sprintf,String#%,Integer#to_s を使用します。

[SEE_ALSO] String#hex, String#oct, String#to_i, Kernel.#Integer, Kernel.#Float

to_i(base = 10) -> Integer

文字列を 10 進数表現された整数であると解釈して、整数に変換します。

p " 10".to_i    # => 10
p "+10".to_i    # => 10
p "-10".to_i    # => -10

p "010".to_i    # => 10
p "-010".to_i   # => -10

整数とみなせない文字があればそこまでを変換対象とします。変換対象が空文字列であれば 0 を返します。

p "0x11".to_i   # => 0
p "".to_i       # => 0

基数を指定することでデフォルトの 10 進以外に 2 ～ 36 進数表現へ変換できます。それぞれ Ruby の整数リテラルで使用可能なプリフィクスは無視されます。また、base に 0 を指定するとプリフィクスから基数を判断します。認識できるプリフィクスは、 0b (2 進数)、0 (8 進数)、0o (8 進数)、0d (10 進数)、0x (16 進数) です。

0, 2 ～ 36 以外の引数を指定した場合は例外 ArgumentError が発生します。

p "01".to_i(2)    # => 1
p "0b1".to_i(2)   # => 1

p "07".to_i(8)    # => 7
p "0o7".to_i(8)   # => 7

p "1f".to_i(16)   # => 31
p "0x1f".to_i(16) # => 31

p "0b10".to_i(0)  # => 2
p "0o10".to_i(0)  # => 8
p "010".to_i(0)   # => 8
p "0d10".to_i(0)  # => 10
p "0x10".to_i(0)  # => 16

[PARAM] base:: 進数を指定する整数。0 か、2～36 の整数。
[RETURN]: 整数

このメソッドの逆に数値を文字列に変換するには、 Kernel.#sprintf, String#%, Integer#to_s を使用します。

String#hex, String#oct, String#to_f, Kernel.#Integer, Kernel.#Float も参照してください。

to_s -> String

to_str -> String

self を返します。

例:

p "str".to_s     # => "str"
p "str".to_str   # => "str"

このメソッドは、文字列を他のクラスのインスタンスと混ぜて処理したいときに有効です。例えば返り値が文字列か nil であるメソッド some_method があるとき、 to_s メソッドを使うと以下のように統一的に処理できます。

# some_method(5).downcase だと返り値が nil のときに
# エラーになるので to_s をはさむ
p some_method(5).to_s.downcase

tr(pattern, replace) -> String

pattern 文字列に含まれる文字を検索し、それを replace 文字列の対応する文字に置き換えます。

search の形式は tr(1) と同じです。つまり、 `a-c' は a から c を意味し、"^0-9" のように文字列の先頭が `^' の場合は指定文字以外が置換の対象になります。

replace に対しても `-' による範囲指定が可能です。例えば String#upcase は tr を使って "foo".tr('a-z', 'A-Z') と書けます。

`-' は文字列の両端にない場合にだけ範囲指定の意味になります。 `^' も文字列の先頭にあるときにだけ否定の効果を発揮します。また、`-', `^', `\' はバックスラッシュ (`\') によりエスケープできます。

replace の範囲が pattern の範囲よりも小さい場合は、 replace の最後の文字が無限に続くものとして扱われます。

[PARAM] pattern:: 置き換える文字のパターン
[PARAM] replace:: pattern で指定した文字を置き換える文字

例:

p "foo".tr("f", "X")      # => "Xoo"
p "foo".tr('a-z', 'A-Z')  # => "FOO"
p "FOO".tr('A-Z', 'a-z')  # => "foo"

[SEE_ALSO] String#tr_s

tr!(pattern, replace) -> self | nil

pattern 文字列に含まれる文字を検索し、それを replace 文字列の対応する文字に破壊的に置き換えます。

pattern の形式は tr(1) と同じです。つまり、`a-c' は a から c を意味し、 "^0-9" のように文字列の先頭が `^' の場合は指定文字以外が置換の対象になります。

replace に対しても `-' による範囲指定が可能です。例えば、String#upcase を tr で書くと、

p "foo".tr('a-z', 'A-Z')
=> "FOO"

となります。

replace の範囲が pattern の範囲よりも小さい場合は、 replace の最後の文字が無限に続くものと扱われます。

tr! は self を変更して返しますが、置換が起こらなかった場合は nil を返します。

[PARAM] pattern:: 置き換える文字のパターン
[PARAM] replace:: pattern で指定した文字を置き換える文字

[SEE_ALSO] String#tr, String#tr_s

tr_s(pattern, replace) -> String

文字列の中に pattern 文字列に含まれる文字が存在したら、 replace 文字列の対応する文字に置き換えます。さらに、置換した部分内に同一の文字の並びがあったらそれを 1 文字に圧縮します。

pattern の形式は tr(1) と同じです。つまり「a-c」は a から c を意味し、 "^0-9" のように文字列の先頭が「^」の場合は指定した文字以外が置換の対象になります。

replace でも「-」を使って範囲を指定できます。

「-」は文字列の両端にない場合にだけ範囲指定の意味になります。同様に、「^」もその効果は文字列の先頭にあるときだけです。また、「-」、「^」、「\」はバックスラッシュ (「\」) でエスケープできます。

replace の範囲が pattern の範囲よりも小さい場合、 replace の最後の文字が無限に続くものとして扱われます。

[PARAM] pattern:: 置き換える文字のパターン
[PARAM] replace:: pattern で指定した文字を置き換える文字

例:

p "gooooogle".tr_s("o", "X")       # => "gXgle"
p "gooooogle".tr_s("a-z", "A-Z")   # => "GOGLE"

注意: 一般に、tr_s を tr と squeeze で置き換えることはできません。 tr と squeeze の組みあわせでは tr の置換後の文字列全体を squeeze しますが、 tr_s は置換された部分だけを squeeze します。以下のコードを参照してください。

p "foo".tr_s("o", "f")              # => "ff"
p "foo".tr("o", "f").squeeze("f")   # => "f"

[SEE_ALSO] String#tr

tr_s!(pattern, replace) -> self | nil

replace でも「-」を使って範囲を指定できます。

p "gooooogle".tr_s("a-z", "A-Z")   # => "GOGLE"

replace の範囲が search の範囲よりも小さい場合、 replace の最後の文字が無限に続くものとして扱われます。

tr_s は置換後の文字列を生成して返します。 tr_s! は self を変更して返しますが、置換が起こらなかった場合は nil を返します。

注意: 一般に、tr_s! を tr! と squeeze! で置き換えることはできません。 tr! と squeeze! の組みあわせでは tr! の置換後の文字列全体を squeeze! しますが、 tr_s! は置換された部分だけを squeeze! します。以下のコードを参照してください。

str = "foo"
str.tr_s!("o", "f")
p str   # => "ff"

str = "foo"
str.tr!("o", "f")
str.squeeze!("f")
p str   # => "f"

[PARAM] pattern:: 置き換える文字のパターン
[PARAM] replace:: pattern で指定した文字を置き換える文字

[SEE_ALSO] String#tr, String#tr_s

unpack(template) -> Array

Array#pack で生成された文字列をテンプレート文字列 template にしたがってアンパックし、それらの要素を含む配列を返します。

[PARAM] template:: pack テンプレート文字列
[RETURN]: オブジェクトの配列

以下にあげるものは、Array#pack、String#unpack のテンプレート文字の一覧です。テンプレート文字は後に「長さ」を表す数字を続けることができます。「長さ」の代わりに`*'とすることで「残り全て」を表すこともできます。

長さの意味はテンプレート文字により異なりますが大抵、

"iiii"

のように連続するテンプレート文字は

"i4"

と書き換えることができます。

テンプレート文字列中の空白類は無視されます。また、`#' から改行あるいはテンプレート文字列の最後まではコメントとみなされ無視されます。

整数のテンプレート文字のシステム依存性

各テンプレート文字の説明の中で、 short や long はシステムによらずそれぞれ 2, 4バイトサイズの数値(32ビットマシンで一般的なshort, longのサイズ)を意味しています。s, S, l, L に対しては直後に _ または ! を "s_" あるいは "s!" のように続けることでシステム依存の short, long のサイズにすることもできます。

i, I (int)のサイズは常にシステム依存であり、n, N, v, V のサイズは常にシステム依存ではない(!をつけられない)ことに注意してください。

つまり、IO#ioctl などで C の構造体を渡すときのように、システム依存のサイズとエンディアンに合わせる必要があるときには s!, S!, i!, I!, l!, L!, q!, Q! を用います。また、ネットワークプロトコルやファイルフォーマットのように、システムに依存しないデータを扱うときには n, N, v, V を用います。

まとめると以下のようになります。

エンディアン非依存、整数サイズ非依存 (ネットワークプロトコルなどに適切)

  n: big endian unsigned 16bit
  N: big endian unsigned 32bit
  v: little endian unsigned 16bit
  V: little endian unsigned 32bit

エンディアン依存、整数サイズ依存 (C の構造体などに適切)

  s!: signed short
  S!: unsigned short
  i!: signed int
  I!: unsigned int
  l!: signed long
  L!: unsigned long
  q!: signed long long
  Q!: unsigned long long

エンディアン依存、整数サイズ非依存 (C99 の stdint.h にある厳密な幅を持つ整数型に適切)

  s: int16_t
  S: uint16_t
  l: int32_t
  L: uint32_t

各テンプレート文字の説明

説明中、Array#pack と String#unpack で違いのあるものは `/' で区切って「Array#pack の説明 / String#unpack の説明」としています。

a

ASCII文字列(null文字を詰める/後続するnull文字やスペースを残す)

    ["abc"].pack("a") => "a"
    ["abc"].pack("a*") => "abc"
    ["abc"].pack("a4") => "abc\0"

    "abc\0".unpack("a4") => ["abc\0"]
    "abc ".unpack("a4") => ["abc "]

A

ASCII文字列(スペースを詰める/後続するnull文字やスペースを削除)

    ["abc"].pack("A") => "a"
    ["abc"].pack("A*") => "abc"
    ["abc"].pack("A4") => "abc "

    "abc ".unpack("A4") => ["abc"]
    "abc\0".unpack("A4") => ["abc"]

Z

null終端文字列(aと同じ / 後続するnull文字を削除)

    ["abc"].pack("Z") => "a"
    ["abc"].pack("Z*") => "abc"
    ["abc"].pack("Z4") => "abc\0"

    "abc\0".unpack("Z4") => ["abc"]
    "abc ".unpack("Z4") => ["abc "]

b

ビットストリング(各バイトごとに下位ビットから上位ビット)

    "\377\000".unpack("b*") => ["1111111100000000"]
    "\001\002".unpack("b*") => ["1000000001000000"]
    "\001\002".unpack("b3") => ["100"]


    ["1000000001000000"].pack("b*") => "\001\002"

B

ビットストリング(各バイトごとに上位ビットから下位ビット)

    "\377\000".unpack("B*")  => ["1111111100000000"]
    "\001\002".unpack("B*")  => ["0000000100000010"]
    "\001\002".unpack("B9")  => ["000000010"]
    "\001\002".unpack("B15") => ["000000010000001"]

    ["0000000100000010"].pack("B*") => "\001\002"
    ["0000000100000010"].pack("B0") => ""
    ["0000000100000010"].pack("B1") => "\000"
    ["0000000100000010"].pack("B7") => "\000"
    ["0000000100000010"].pack("B8") => "\001"
    ["0000000100000010"].pack("B9") => "\001\000"
    ["0000000100000010"].pack("B14") => "\001\000"
    ["0000000100000010"].pack("B15") => "\001\002"
    ["0000000100000010"].pack("B16") => "\001\002"

h

16進文字列(下位ニブルが先)

    "\x01\xfe".unpack("h*") => ["10ef"]
    "\x01\xfe".unpack("h3") => ["10e"]

    ["10ef"].pack("h*") => "\001\376"

H

16進文字列(上位ニブルが先)

    "\x01\xfe".unpack("H*") => ["01fe"]
    "\x01\xfe".unpack("H3") => ["01f"]
    "~".unpack("H2") => ["7e"]

    ["01fe"].pack("H*") => "\001\376"
    ["7e"].pack("H2") => "~"

c

char (8bit 符号つき整数)

    "\001\376".unpack("c*") => [1, -2]

    [1, -2].pack("c*") => "\001\376"
    [1, 254].pack("c*") => "\001\376"

C

unsigned char (8bit 符号なし整数)

    "\001\376".unpack("C*") => [1, 254]

    [1, -2].pack("C*") => "\001\376"
    [1, 254].pack("C*") => "\001\376"

s

short (16bit 符号つき整数, エンディアンに依存) (s! は 16bit でなく、short のサイズに依存)

リトルエンディアン:

    "\001\002\376\375".unpack("s*") => [513, -514]

    [513, 65022].pack("s*") => "\001\002\376\375"
    [513, -514].pack("s*") => "\001\002\376\375"

ビッグエンディアン:

    "\001\002\376\375".unpack("s*") => [258, -259]

    [258, 65277].pack("s*") => "\001\002\376\375"
    [258, -259].pack("s*") => "\001\002\376\375"

S

unsigned short (16bit 符号なし整数, エンディアンに依存) (S! は 16bit でなく、short のサイズに依存)

リトルエンディアン:

    "\001\002\376\375".unpack("S*") => [513, 65022]

    [513, 65022].pack("s*") => "\001\002\376\375"
    [513, -514].pack("s*") => "\001\002\376\375"

ビッグエンディアン:

    "\001\002\376\375".unpack("S*") => [258, 65277]

    [258, 65277].pack("S*") => "\001\002\376\375"
    [258, -259].pack("S*") => "\001\002\376\375"

i

int (符号つき整数, エンディアンと int のサイズに依存)

リトルエンディアン, 32bit int:

    "\001\002\003\004\377\376\375\374".unpack("i*") => [67305985, -50462977]

    [67305985, 4244504319].pack("i*") => RangeError
    [67305985, -50462977].pack("i*") => "\001\002\003\004\377\376\375\374"

ビッグエンディアン, 32bit int:

    "\001\002\003\004\377\376\375\374".unpack("i*") => [16909060, -66052]

    [16909060, 4294901244].pack("i*") => RangeError
    [16909060, -66052].pack("i*") => "\001\002\003\004\377\376\375\374"

I

unsigned int (符号なし整数, エンディアンと int のサイズに依存)

リトルエンディアン, 32bit int:

    "\001\002\003\004\377\376\375\374".unpack("I*") => [67305985, 4244504319]

    [67305985, 4244504319].pack("I*") => "\001\002\003\004\377\376\375\374"
    [67305985, -50462977].pack("I*") => "\001\002\003\004\377\376\375\374"

ビッグエンディアン, 32bit int:

    "\001\002\003\004\377\376\375\374".unpack("I*") => [16909060, 4294901244]

    [16909060, 4294901244].pack("I*") => "\001\002\003\004\377\376\375\374"
    [16909060, -66052].pack("I*") => "\001\002\003\004\377\376\375\374"

l

long (32bit 符号つき整数, エンディアンに依存) (l! は 32bit でなく、long のサイズに依存)

リトルエンディアン, 32bit long:

    "\001\002\003\004\377\376\375\374".unpack("l*") => [67305985, -50462977]

    [67305985, 4244504319].pack("l*") => RangeError
    [67305985, -50462977].pack("l*") => "\001\002\003\004\377\376\375\374"

L

unsigned long (32bit 符号なし整数, エンディアンに依存) (L! は 32bit でなく、long のサイズに依存)

リトルエンディアン, 32bit long:

    "\001\002\003\004\377\376\375\374".unpack("L*") => [67305985, 4244504319]

    [67305985, 4244504319].pack("L*") => "\001\002\003\004\377\376\375\374"
    [67305985, -50462977].pack("L*") => "\001\002\003\004\377\376\375\374"

q

long long (符号付き整数, エンディアンと long long のサイズに依存) (C で long long が扱えない場合には 64bit)

リトルエンディアン, 64bit long long:

    "\001\002\003\004\005\006\007\010\377\376\375\374\373\372\371\370".unpack("q*")
    => [578437695752307201, -506097522914230529]

    [578437695752307201, -506097522914230529].pack("q*")
    => "\001\002\003\004\005\006\a\010\377\376\375\374\373\372\371\370"
    [578437695752307201, 17940646550795321087].pack("q*")
    => "\001\002\003\004\005\006\a\010\377\376\375\374\373\372\371\370"

Q

unsigned long long (符号なし整数, エンディアンと long long のサイズに依存) (C で long long が扱えない場合には 64bit)

リトルエンディアン, 64bit long long:

    "\001\002\003\004\005\006\007\010\377\376\375\374\373\372\371\370".unpack("Q*")
    => [578437695752307201, 17940646550795321087]

    [578437695752307201, 17940646550795321087].pack("Q*")
    => "\001\002\003\004\005\006\a\010\377\376\375\374\373\372\371\370"
    [578437695752307201, -506097522914230529].pack("Q*")
    => "\001\002\003\004\005\006\a\010\377\376\375\374\373\372\371\370"

m

base64された文字列。60 オクテットごと(と最後)に改行コードが付加されます。

Base64は、3オクテット(8bits * 3 = 24bits)のバイナリコードをASCII文字のうちの65文字 ([A-Za-z0-9+/]の64文字とpaddingのための'=')だけを使用して 4オクテット(6bits * 4 = 24bits)の印字可能文字列に変換するエンコーディング法です。RFC2045で定義されています。

    [""].pack("m") => ""
    ["\0"].pack("m") => "AA==\n"
    ["\0\0"].pack("m") => "AAA=\n"
    ["\0\0\0"].pack("m") => "AAAA\n"
    ["\377"].pack("m") => "/w==\n"
    ["\377\377"].pack("m") => "//8=\n"
    ["\377\377\377"].pack("m") => "////\n"

    ["abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"].pack("m")
    => "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXpBQkNERUZHSElKS0xNTk9QUVJT\nVFVWV1hZWg==\n"
    ["abcdefghijklmnopqrstuvwxyz"].pack("m3")
    => "YWJj\nZGVm\nZ2hp\namts\nbW5v\ncHFy\nc3R1\ndnd4\neXo=\n"

    "".unpack("m") => [""]
    "AA==\n".unpack("m") => ["\000"]
    "AA==".unpack("m") => ["\000"]

    "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXpBQkNERUZHSElKS0xNTk9QUVJT\nVFVWV1hZWg==\n".unpack("m")
    => ["abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"]
    "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXpBQkNERUZHSElKS0xNTk9QUVJTVFVWV1hZWg==\n".unpack("m")
    => ["abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"]

M

quoted-printable encoding された文字列

    ["a b c\td \ne"].pack("M") => "a b c\td =\n\ne=\n"

    "a b c\td =\n\ne=\n".unpack("M") => ["a b c\td \ne"]

n

ネットワークバイトオーダー(ビッグエンディアン)のunsigned short (16bit 符号なし整数)

    [0,1,-1,32767,-32768,65535].pack("n*")
    => "\000\000\000\001\377\377\177\377\200\000\377\377"

    "\000\000\000\001\377\377\177\377\200\000\377\377".unpack("n*")
    => [0, 1, 65535, 32767, 32768, 65535]

N

ネットワークバイトオーダー(ビッグエンディアン)のunsigned long (32bit 符号なし整数)

    [0,1,-1].pack("N*") => "\000\000\000\000\000\000\000\001\377\377\377\377"

    "\000\000\000\000\000\000\000\001\377\377\377\377".unpack("N*") => [0, 1, 4294967295]

v

"VAX"バイトオーダー(リトルエンディアン)のunsigned short (16bit 符号なし整数)

    [0,1,-1,32767,-32768,65535].pack("v*")
    => "\000\000\001\000\377\377\377\177\000\200\377\377"

    "\000\000\001\000\377\377\377\177\000\200\377\377".unpack("v*")
    => [0, 1, 65535, 32767, 32768, 65535]

V

"VAX"バイトオーダー(リトルエンディアン)のunsigned long (32bit 符号なし整数)

    [0,1,-1].pack("V*") => "\000\000\000\000\001\000\000\000\377\377\377\377"

    "\000\000\000\000\001\000\000\000\377\377\377\377".unpack("V*") => [0, 1, 4294967295]

f

単精度浮動小数点数(機種依存)

IA-32 (x86) (IEEE754 単精度リトルエンディアン):

    [1.0].pack("f") => "\000\000\200?"
    [0.0/0.0].pack("f") => "\000\000\300\377"       # NaN
    [1.0/0.0].pack("f") => "\000\000\200\177"       # +Inf
    [-1.0/0.0].pack("f") => "\000\000\200\377"      # -Inf

SPARC (IEEE754 単精度ビッグエンディアン):

    [1.0].pack("f") => "?\200\000\000"
    [0.0/0.0].pack("f") => "\177\377\377\377"       # NaN
    [1.0/0.0].pack("f") => "\177\200\000\000"       # +Inf
    [-1.0/0.0].pack("f") => "\377\200\000\000"      # -Inf

VAX (NetBSD 3.0) (非IEEE754):

    [1.0].pack("f") => "\200@\000\000"

d

倍精度浮動小数点数(機種依存)

IA-32 (IEEE754 倍精度リトルエンディアン):

    [1.0].pack("d") => "\000\000\000\000\000\000\360?"
    [0.0/0.0].pack("d") => "\000\000\000\000\000\000\370\377"       # NaN
    [1.0/0.0].pack("d") => "\000\000\000\000\000\000\360\177"       # +Inf
    [-1.0/0.0].pack("d") => "\000\000\000\000\000\000\360\377"      # -Inf

SPARC (IEEE754 倍精度ビッグエンディアン):

    [1.0].pack("d") => "?\360\000\000\000\000\000\000"
    [0.0/0.0].pack("d") => "\177\377\377\377\377\377\377\377"       # NaN
    [1.0/0.0].pack("d") => "\177\360\000\000\000\000\000\000"       # +Inf
    [-1.0/0.0].pack("d") => "\377\360\000\000\000\000\000\000"      # -Inf

VAX (NetBSD 3.0) (非IEEE754):

    [1.0].pack("d") => "\200@\000\000\000\000\000\000"

e

リトルエンディアンの単精度浮動小数点数(機種依存)

IA-32 (IEEE754):

    [1.0].pack("e") => "\000\000\200?"

SPARC (IEEE754):

    [1.0].pack("e") => "\000\000\200?"

E

リトルエンディアンの倍精度浮動小数点数(機種依存)

IA-32 (IEEE754):

    [1.0].pack("E") => "\000\000\000\000\000\000\360?"

SPARC (IEEE754):

    [1.0].pack("E") => "\000\000\000\000\000\000\360?"

g

ビッグエンディアンの単精度浮動小数点数(機種依存)

IA-32 (IEEE754):

    [1.0].pack("g") => "?\200\000\000"

SPARC (IEEE754):

    [1.0].pack("g") => "?\200\000\000"

IEEE754準拠な環境の場合、以下のようにして符号、指数部、仮数部を取り出せます。

    s = [v].pack("g").unpack("B*")[0][0,1]      # 符号
    e = [v].pack("g").unpack("B*")[0][1,8]      # 指数部
    f = [v].pack("g").unpack("B*")[0][9,23]     # 仮数部

そして、s, e, f の意味は以下の通りです。

    sgn = s == "0" ? +1.0 : -1.0
    exp = Integer("0b" + e)
    fra = Integer("0b" + f)
    if exp == 0
      if fra == 0
        sgn * 0                     # ±0 (positive/negative zero)
      else
        sgn * fra * 2**(-126-23)    # 非正規化数 (denormalized number)
      end
    elsif exp == 255
      if fra == 0
        sgn * Inf                   # ±∞ (positive/negative infinity)
      else
        NaN                         # 非数 (not a number)
      end
    else
      fra += 1 << 23                # ゲタ
      sgn * fra * 2**(exp-127-23)   # 正規化数 (normalized number)
    end

G

ビッグエンディアンの倍精度浮動小数点数(機種依存)

IA-32:

    [1.0].pack("G") => "?\360\000\000\000\000\000\000"

SPARC:

    [1.0].pack("G") => "?\360\000\000\000\000\000\000"

IEEE754準拠な環境の場合、以下のようにして符号、指数部、仮数部を取り出せます。

    s = [v].pack("G").unpack("B*")[0][0,1]    # 符号
    e = [v].pack("G").unpack("B*")[0][1,11]   # 指数部
    f = [v].pack("G").unpack("B*")[0][12,52]  # 仮数部

そして、s, e, f の意味は以下の通りです。

    sgn = s == "0" ? +1.0 : -1.0
    exp = Integer("0b" + e)
    fra = Integer("0b" + f)
    if exp == 0
      if fra == 0
        sgn * 0                     # ±0 (positive/negative zero)
      else
        sgn * fra * 2**(-1022-52)   # 非正規化数 (denormalized number)
      end
    elsif exp == 2047
      if fra == 0
        sgn * Inf                   # ±∞ (positive/negative infinity)
      else
        NaN                         # 非数 (not a number)
      end
    else
      fra += 1 << 52                # ゲタ
      sgn * fra * 2**(exp-1023-52)  # 正規化数 (normalized number)
    end

p

ナル終端の文字列へのポインタ

    [""].pack("p") => "\310\037\034\010"
    ["a", "b", "c"].pack("p3") => " =\030\010\340^\030\010\360^\030\010"
    [nil].pack("p") => "\000\000\000\000"

P

構造体(固定長文字列)へのポインタ

    [nil].pack("P") => "\000\000\000\000"
    ["abc"].pack("P3") => "x*\024\010"

    ["abc"].pack("P4") => ArgumentError: too short buffer for P(3 for 4)
    [""].pack("P") => ArgumentError: too short buffer for P(0 for 1)

u

uuencodeされた文字列

    [""].pack("u") => ""
    ["a"].pack("u") => "!80``\n"
    ["abc"].pack("u") => "#86)C\n"
    ["abcd"].pack("u") => "$86)C9```\n"
    ["a"*45].pack("u") => "M86%A86%A86%A86%A86%A86%A86%A86%A86%A86%A86%A86%A86%A86%A86%A\n"
    ["a"*46].pack("u") => "M86%A86%A86%A86%A86%A86%A86%A86%A86%A86%A86%A86%A86%A86%A86%A\n!80``\n"
    ["abcdefghi"].pack("u6") => "&86)C9&5F\n#9VAI\n"

U

UTF-8

    [0].pack("U") => "\000"
    [1].pack("U") => "\001"
    [0x7f].pack("U") => "\177"
    [0x80].pack("U") => "\302\200"
    [0x7fffffff].pack("U") => "\375\277\277\277\277\277"
    [0x80000000].pack("U") => RangeError
    [0,256,65536].pack("U3") => "\000\304\200\360\220\200\200"

    "\000\304\200\360\220\200\200".unpack("U3") => [0, 256, 65536]
    "\000\304\200\360\220\200\200".unpack("U") => [0]
    "\000\304\200\360\220\200\200".unpack("U*") => [0, 256, 65536]

w

BER圧縮整数

1バイトあたり7ビットを使用して必要最小限のバイト数で任意サイズの 0以上の整数を表す数値表現。各バイトの最上位ビットはデータの最後を除いて必ず1が立っている(つまり最上位ビットはどこまでデータがあるかを示している)。

ISO/IEC 8825-1:1995 : Information technology－ASN.1 encoding rules : Specification of Basic Encoding Rules(BER) に定められる整数の符号化方法。

    [0].pack("w") => "\000"
    [1].pack("w") => "\001"
    [127].pack("w") => "\177"
    [128].pack("w") => "\201\000"
    [0x3fff].pack("w") => "\377\177"
    [0x4000].pack("w") => "\201\200\000"
    [0x3fffffff].pack("w") => "\203\377\377\377\177"
    [0x40000000].pack("w") => "\204\200\200\200\000"
    [0xffffffff].pack("w") => "\217\377\377\377\177"
    [0x100000000].pack("w") => "\220\200\200\200\000"

    "\0".unpack("w") => [0]
    "\0\201\0\1".unpack("w*") => [0, 128, 1]

なお、BER圧縮整数でエンコードした結果は大小関係を保存しない。たとえば、[0x3fff].pack("w") > [0x4000].pack("w") である。

x

ナルバイト/1バイト読み飛ばす

    [?a, ?b].pack("CxC") => "a\000b"
    [?a, ?b].pack("Cx3C") => "a\000\000\000b"

    "a\000b".unpack("CxC") => [97, 98]
    "a\377b".unpack("CxC") => [97, 98]
    "a\377b".unpack("Cx3C") => ArgumentError: x outside of string

X

1バイト後退

    [?a, ?b, ?c].pack("CCXC") => "ac"

    "abcdef".unpack("x*XC") => [102]

@

絶対位置への移動

    [?a, ?b].pack("C @3 C") => "a\000\000b"

    "a\000\000b".unpack("C @3 C") => [97, 98]

使用例

以下、pack/unpack の使用例の一部です。

pack を使用しなくても同じことができる場合はその例も載せています。 pack は暗号になりやすい面があることを考慮し、pack を使いたくない人に別解を示すためです。

数値(文字コード)の配列を文字列に変換する例

    p [82, 117, 98, 121].pack("cccc")
    => "Ruby"

    p [82, 117, 98, 121].pack("c4")
    => "Ruby"

    p [82, 117, 98, 121].pack("c*")
    => "Ruby"

    s = ""
    [82, 117, 98, 121].each {|c| s << c}
    p s
    => "Ruby"

    p [82, 117, 98, 121].collect {|c| sprintf "%c", c}.join
    => "Ruby"

    p [82, 117, 98, 121].inject("") {|s, c| s << c}
    => "Ruby"

文字列を数値(文字コード)の配列に変換する例

    p "Ruby".unpack('C*')
    => [82, 117, 98, 121]

    a = []
    "Ruby".each_byte {|c| a << c}
    p a
    => [82, 117, 98, 121]

"x" でナルバイトを埋めることができる

    p [82, 117, 98, 121].pack("ccxxcc")
    => "Ru\000\000by"

"x" で文字を読み飛ばす事が出来る

    p "Ru\0\0by".unpack('ccxxcc')
    => [82, 117, 98, 121]

Hexダンプを数値の配列に変換する例

    p "61 62 63 64 65 66".delete(' ').to_a.pack('H*').unpack('C*')
    => [97, 98, 99, 100, 101, 102]

    p "61 62 63 64 65 66".split.collect {|c| c.hex}
    => [97, 98, 99, 100, 101, 102]

バイナリと16進数のpackでは長さ指定は生成されるバイト数ではなく、ビットやニブルの個数を表す

    p [0b01010010, 0b01110101, 0b01100010, 0b01111001].pack("C4")
    => "Ruby"
    p ["01010010011101010110001001111001"].pack("B32") # 8 bits * 4
    => "Ruby"

    p [0x52, 0x75, 0x62, 0x79].pack("C4")
    => "Ruby"
    p ["52756279"].pack("H8")  # 2 nybbles * 4
    => "Ruby"

テンプレート文字'a'の長さ指定は1つの文字列だけに適用される

    p  ["RUBY", "u", "b", "y"].pack("a4")
    => "RUBY"

    p ["RUBY", "u", "b", "y"].pack("aaaa")
    => "Ruby"

    p ["RUBY", "u", "b", "y"].pack("a*aaa")
    => "RUBYuby"

テンプレート文字"a"は、長さが足りない分をヌル文字で補う

    p ["Ruby"].pack("a8")
    => "Ruby\000\000\000\000"

リトルエンディアンとビッグエンディアン

    p [1,2].pack("s2")
    => "\000\001\000\002" # ビッグエンディアンのシステムでの出力
    => "\001\000\002\000" # リトルエンディアンのシステムでの出力

    p [1,2].pack("n2")
    => "\000\001\000\002" # システムによらずビッグエンディアン

    p [1,2].pack("v2")
    => "\001\000\002\000" # システムによらずリトルエンディアン

ネットワークバイトオーダの signed long

      s = "\xff\xff\xff\xfe"
      n = s.unpack("N")[0]
      if n[31] == 1
        n = -((n ^ 0xffff_ffff) + 1)
      end
      p n
      => -2

ネットワークバイトオーダの signed long(その2)

      s = "\xff\xff\xff\xfe"
      p n = s.unpack("N").pack("l").unpack("l")[0]
      => -2

IPアドレス

      require 'socket'
      p Socket.gethostbyname("localhost")[3].unpack("C4").join(".")
      => "127.0.0.1"

      p "127.0.0.1".split(".").collect {|c| c.to_i}.pack("C4")
      => "\177\000\000\001"

sockaddr_in 構造体

      require 'socket'
      p [Socket::AF_INET,
         Socket.getservbyname('echo'),
         127, 0, 0, 1].pack("s n C4 x8")
      => "\002\000\000\a\177\000\000\001\000\000\000\000\000\000\000\000"

pack/unpack を使う代わりに Socket.pack_sockaddr_in, Socket.unpack_sockaddr_in メソッドがあります。

'\0'終端文字列のアドレス

テンプレート文字 "p" や "P" は、C 言語レベルのインタフェースのためにあります(例えば IO#ioctl)。

    p ["foo"].pack("p")
    => "8\266\021\010"

結果の文字列はゴミに見えますが、実際は文字列"foo\0"を指すアドレス(のバイナリ表現)です。以下のようにすれば見慣れた表記で見ることが出来ます

    printf "%#010x\n", "8\266\021\010".unpack("L")[0]
    => 0x0811b638

アドレスが指す先のオブジェクト(この例で "foo\0") は、pack の結果が GC されるまではGCされないことが保証されています。

unpack("p"), unpack("P") は、pack の結果からしか unpack できません。

    p ["foo"].pack("p").unpack("p")
    => ["foo"]
    p "8\266\021\010".unpack("p")
    => -:1:in `unpack': no associated pointer (ArgumentError)
            from -:1

"p" や "P" は、nil を特別に扱い NULL ポインタとして解釈します。(以下は、32bitマシンで一般的な結果)

      p [nil].pack("p")        #=> "\000\000\000\000"
      p "\0\0\0\0".unpack("p") #=> [nil]

構造体のアドレス

例えば、

      struct {
        int   a;
        short b;
        long  c;
      } v = {1,2,3};

を表す文字列は

      v = [1,2,3].pack("i!s!l!")

です。(byte alignment の問題から実際は適当な padding が必要になるかもしれません)

この構造体を指すアドレスは

      p [v].pack("P")
      => "\300\265\021\010"

で得られます。

UTF-8からUCS-2への変換 (サロゲートを処理していないので UTF-16 とはいえない)

Little endian:

    p(("Comments").unpack("U*").pack("v*"))
    "C\000o\000m\000m\000e\000n\000t\000s\000"

Big endian:

    p(("Comments").unpack("U*").pack("n*"))
    "\000C\000o\000m\000m\000e\000n\000t\000s"

upcase -> String

'a' から 'z' までのアルファベット小文字を大文字に変換した文字列を作成し返します。

このメソッドはマルチバイト文字列を認識しますが、それはあくまでも「1 文字を 1 文字として認識する」だけであって、いわゆる全角アルファベットの大文字小文字までは変換しません。

また、マルチバイト文字列に対応するためには $KCODE を設定する必要があります。文字列が Shift JIS エンコーディングで $KCODE が適切に設定されていないときは以下のようにマルチバイト文字の一部も変換してしまいます。

#coding:Shift_JIS
$KCODE = "SJIS"
puts "蟻".upcase   # => 蟻   ($KCODE が適切なので正しく無視された)

$KCODE = "NONE"
puts "蟻".upcase   # => 帰   ($KCODE が不適切なので誤って処理された)

例:

p "stRIng? STring.".upcase   # => "STRING? STRING."

[SEE_ALSO] String#upcase!, String#downcase, String#swapcase, String#capitalize

upcase! -> self | nil

ASCII 文字列の範囲内で 'a' から 'z' までのアルファベット小文字を全て大文字にします。このメソッドは self を破壊的に変更して返しますが、置換が起こらなかった場合は nil を返します。

#coding:Shift_JIS
$KCODE = "SJIS"
str = "蟻"
str.upcase!
puts str   # => 蟻   ($KCODE が適切なので正しく無視された)

$KCODE = "NONE"
str = "蟻"
str.upcase!
puts str   # => 帰   ($KCODE が不適切なので誤って処理された)

例:

buf = "stRIng? STring."
buf.upcase!
p buf   # => "STRING? STRING."

[SEE_ALSO] String#upcase, String#downcase!, String#swapcase!, String#capitalize!

upto(max, exclusive = false) {|s| ... } -> self

self から始めて max まで「次の文字列」を順番にブロックに与えて繰り返します。「次」の定義については String#succ を参照してください。

たとえば以下のコードは a, b, c, ... z, aa, ... az, ..., za を出力します。

("a" .. "za").each do |str|
  puts str
end
'a'.upto('za') do |str|
  puts str
end

[PARAM] max:: 繰り返しをやめる文字列
[PARAM] exclusive:: max を含むかどうか。false の場合は max を含む。

valid_encoding? -> bool

文字列の内容が、現在のエンコーディングに照らしあわせて妥当であれば true を返します。さもなくば false を返します。

追加されるメソッド

ext(newext = '') -> String [added by rake]

自身の拡張子を与えられた拡張子で置き換えます。

自身に拡張子が無い場合は、与えられた拡張子を追加します。与えられた拡張子が空文字列の場合は、自身の拡張子を削除します。

[PARAM] newext:: 新しい拡張子を指定します。

is_binary_data? [added by yaml]

is_complex_yaml? [added by yaml]

iseuc [added by kconv]

((<ruby 1.8.2 feature>))

Kconv.iseuc(self) と同じです。

issjis [added by kconv]

((<ruby 1.8.2 feature>))

Kconv.issjis(self) と同じです。

isutf8 [added by kconv]

((<ruby 1.8.2 feature>))

Kconv.isutf8(self) と同じです。

kconv(out_code, in_code = Kconv::AUTO) [added by kconv]

self のエンコーディングを out_code に変換したのを返します。out_code in_code は Kconv の定数で指定します。

pathmap(spec = nil) { ... } [added by rake]

与えられた書式指定文字列に応じてパス(自身)を変換します。

与えられた書式指定文字列は変換の詳細を制御します。指定できる書式指定文字列は以下の通りです。

%p: 完全なパスを表します。
%f: 拡張子付きのファイル名を表します。ディレクトリ名は含まれません。
%n: 拡張子なしのファイル名を表します。
%d: パスに含まれるディレクトリのリストを表します。
%x: パスに含まれるファイルの拡張子を表します。拡張子が無い場合は空文字列を表します。
%X: 拡張子以外すべてを表します。
%s: 定義されていれば、代替のファイルセパレータを表します。定義されてい無い場合は、標準のファイルセパレータを表します。
%%: パーセント自身を表します。

%d は数値のプレフィクスを取ることができます。

例:

'a/b/c/d/file.txt'.pathmap("%2d")   => 'a/b'
'a/b/c/d/file.txt'.pathmap("%-2d")  => 'c/d'

また、%d, %p, %f, %n, %x, %X には単純な文字列置換を行うための置換パターンを表すパラメータを指定することが出来ます。パターンと置換文字列はコンマで区切り全体を中括弧でくくります。置換指定は、% と指示子の間に置きます。(例: "%{old,new}d") 複数の置換を行う場合はパターンをセミコロンで区切ってください。 (例: "%{old,new;src,bin}d")

正規表現や後方参照をパターンとして使用することがあるかもしれません。中括弧、コンマ、セミコロンはパターンと置換文字列に使用しないでください。

例:

"src/org/onestepback/proj/A.java".pathmap("%{^src,bin}X.class")
#=> "bin/org/onestepback/proj/A.class"

置換文字列に '*' を指定した場合は、置換文字列を計算するためにブロックを評価します。

例:

"/path/to/file.TXT".pathmap("%X%{.*,*}x") { |ext| ext.downcase }
#=> "/path/to/file.txt"

pathmap_explode -> Array [added by rake]

自身をパスを表す部分ごとに分解して配列にして返します。

[SEE_ALSO] String#pathmap

pathmap_partial(n) -> String [added by rake]

自身から与えられた階層分パスを抜粋します。

与えられた数値が正である場合は左から、負である場合は右から抜粋します。

pathmap_replace(patterns) { ... } -> String [added by rake]

与えられたパスを前もって置き換えます。

[PARAM] patterns:: 'pat1,rep1;pat2,rep2;...' のような形式で置換パターンを指定します。

scanf(format) -> Array [added by scanf]

scanf(format) {|*ary| ...} -> Array [added by scanf]

ブロックを指定しない場合、見つかった文字列を format に従って変換し、そのオブジェクトの配列を返します。 format で指定した文字列が見つからない場合は空の配列を生成して返します。

str = "123 abc 456 def 789 ghi"
p str.scanf("%d%s") #=> [123, "abc"]

ブロックを指定した場合は scanf を継続して実行し、順次見つかった文字列を変換したオブジェクトの配列を引数に、ブロックを実行します。このとき、ブロックの実行結果を要素とする配列を返します。

str = "123 0x45 678 0x90"
p str.scanf("%d%x"){|n, s| [n, s]}
#=> [[123, 69], [678, 144]]

formatに完全にマッチしていなくても、部分的にマッチしていれば、ブロックは実行されます。

str = "123 abc 456 def"
ret = str.scanf("%s%d") { |s, n| [s, n] }
p ret #=> [["123", nil], ["abc", 456], ["def", nil]]

[PARAM] format:: スキャンするフォーマットを文字列で指定します。詳細は、[[unknown:scanfフォーマット文字列]] を参照してください。

使用例:

str = "123 abc 456 def 789 ghi"
p str.scanf("%d%s") #=> [123, "abc"]

scanfフォーマット文字列

文字 '%' と(s,d のような)指示子の間に、整数を指定する事により読み込む文字列の幅を指定する事ができます。もし幅が与えられなければ、無限大の値が規定値として使用されます。 (但し、%c では、この規定値は適用されません。) 上記の幅が整数 n で与えられた場合、多くても n 個の文字列がマッチします。このフォーマット文字列によるマッチの実行前、多くの場合入力文字列のスペースは読み飛ばされます。つまり、スペースは幅の数として数えられない事になります。

動作例;

p "a           10".scanf("%s %d")  # => ["a", 10]
p "a10".scanf("%1s %d")      # => ["a", 10]

使用例；

str = "1234"
p str.scanf("%1s%3d")  #=> ["1", 234]

また、1.9 以降では、スペースには全角文字列が含まれます。

動作例；

# encoding: utf-8
require 'scanf'

str = "1　　　　　aaa"
p str.scanf("%d %s") #=> [1, "aaa"]

space

フォーマット中の空白は(0個を含む)任意の数の空白にマッチします。

  p "a           10".scanf("%s %d")  # => ["a", 10]
  p "a10".scanf("%1s %d")            # => ["a", 10]

%%

% そのもの

%d

%u

符号付き10進数

%i

Kernel.#Integerのように接頭辞を受け付ける符号付き整数

%o

符号付き8進数

%x

%X

符号付き16進数

%f

%g

%e

%E

符号付き浮動小数点数

%s

空白文字を含まない文字列 (幅が指定されているときは指定された文字数か空白文字の直前までの短い方)

%c

1文字(幅が指定されているときは指定された文字数)

[...]

[[unknown:正規表現/文字クラス]]

shellescape -> String [added by shellwords]

文字列を Bourne シェルのコマンドライン中で安全に使えるようにエスケープします。

string.shellescape は、Shellwords.escape(string) と等価です。

[RETURN]: エスケープされた文字列を返します。

[SEE_ALSO] Shellwords.#shellescape

shellsplit -> [String] [added by shellwords]

Bourne シェルの単語分割規則に従った空白区切りの単語分割を行い、単語 (文字列) の配列を返します。

string.shellsplit は、Shellwords.shellsplit(string) と等価です。

[RETURN]: 分割結果の各文字列を要素とする配列を返します。
[EXCEPTION] ArgumentError:: 引数の中に対でないシングルクォートまたはダブルクォートが現れた場合に発生します。

[SEE_ALSO] Shellwords.#shellsplit

to_d [added by bigdecimal/util]

BigDecimalに変換する

toeuc [added by kconv]

self のエンコーディングを euc-jp に変換した文字列を返します。

tojis [added by kconv]

self のエンコーディングを iso-2022-jp に変換した文字列を返します。

tosjis [added by kconv]

self のエンコーディングを shift_jis に変換した文字列を返します。

toutf16 [added by kconv]

((<ruby 1.8.2 feature>))

self のエンコーディングを utf16 に変換した文字列を返します。

toutf8 [added by kconv]

((<ruby 1.8.2 feature>))

self のエンコーディングを utf8 に変換した文字列を返します。

class String

Abstract

破壊的な変更

多言語化と文字列のエンコーディング

文字列同士の比較・結合

7bit クリーンな文字列

バイト列を表す文字列

特異メソッド

インスタンスメソッド

sprintf フォーマット

フラグ

幅

精度

指示子

引数指定

整数のテンプレート文字のシステム依存性

各テンプレート文字の説明

使用例

追加されるメソッド

scanfフォーマット文字列

Methods

Classes