module EmojiData

Returns a list of all known Emoji characters as ‘EmojiChar` objects.

@return [Array<EmojiChar>] a list of all known ‘EmojiChar`.

# File lib/emoji_data.rb, line 39
def self.all
  EMOJI_CHARS
end

Returns a list of all ‘EmojiChar` that are represented with doublebyte encoding.

@return [Array<EmojiChar>] a list of all doublebyte ‘EmojiChar`.

# File lib/emoji_data.rb, line 47
def self.all_doublebyte
  EMOJI_CHARS.select(&:doublebyte?)
end

Returns a list of all ‘EmojiChar` that have at least one variant encoding.

@return [Array<EmojiChar>] a list of all ‘EmojiChar` with variant encoding.

# File lib/emoji_data.rb, line 54
def self.all_with_variants
  EMOJI_CHARS.select(&:variant?)
end

Convert a native UTF-8 string glyph to its unified codepoint ID.

This is a conversion operation, not a match, so it may produce unexpected results with different types of values.

@param char [String] a single rendered emoji glyph encoded as a UTF-8 string @return [String] the unified ID

@example

>> EmojiData.unified_to_char("1F47E")
=> "👾"

# File lib/emoji_data.rb, line 110
def self.char_to_unified(char)
  char.codepoints.to_a.map { |i| i.to_s(16).rjust(4,'0')}.join('-').upcase
end

Returns a list of all known Emoji characters rendered as UTF-8 strings.

By default, the default rendering options for this library will be used. However, if you pass an option hash with ‘include_variants: true` then all possible renderings of a single glyph will be included, meaning that:

1. You will have “duplicate” emojis in your list.

2. This list is now suitable for exhaustably matching against in a search.

@option opts [Boolean] :include_variants whether or not to include all

possible encoding variants in the list

@return [Array<String>] all Emoji characters rendered as UTF-8 strings

# File lib/emoji_data.rb, line 71
def self.chars(opts={})
  options = {include_variants: false}.merge(opts)

  normals = EMOJI_CHARS.map { |c| c.render({variant_encoding: false}) }

  if options[:include_variants]
    extras  = self.all_with_variants.map { |c| c.render({variant_encoding: true}) }
    return normals + extras
  end
  normals
end

Returns a list of all known codepoints representing Emoji characters.

@option (see .chars) @return [Array<String>] all codepoints represented as unified ID strings

# File lib/emoji_data.rb, line 87
def self.codepoints(opts={})
  options = {include_variants: false}.merge(opts)

  normals = EMOJI_CHARS.map(&:unified)

  if options[:include_variants]
    extras = self.all_with_variants.map {|c| c.variant}
    return normals + extras
  end
  normals
end

Finds any ‘EmojiChar` that contains given string in its official name.

@param name [String] @return [Array<EmojiChar>]

# File lib/emoji_data.rb, line 160
def self.find_by_name(name)
  self.find_by_value(:name, name.upcase)
end

Find all ‘EmojiChar` that match string in any of their associated short name keywords.

@param short_name [String] @return [Array<EmojiChar>]

# File lib/emoji_data.rb, line 169
def self.find_by_short_name(short_name)
  self.find_by_value(:short_name, short_name.downcase)
end

Finds a specific ‘EmojiChar` based on the unified codepoint ID.

Must be exact match.

@param short_name [String] @return [EmojiChar]

# File lib/emoji_data.rb, line 179
def self.from_short_name(short_name)
  EMOJICHAR_KEYWORD_MAP[short_name.downcase]
end

Finds a specific ‘EmojiChar` based on its unified codepoint ID.

@param uid [String] the unified codepoint ID for an emoji @return [EmojiChar]

# File lib/emoji_data.rb, line 130
def self.from_unified(uid)
  EMOJICHAR_UNIFIED_MAP[uid.upcase]
end

Scans a string for all encoded emoji characters contained within.

@param str [String] the target string to search @return [Array<EmojiChar>] all emoji characters contained within the target

string, in the order they appeared.

@example

>> EmojiData.scan("flying on my 🚀 to visit the 👾 people.")
=> [#<EmojiData::EmojiChar... @name="ROCKET", @unified="1F680", ...>,
#<EmojiData::EmojiChar... @name="ALIEN MONSTER", @unified="1F47E", ...>]

# File lib/emoji_data.rb, line 151
def self.scan(str)
  matches = str.scan(FBS_REGEXP)
  matches.map { |m| EmojiData.from_unified(EmojiData.char_to_unified(m)) }
end

Convert a unified codepoint ID directly to its UTF-8 string representation.

@param uid [String] the unified codepoint ID for an emoji @return [String] UTF-8 string rendering of the emoji character

@example

>> EmojiData.char_to_unified("👾")
=> "1F47E"

# File lib/emoji_data.rb, line 122
def self.unified_to_char(uid)
  EmojiChar::unified_to_char(uid)
end