LCMapString

9/8/2008

Essa função mapeia um seqüência de caracteres para outro, executando uma localidade especificada-dependente transformação. LCMapString Também pode ser usado para gerar um chave de classificação para a entrada seqüência de caracteres.

Syntax

int LCMapString(
  LCID Locale, 
  DWORD dwMapFlags, 
  LPCTSTR lpSrcStr, 
  int cchSrc, 
  LPTSTR lpDestStr, 
  int cchDest 
);

Parameters

• Localidade
  [no] Identificador de localidade. A localidade fornece um contexto para a geração mapeamento ou chave de classificação seqüência de caracteres. Um aplicativo pode usar o MAKELCID macro para criar um identificador localidade.

• dwMapFlags
  [no] Valor que especifica o tipo de transformação a ser usado durante a geração chave de classificação ou seqüência de caracteres mapeamento. Um aplicativo pode especificar mais de uma destas opções em uma transformação única, embora algumas combinações inválido. A seguinte tabela apresentação tanto as opções mapeamento e quaisquer restrições.

  Valor	Descrição
  LCMAP_BYTEREV	Use a reversão byte. De exemplo, se você transmitir no 0x3450 0x4822 o resultado é 0x5034 0x2248.
  LCMAP_FULLWIDTH	Caracteres de largura (onde aplicável).
  LCMAP_HALFWIDTH	Restringir caracteres (onde aplicável).
  LCMAP_HIRAGANA	Hiragana.
  LCMAP_KATAKANA	Katakana.
  LCMAP_LINGUISTIC_CASING	Utiliza regras lingüísticos para capitalização, em vez de regras sistema de arquivos (o usar como padrão). Válido com LCMAP_LOWERCASE ou LCMAP_UPPERCASE somente.
  LCMAP_LOWERCASE	Use minúsculas.
  LCMAP_SORTKEY	Produzir um normalizado ampla-chave classificar caractere.
  LCMAP_UPPERCASE	Usar maiúscula.
  NORM_IGNORECASE	Ignore maiúsculas e minúsculas.
  NORM_IGNOREKANATYPE	Não diferenciar entre caracteres hiragana e katakana. Correspondente hiragana e katakana irão Comparar como igual.
  NORM_IGNORENONSPACE	Ignore nonspacing. Este sinalizador também remove caracteres em japonês acentuação.
  NORM_IGNORESYMBOLS	Ignore símbolos.
  NORM_IGNOREWIDTH	Não diferenciar entre um único-byte caractere e o mesmo caractere como um double-byte character.
  SORT_STRINGSORT	Trate a pontuação o mesmo como símbolos.

  Se theLCMAP_SORTKEY sinalizador não for especificado, o LCMapString função executa mapeamento seqüência de caracteres. Nesta maiúsculas e minúsculas o seguinte aplicar restrições:

  • LCMAP_LOWERCASE e LCMAP_UPPERCASE são mutuamente exclusivos.
  • LCMAP_HIRAGANA e LCMAP_KATAKANA são mutuamente exclusivos.
  • LCMAP_HALFWIDTH e LCMAP_FULLWIDTH são mutuamente exclusivos.
  • SORT_STRINGSORT, NORM_IGNOREKANATYPE, NORM_IGNOREWIDTH e NORM_IGNORECASE não são válido.
  • LCMAP_TRADITIONAL_CHINESE e LCMAP_SIMPLIFIED_CHINESE são mutuamente exclusivos.
  • LCMAP_LOWERCASE e LCMAP_UPPERCASE não são sinalizadores válido em combinação com qualquer um do seguinte: LCMAP_HIRAGANA, LCMAP_KATAKANA, LCMAP_HALFWIDTH e LCMAP_FULLWIDTH.
    Quando o sinalizador LCMAP_SORTKEY for especificada, o LCMapString função gera uma chave classificar. Nesta maiúsculas e minúsculas o seguinte restrição se aplica:
  • LCMAP_SORTKEY é mutuamente com todos os outros sinalizadores LCMAP_ *, com a exceção único de LCMAP_BYTEREV.

• lpSrcStr
  [no] Ponteiro para uma seqüência de caracteres origem que a função mapeia ou usa para geração chave de classificação.

• cchSrc
  [no] Tamanho, em caracteres, da seqüência de caracteres apontado pelo lpSrcStr parâmetro.

  Esta contagem pode incluir o NULL terminador, ou não incluí-lo. Se o NULL terminador é incluído na contagem de caractere, ele não afeta significativamente o comportamento mapeamento. Isso ocorre porque NULL é considerado como unsortable e sempre mapeia a si mesmo.

  A cchSrc valor de – 1 especifica que o seqüência de caracteres apontado pelo lpSrcStr é terminada por caractere nulo. Se esse for a maiúsculas e minúsculas, e LCMapString está sendo usado na sua seqüência de caracteres-modo de mapeamento, a função calcula o comprimento do seqüência de caracteres o próprio e nulo-encerra o seqüência de caracteres mapeada armazenados em *lpDestStr.

• lpDestStr
  [out] Ponteiro longo para uma reserva para o qual a função armazena a chave seqüência de caracteres ou classificar mapeada.

  Se LCMAP_SORTKEY for especificada, LCMapString Armazena uma chave classificar para a reserva. A chave classificar é armazenado como uma matriz de valores byte no seguinte formato:

  [all Unicode sort weights] 0x01 [all Diacritic weights] 
  0x01 [all Case weights] 0x01 [all Special weights] 0x00 
  
  

  Observe que a chave classificar é terminada por caractere nulo. Isso é verdadeiro regardless of o valor de cchSrc. Também detalhes que, mesmo se alguns dos pesos de classificar estiver ausentes da chave de classificar, devido a a presença de ignorar uma ou mais sinalizadores no dwMapFlags, os separadores 0 x 01 e o terminador 0 x 00 estão ainda presentes.

• cchDest
  [no] Tamanho, em caracteres, da reserva apontado pelo lpDestStr.

  Se a função está sendo usada para mapeamento seqüência de caracteres, o tamanho é uma contagem caractere. Se espaço para um NULL terminador está incluído no cchSrc, em seguida, cchDest Também deve incluir espaço para um NULL terminador.

  Se a função está sendo usada para gerar um chave de classificação, o tamanho é um contagem de bytes. Esta contagem de bytes deve incluir espaço para o terminador 0 x 00 chave de classificação.

  Se cchDest for zero, valor de retorno a função é o número de caracteres, ou bytes se LCMAP_SORTKEY for especificada, exigido para manter o seqüência de caracteres mapeada ou chave classificar. Neste maiúsculas e minúsculas, a reserva apontado pelo lpDestStr não é usado.

Return Value

Se o valor de cchDest é o número de caracteres ou bytes, diferente de zero se LCMAP_SORTKEY for especificada, gravados a reserva indica sucesso. Essa contagem inclui espaço para um NULL terminador.

Se o valor de cchDest é zero, o tamanho da reserva em caracteres ou bytes se LCMAP_SORTKEY for especificada, exigido para receber o seqüência de caracteres traduzido ou chave classificar indica sucesso. Esse tamanho inclui espaço para um NULL terminador. Zero indica falha.

Para informações de erro estendidas get, chamar o GetLastError função. A seguinte tabela mostra possíveis valores para GetLastError.

Remarks

O seqüência de caracteres mapeada é NULL finalizado se seqüência de caracteres a origem é NULL finalizado.

Se o sinalizador LCMAP_HIRAGANA for especificada para mapa (n.); mapear (v.) caracteres katakana para caracteres Hiragana e LCMAP_FULLWIDTH não for especificado, a função apenas mapeia completa - largura caracteres para hiragana. Neste maiúsculas e minúsculas, qualquer half - largura Katakana caracteres são colocados como - está no seqüência de caracteres de saída, com nenhum mapeamento para hiragana. Um aplicativo deve especificar LCMAP_FULLWIDTH se ele quer metade - caracteres Katakana largura mapeado para hiragana.

O lpSrcStr e lpDestStr Ponteiros não devem ser o mesmo. Se eles forem iguais, a função falhará, e GetLastError Retorna ERROR_INVALID_PARAMETER.

Embora Windows Embedded CE oferece suporte somente a versão Unicode desta função, o seqüência de caracteres saída está somente em WCHAR Ou Char formato se o seqüência de caracteres-modo de mapeamento de LCMapString é usado. Se o modo de geração chave de classificação for usado, especificado por LCMAP_SORTKEY, a saída é uma matriz de valores byte. Um aplicativo pode comparar as chaves classificar usando um byte - Por - comparação byte.

Um aplicativo pode chamar a função com os sinalizadores NORM_IGNORENONSPACE e NORM_IGNORESYMBOLS definidos e todas as outras opções sinalizadores desmarcados, na ordem a simplesmente tirar caracteres da entrada seqüência de caracteres. Se isso é feito com uma entrada seqüência de caracteres que não são Null-Terminated, é possível para LCMapString Para retornar um seqüência vazia e não retornará um erro.

O LCMapString função ignora o kashida árabe. Se um aplicativo chama a função para criar um chave de classificação de um seqüência de caracteres que contém um Arabic Kashida, não haverá nenhum valor chave de classificação para a kashida.

A função trata o hífen e apóstrofo um bit de forma diferente de outros símbolos de pontuação, para que as palavras como coop e co-op permaneçam juntas em uma lista. Pontuação todos os símbolos que não seja o hífen e apóstrofo classificar antes de alfanumérico caracteres. Um aplicativo pode alteração esse comportamento por configuração o sinalizador SORT_STRINGSORT. Para uma discussão mais detalhada deste emitir, consulte o CompareString função.

Quando LCMapString é usado para gerar uma chave classificar, pela configuração o sinalizador LC_MAPSORTKEY, a chave classificar armazenados em *lpDestStr Pode conter um ímpar número de bytes. A opção LCMAP_BYTEREV inverte somente um número par de bytes. Se ambas as opções são escolhidas, o último byte (odd-positioned) na chave classificar não é revertida. Se a terminação byte 0 x 00 é um byte odd-positioned, em seguida, ele permanecerá o último byte na chave de classificar. Se a terminação byte 0 x 00 é um byte even-positioned, ele troca posições com o byte que o precede.

Para obter mais informações sobre LCID, consulte Identificadores de localidade suporte (NLS) idioma nacional.

Requirements

See Also

Reference

CompareString
FoldString
MAKELCID

Other Resources

National Language Support (NLS) Locale Identifiers