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 BYTE e, para a função Unicode, ele é especificado como uma contagem de WORD.

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

Cada uma dessas funções tem uma contagem de comprimento. Para a versão "ANSI" de cada função, o comprimento é especificado como um comprimento de contagem BYTE de uma cadeia de caracteres que não inclui o terminador NULL . Para a função Unicode, a contagem de comprimento é a contagem de bytes dividida por sizeof(WCHAR), que é 2, sem incluir o terminador NULL . 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 levam 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. Contagem de comprimento é a quantidade de dados. Contagem de caracteres é o número de unidades processadas como uma entidade. Glifos são o que é renderizado. Por exemplo, em Unicode, você pode ter uma cadeia de caracteres com comprimento de 3, que é de 2 caracteres e que resulta na renderização de 1 glifo. No entanto, normalmente, a maioria das cadeias de caracteres Unicode, a contagem de caracteres e o número de glifos renderizados são iguais.

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 especiais de processamento, como guias e hifens macios que nem sempre são desenhados, podem afetar a saída desenhada. Eles são incluídos nas contagens de caracteres e comprimento da cadeia 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 foi terminada em nulo; nesse caso, a função calculará a contagem de caracteres automaticamente. Nem todas as funções oferecem essa funcionalidade. Isso é especificado em uma base função por função; consulte a documentação da função individual.