Class: Symbol
Relationships & Source Files | |
Super Chains via Extension / Inclusion / Inheritance | |
Instance Chain:
self,
::Comparable
|
|
Inherits: | Object |
Defined in: | string.c, proc.c, string.c, symbol.c, symbol.rb |
Overview
A Symbol
object represents a named identifier inside the Ruby interpreter.
You can create a Symbol
object explicitly with:
-
A
symbol literal
.
The same Symbol
object will be created for a given name or string for the duration of a program’s execution, regardless of the context or meaning of that name. Thus if Fred
is a constant in one context, a method in another, and a class in a third, the Symbol
:Fred
will be the same object in all three contexts.
module One
class Fred
end
$f1 = :Fred
end
module Two
Fred = 1
$f2 = :Fred
end
def Fred()
end
$f3 = :Fred
$f1.object_id #=> 2514190
$f2.object_id #=> 2514190
$f3.object_id #=> 2514190
Constant, method, and variable names are returned as symbols:
module One
Two = 2
def three; 3 end
@four = 4
@@five = 5
$six = 6
end
seven = 7
One.constants
# => [:Two]
One.instance_methods(true)
# => [:three]
One.instance_variables
# => [:@four]
One.class_variables
# => [:@@five]
global_variables.grep(/six/)
# => [:$six]
local_variables
# => [:seven]
A Symbol
object differs from a ::String
object in that a Symbol
object represents an identifier, while a ::String
object represents text or data.
What’s Here
First, what’s elsewhere. Class Symbol
:
-
Inherits from
class Object
. -
Includes
module Comparable
.
Here, class Symbol
provides methods that are useful for:
-
Querying
-
Comparing
-
Converting
Methods for Querying
-
.all_symbols: Returns an array of the symbols currently in Ruby’s symbol table.
-
#=~: Returns the index of the first substring in symbol that matches a given Regexp or other object; returns
nil
if no match is found. -
#[], #slice : Returns a substring of symbol determined by a given index, start/length, or range, or string.
-
#empty?: Returns
true
ifself.length
is zero;false
otherwise. -
#encoding: Returns the
::Encoding
object that represents the encoding of symbol. -
#end_with?: Returns
true
if symbol ends with any of the given strings. -
#match: Returns a
::MatchData
object if symbol matches a given Regexp;nil
otherwise. -
#match?: Returns
true
if symbol matches a given Regexp;false
otherwise. -
#start_with?: Returns
true
if symbol starts with any of the given strings.
Methods for Comparing
-
#<=>: Returns -1, 0, or 1 as a given symbol is smaller than, equal to, or larger than symbol.
-
#==, #===: Returns
true
if a given symbol has the same content and encoding. -
#casecmp: Ignoring case, returns -1, 0, or 1 as a given symbol is smaller than, equal to, or larger than symbol.
-
#casecmp?: Returns
true
if symbol is equal to a given symbol after Unicode case folding;false
otherwise.
Methods for Converting
-
#capitalize: Returns symbol with the first character upcased and all other characters downcased.
-
#downcase: Returns symbol with all characters downcased.
-
#inspect: Returns the string representation of
self
as a symbol literal. -
#name: Returns the frozen string corresponding to symbol.
-
#succ, #next: Returns the symbol that is the successor to symbol.
-
#swapcase: Returns symbol with all upcase characters downcased and all downcase characters upcased.
-
#to_proc: Returns a
::Proc
object which responds to the method named by symbol. -
#upcase: Returns symbol with all characters upcased.
Class Method Summary
-
.all_symbols ⇒ Symbol
Returns an array of all symbols currently in Ruby’s symbol table:
Instance Attribute Summary
-
#empty? ⇒ Boolean
readonly
Returns
true
ifself
is:''
,false
otherwise.
Instance Method Summary
-
#<=>(object) ⇒ 1, ...
If
object
is a symbol, returns the equivalent ofsymbol.to_s <=> object.to_s
: - #==
- #===
-
#=~(object) ⇒ Integer?
Equivalent to
symbol.to_s =~ object
, including possible updates to global variables; see String#=~. -
#[](index) ⇒ String?
(also: #slice)
Equivalent to
symbol.to_s[]
; see String#[]. -
#capitalize(*options) ⇒ Symbol
Equivalent to
sym.to_s.capitalize.to_sym
. -
#casecmp(object) ⇒ 1, ...
Like Symbol#<=>, but case-insensitive; equivalent to
self.to_s.casecmp(object.to_s)
: -
#casecmp?(object) ⇒ true, ...
Returns
true
ifself
andobject
are equal after Unicode case folding, otherwisefalse
: -
#downcase(*options) ⇒ Symbol
Equivalent to
sym.to_s.downcase.to_sym
. -
#encoding ⇒ Encoding
Equivalent to
self.to_s.encoding
; see String#encoding. -
#end_with?(*strings) ⇒ Boolean
Equivalent to
self.to_s.end_with?
; see String#end_with?. -
#id2name
Alias for #to_s.
-
#inspect ⇒ String
Returns a string representation of
self
(including the leading colon): -
#intern
Alias for #to_sym.
-
#length ⇒ Integer
(also: #size)
Equivalent to
self.to_s.length
; see String#length. -
#match(pattern, offset = 0) ⇒ MatchData?
Equivalent to
self.to_s.match
, including possible updates to global variables; see String#match. -
#match?(pattern, offset) ⇒ Boolean
Equivalent to
sym.to_s.match?
; see String#match. -
#name ⇒ String
Returns a frozen string representation of
self
(not including the leading colon): -
#next
(also: #succ)
Equivalent to
self.to_s.succ.to_sym
: -
#size ⇒ Integer
Alias for #length.
-
#[](index) ⇒ String?
Alias for #[].
-
#start_with?(*string_or_regexp) ⇒ Boolean
Equivalent to
self.to_s.start_with?
; see String#start_with?. -
#succ
Alias for #next.
-
#swapcase(*options) ⇒ Symbol
Equivalent to
sym.to_s.swapcase.to_sym
. -
#to_proc ⇒ Proc
Returns a
::Proc
object which calls the method with name ofself
on the first parameter and passes the remaining parameters to the method. -
#to_s ⇒ String
(also: #id2name)
Returns a string representation of
self
(not including the leading colon): -
#to_sym ⇒ self
(also: #intern)
Returns
self
. -
#upcase(*options) ⇒ Symbol
Equivalent to
sym.to_s.upcase.to_sym
.
::Comparable
- Included
#< | Compares two objects based on the receiver’s #<=> method, returning true if it returns a value less than 0. |
#<= | Compares two objects based on the receiver’s #<=> method, returning true if it returns a value less than or equal to 0. |
#== | Compares two objects based on the receiver’s #<=> method, returning true if it returns 0. |
#> | Compares two objects based on the receiver’s #<=> method, returning true if it returns a value greater than 0. |
#>= | Compares two objects based on the receiver’s #<=> method, returning true if it returns a value greater than or equal to 0. |
#between? | |
#clamp |
Class Method Details
.all_symbols ⇒ Symbol
Returns an array of all symbols currently in Ruby’s symbol table:
Symbol.all_symbols.size # => 9334
Symbol.all_symbols.take(3) # => [:!, :"\"", :"#"]
# File 'string.c', line 12480
static VALUE sym_all_symbols(VALUE _) { return rb_sym_all_symbols(); }
Instance Attribute Details
#empty? ⇒ Boolean
(readonly)
Returns true
if self
is :''
, false
otherwise.
# File 'string.c', line 12320
static VALUE sym_empty(VALUE sym) { return rb_str_empty(rb_sym2str(sym)); }
Instance Method Details
#<=>(object) ⇒ 1
, ...
If object
is a symbol, returns the equivalent of symbol.to_s <=> object.to_s
:
: <=> :foo # => -1
:foo <=> :foo # => 0
:foo <=> : # => 1
Otherwise, returns nil
:
:foo <=> 'bar' # => nil
Related: String#<=>.
# File 'string.c', line 12190
static VALUE sym_cmp(VALUE sym, VALUE other) { if (!SYMBOL_P(other)) { return Qnil; } return rb_str_cmp_m(rb_sym2str(sym), rb_sym2str(other)); }
#==
[ GitHub ]#===
[ GitHub ]#=~(object) ⇒ Integer?
Equivalent to symbol.to_s =~ object
, including possible updates to global variables; see String#=~.
# File 'string.c', line 12243
static VALUE sym_match(VALUE sym, VALUE other) { return rb_str_match(rb_sym2str(sym), other); }
Also known as: #slice
Equivalent to symbol.to_s[]
; see String#[].
# File 'string.c', line 12293
static VALUE sym_aref(int argc, VALUE *argv, VALUE sym) { return rb_str_aref_m(argc, argv, rb_sym2str(sym)); }
#capitalize(*options) ⇒ Symbol
Equivalent to sym.to_s.capitalize.to_sym
.
See String#capitalize.
# File 'string.c', line 12370
static VALUE sym_capitalize(int argc, VALUE *argv, VALUE sym) { return rb_str_intern(rb_str_capitalize(argc, argv, rb_sym2str(sym))); }
#casecmp(object) ⇒ 1
, ...
Like #<=>, but case-insensitive; equivalent to self.to_s.casecmp(object.to_s)
:
lower = :abc
upper = :ABC
upper.casecmp(lower) # => 0
lower.casecmp(lower) # => 0
lower.casecmp(upper) # => 0
Returns nil if self
and object
have incompatible encodings, or if object
is not a symbol:
sym = 'äöü'.encode("ISO-8859-1").to_sym
other_sym = 'ÄÖÜ'
sym.casecmp(other_sym) # => nil
:foo.casecmp(2) # => nil
Unlike #casecmp?, case-insensitivity does not work for characters outside of ‘A’..‘Z’ and ‘a’..‘z’:
lower = :äöü
upper = :ÄÖÜ
upper.casecmp(lower) # => -1
lower.casecmp(lower) # => 0
lower.casecmp(upper) # => 1
Related: #casecmp?, String#casecmp.
# File 'string.c', line 12207
static VALUE sym_casecmp(VALUE sym, VALUE other) { if (!SYMBOL_P(other)) { return Qnil; } return str_casecmp(rb_sym2str(sym), rb_sym2str(other)); }
#casecmp?(object) ⇒ true
, ...
Returns true
if self
and object
are equal after Unicode case folding, otherwise false
:
lower = :abc
upper = :ABC
upper.casecmp?(lower) # => true
lower.casecmp?(lower) # => true
lower.casecmp?(upper) # => true
Returns nil if self
and object
have incompatible encodings, or if object
is not a symbol:
sym = 'äöü'.encode("ISO-8859-1").to_sym
other_sym = 'ÄÖÜ'
sym.casecmp?(other_sym) # => nil
:foo.casecmp?(2) # => nil
Unlike #casecmp, works for characters outside of ‘A’..‘Z’ and ‘a’..‘z’:
lower = :äöü
upper = :ÄÖÜ
upper.casecmp?(lower) # => true
lower.casecmp?(lower) # => true
lower.casecmp?(upper) # => true
Related: #casecmp, String#casecmp?.
# File 'string.c', line 12224
static VALUE sym_casecmp_p(VALUE sym, VALUE other) { if (!SYMBOL_P(other)) { return Qnil; } return str_casecmp_p(rb_sym2str(sym), rb_sym2str(other)); }
#downcase(*options) ⇒ Symbol
# File 'string.c', line 12354
static VALUE sym_downcase(int argc, VALUE *argv, VALUE sym) { return rb_str_intern(rb_str_downcase(argc, argv, rb_sym2str(sym))); }
#encoding ⇒ Encoding
Equivalent to self.to_s.encoding
; see String#encoding.
# File 'string.c', line 12429
static VALUE sym_encoding(VALUE sym) { return rb_obj_encoding(rb_sym2str(sym)); }
#end_with?(*strings) ⇒ Boolean
Equivalent to self.to_s.end_with?
; see String#end_with?.
# File 'string.c', line 12415
static VALUE sym_end_with(int argc, VALUE *argv, VALUE sym) { return rb_str_end_with(argc, argv, rb_sym2str(sym)); }
#id2name
Alias for #to_s.
# File 'symbol.rb', line 15
alias id2name to_s
#inspect ⇒ String
# File 'string.c', line 12101
static VALUE sym_inspect(VALUE sym) { VALUE str = rb_sym2str(sym); const char *ptr; long len; char *dest; if (!rb_str_symname_p(str)) { str = rb_str_inspect(str); len = RSTRING_LEN(str); rb_str_resize(str, len + 1); dest = RSTRING_PTR(str); memmove(dest + 1, dest, len); } else { rb_encoding *enc = STR_ENC_GET(str); VALUE orig_str = str; len = RSTRING_LEN(orig_str); str = rb_enc_str_new(0, len + 1, enc); // Get data pointer after allocation ptr = RSTRING_PTR(orig_str); dest = RSTRING_PTR(str); memcpy(dest + 1, ptr, len); RB_GC_GUARD(orig_str); } dest[0] = ':'; RUBY_ASSERT_BUILTIN_TYPE(str, T_STRING); return str; }
#intern
Alias for #to_sym.
# File 'symbol.rb', line 27
alias intern to_sym
#length ⇒ Integer Also known as: #size
Equivalent to self.to_s.length
; see String#length.
# File 'string.c', line 12306
static VALUE sym_length(VALUE sym) { return rb_str_length(rb_sym2str(sym)); }
Equivalent to self.to_s.match
, including possible updates to global variables; see String#match.
# File 'string.c', line 12260
static VALUE sym_match_m(int argc, VALUE *argv, VALUE sym) { return rb_str_match_m(argc, argv, rb_sym2str(sym)); }
#match?(pattern, offset) ⇒ Boolean
Equivalent to sym.to_s.match?
; see String#match.
# File 'string.c', line 12275
static VALUE sym_match_m_p(int argc, VALUE *argv, VALUE sym) { return rb_str_match_m_p(argc, argv, sym); }
#name ⇒ String
# File 'symbol.c', line 969
VALUE rb_sym2str(VALUE sym) { VALUE str; if (DYNAMIC_SYM_P(sym)) { str = RSYMBOL(sym)->fstr; RUBY_ASSERT_BUILTIN_TYPE(str, T_STRING); } else { str = rb_id2str(STATIC_SYM2ID(sym)); if (str) RUBY_ASSERT_BUILTIN_TYPE(str, T_STRING); } return str; }
#next Also known as: #succ
# File 'string.c', line 12166
static VALUE sym_succ(VALUE sym) { return rb_str_intern(rb_str_succ(rb_sym2str(sym))); }
Alias for #length.
Alias for #[].
#start_with?(*string_or_regexp) ⇒ Boolean
Equivalent to self.to_s.start_with?
; see String#start_with?.
# File 'string.c', line 12400
static VALUE sym_start_with(int argc, VALUE *argv, VALUE sym) { return rb_str_start_with(argc, argv, rb_sym2str(sym)); }
#next
#succ
Alias for #next.
#swapcase(*options) ⇒ Symbol
Equivalent to sym.to_s.swapcase.to_sym
.
See String#swapcase.
# File 'string.c', line 12386
static VALUE sym_swapcase(int argc, VALUE *argv, VALUE sym) { return rb_str_intern(rb_str_swapcase(argc, argv, rb_sym2str(sym))); }
#to_proc ⇒ Proc
Returns a ::Proc
object which calls the method with name of self
on the first parameter and passes the remaining parameters to the method.
proc = :to_s.to_proc # => #<Proc:0x000001afe0e48680(&:to_s) (lambda)>
proc.call(1000) # => "1000"
proc.call(1000, 16) # => "3e8"
(1..3).collect(&:to_s) # => ["1", "2", "3"]
# File 'proc.c', line 1477
VALUE rb_sym_to_proc(VALUE sym) { static VALUE sym_proc_cache = Qfalse; enum {SYM_PROC_CACHE_SIZE = 67}; VALUE proc; long index; ID id; if (!sym_proc_cache) { sym_proc_cache = rb_ary_hidden_new(SYM_PROC_CACHE_SIZE * 2); rb_vm_register_global_object(sym_proc_cache); rb_ary_store(sym_proc_cache, SYM_PROC_CACHE_SIZE*2 - 1, Qnil); } id = SYM2ID(sym); index = (id % SYM_PROC_CACHE_SIZE) << 1; if (RARRAY_AREF(sym_proc_cache, index) == sym) { return RARRAY_AREF(sym_proc_cache, index + 1); } else { proc = sym_proc_new(rb_cProc, ID2SYM(id)); RARRAY_ASET(sym_proc_cache, index, sym); RARRAY_ASET(sym_proc_cache, index + 1, proc); return proc; } }
#to_s ⇒ String Also known as: #id2name
# File 'symbol.rb', line 10
def to_s Primitive.attr! :leaf Primitive.cexpr! 'rb_sym_to_s(self)' end
#to_sym ⇒ self
Also known as: #intern
Returns self
.
Related: String#to_sym.
# File 'symbol.rb', line 23
def to_sym self end
#upcase(*options) ⇒ Symbol
Equivalent to sym.to_s.upcase.to_sym
.
See String#upcase.
# File 'string.c', line 12336
static VALUE sym_upcase(int argc, VALUE *argv, VALUE sym) { return rb_str_intern(rb_str_upcase(argc, argv, rb_sym2str(sym))); }