WoW API: GetUnitName

Reference e
AddOns WoW API Widget API XML UI Event API WoW Lua Macro API CVars Battle.net HOWTOs Snippets UI tech Categories

→ WoW API

← WoW API < GetUnitName

This function is implemented in Lua here FrameXML/UnitFrame.lua.

Returns the name and realm of the specified unit.

name = GetUnitName(unit, showServerName)

Parameters

Arguments

("unit", showServerName)

unit

String - The UnitId to query (e.g. "player", "party2", "pet", "target" etc.)

showServerName

Boolean - If true, append " - [server name]" to name if it's available or FOREIGN_SERVER_LABEL (" (*)" on enUS locale) if nil or false.

Returns

name

A formatted string based on the return values of UnitName(unit).

Example

print(GetUnitName("target"))

Result

Print "Bob" if Bob is your target and is on your server or "Bob - Server Name" if Bob is your target and is from a different server.

NOTE: GetUnitName returns different results based upon the string passed to it. It is very important to be aware of this, especially if you are using UnitName as a variable.

Example: Let's get the UnitName of a hunter that you have targeted in a battleground from Darkspear server, and the same hunter from an event caught in the combat log.

--Target Bob
UN = GetUnitName("target", true);
print (UN); -- Result is "BobTheHunter - Darkspear"
-- In event handler for COMBAT_LOG_EVENT_UNFILTERED
local pattern = "_DAMAGE";
local comEvent = select(2, ...);
local start = string.find(comEvent, pattern);
--continue working with 'damage' 
if start then
  local damage, overkill = select(15, ...);
  sourceGUID, killer, killerFlag, _, destGUID, victim, vicFlag = select(4, ...);
  -- for example, we just killed this hunter Bob
  UN = GetUnitName(victim, true);
  print(UN); -- Result is "BobTheHunter-Darkspear"
end

Note the differences in strings, namely the white space. I would strongly suggest running all results from GetUnitName() through a function of some sort to ensure the results are what is expected. However, make sure this is only player names, or you will end up with 'Stormwind-Guard' for example (which is invalid, of course).

Example - get unit name in the format of 'Name-Server' for your target.

--check the unitGUID to get the type of unit
local guid = UnitGUID(UN);
local B = tonumber(guid:sub(5,5), 16);
local maskedB = B % 8; -- x % 8 has the same effect as x & 0x7 on numbers <= 0xf

-- strip spaces out of a player 'name - server' string
if (maskedB == 0) then
 UN = SpaceStripper(GetUnitName("target", true); 
--  otherwise, just use the name as returned
else
 UN = GetUnitName("target", false);
end

--strip the spaces here, and return the new string
function SpaceStripper(str)
 if str ~= nil then
  res=split(str, ' - ');
  local count = 0;
  for _ in pairs(res) do count = count + 1 end  		
   if (count == 1) then res2 = res[1]; 
   else
    res2 = res[1]..'-'..res[3];	
    if (count > 3) then
     for i = 4, count, 1 do res2 = res2..res[i]; end
    end
   end 
  end
  return res2;
end

-- split function
-- http://lua-users.org/wiki/SplitJoin
function split(str, pat)
  local t = {}  -- NOTE: use {n = 0} in Lua-5.0
  local fpat = "(.-)" .. pat
  local last_end = 1
  local s, e, cap = str:find(fpat, 1)
  while s do
   if s ~= 1 or cap ~= "" then
    table.insert(t,cap)
   end
     last_end = e+1
     s, e, cap = str:find(fpat, last_end)
  end
  if last_end <= #str then
     cap = str:sub(last_end)
     table.insert(t, cap)
  end
  return t
end

Now using the above code, you will have a consistently formatted result from GetUnitName().

Details

See UnitName for more details.