Especificando o comprimento da cadeia de caracteres de saída de texto

Várias das funções de fonte e saída de texto têm um parâmetro que especifica o comprimento da cadeia de caracteres de saída de texto. Um exemplo típico é o parâmetro cchText de DrawTextEx.

Cada uma dessas funções tem uma versão "ANSI" e uma versão Unicode (por exemplo, DrawTextExA e DrawTextExW, respectivamente). Para a versão "ANSI" de cada função, o comprimento é especificado como uma contagem de bytes e para a função Unicode é especificado como uma contagem de WORD.

É tradicional pensar nisso como uma "contagem de caracteres". Isso é geralmente exato para muitas línguas, incluindo o inglês, mas não é exato em geral. Em cadeias de caracteres "ANSI", os caracteres das páginas de código SBCS ocupam um byte cada, mas a maioria dos caracteres nas páginas de código DBCS ocupam dois bytes. Da mesma forma, a maioria dos caracteres Unicode atualmente definidos residem no Plano Multilíngüe Básico (BMP) e suas representações UTF-16 cabem em uma WORD, mas caracteres suplementares são representados em Unicode por ''substitutos'', que requerem duas WORDs.

Cada uma dessas funções tem uma contagem de comprimento. Para a versão "ANSI" de cada função, o comprimento é especificado como a contagem em bytes de uma string, não incluindo o terminador NULL . Para a função Unicode, a contagem de comprimento é a contagem de bytes dividida por sizeof(WCHAR), que é 2, não incluindo o NULL terminador. A contagem de caracteres é a contagem do número de caracteres, que pode não ser igual à contagem de comprimento da cadeia de caracteres. Em alguns casos, os caracteres usam mais de um BYTE para ANSI (por exemplo, caractere DBCS) e mais de um WORD para Unicode (por exemplo, caracteres substitutos). Além disso, o número de glifos pode não ser igual ao número de caracteres porque vários caracteres podem ser compostos para criar um glifo. A contagem de comprimento é a quantidade de dados. Contagem de caracteres é o número de unidades que são processadas como uma entidade. Os glifos são aquilo que é renderizado. Por exemplo, em Unicode, você pode ter uma cadeia de caracteres com comprimento de 3, que é de 2 caracteres e que resulta em 1 glifo sendo renderizado. No entanto, normalmente, a maioria das cadeias de caracteres Unicode têm o mesmo comprimento, contagem de caracteres e número de glifos renderizados.

Você pode usar _tcslen() para obter o comprimento da cadeia de caracteres. Para ANSI, _tcslen() retorna o número de bytes. Para Unicode, _tcslen() retorna o número de WCHARs (ou seja, WORDs).

Caracteres de processamento especiais, como guias e hífenes suaves, que nem sempre são desenhados, podem afetar a saída desenhada. Eles são incluídos no comprimento da cadeia de caracteres e nas contagens de caracteres, mas podem não ser representados diretamente por um glifo renderizado.

Algumas dessas funções permitem que o chamador especifique o comprimento como -1 para indicar que a cadeia de caracteres é terminada em nulo; nesse caso, a função calculará a contagem de caracteres automaticamente. Nem todas as funções oferecem essa capacidade. Isso é especificado função a função; consulte a documentação da função individual.