String#encode

str.encode(encoding) -> string

String#encode converts the encoding of a string to a specified target encoding. It returns a new string with the same characters but re-encoded, leaving the original string unchanged. This method is essential for handling multi-language text, fixing encoding issues, and ensuring strings are compatible with specific protocols or storage systems.

Syntax

string.encode(target_encoding)
string.encode(target_encoding, source_encoding)
string.encode(target_encoding, options)

Parameters

Parameter	Type	Default	Description
target_encoding	Symbol	Required	The encoding to convert to (e.g., :UTF_8, :ISO-8859-1)
source_encoding	Symbol	nil	The current encoding of the string (Ruby attempts to detect if omitted)
options	Hash	{}	Conversion options like invalid: :replace, undef: :replace

Examples

Basic encoding conversion

string = "hello"
string.encoding
# => #<Encoding:UTF-8>

utf8_string = "hello"
utf8_string.encode(:ISO-8859-1)
# => "hello"
# Returns a new string in ISO-8859-1 encoding

Converting from ASCII-8BIT

binary_data = "hello".encode(Encoding::ASCII_8BIT)
# Convert bytes to UTF-8
binary_data.force_encoding("UTF-8")
# => "hello"

# Or use encode directly
binary_data.encode("UTF-8")
# => "hello"

Handling invalid characters

invalid_utf8 = "hello\xFFworld"
invalid_utf8.encode("UTF-8", invalid: :replace, undef: :replace)
# => "hello?world"

Common Patterns

Transcoding for file I/O

content = File.read("data.csv", encoding: "UTF-8")
# Convert to ASCII for legacy systems
ascii_content = content.encode("US-ASCII", undef: :replace, invalid: :replace)
File.write("data ascii.csv", ascii_content, encoding: "US-ASCII")

Normalizing Unicode

text = "café"
text.encode!("UTF-8")  # in-place conversion

# Use Unicode normalization forms
normalized = text.encode("UTF-8").normalize(:nfc)

Encoding detection and conversion

def convert_to_utf8(string)
  # First force UTF-8 encoding, then re-encode properly
  string.force_encoding("UTF-8").encode("UTF-8")
end

# Handle various input encodings
def sanitize_encoding(input)
  input.encode("UTF-8", invalid: :replace, undef: :replace)
end

Working with external APIs

# Convert string for HTTP requests
query = "search term"
encoded_query = query.encode("UTF-8")

# Convert for legacy database storage
legacy_string = "old data".encode("Windows-1252")

CSV encoding handling

require "csv"

# Read CSV with specific encoding
CSV.foreach("data.csv", encoding: "ISO-8859-1") do |row|
  # Convert each field to UTF-8
  utf8_row = row.map { |cell| cell.encode("UTF-8", invalid: :replace) }
  process(utf8_row)
end

Email and HTTP headers

# Encode subject for email (RFC 2047)
subject = "Subject: =?UTF-8?B?#{["café"].pack("m0")}?="
# => "Subject: Y2Fmw6k="

# Decode received subject
decoded = subject.force_encoding("UTF-8")

Errors

• Encoding::UndefinedConversionError: Raised when the conversion is not defined between encodings. Handle with invalid: and undef: options.
• Encoding::InvalidByteSequenceError: Raised when the string contains bytes invalid for the source encoding. Use invalid: :replace to handle.
• ArgumentError: Raised when an invalid encoding name is provided.

See Also

• String#to_sym
• String#unpack
• String#unpack1