The simplest string literals are enclosed in single quotes (the apostrophe character). The text within the quote marks is the value of the string:

'This is a simple Ruby string literal'

If you need to place an apostrophe within a single-quoted string literal, precede it with a backslash so that the Ruby interpreter does not think that it terminates the string:

'Won't you read O'Reilly's book?'

The backslash also works to escape another backslash, so that the second backslash is not itself interpreted as an escape character. Here are some situations in which you need to use a double backslash:

'This string literal ends with a single backslash: '
'This is a backslash-quote: ''
'Two backslashes: \'

In single-quoted strings, a backslash is not special if the character that follows it is anything other than a quote or a backslash. Most of the time, therefore, backslashes need not be doubled (although they can be) in string literals. For example, the following two string literals are equal:

'a' == 'a\b'

Single-quoted strings may extend over multiple lines, and the resulting string literal includes the newline characters. It is not possible to escape the newlines with a backslash:

'This is a long string literal 
that includes a backslash and a newline'

If you want to break a long single-quoted string literal across multiple lines without embedding newlines in it, simply break it into multiple adjacent string literals; the Ruby interpreter will concatenate them during the parsing process. Remember, though, that you must escape the newlines (see Chapter 2) between the literals so that Ruby does not interpret the newline as a statement terminator:

message = 
'These three literals are '
'concatenated into one by the interpreter. '
'The resulting string contains no newlines.'

String literals delimited by double quotation marks are much more flexible than single-quoted literals. Double-quoted literals support quite a few backslash escape sequences, such as for newline, for tab, and " for a quotation mark that does not terminate the string:

"	"This quote begins with a tab and ends with a newline"
"
"\"  # A single backslash

In Ruby 1.9, the u escape embeds arbitrary Unicode characters, specified by their codepoint, into a double-quoted string. This escape sequence is complex enough that we’ll describe it in its own section (see Unicode escapes). Many of the other backslash escape sequences are obscure and are used for encoding binary data into strings. The complete list of escape sequences is shown in Table 3-1.

More powerfully, double-quoted string literals may also include arbitrary Ruby expressions. When the string is created, the expression is evaluated, converted to a string, and inserted into the string in place of the expression text itself. This substitution of an expression with its value is known in Ruby as “string interpolation.” Expressions within double-quoted strings begin with the # character and are enclosed within curly braces:

"360 degrees=#{2*Math::PI} radians" # "360 degrees=6.28318530717959 radians"

When the expression to be interpolated into the string literal is simply a reference to a global, instance, or class variable, then the curly braces may be omitted:

$salutation = 'hello'     # Define a global variable
"#$salutation world"      # Use it in a double-quoted string

Use a backslash to escape the # character if you do not want it to be treated specially. Note that this only needs to be done if the character after # is {, $, or @:

"My phone #: 555-1234"                # No escape needed
"Use #{ to interpolate expressions"  # Escape #{ with backslash

sprintf("pi is about %.4f", Math::PI) # Returns "pi is about 3.1416"

"pi is about %.4f" % Math::PI # Same as example above
"%s: %f" % ["pi", Math::PI]   # Array on righthand side for multiple args

Double-quoted string literals may span multiple lines, and line terminators become part of the string literal, unless escaped with a backslash:

"This string literal
has two lines 
but is written on three"

You may prefer to explicitly encode the line terminators in your strings—in order to enforce network CRLF (Carriage Return Line Feed) line terminators, as used in the HTTP protocol, for example. To do this, write all your string literals on a single line and explicitly include the line endings with the and escape sequences. Remember that adjacent string literals are automatically concatenated, but if they are written on separate lines, the newline between them must be escaped:

"This string has three lines.
" 
"It is written as three adjacent literals
" 
"separated by escaped newlines
"

In Ruby 1.9, double-quoted strings can include arbitrary Unicode characters with u escapes. In its simplest form, u is followed by exactly four hexadecimal digits (letters can be upper- or lowercase), which represent a Unicode codepoint between 0000 and FFFF. For example:

"u00D7"       # => "×": leading zeros cannot be dropped
"u20ac"       # => "€": lowercase letters are okay

A second form of the u escape is followed by an open curly brace, one to six hexadecimal digits, and a close curly brace. The digits between the braces can represent any Unicode codepoint between 0 and 10FFFF, and leading zeros can be dropped in this form:

"u{A5}"      # => "¥": same as "u00A5"
"u{3C0}"     # Greek lowercase pi: same as "u03C0"
"u{10ffff}"  # The largest Unicode codepoint

Finally, the u{} form of this escape allows multiple codepoints to be embedded within a single escape. Simply place multiple runs of one to six hexadecimal digits, separated by a single space or tab character, within the curly braces. Spaces are not allowed after the opening curly brace or before the closing brace:

money = "u{20AC A3 A5}"  # => "€£¥"

Note that spaces within the curly braces do not encode spaces in the string itself. You can, however, encode the ASCII space character with Unicode codepoint 20:

money = "u{20AC 20 A3 20 A5}"  # => "€ £ ¥"

Strings that use the u escape are encoded using the Unicode UTF-8 encoding. (See String Encodings and Multibyte Characters for more on the encoding of strings.)

u escapes are usually, but not always, legal in strings. If the source file uses an encoding other than UTF-8, and a string contains multibyte characters in that encoding (literal characters, not characters created with escapes), then it is not legal to use u in that string—it is just not possible for one string to encode characters in two different encodings. You can always use u if the source encoding (see Specifying Program Encoding) is UTF-8. And you can always use u in a string that only contains ASCII characters.

u escapes may appear in double-quoted strings, and also in other forms of quoted text (described shortly) such as regular expressions, characters literals, %- and %Q-delimited strings, %W-delimited arrays, here documents, and backquote-delimited command strings. Java programmers should note that Ruby’s u escape can only appear in quoted text, not in program identifiers.

When working with text that contains apostrophes and quotation marks, it is awkward to use it as single- and double-quoted string literals. Ruby supports a generalized quoting syntax for string literals (and, as we’ll see later, for regular expression and array literals as well). The sequence %q begins a string literal that follows single-quoted string rules, and the sequence %Q (or just %) introduces a literal that follows double-quoted string rules. The first character following q or Q is the delimiter character, and the string literal continues until a matching (unescaped) delimiter is found. If the opening delimiter is (, [, {, or <, then the matching delimiter is ), ], }, or >. (Note that the backtick ` and apostrophe ' are not a matched pair.) Otherwise, the closing delimiter is the same as the opening delimiter. Here are some examples:

%q(Don't worry about escaping ' characters!)
%Q|"How are you?", he said|
%-This string literal ends with a newline
-  # Q omitted in this one

If you find that you need to escape the delimiter character, you can use a backslash (even in the stricter %q form) or just choose a different delimiter:

%q_This string literal contains \_underscores\__
%Q!Just use a _different_ delimiter!!

If you use paired delimiters, you don’t need to escape those delimiters in your literals, as long as they appear in properly nested pairs:

# XML uses paired angle brackets:
%<<book><title>Ruby in a Nutshell</title></book>>  # This works
# Expressions use paired, nested parens:
%((1+(2*3)) = #{(1+(2*3))})                        # This works, too
%(A mismatched paren ( must be escaped)           # Escape needed here

For long string literals, there may be no single character delimiter that can be used without worrying about remembering to escape characters within the literal. Ruby’s solution to this problem is to allow you to specify an arbitrary sequence of characters to serve as the delimiter for the string. This kind of literal is borrowed from Unix shell syntax and is historically known as a here document. (Because the document is right here in the source code rather than in an external file.)

Here documents begin with << or <<-. These are followed immediately (no space is allowed, to prevent ambiguity with the left-shift operator) by an identifier or string that specifies the ending delimiter. The text of the string literal begins on the next line and continues until the text of the delimiter appears on a line by itself. For example:

document = <<HERE        # This is how we begin a here document
This is a string literal.
It has two lines and abruptly ends...
HERE

The Ruby interpreter gets the contents of a string literal by reading a line at a time from its input. This does not mean, however, that the << must be the last thing on its own line. In fact, after reading the content of a here document, the Ruby interpreter goes back to the line it was on and continues parsing it. The following Ruby code, for example, creates a string by concatenating two here documents (and the newlines that terminate them) and a regular single-quoted string:

greeting = <<HERE + <<THERE + "World"
Hello
HERE
There
THERE

The <<HERE on line 1 causes the interpreter to read lines 2 and 3. And the <<THERE causes the interpreter to read lines 4 and 5. After these lines have been read, the three string literals are concatenated into one.

The ending delimiter of a here document really must appear on a line by itself: no comment may follow the delimiter. If the here document begins with <<, then the delimiter must start at the beginning of the line. If the literal begins with <<- instead, then the delimiter may have whitespace in front of it. The newline at the beginning of a here document is not part of the literal, but the newline at the end of the document is. Therefore, every here document ends with a line terminator, except for an empty here document, which is the same as "":

empty = <<END
END

If you use an unquoted identifier as the terminator, as in the previous examples, then the here document behaves like a double-quoted string for the purposes of interpreting backslash escapes and the # character. If you want to be very, very literal, allowing no escape characters whatsoever, place the delimiter in single quotes. Doing this also allows you to use spaces in your delimiter:

document = <<'THIS IS THE END, MY ONLY FRIEND, THE END'
    .
    . lots and lots of text goes here
    . with no escaping at all.
    .
THIS IS THE END, MY ONLY FRIEND, THE END

The single quotes around the delimiter hint that this string literal is like a single-quoted string. In fact, this kind of here document is even stricter. Because the single quote is not a delimiter, there is never a need to escape a single quote with a backslash. And because the backslash is never needed as an escape character, there is never a need to escape the backslash itself. In this kind of here document, therefore, backslashes are simply part of the string literal.

You may also use a double-quoted string literal as the delimiter for a here document. This is the same as using a single identifier, except that it allows spaces within the delimiter:

document = <<-"# # #"    # This is the only place we can put a comment
<html><head><title>#{title}</title></head>
<body>
<h1>#{title}</h1>
#{body}
</body>
</html>
               # # #

Note that there is no way to include a comment within a here document except on the first line after the << token and before the start of the literal. Of all the # characters in this code, one introduces a comment, three interpolate expressions into the literal, and the rest are the delimiter.

Ruby supports another syntax involving quotes and strings. When text is enclosed in backquotes (the ` character, also known as backticks), that text is treated as a double-quoted string literal. The value of that literal is passed to the specially named Kernel.` method. This method executes the text as an operating system shell command and returns the command’s output as a string.

Consider the following Ruby code:

`ls`

On a Unix system, these four characters yield a string that lists the names of the files in the current directory. This is highly platform-dependent, of course. A rough equivalent in Windows might be `dir`.

Ruby supports a generalized quote syntax you can use in place of backticks. This is like the %Q syntax introduced earlier, but uses %x (for execute) instead:

%x[ls]

Note that the text within the backticks (or following %x) is processed like a double-quoted literal, which means that arbitrary Ruby expressions can be interpolated into the string. For example:

if windows
  listcmd = 'dir'
else
  listcmd = 'ls'
end
listing = `#{listcmd}`

In a case like this, however, it is simpler just to invoke the backtick method directly:

listing = Kernel.`(listcmd)  # irb doesn't support this legal syntax

Strings are mutable in Ruby. Therefore, the Ruby interpreter cannot use the same object to represent two identical string literals. (If you are a Java programmer, you may find this surprising.) Each time Ruby encounters a string literal, it creates a new object. If you include a literal within the body of a loop, Ruby will create a new object for each iteration. You can demonstrate this for yourself as follows:

10.times { puts "test".object_id }

For efficiency, you should avoid using literals within loops.

In addition to all the string literal options described earlier, you can also create new strings with the String.new method. With no arguments, this method returns a newly created string with no characters. With a single string argument, it creates and returns a new String object that represents the same text as the argument object.

The String class has been rewritten in Ruby 1.9 to be aware of and properly handle multibyte characters. Although multibyte support is the biggest change in Ruby 1.9, it is not a highly visible change: code that uses multibyte strings just works. It is worth understanding why it works, however, and this section explains the details.

If a string contains multibyte characters, then the number of bytes does not correspond to the number of characters. In Ruby 1.9, the length and size methods return the number of characters in a string, and the new bytesize method returns the number of bytes. The [] and []= operators allow you to query and set the characters of a string, and the new methods getbyte and setbyte allow you to query and set individual bytes (though you should not often need to do this):

# -*- coding: utf-8 -*-   # Specify Unicode UTF-8 characters

# This is a string literal containing a multibyte multiplication character
s = "2×2=4"

# The string contains 6 bytes which encode 5 characters
s.bytesize                                     # => 6
s.bytesize.times {|i| print s.getbyte(i), " "} # Prints "50 195 151 50 61 52"
s.length                                       # => 5
s.length.times { |i| print s[i], " "}          # Prints "2 × 2 = 4"
s.setbyte(5, s.getbyte(5)+1);                  # s is now "2×2=5"

Note that the first line in this code is a coding comment that sets the source encoding (see Specifying Program Encoding) to UTF-8. Without this comment, the Ruby interpreter would not know how to decode the sequence of bytes in the string literal into a sequence of characters.

When a string contains characters encoded with varying numbers of bytes, it is no longer possible to map directly from character index to byte offset in the string. In the string above, for example, the second character begins at the second byte. But the third character begins at the fourth byte. This means that you cannot assume that random access to arbitrary characters within a string is a fast operation. When you use the [] operator, as we did in the code above, to access a character or substring within a multibyte string, the Ruby implementation must internally iterate sequentially through the string to find the desired character index. In general, therefore, you should try to do your string processing using sequential algorithms when possible. That is: use the each_char iterator when possible instead of repeated calls to the [] operator. On the other hand, it is usually not necessary to worry too much about this. Ruby implementations optimize the cases that can be optimized, and if a string consists entirely of 1-byte characters, random access to those characters will be efficient. If you want to attempt your own optimizations, you can use the instance method ascii_only? to determine whether a string consists entirely of 7-bit ASCII characters.

The Ruby 1.9 String class defines an encoding method that returns the encoding of a string (the return value is an Encoding object, which is described below):

# -*- coding: utf-8 -*-
s = "2×2=4"     # Note multibyte multiplication character
s.encoding      # => <Encoding: UTF-8>

The encoding of string literals is always the same as the source encoding of the file, except that literals that contain u escapes are always encoded in UTF-8, regardless of the source encoding.

Certain string operations, such as concatenation and pattern matching, require that two strings (or a string and a regular expression) have compatible encodings. If you concatenate an ASCII string with a UTF-8 string, for example, you obtain a UTF-8 string. It is not possible, however, to concatenate a UTF-8 string and an SJIS string: the encodings are not compatible, and an exception will be raised. You can test whether two strings (or a string and a regular expression) have compatible encodings by using the class method Encoding.compatible?. If the encodings of the two arguments are compatible, it returns the one that is the superset of the other. If the encodings are incompatible, it returns nil.

You can explicitly set the encoding of a string with force_encoding. This is useful if you have a string of bytes (read from an I/O stream, perhaps) and want to tell Ruby how they should be interpreted as characters. Or, if you have a string of multibyte characters, but you want to index individual bytes with []:

text = stream.readline.force_encoding("utf-8")
bytes = text.dup.force_encoding("binary")

force_encoding does not make a copy of its receiver; it modifies the encoding of the string and returns the string. This method does not do any character conversion—the underlying bytes of the string are not changed, only Ruby’s interpretation of them is changed. The argument to force_encoding can be the name of an encoding or an Encoding object.

force_encoding does no validation; it does not check that the underlying bytes of the string represent a valid sequence of characters in the specified encoding. Use valid_encoding? to perform validation. This instance method takes no arguments and checks whether the bytes of a string can be interpreted as a valid sequence of characters using the string’s encoding:

s = "xa4".force_encoding("utf-8")  # This is not a valid UTF-8 string
s.valid_encoding?                   # => false

The encode method (and the mutating encode! variant) of a string is quite different from force_encoding. It returns a string that represents the same sequence of characters as its receiver, but using a different encoding. In order to change the encoding of—or transcode—a string like this, the encode method must alter the underlying bytes that make up the string. Here is an example:

# -*- coding: utf-8 -*-
euro1 = "u20AC"                     # Start with the Unicode Euro character
puts euro1                           # Prints "€"
euro1.encoding                       # => <Encoding:UTF-8>
euro1.bytesize                       # => 3

euro2 = euro1.encode("iso-8859-15")  # Transcode to Latin-15
puts euro2.inspect                   # Prints "xA4"
euro2.encoding                       # => <Encoding:iso-8859-15>
euro2.bytesize                       # => 1

euro3 = euro2.encode("utf-8")        # Transcode back to UTF-8
euro1 == euro3                       # => true

Note that you should not often need to use the encode method. The most common time to transcode strings is before writing them to a file or sending them across a network connection. And, as we’ll see in Streams and Encodings, Ruby’s I/O stream classes support the automatic transcoding of text when it is written out.

If the string that you are calling encode on consists of unencoded bytes, you need to specify the encoding by which to interpret those bytes before transcoding them to another encoding. Do this by passing two arguments to encode. The first argument is the desired encoding, and the second argument is the current encoding of the string. For example:

# Interpret a byte as an iso-8859-15 codepoint, and transcode to UTF-8
byte = "xA4"
char = byte.encode("utf-8", "iso-8859-15")

That is, the following two lines of code have the same effect:

text = bytes.encode(to, from)
text = bytes.dup.force_encoding(from).encode(to)

If you call encode with no arguments, it transcodes its receiver to the default internal encoding, if one has been set with the -E or -U interpreter options (see Encoding Options). This allows library modules (for example) to transcode their public string constants to a common encoding for interoperability.

Character encodings differ not only in their mapping from bytes to characters, but in the set of characters that they can represent. Unicode (also known as UCS—the Universal Character Set) tries to allow all characters, but character encodings not based on Unicode can only represent a subset of characters. It is not possible, therefore, to transcode all UTF-8 strings to EUC-JP (for example); Unicode characters that are neither Latin nor Japanese cannot be translated.

If the encode or encode! method encounters a character that it cannot transcode, it raises an exception:

"u20AC".encode("iso-8859-1") # No euro sign in Latin-1, so raise exception

encode and encode! accept a hash of transcoding options as their final argument. At the time of this writing, the only defined option name is :invalid, and the only defined value for that key is :ignore. “ri String.encode” will give details when more options are implemented.

The Encoding class of Ruby 1.9 represents a character encoding. Encoding objects act as opaque identifiers for an encoding and do not have many methods of their own. The name method returns the name of an encoding. to_s is a synonym for name, and inspect converts an Encoding object to a string in a more verbose way than name does.

Ruby defines a constant for each of the built-in encodings it supports, and these are the easiest way to specify a hardcoded encoding in your program. The predefined constants include at least the following:

Encoding::ASCII_8BIT     # Also ::BINARY
Encoding::UTF_8          # UTF-8-encoded Unicode characters
Encoding::EUC_JP         # EUC-encoded Japanese
Encoding::SHIFT_JIS      # Japanese: also ::SJIS, ::WINDOWS_31J, ::CP932

Note that because these are constants, they must be written in uppercase, and hyphens in the encoding names must be converted to underscores. Ruby 1.9 also supports the US-ASCII encoding, the European encodings ISO-8859-1 through ISO-8859-15, and the Unicode UTF-16 and UTF-32 encodings in big-endian and little-endian variants.

If you have an encoding name as a string and want to obtain the corresponding Encoding object, use the Encoding.find factory method:

encoding = Encoding.find("utf-8")

Using Encoding.find causes the named encoding to be dynamically loaded, if necessary. Encoding.find accepts encoding names that are in either upper- or lowercase. Call the name method of an Encoding to obtain the name of the encoding as a string.

Encoding.list returns an array of all available encoding objects. Encoding.name_list returns an array of the names (as strings) of all available encodings. Many encodings have more than one name in common use, and Encoding.aliases returns a hash that maps encoding aliases to the official encoding names for which they are synonyms. The array returned by Encoding.name_list includes the aliases in the Encoding.aliases hash.

Use Encoding.default_external and Encoding.default_internal to obtain the Encoding objects that represent the default external and default internal encodings (see Source, External, and Internal Encodings). To obtain the encoding for the current locale, call Encoding.locale_charmap and pass the resulting string to Encoding.find.

Most methods that expect an Encoding object will also accept a case-insensitive encoding name (such as ascii, binary, utf-8, euc-jp, or sjis) in place of an Encoding object.

Normally, Ruby 1.8 treats all strings as sequences of 8-bit bytes. There is rudimentary support for multibyte characters (using the UTF-8, EUC, or SJIS encodings) in the jcode module of the standard library.

To use this library, require the jcode module, and set the global $KCODE variable to the encoding that your multibyte characters use. (Alternatively, use the -K command-line option when you start the Ruby interpreter.) The jcode library defines a new jlength method for String objects: it returns the length of the string in characters rather than in bytes. The existing 1.8 length and size methods are unchanged—they return the string length in bytes.

The jcode library does not modify the array indexing operator on strings, and does not allow random access to the characters that comprise a multibyte string. But it does define a new iterator named each_char, which works like the standard each_byte but passes each character of the string (as a string instead of as a character code) to the block of code you supply:

$KCODE = "u"        # Specify Unicode UTF-8, or start Ruby with -Ku option
require "jcode"     # Load multibyte character support

mb = "23032272=4" # This is "2×2=4" with a Unicode multiplication sign
mb.length           # => 6: there are 6 bytes in this string
mb.jlength          # => 5: but only 5 characters
mb.mbchar?          # => 1: position of the first multibyte char, or nil
mb.each_byte do |c| # Iterate through the bytes of the string.
  print c, " "      # c is Fixnum
end                 # Outputs "50 195 151 50 61 52 "
mb.each_char do |c| # Iterate through the characters of the string
  print c, " "      # c is a String with jlength 1 and variable length
end                 # Outputs "2 × 2 = 4 "

The jcode library also modifies several existing String methods, such as chop, delete, and tr, to work with multibyte strings.